# Xử lý sự cố

> Cách xử lý lỗi thường gặp: không vào được panel, quên mật khẩu hoặc mất 2FA, lỗi SSL và mail, trang "đang bận", cập nhật lỗi, license và cách nhờ hỗ trợ.

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

Hãy bắt đầu bằng doctor. Lệnh này kiểm tra dịch vụ, panel, database, ổ đĩa, RAM, chứng chỉ, đồng hồ và lần cập nhật gần nhất, rồi cho biết cách xử lý từng lỗi:

```bash
zopanel ctl doctor
```

Các mục dưới đây là những lỗi gặp nhiều nhất. Mọi lệnh đều chạy bằng root trên server.

## Không vào được panel

Panel lắng nghe ở cổng **8888**: `https://IP-CỦA-BẠN:8888`, hoặc `https://ten-mien-panel:8888` sau khi đã đặt tên miền cho panel. Khi truy cập bằng IP, chứng chỉ là tự ký, nên trình duyệt sẽ cảnh báo ở lần đầu.

1. **Panel có đang chạy không?**
   ```bash
   systemctl status zopanel zopanel-agent
   journalctl -u zopanel -n 50
   ```
2. **Cổng có đang mở không?** Bộ cài mở SSH, 80, 443 và 8888 trên UFW; kiểm tra bằng `ufw status`. Nếu nhà cung cấp có firewall riêng hoặc security group, hãy mở thêm cổng 8888/tcp ở đó.
3. **IP của bạn có được phép không?** Nếu đã bật **Giới hạn truy cập panel** mà IP của bạn đổi, hãy xoá danh sách:
   ```bash
   zopanel ctl allow-ip --clear            # cho phép mọi địa chỉ
   zopanel ctl allow-ip 203.0.113.10       # hoặc chỉ IP mới của bạn
   ```
4. **IP của bạn có bị chặn không?** Sau 8 lần đăng nhập sai trong 15 phút, fail2ban chặn địa chỉ đó ở cổng 8888 trong 1 giờ. Bỏ chặn bằng lệnh:
   ```bash
   fail2ban-client set zopanel unbanip 203.0.113.10
   ```
   Quản trị viên đăng nhập từ địa chỉ khác cũng có thể bỏ chặn tại **Bảo mật → Bỏ chặn**.

## Quên mật khẩu admin

```bash
zopanel ctl reset-password admin
```

Lệnh in ra một mật khẩu ngẫu nhiên mới. Thêm `--password` nếu muốn tự đặt mật khẩu. Mọi phiên đăng nhập của user đó bị đăng xuất và API token bị thu hồi. Lệnh dùng được cho mọi user của panel.

## Mất thiết bị xác thực hai lớp

```bash
zopanel ctl disable-2fa admin
```

Đăng nhập bằng mật khẩu, rồi thiết lập lại 2FA trong **Tài khoản của tôi**. Nếu **Bắt buộc xác thực hai lớp** đang bật, panel sẽ yêu cầu thiết lập ngay khi đăng nhập.

## Không cấp được chứng chỉ Let's Encrypt

| Thông báo | Cách xử lý |
| --- | --- |
| domain does not resolve | Tạo bản ghi A/AAAA trỏ về server này và chờ DNS cập nhật. |
| validation failed | Tên miền phải trỏ về server này. Cổng 80 phải mở ra Internet, kể cả trên firewall của nhà cung cấp. |
| Let's Encrypt rate limit reached | Chờ một thời gian rồi thử lại. Không thử lặp liên tục. |
| wildcard certificates need this server's DNS | Chứng chỉ wildcard cần thành phần DNS server, và zone phải được host trên server này. |

Kiểm tra tên miền đang trỏ về đâu:

```bash
dig +short example.com A
curl -I http://example.com/
```

Bạn không cần thử lại bằng tay:

- **AutoSSL** kiểm tra mỗi giờ các website chưa có chứng chỉ. Nó xin chứng chỉ ngay khi **mọi** địa chỉ của tên miền đều là IP của server này. Tên miền còn trỏ về server cũ, hoặc trỏ một phần sang nơi khác, sẽ được chờ.
- Lần thử thất bại được giãn cách dần, từ 2 giờ tới tối đa một ngày.
- Chứng chỉ tự gia hạn 30 ngày trước khi hết hạn.
- Gia hạn thất bại được thử lại sau 1, 2 rồi 4 ngày, và bạn nhận cảnh báo **Gia hạn SSL thất bại**.

Với chứng chỉ của chính panel, dùng **Cài đặt → Chung → Tên miền & SSL cho panel → Cấp chứng chỉ**. Xem thêm [Chứng chỉ SSL](/vi/docs/ssl).

## Mail không tới nơi

Mở **Email**, chọn tên miền và chạy **Kiểm tra gửi/nhận mail**. Công cụ kiểm tra MX, SPF, DKIM, DMARC, reverse DNS (PTR), cổng 25 gửi ra và danh sách đen, rồi cho biết bản ghi cần thêm.

- **Cổng 25 gửi ra bị chặn.** Nhiều nhà cung cấp VPS chặn cổng 25. Hãy yêu cầu họ mở, hoặc gửi qua dịch vụ SMTP: quản trị viên dùng **Email → Gửi mail qua relay (smarthost)** (SendGrid, Mailgun, Amazon SES, Brevo…).
- **Reverse DNS (PTR).** Nhờ nhà cung cấp VPS đặt reverse DNS của IP thành hostname mail, ví dụ `mail.example.com`.
- **Danh sách đen (Spamhaus, SpamCop, Barracuda).** Trước hết, tìm nguồn gửi spam; thường là một website bị hack. Xem **Email → Hàng đợi mail** và **Giới hạn gửi mail**, rồi gửi yêu cầu gỡ trên trang của danh sách đen đó. ZoPanel kiểm tra IP server mỗi ngày và gửi cảnh báo **IP máy chủ bị đưa vào blacklist**.
- **Hàng đợi mail tăng bất thường.** Từ 300 thư đang chờ trở lên sẽ có cảnh báo. Xem trong hàng đợi có phải một người gửi hay một server nhận đang từ chối mail không.
- **Thiếu DKIM.** Tạo bản ghi TXT DKIM đúng như trong bảng DNS của tên miền. Xem thêm [Email](/vi/docs/email).

## Website hiện trang "đang bận"

Website PHP và website ứng dụng hiện trang "đang bận, vui lòng thử lại" (HTTP 503, `Retry-After: 30`) khi PHP hoặc ứng dụng không phản hồi được, do quá tải, đang khởi động lại hoặc hết RAM. Công cụ tìm kiếm coi đây là lỗi tạm thời. Nguyên nhân, theo thứ tự thường gặp:

1. **Tài khoản chạm giới hạn của gói.** Mở tab **Nhật ký** của website và bấm **Chạy chẩn đoán**.
   - "Quá nhiều request PHP đồng thời" nghĩa là **Số PHP worker** quá thấp.
   - "Tiến trình bị dừng do hết RAM" nghĩa là **RAM (MB)** của gói quá thấp.

   Hãy tăng các giới hạn này trong **Gói hosting**, hoặc bật cache.
2. **Server thiếu RAM.** Xem trang **Tối ưu** và **Lịch sử tài nguyên** của tài khoản (trong **Tài khoản**). Khi thiếu RAM nghiêm trọng, ZoPanel dừng các pool PHP rảnh và huỷ những request chờ quá lâu, để server phục hồi ngay khi tải giảm.
3. **Bot hoặc lượng truy cập tăng đột biến.** Bật **Page cache** và **Giới hạn tốc độ request** trong tab **PHP & cấu hình** của website.
4. **Ứng dụng không chạy.** Với ứng dụng Node.js, Python hoặc Docker, xem output ở tab **Deploy** hoặc **Docker** và khởi động lại ứng dụng.

Xem [Hiệu năng và sức chứa](/vi/docs/performance) để hiểu cách ZoPanel xử lý quá tải.

## Cập nhật bị lỗi

Mỗi bản cập nhật đều được kiểm tra và tự lùi bản khi lỗi. Nếu phiên bản mới không hoạt động ổn định trong 3 phút, file chạy và database cũ được khôi phục, và bạn nhận cảnh báo **Cập nhật panel lỗi hoặc đã tự lùi bản**. Để rollback bằng tay, ví dụ khi phát hiện lỗi sau đó:

```bash
zopanel rollback          # phiên bản trước, giữ database hiện tại
zopanel rollback --db     # khôi phục cả database đã lưu trước khi cập nhật
```

`zopanel ctl doctor` hiển thị kết quả lần cập nhật gần nhất. Nếu cập nhật lỗi lặp lại, hãy gửi ticket kèm support bundle (xem bên dưới).

## License bị từ chối

Kiểm tra license tại **Cài đặt → License**, hoặc trên server bằng `zopanel ctl info`. Khi license không hợp lệ, panel chạy ở gói miễn phí (3 tài khoản và 10 website).

| Lý do hiển thị | Cách xử lý |
| --- | --- |
| license is bound to another server | Mỗi license dùng cho một server, nhận diện bằng **Server ID** (tính từ `/etc/machine-id`). Bấm **Gỡ license** trên server cũ trước khi kích hoạt ở server mới. Nếu server cũ không còn, đăng nhập zopanel.net, mở license trong **Tài khoản** và dùng **Chuyển sang server khác** (3 lần/năm); quá số lần đó, hãy gửi ticket hỗ trợ. |
| license expired on … | Gia hạn license. |
| license could not be verified online for more than 14 days | Server phải kết nối được tới máy chủ license qua HTTPS. License online được làm mới định kỳ và vẫn hoạt động 14 ngày khi mất kết nối. |
| the system clock is behind | Chỉnh lại giờ: `timedatectl set-ntp true`. |
| this ZoPanel binary has been modified | Cài lại bản chính thức bằng `zopanel update`. |

Xem [License](/vi/docs/licensing) để biết về các gói và cách kích hoạt.

## Log nằm ở đâu?

| Nội dung | Vị trí |
| --- | --- |
| Panel và agent | `journalctl -u zopanel -u zopanel-agent -n 200` |
| Website | `/var/log/zopanel/sites/<domain>.access.log` và `.error.log`, hoặc tab **Nhật ký** của website |
| Lỗi PHP | `~/logs/php<phiên bản>_errors.log` trong thư mục home của tài khoản |
| nginx | `/var/log/nginx/error.log` |
| Đăng nhập panel thất bại | `/var/log/zopanel/auth.log` |
| Mail | `journalctl -u postfix@- -u dovecot` |
| Thao tác trong panel và sự kiện watchdog | **Nhật ký hoạt động** |

## Nhờ hỗ trợ

1. Chạy doctor và giữ lại kết quả:
   ```bash
   zopanel ctl doctor
   zopanel version
   zopanel ctl info
   ```
2. Tạo support bundle:
   ```bash
   zopanel ctl support-bundle
   ```
   Lệnh tạo file `/root/zopanel-support-<ngày>-<giờ>.tar.gz`, gồm:
   - báo cáo doctor, phiên bản phần mềm, dịch vụ lỗi và mức dùng tài nguyên;
   - 500 dòng gần nhất của các log chính;
   - cấu hình, đã loại bỏ mật khẩu, secret, token và khoá.
3. Gửi ticket:
   - Nếu có tài khoản ZoPanel, vào **Ticket hỗ trợ → Ticket mới** và chọn license liên quan.
   - Nếu chưa có, dùng [trang hỗ trợ](/vi/support).

   Chọn chủ đề **Hỗ trợ kỹ thuật**, dán kết quả doctor và mô tả những gì đã thay đổi trước khi lỗi xảy ra. Hãy chuẩn bị sẵn support bundle, vì đội hỗ trợ có thể yêu cầu.

Không bao giờ gửi mật khẩu, khoá bí mật hay khoá khôi phục trong ticket.