# Cài đặt ZoPanel

> Cài ZoPanel bằng một lệnh, chọn thành phần và tuỳ chọn qua tham số, cài tự động bằng cloud-init và đăng nhập tại https://IP:8888.

Source: https://zopanel.net/vi/docs/install  
Updated: 2026-10-07

ZoPanel được cài bằng một lệnh duy nhất trên server Ubuntu hoặc Debian mới cài. Bộ cài cập nhật hệ thống, dựng web stack và khởi động panel. Hãy xem [Yêu cầu hệ thống](/vi/docs/requirements) trước.

## Cài nhanh

SSH vào server bằng root (hoặc user có sudo) và chạy:

```bash
curl -fsSL https://get.zopanel.net | sudo bash
```

Để truyền tuỳ chọn, đặt chúng sau `sudo bash -s --`:

```bash
curl -fsSL https://get.zopanel.net | sudo bash -s -- --php 8.3,8.2 --admin-email you@example.com
```

Script khởi tạo kiểm tra hệ điều hành và kiến trúc, tải manifest phát hành, xác minh chữ ký Ed25519 của manifest và checksum SHA-256 của file chạy, cài `/usr/local/zopanel/bin/zopanel` rồi chạy `zopanel setup` với các tuỳ chọn của bạn.

## Bộ cài làm những gì

Bộ cài in ra từng bước khi chạy:

1. **Checking system**: kiểm tra hệ điều hành, kiến trúc, RAM, và không có web server hay control panel nào khác.
2. **Updating the system**: `apt update` và nâng cấp toàn bộ gói (full upgrade), thử lại tối đa 3 lần. Sau đó bật **tự động cài bản vá bảo mật** (unattended-upgrades) và xử lý kernel (xem bên dưới).
3. **Installing packages**: nginx, MariaDB, UFW, Fail2ban, công cụ quota, OpenSSH và kho PHP (PPA ondrej trên Ubuntu, packages.sury.org trên Debian).
4. **Installing PHP**: các phiên bản trong `--php`, kèm wp-cli.
5. **Installing language runtimes**: mặc định Node.js 22, Composer và Python.
6. **Creating users and directories**: user hệ thống `zopanel` và các nhóm cho hosting.
7. **Configuring nginx**, **MariaDB** (buffer pool bằng 20% RAM, thêm swap cho server nhỏ) và **SFTP** (chroot).
8. **Configuring firewall and fail2ban**: UFW mở cổng SSH của bạn, 80, 443 và 8888; Fail2ban bảo vệ SSH và trang đăng nhập panel.
9. **Enabling disk quotas** và **Hiding processes between accounts** (ẩn tiến trình giữa các tài khoản).
10. **Installing ZoPanel**: cấu hình, chứng chỉ tự ký, quản trị viên đầu tiên, gói `Default` và hai dịch vụ `zopanel`, `zopanel-agent`.

Các thành phần tuỳ chọn và license key (nếu có) được chuyển cho panel, panel sẽ cài hoặc kích hoạt chúng chạy nền ngay sau khi khởi động.

Có thể chạy lại bộ cài an toàn: nó sửa lại cấu hình mà không đụng tới dữ liệu và giữ nguyên các tài khoản quản trị đã có.

### Xử lý kernel

ZoPanel nén được bộ nhớ rảnh của khách ngay trong RAM khi chạy Linux 6.8 trở lên. Nếu kernel đang chạy cũ hơn:

| Hệ điều hành | Bộ cài làm gì |
| --- | --- |
| Ubuntu 22.04 | Mặc định cài kernel HWE của Ubuntu (`linux-generic-hwe-22.04`) |
| Debian 12 | Hỏi có cài kernel backports 6.12 không (mặc định: không). Kernel này nằm ngoài diện hỗ trợ bảo mật của Debian. |
| Ubuntu 24.04, Debian 13 | Đã có kernel 6.8+: không cần làm gì |
| Container | Dùng kernel của máy chủ vật lý: không cần làm gì |

Bạn có thể đổi ý sau: trang **Tối ưu** hiển thị lệnh để cài kernel mới hơn.

### Câu hỏi khởi động lại

Khi kernel mới hoặc thư viện hệ thống cần khởi động lại, bộ cài hỏi **một lần duy nhất, ngay từ đầu**:

```text
A restart is needed to finish (new kernel or system libraries). Restart automatically
when the installation is done? [Y/n]
```

Nếu trả lời có, server tự khởi động lại 15 giây sau khi bộ cài chạy xong và ZoPanel tự chạy lên. Các thành phần đã chọn được cài sau khi khởi động lại. Nếu trả lời không, hãy chạy `reboot` sau đó để hoàn tất việc cập nhật.

## Tuỳ chọn của bộ cài

| Tham số | Mặc định | Tác dụng |
| --- | --- | --- |
| `--profile web\|full` | `web` | `web`: chỉ web stack. `full`: thêm mail, webmail, lịch & danh bạ, DNS, WAF, Apache (.htaccess), FTP, PostgreSQL, Adminer và Docker. |
| `--with DANH-SÁCH` | không | Thành phần thêm, cách nhau bởi dấu phẩy: `mail`, `webmail`, `dav`, `dns`, `waf`, `apache`, `ftp`, `postgres`, `mongo`, `adminer`, `docker`, `storage`. |
| `--php PHIÊN-BẢN` | `8.3` | Các phiên bản PHP cần cài, cách nhau bởi dấu phẩy (7.4 đến 8.4). Bản đầu tiên là bản mặc định. |
| `--admin-user TÊN` | `admin` | Tên đăng nhập của quản trị viên đầu tiên. |
| `--admin-email EMAIL` | không | Email quản trị, dùng cho Let's Encrypt và thông báo. |
| `--hostname HOST` | hostname hệ thống | Hostname của server. |
| `--mail-hostname HOST` | không | Tên máy chủ mail, cần cho `mail` và `webmail`. Nếu bỏ trống mà `--hostname` có từ ba phần trở lên (như `srv1.example.com`), hostname đó được dùng. |
| `--nameservers DANH-SÁCH` | không | Nameserver cho máy chủ DNS, cần cho `dns`. |
| `--license KEY` | không | License key, được kích hoạt khi panel chạy. |
| `--runtimes DANH-SÁCH` | `node22,composer,python` | Runtime cần cài (`node<major>`, `go`, `python`, `composer`). |
| `--yes` | tắt | Không hỏi gì, dùng giá trị mặc định. Không khởi động lại trừ khi có thêm `--reboot`. |
| `--reboot` | tắt | Tự khởi động lại khi xong nếu cần. |
| `--no-reboot` | tắt | Không bao giờ khởi động lại, chỉ thông báo khi cần. |
| `--keep-kernel` | tắt | Không bao giờ cài kernel mới hơn. |
| `--kernel-backports` | tắt | Debian 12: cài kernel backports 6.12 mà không hỏi. |
| `--no-os-upgrade` | tắt | Giữ nguyên các gói hệ thống (đồng thời bỏ qua bản vá bảo mật tự động và kernel). |
| `--force` | tắt | Vẫn tiếp tục trên hệ thống không được hỗ trợ hoặc đã có web server khác. |

Lưu ý:

- Không dùng `--reboot` và `--no-reboot` cùng lúc.
- Nếu chọn `mail`/`webmail` mà không có tên máy chủ mail, hoặc `dns` mà không có nameserver, thành phần đó bị bỏ qua kèm thông báo; bạn cài sau ở trang **Thành phần**.
- Để thông tin bí mật không hiện trong danh sách tiến trình, truyền license qua biến môi trường `ZOPANEL_LICENSE_KEY` và mật khẩu admin tự chọn qua `ZOPANEL_ADMIN_PASSWORD` thay cho tham số. Nếu không đặt mật khẩu, bộ cài tạo mật khẩu ngẫu nhiên.
- Khi không có terminal, các câu hỏi nhận câu trả lời mặc định.

### Ví dụ

Server đầy đủ có mail và DNS:

```bash
curl -fsSL https://get.zopanel.net | sudo bash -s -- \
  --profile full \
  --hostname srv1.example.com \
  --admin-email admin@example.com \
  --mail-hostname mail.example.com \
  --nameservers ns1.example.com,ns2.example.com
```

Hai phiên bản PHP và một license:

```bash
curl -fsSL https://get.zopanel.net | sudo bash -s -- --php 8.3,8.2 --license ZP-XXXX-XXXX-XXXX
```

## Cài tự động (cloud-init)

Dùng `--yes` để không bị hỏi, và quyết định việc khởi động lại bằng `--reboot` hoặc `--no-reboot`:

```yaml
#cloud-config
runcmd:
  - curl -fsSL https://get.zopanel.net | ZOPANEL_LICENSE_KEY=ZP-XXXX-XXXX-XXXX bash -s -- --yes --reboot --admin-email admin@example.com
```

cloud-init đã chạy bằng root nên không cần `sudo`. Mật khẩu admin được tạo sẽ in trong output của bộ cài, cloud-init ghi output này vào log (thường là `/var/log/cloud-init-output.log`). Bạn có thể đặt lại bất cứ lúc nào bằng `zopanel ctl reset-password admin`.

## Khi cài xong

Bộ cài in ra địa chỉ và thông tin đăng nhập đầu tiên:

```text
 ZoPanel is ready!

  URL:      https://203.0.113.10:8888
  Username: admin
  Password: ••••••••••••••••

  Save this password now — it is not stored anywhere in plain text.
  The certificate is self-signed until you set a panel domain in Settings.
```

Hãy lưu mật khẩu ngay: nó không được lưu ở đâu dưới dạng văn bản thường. Mở URL trên trình duyệt, chấp nhận cảnh báo chứng chỉ tự ký một lần rồi đăng nhập. Sau đó làm theo [Bắt đầu nhanh](/vi/docs/quick-start).

### Khi gặp sự cố

- Chạy `zopanel ctl doctor` để kiểm tra server và xem cách khắc phục.
- Quên mật khẩu: `zopanel ctl reset-password admin`.
- Bị khoá ngoài do giới hạn IP truy cập panel: `zopanel ctl allow-ip --clear`.
- Bước nào lỗi thì chạy lại bộ cài để thử lại.