# Cập nhật ZoPanel

> Cập nhật ZoPanel từ panel hoặc bằng zopanel update. Mỗi lần cập nhật đều lưu database, kiểm tra sức khoẻ và tự lùi bản khi có lỗi.

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

ZoPanel tự cập nhật dưới dạng một file chạy duy nhất có chữ ký số. Mỗi lần cập nhật đều được bảo vệ: database của panel được lưu trước, phiên bản mới phải qua bước kiểm tra sức khoẻ, nếu không đạt thì phiên bản cũ và database cũ tự động được khôi phục. Trang này hướng dẫn cập nhật thủ công, cập nhật tự động và cách tự lùi bản.

## Quá trình cập nhật

1. **Tải và xác minh.** Manifest phát hành của kênh bạn chọn được tải về và kiểm tra chữ ký Ed25519. File chạy phải khớp SHA-256 ghi trong manifest đã ký. Bản không có chữ ký hoặc bị sửa đổi đều bị từ chối.
2. **Giữ phiên bản cũ.** File chạy hiện tại được sao lưu riêng để có thể khôi phục.
3. **Snapshot database.** Database của panel được sao chép nhất quán vào `/var/lib/zopanel/pre-update/`. Hệ thống giữ 3 snapshot gần nhất. Nếu snapshot lỗi, quá trình cập nhật dừng lại và dịch vụ không được khởi động lại trên phiên bản mới.
4. **Khởi động lại trên phiên bản mới.** Hai dịch vụ `zopanel-agent` và `zopanel` khởi động lại. Phiên bản mới tự nâng cấp (migrate) database khi chạy.
5. **Kiểm tra sức khoẻ.** Cơ chế bảo vệ chờ tối đa 3 phút để cả hai dịch vụ chạy, agent phản hồi và health check của panel đạt, rồi kiểm tra lại sau 20 giây để chắc chắn panel chạy ổn định.
6. **Tự lùi bản.** Nếu kiểm tra không đạt, file chạy cũ và snapshot database được đưa trở lại, dịch vụ khởi động lại trên phiên bản cũ.

Cơ chế bảo vệ chạy như một unit systemd riêng, nên mất kết nối SSH hay đóng tab trình duyệt cũng không làm nó dừng giữa chừng. Website, database và mail vẫn chạy suốt quá trình: chỉ panel và agent của nó khởi động lại.

## Cập nhật từ panel

1. Vào **Cài đặt → Cập nhật**.
2. Thẻ cập nhật hiển thị **Phiên bản đang dùng** và **Phiên bản mới nhất**. Bấm **Kiểm tra** để kiểm tra lại.
3. Khi có bản mới, ghi chú phát hành được hiển thị. Bấm **Cập nhật ngay**.

Việc cập nhật chạy dưới dạng tác vụ. Panel tạm không truy cập được trong giây lát khi khởi động lại.

## Cập nhật bằng dòng lệnh

Chạy bằng root trên server:

```bash
zopanel update
```

Lệnh in ra từng bước và kết thúc bằng `ZoPanel X.Y.Z is up and healthy`, hoặc lý do đã lùi bản. Nếu đang ở bản mới nhất, lệnh thông báo và không làm gì.

Xem phiên bản đang cài:

```bash
zopanel version
```

## Cập nhật tự động và kênh phát hành

Trong **Cài đặt → Cập nhật → Tuỳ chọn cập nhật**:

| Thiết lập | Lựa chọn | Tác dụng |
| --- | --- | --- |
| **Kênh** | Stable, Beta | Loại bản phát hành server sẽ cài |
| **Tự động cập nhật** | Bật / tắt | Cài bản mới lúc 04:00 theo giờ máy chủ |

Tự động cập nhật mặc định tắt cho tới khi bạn bật. Khi tắt, panel kiểm tra mỗi ngày một lần và gửi cảnh báo **Có bản cập nhật** một lần cho mỗi bản mới.

Cập nhật tự động dùng đúng cơ chế bảo vệ như cập nhật thủ công.

## Cảnh báo về cập nhật

Trong **Cài đặt → Cảnh báo**, bật các sự kiện sau để nhận thông báo qua Telegram, email hoặc webhook:

- **Cập nhật panel lỗi hoặc đã tự lùi bản**: phiên bản mới không chạy ổn và đã được lùi lại, hoặc cập nhật thất bại.
- **Có bản cập nhật**: có bản phát hành mới (khi tự động cập nhật đang tắt).

Nếu server khởi động lại đúng lúc đang kiểm tra sức khoẻ, panel báo rằng bản cập nhật chưa được kiểm tra, và bạn tự quyết định giữ bản mới hay lùi lại.

## Tự lùi bản bằng tay

Nếu bản mới vẫn chạy nhưng bạn muốn quay về bản trước, chạy bằng root:

```bash
zopanel rollback
```

Lệnh đưa file chạy cũ trở lại và khởi động lại dịch vụ. Database của panel được xử lý tuỳ tình huống:

| Tình huống | Database |
| --- | --- |
| Lần cập nhật gần nhất bị lỗi, cách đây chưa tới 30 phút | Khôi phục từ snapshot chụp trước lần cập nhật đó |
| Cập nhật thành công, hoặc snapshot đã cũ hơn | **Giữ nguyên**, nên mọi thay đổi từ đó tới nay (tài khoản, website, hộp thư) không bị mất |

Lệnh in ra trường hợp đang áp dụng và tuổi của snapshot.

### `--db`: khôi phục cả database

```bash
zopanel rollback --db
```

Khôi phục luôn snapshot database chụp trước lần cập nhật gần nhất, bất kể đã bao lâu. Dùng khi phiên bản cũ không chạy được trên database hiện tại. **Mọi thay đổi trên panel kể từ lần cập nhật đó sẽ mất**: tài khoản, website, database, hộp thư và thiết lập được tạo hoặc sửa sau thời điểm đó. File website và dữ liệu bên trong database của khách không nằm trong database của panel, nhưng các bản ghi quản lý chúng trên panel thì có.

### `--binary-only`: không đụng tới database

```bash
zopanel rollback --binary-only
```

Chỉ đưa file chạy cũ trở lại, luôn giữ nguyên database hiện tại.

Lệnh lùi bản báo lỗi `no previous version to roll back to` nếu chưa có file chạy cũ nào được lưu, ví dụ ngay sau khi vừa cài mới.

## Xử lý sự cố

| Vấn đề | Cách xử lý |
| --- | --- |
| Không mở được panel sau khi cập nhật | Chờ tối đa 3 phút để cơ chế bảo vệ chạy xong. Sau đó chạy `systemctl status zopanel zopanel-agent` và `journalctl -u zopanel`. |
| Bản cập nhật đã bị lùi | Cảnh báo và log tác vụ cho biết lý do. Chạy `zopanel ctl doctor`, và gửi `zopanel ctl support-bundle` cho bộ phận hỗ trợ khi cần. |
| Website chạy khác thường sau khi cập nhật | Chạy `zopanel ctl rebuild` để áp dụng lại cấu hình của mọi tài khoản và website. |

## Cập nhật hệ điều hành

Cập nhật ZoPanel không nâng cấp các gói của hệ điều hành. Bộ cài đã bật tự động cài bản vá bảo mật (unattended-upgrades). **Trung tâm bảo mật** trên trang **Bảo mật** cho biết khi nào có bản vá bảo mật đang chờ hoặc cần khởi động lại sau khi cập nhật kernel.