Cài đặt Uptime Kuma trên VPS: Docker Compose, Caddy, cảnh báo

Uptime Kuma là công cụ giám sát mã nguồn mở, tự lưu trữ, hỗ trợ kiểm tra HTTP(S), TCP, ping, DNS, WebSocket và nhiều loại khác. Đặt trên một VPS riêng, nó vẫn tiếp tục kiểm tra khi máy chủ production của bạn gặp sự cố, thay vì biến mất cùng nó.

Hướng dẫn cài đặt Uptime Kuma trên VPS này triển khai v2 bằng Docker Compose, giữ cổng 3001 ở loopback, bổ sung HTTPS qua Caddy, chuyển cảnh báo tới Telegram, Discord và Slack, đồng thời công bố một trang trạng thái.

Điều kiện cần và những thứ bạn sẽ dùng

Một VPS có tối thiểu 1 vCPU, 1 GB RAM và 10 GB dung lượng SSD cục bộ
Ubuntu 24.04 LTS hoặc một bản Ubuntu hiện hành khác được Docker hỗ trợ
Docker Engine và Docker Compose đã cài trên VPS
Một tên miền hoặc tên miền phụ trỏ về VPS qua bản ghi A (chẳng hạn status.example.com)
Quyền truy cập SSH và mức độ thành thạo cơ bản với dòng lệnh

Nếu Docker chưa được cài, hãy làm theo hướng dẫn cài đặt Docker trên Ubuntu. Hướng dẫn này cài Docker Engine và plugin Compose dùng ở phần dưới.

Vì sao VPS giám sát phải tách khỏi những thứ nó theo dõi

Production in Region A has failed and its website, API and database are down, while Uptime Kuma on a separate VPS in Region B stays online, keeps probing those services and routes alerts to Telegram, Discord and Slack. An external watchdog checks Uptime Kuma itself.

Production và giám sát nằm trên cùng một máy chủ thì cùng chung một miền lỗi. Nếu máy chủ đó dừng, cả ứng dụng lẫn hệ thống có nhiệm vụ gửi cảnh báo đều biến mất.

Có hai cách bố trí thực tế giúp cải thiện điều này:

Cùng nhà cung cấp, khác vị trí. Đặt production và giám sát trên các máy chủ riêng ở những vị trí khác nhau. Cách này giảm rủi ro hỏng một máy chủ hoặc một trung tâm dữ liệu, nhưng không bảo vệ trước mọi sự cố mạng hay control plane trên toàn nhà cung cấp.
Nhà cung cấp hoàn toàn khác. Đặt công cụ giám sát ở nơi khác giúp chống lại cả những sự cố trên toàn nhà cung cấp. Đổi lại, bạn có thêm một tài khoản, một hóa đơn và một mảng vận hành phải quản lý.

Một instance Uptime Kuma đơn lẻ vẫn không có ai canh chừng từ bên ngoài. Hãy thêm một phép kiểm tra HTTP(S) từ bên ngoài nhắm vào trang trạng thái công khai của nó. Gói miễn phí của UptimeRobot hiện gồm 50 monitor với chu kỳ kiểm tra năm phút. Cách này không khiến Uptime Kuma đạt tính sẵn sàng cao, nhưng sẽ báo cho bạn khi chính công cụ giám sát biến mất.

Nguyên tắc đó cũng áp dụng cho trang trạng thái công khai: thứ báo cho bạn biết có sự cố không được nằm chung miền lỗi với thứ đang hỏng.

Xây dựng trên VPS Linux với quyền root, NVMe và sức mạnh AMD EPYC.

Xem các gói Linux

Chọn cấu hình VPS

Uptime Kuma không có công thức đáng tin cậy quy đổi số lượng monitor sang RAM, vì tải thay đổi theo loại monitor, chu kỳ kiểm tra, thiết lập retry và thời gian lưu lịch sử. Các phép kiểm tra HTTP(S), TCP, ping và DNS đơn giản nhẹ hơn kiểm tra Browser Engine, vốn phải chạy Chromium.

Với một nhóm nhỏ các phép kiểm tra cơ bản, hãy bắt đầu với 1 vCPU, 1 GB RAM và ổ SSD cục bộ. Theo dõi mức sử dụng thực tế bằng docker stats uptime-kuma và mức tăng của cơ sở dữ liệu bằng du -sh /opt/uptime-kuma/data. Hãy tăng bộ nhớ khi mức sử dụng luôn ở mức cao, khi container báo OOM kill, hoặc khi bạn bắt đầu dùng kiểm tra Browser Engine.

Image v2 bản đầy đủ có sẵn Chromium và MariaDB nhúng; tài liệu về tag Docker giải thích khác biệt giữa image full và slim.

Triển khai Uptime Kuma bằng Docker Compose

Lưu tệp này thành docker-compose.yml trong /opt/uptime-kuma/:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      # Bind to localhost only. The reverse proxy will expose it on 443.
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data

Có ba dòng đáng chú ý:

image: louislam/uptime-kuma:2 ghim phiên bản chính. Tag :2 bám theo nhánh phát hành ổn định 2.x. Đừng dùng :latest.
127.0.0.1:3001:3001 chỉ gắn container vào localhost. Internet công cộng không bao giờ được chạm trực tiếp tới cổng 3001. Chứng chỉ TLS và tên miền công khai do reverse proxy nắm giữ.
Volume dữ liệu chứa cơ sở dữ liệu, cấu hình monitor và lịch sử. Hãy giữ nó trên ổ đĩa cục bộ, vì tài liệu cài đặt của Uptime Kuma cảnh báo rằng các hệ thống tệp không có cơ chế khóa POSIX đáng tin cậy, kể cả nhiều cấu hình NFS, có thể làm hỏng SQLite. Hãy dừng stack trước khi sao chép ở mức hệ thống tệp.

Khởi chạy rồi kiểm tra:

sudo install -d -o "$USER" -g "$USER" /opt/uptime-kuma
cd /opt/uptime-kuma
# Paste the docker-compose.yml file above.
sudo docker compose up -d
sudo docker compose ps

Kết quả mong đợi của docker compose ps:

NAME          IMAGE                       STATUS                   PORTS
uptime-kuma   louislam/uptime-kuma:2      Up (healthy)             127.0.0.1:3001->3001/tcp

Để vào bảng điều khiển lần đầu, đừng mở cổng 3001 ra internet công cộng, dù chỉ trong chốc lát. Hãy dùng SSH tunnel:

ssh -L 3001:127.0.0.1:3001 [email protected]

Mở http://localhost:3001 trong trình duyệt, tạo tài khoản quản trị, đặt mật khẩu mạnh rồi đóng tunnel. Từ giờ bảng điều khiển sẽ đến với bạn qua HTTPS thông qua reverse proxy.

Nếu bạn không cần tự tay dựng bằng Compose, chúng tôi còn có Uptime Kuma dưới dạng ứng dụng cài một chạm. Trang ứng dụng hiện ghi v1 nên không khớp với cách dựng v2 bằng Compose trong bài này. Nếu bạn cần đúng v2, hãy đi theo hướng Compose thủ công.

Reverse proxy và TLS

Public traffic reaches Caddy on the host or an Nginx Proxy Manager container over HTTPS on port 443. Caddy forwards to Uptime Kuma on 127.0.0.1:3001 while the NPM container uses a shared Docker network instead. Public access to port 3001 is blocked, and first-time setup runs through an SSH tunnel to localhost:3001.

Đừng phơi Uptime Kuma ra ngoài trực tiếp. Hãy đặt một reverse proxy phía trước để lo TLS, xử lý URL đúng cách và tạo một điểm vào công khai duy nhất. Có hai hướng.

Caddy. Nếu Caddy chưa được cài, hãy làm theo hướng dẫn gói chính thức cho Ubuntu. Khi Caddy chạy như một service trên host, Caddyfile bên dưới sẽ proxy tới Uptime Kuma trên loopback và tự động lo việc cấp cũng như gia hạn chứng chỉ.

Mẹo: khi VPS giám sát chỉ chạy mỗi Uptime Kuma, hãy dùng Caddy. Caddyfile chỉ ba dòng, và Caddy tự lo việc cấp lẫn gia hạn chứng chỉ. Không cần Certbot, cũng không có timer gia hạn riêng phải canh lúc 4 giờ sáng.

Lưu nội dung này thành /etc/caddy/Caddyfile:

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

Nạp lại Caddy:

sudo systemctl reload caddy

Kiểm tra:

curl -I https://status.example.com

Bạn sẽ nhận được phản hồi 2xx hoặc 3xx thành công kèm chứng chỉ hợp lệ. Nếu kết nối thất bại, hãy xác nhận bản ghi A hoặc AAAA của tên miền trỏ về VPS này, cổng 80 và 443 truy cập được, và Caddy có thể bind cả hai cổng. Đây đều là những phần thuộc yêu cầu về HTTPS tự động của Caddy.

Nginx Proxy Manager. Nếu NPM chạy trực tiếp trên host, hãy thêm một Proxy Host cho status.example.com, chuyển tiếp tới 127.0.0.1 cổng 3001, yêu cầu chứng chỉ Let's Encrypt và bật Websockets Support. Nếu NPM chạy trong Docker, 127.0.0.1 sẽ trỏ ngược về chính container NPM. Khi đó hãy nối NPM và Uptime Kuma vào cùng một Docker network, rồi trỏ proxy host tới uptime-kuma cổng 3001.

Định tuyến cảnh báo: Telegram, Discord, Slack

Uptime Kuma có thể gửi cùng một sự kiện của monitor tới nhiều kênh thông báo. Hãy cấu hình mỗi nhà cung cấp một lần, rồi gắn một hoặc nhiều kênh vào từng monitor tùy theo ai cần nhận cảnh báo.

Thông báo được cấu hình chung tại Cài đặt > Thông báo, rồi được gán cho từng monitor. Mỗi monitor có thể bắn tới một hoặc nhiều kênh. Cùng một cảnh báo có thể tới Telegram cho kỹ sư trực, tới Slack cho cả nhóm và tới email để lưu nhật ký kiểm toán, tất cả từ một sự kiện duy nhất.

Trong Telegram, hãy nhắn tin cho @BotFather rồi chạy /newbot. Chọn một tên và một username. BotFather sẽ trả về bot token. Hãy lưu lại.
Gửi một tin nhắn bất kỳ cho bot mới. Sau đó mở https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates trên trình duyệt. Tìm trường chat.id, đó chính là chat ID của bạn.
Trong Uptime Kuma: Cài đặt > Thông báo > Thiết lập thông báo > Telegram. Dán bot token và chat ID. Bấm Kiểm tra. Xác nhận rằng bot có gửi cảnh báo thử.
Nếu tin nhắn thử không tới, hãy kiểm tra bot token và chat ID có đúng không, đồng thời xác nhận tường lửa của VPS cho phép HTTPS đi ra tới api.telegram.org.

Discord

Mở máy chủ Discord mà bạn muốn nhận cảnh báo. Bấm chuột phải vào kênh đích, rồi chọn Chỉnh sửa kênh > Tích hợp > Webhook > Webhook mới. Đặt tên cho nó (chẳng hạn "Uptime Kuma"), chọn kênh, rồi sao chép URL webhook.
Trong Uptime Kuma: Cài đặt > Thông báo > Thiết lập thông báo > Discord. Dán URL webhook. Nếu muốn, bạn có thể đặt thêm username và avatar.
Nhấp Kiểm tra. Xác nhận webhook có đăng cảnh báo thử vào kênh.

Slack

Trong Slack, hãy tạo một Incoming Webhook cho kênh mà bạn muốn nhận cảnh báo. Slack sẽ trả về một URL webhook dạng https://hooks.slack.com/services/T.../B.../....
Trong Uptime Kuma: Cài đặt > Thông báo > Thiết lập thông báo > Slack. Dán URL webhook. Nếu muốn, bạn có thể cấu hình thêm biểu tượng và kênh ghi đè.
Nhấp Kiểm tra.

Khi mọi phép thử đều đạt, hãy sửa từng monitor và chọn các kênh thông báo mà nó sẽ dùng. Đặt Max Retries (số lần thử lại tối đa) và Retry Interval (khoảng cách giữa các lần thử lại) sao cho một lần lỗi thoáng qua không lập tức kích hoạt cảnh báo.

Trang trạng thái tích hợp sẵn (và khi nào bạn sẽ thấy nó không đủ)

Uptime Kuma có sẵn trang trạng thái công khai với slug tùy chỉnh, gom nhóm monitor, tên miền riêng, bài đăng sự cố và thông báo bảo trì theo lịch. Bạn cũng có thể xuất bản nhiều trang trạng thái từ một instance, cho các dịch vụ hoặc nhóm người xem khác nhau.

Hạn chế lớn hơn nằm ở khâu liên lạc với khách hàng. Hiện người xem chưa thể đăng ký nhận cập nhật qua email ngay trên trang trạng thái, và trang công khai đó vẫn thuộc cùng một ứng dụng Uptime Kuma với bảng điều khiển của người vận hành. Việc người xem tự đăng ký vẫn đang được theo dõi dưới dạng một yêu cầu tính năng còn mở.

Nếu bạn cần cho khách hàng đăng ký nhận tin hoặc muốn một hệ thống trạng thái tách khỏi bảng điều khiển giám sát, Kener là một lựa chọn. Bài bộ công cụ giám sát tự lưu trữ của chúng tôi giải thích cách kết hợp hai công cụ này.

Sự cố thường gặp

Thông báo âm thầm thất bại khi tường lửa của VPS chặn HTTPS đi ra. Triệu chứng: nút Test chạy được với một số kênh nhưng không chạy với kênh khác. Cách khắc phục: xác nhận kết nối HTTPS đi ra được cho phép và lệnh curl -I https://api.telegram.org chạy thành công từ VPS.

Trình duyệt báo "ERR_TOO_MANY_REDIRECTS" sau khi bật proxy. Hãy kiểm tra xem có chuyển hướng HTTP sang HTTPS bị lặp trong Caddy, Nginx Proxy Manager hay ở CDN phía trước không. Uptime Kuma vẫn nên phục vụ HTTP trên cổng 3001, còn reverse proxy công khai mới là nơi kết thúc TLS. Nếu bạn bật header proxy tin cậy, đường dẫn hiện tại là Cài đặt > Reverse Proxy > HTTP Headers > Trust Proxy.

Container khởi động lại vài phút một lần. Kiểm tra xem container có bị dừng vì hết bộ nhớ không, rồi theo dõi mức dùng hiện tại bằng docker stats uptime-kuma. Nếu container bị OOM kill hoặc bộ nhớ luôn sát trần của VPS, hãy tăng RAM, bớt các phép kiểm tra nặng, hoặc giãn chu kỳ của chúng ra.

Trang trạng thái chạy được trên localhost nhưng không chạy qua tên miền công khai. Hãy xác nhận reverse proxy chuyển tiếp đường dẫn gốc nguyên vẹn, giữ nguyên header Host và hỗ trợ WebSockets. Uptime Kuma không hỗ trợ cài trong thư mục con, nên hãy dùng một tên miền hoặc tên miền phụ riêng thay vì đường dẫn kiểu example.com/uptime-kuma.

Tổng kết

Chạy Uptime Kuma trên một VPS riêng cho bạn quyền kiểm soát các phép kiểm tra, cách định tuyến cảnh báo và trang trạng thái công khai, nhưng bạn cũng gánh luôn việc cập nhật, sao lưu, vá hệ điều hành và lo cả người canh chừng bên ngoài cho chính công cụ giám sát. Hãy chọn VPS ở vị trí khác với production, triển khai v2 bằng Docker Compose hoặc dùng ứng dụng cài một chạm sau khi kiểm tra phiên bản được ghi, đặt Caddy phía trước, rồi nối tới những kênh mà đội của bạn thực sự theo dõi.

Câu hỏi thường gặp

Uptime Kuma cần bao nhiêu RAM?

Uptime Kuma không có công thức đáng tin cậy quy đổi số monitor sang RAM, vì mức dùng thay đổi theo loại monitor, chu kỳ kiểm tra, thiết lập retry, thời gian lưu lịch sử và việc có dùng Browser Engine hay không. Với một nhóm nhỏ các phép kiểm tra cơ bản, hãy bắt đầu với 1 GB RAM và theo dõi mức dùng thực tế bằng docker stats uptime-kuma. Tăng bộ nhớ nếu mức dùng luôn sát trần hoặc container bị OOM kill.

Có nên chạy Uptime Kuma trên cùng máy chủ với ứng dụng của tôi không?

Không. Nếu công cụ giám sát và ứng dụng dùng chung một máy chủ, sự cố sẽ hạ cả hai cùng lúc và bạn mất cảnh báo đúng vào lúc cần nó nhất. Hãy chạy Uptime Kuma trên một VPS riêng, tốt nhất là ở trung tâm dữ liệu khác.

Uptime Kuma có gửi được cảnh báo tới Telegram, Discord và Slack không?

Có. Telegram, Discord và Slack đều là dịch vụ thông báo tích hợp sẵn, bên cạnh email, webhook chung, PagerDuty, ntfy, Mattermost và nhiều dịch vụ khác. Telegram dùng bot token và chat ID, còn Discord và Slack dùng URL webhook. Bạn có thể gắn nhiều kênh thông báo vào cùng một monitor.

Uptime Kuma và UptimeRobot khác nhau thế nào?

Uptime Kuma là tự lưu trữ, nên bạn tự lo máy chủ, cập nhật, sao lưu và định tuyến cảnh báo. Nó hỗ trợ chu kỳ kiểm tra ngắn tới 20 giây. UptimeRobot là SaaS được lưu trữ sẵn, và gói miễn phí hiện tại của họ gồm 50 monitor với chu kỳ kiểm tra năm phút. Chọn Uptime Kuma nếu bạn muốn quyền kiểm soát, hoặc UptimeRobot nếu bạn không muốn vận hành máy chủ giám sát.

Uptime Kuma có trang trạng thái công khai không?

Có. Bạn có thể chọn hiển thị monitor nào, gom nhóm chúng, xuất bản nhiều trang trạng thái, gắn chúng với tên miền riêng và lên lịch thông báo bảo trì. Tính năng để người xem tự đăng ký nhận email thì không có sẵn, nên khi khách hàng cần đăng ký nhận cập nhật, hãy dùng một công cụ trang trạng thái hướng khách hàng riêng.

Cách cài đặt Uptime Kuma trên VPS