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.
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
- 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.
- 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.
- Snapshot database. Database của panel được sao chép nhất quán vào
/var/lib/zopanel-root/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. - Khởi động lại trên phiên bản mới. Hai dịch vụ
zopanel-agentvàzopanelkhởi động lại. Phiên bản mới tự nâng cấp (migrate) database khi chạy. - 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.
- 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
- Vào Cài đặt → Cập nhật.
- 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.
- 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:
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:
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 mọi bản mới lúc 04:00 theo giờ máy chủ |
| Tự cài bản vá bảo mật | Bật / tắt | Cài bản vá bảo mật trong khoảng một giờ, vào bất kỳ giờ nào |
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.
Bản vá bảo mật
Bản phát hành có manifest đã ký đánh dấu là bản vá bảo mật (hoặc bản phát hành sau đó mang theo bản vá mà server chưa có) có thể tự cài, không phải chờ tới 04:00 và không cần bật cập nhật mọi bản:
- Server mới (cài từ 0.4.29) được bật sẵn. Bộ cài hỏi một lần;
--no-auto-security-updates(hoặcZOPANEL_NO_AUTO_SECURITY_UPDATES=1) cài với tuỳ chọn này tắt. - Server cài trước 0.4.29 giữ tắt. Quản trị viên toàn quyền được hỏi một lần trên trang tổng quan (Tự cài bản vá bảo mật của ZoPanel?, Bật hoặc Không, cảm ơn); câu trả lời nào cũng được giữ và có thể đổi sau trong Cài đặt → Cập nhật.
Khi bật, panel kiểm tra máy chủ cập nhật mỗi giờ. Bản vá bảo mật được cài ở lượt kiểm tra 15 phút đầu tiên sau khi đã biết tới nó được 15 phút, tức là trong khoảng một giờ kể từ khi phát hành. Việc cài giống hệt bấm Cập nhật ngay: agent chạy quyền root kiểm tra lại chữ ký và chống phát lại của manifest, lưu database, phiên bản mới phải qua kiểm tra sức khoẻ, và bản không chạy ổn sẽ được lùi lại cùng database. Nếu đang sao lưu, khôi phục, nhập dữ liệu hay chuyển tài khoản, việc cài chờ tới lượt sau. Tải hoặc cài lỗi sẽ thử lại sau một giờ, tối đa 3 lần cho mỗi bản.
Bản vá bảo mật đã bị lùi, do cơ chế bảo vệ hay do bạn chạy zopanel rollback, không bao giờ tự cài lại: hãy cài bằng Cập nhật ngay sau khi đã xem lý do. Cài đặt → Cập nhật cho biết trạng thái bản đang chờ (sẽ cài trong vòng một giờ, đang chờ sao lưu, đang thử lại, hoặc không tự cài nữa và lý do).
Mỗi bước được ghi vào nhật ký hoạt động (Bắt đầu tự cài bản vá bảo mật, Đã tự cài bản vá bảo mật, Tự cài bản vá bảo mật thất bại). Cảnh báo Đã tự cài bản vá bảo mật (bật sẵn, kể cả trên server đã lưu thiết lập cảnh báo trước khi có sự kiện này) và Cập nhật panel lỗi hoặc đã tự lùi bản cho bạn biết chuyện gì đã xảy ra.
Khi có bản mới hơn, quản trị viên toàn quyền còn thấy ngay trong panel: mục Đã có ZoPanel X trong Cần bạn xử lý trên trang tổng quan, kèm vài dòng đầu của ghi chú phát hành, liên kết Có gì mới tới nhật ký thay đổi và nút Cập nhật mở Cài đặt → Cập nhật; menu Cài đặt có một chấm báo. Bản vá bảo mật được hiện ở mức cảnh báo. Panel dùng kết quả của lần kiểm tra gần nhất (tối đa 12 giờ một lần, và ngay sau khi khởi động); mở trang tổng quan không bao giờ gọi tới máy chủ cập nhật. Quản trị viên giới hạn, reseller và khách hàng không thấy các thông báo này.
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.
- Đã tự cài bản vá bảo mật: một bản vá bảo mật đã tự cài và chạy ổn (xem ở trên).
- 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), kèm vài dòng đầu của ghi chú phát hành và liên kết nhật ký thay đổi. Bật sẵn trên server cài từ bản 0.4.26 trở đi; server cài trước đó giữ trạng thái tắt cho tới khi bạn bậ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:
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
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
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.
Cập nhật PHP
PHP được cài từ kho riêng: packages.sury.org trên Debian và PPA ondrej/php trên Ubuntu (Ubuntu 26.04 dùng PHP của bản phân phối). Cấu hình unattended-upgrades mặc định chỉ gồm kho của bản phân phối, nên từ 0.4.27 ZoPanel thêm kho PHP vào một file riêng, /etc/apt/apt.conf.d/52zopanel-php (origin deb.sury.org và LP-PPA-ondrej-php). File này được tạo trên server mới và, với server đang chạy, một lần khi agent khởi động, chỉ khi đã bật tự động cài bản vá bảo mật và file chưa có; 50unattended-upgrades và những gì bạn tự sửa không bao giờ bị đụng tới. Xoá file này để ngừng tự cập nhật PHP: ZoPanel không tạo lại, trừ khi bạn bấm Sửa ở mục Bản vá PHP tự động được cài trong Trung tâm bảo mật. Kiểm tra bằng unattended-upgrade --dry-run -d: danh sách origin được phép có origin=deb.sury.org hoặc origin=LP-PPA-ondrej-php.
Cài gói PHP đã vá chưa đủ: mỗi tài khoản có PHP-FPM master riêng, Adminer và webmail cũng vậy, và master đang chạy vẫn giữ file PHP cũ trong bộ nhớ. Vì vậy ZoPanel thêm một hook của apt (/etc/apt/apt.conf.d/80zopanel-php-restart) và kiểm tra thêm mỗi 5 phút: sau mỗi lần nâng cấp PHP, dù bằng unattended-upgrades, bằng Server → Cập nhật hệ điều hành hay chạy apt bằng tay, mọi PHP-FPM master còn chạy file đã bị thay được nạp lại trên bản mới (request đang chạy vẫn xử lý xong), và được khởi động lại nếu nạp lại chưa đủ. Pool đang dừng sẽ chạy bản mới ở lượt truy cập tiếp theo. Mỗi lần chuyển được ghi vào Nhật ký hoạt động ("Chuyển PHP sang bản mới").
Khi panel được cập nhật lên 0.4.27, agent cài ngay bản PHP đã vá cho các phiên bản PHP đang cài (PHP2Shell, CVE-2026-109618 và CVE-2026-109619, đã vá ở 8.5.12, 8.4.27, 8.3.36 và 8.2.35): chỉ các gói php* của những phiên bản đó, không gói nào khác, rồi chuyển master như trên. Nếu apt đang bận, agent thử lại mỗi 5 phút.
Docker, MongoDB, .NET, Redis và backports
ZoPanel thêm vài kho nữa khi bạn cài thành phần: kho của Docker (download.docker.com, trên Debian 12), của MongoDB (repo.mongodb.org, một dòng phiên bản như 8.0), của Microsoft cho .NET trên Debian (packages.microsoft.com), PPA .NET backports trên Ubuntu (ppa:dotnet/backports), của Redis trên Ubuntu 22.04 (packages.redis.io) và backports của Debian cho kernel 6.12 trên Debian 12 khi bạn chọn. PostgreSQL và MariaDB lấy từ bản phân phối, đã có sẵn trong unattended-upgrades. Từ 0.4.29:
- Bản vá của các kho này tự cài.
/etc/apt/apt.conf.d/53zopanel-thirdpartythêm origin của chúng vào unattended-upgrades (ví dụorigin=Docker,label=Docker CEvàorigin=mongodb,archive=${distro_codename}/mongodb-org/8.0). File đi theo các kho đang có, được giữ nguyên khi bạn sửa, và không tạo lại nếu bạn xoá (trừ khi bạn bấm Sửa trong Trung tâm bảo mật). Kiểm tra bằngunattended-upgrade --dry-run -d. - Không bao giờ nhảy phiên bản chính.
/etc/apt/preferences.d/zopanel-majorsgiữ các gói Docker, containerd và Redis ở phiên bản chính đang cài (Pin: version 5:29.*, các phiên bản khác của kho đó ở mức ưu tiên -1), nên Docker 29 nhận bản vá 29.x nhưng không bao giờ lên 30, kể cả khi dùng Server → Cập nhật hệ điều hành hayapt upgrade. Kho MongoDB chỉ có một dòng phiên bản (8.0 không bao giờ đưa 8.2), còn gói .NET mang phiên bản chính trong tên (dotnet-runtime-8.0). Kho Microsoft chỉ dùng cho .NET: các gói khác của kho có mức ưu tiên 100, nên không bao giờ thay gói của bản phân phối. Muốn chủ động lên phiên bản chính mới: xoá file (ZoPanel không tạo lại trừ khi bạn bấm Sửa), nâng cấp, rồi bấm Sửa để giữ phiên bản chính mới. - Docker khởi động lại mà ứng dụng vẫn chạy. Nâng cấp Docker khởi động lại
dockerd.daemon.jsoncủa ZoPanel có"live-restore": true, nên container vẫn chạy (đo trên Debian 12 với Docker 29.9.0 → 29.9.2 và containerd 2.4.1 → 2.4.2: tiến trình container giữ nguyên; địa chỉ publish của chúng không phản hồi khoảng 2 giây khidockerdkhởi động lại). Nếudaemon.jsoncủa bạn không cólive-restore, mọi container sẽ khởi động lại, nên Docker bị loại khỏi cập nhật tự động (Package-Blacklist) và Trung tâm bảo mật đưa nút cập nhật một lần bấm thay vào đó. - Dịch vụ chạy lại trên bản mới. Gói MongoDB không khởi động lại
mongodsau khi nâng cấp, và Debian không cóneedrestart. Sau mỗi lần apt chạy, ZoPanel khởi động lạimongod(vàredis-server) nếu nó còn chạy file đã bị thay, và chạy lại mọi unit của ZoPanel bị lỗi trong lúc đó; cả hai đều ghi vào nhật ký hoạt động. Trên Ubuntu,needrestarttự khởi động lại hầu hết dịch vụ;/etc/needrestart/conf.d/zopanel.confbảo nó để yênzopanelvàzopanel-agent, hai dịch vụ ZoPanel tự khởi động lại dưới cơ chế bảo vệ khi cập nhật. - Trung tâm bảo mật. Mỗi kho có một mục kiểm tra, Không có bản cập nhật chờ từ …, liệt kê các gói có bản mới hơn và nút Sửa cài ngay (chỉ các gói đó, trong phạm vi phiên bản đang giữ; với Docker có báo trước rằng địa chỉ của ứng dụng tạm dừng vài giây). Mục Bản vá từ các kho ZoPanel thêm được cài tự động báo lỗi khi có kho nằm ngoài cập nhật tự động.