Hướng dẫn · 19/09/2026

Hướng dẫn cài Uptime Kuma để giám sát website, API và SSL

Website hoạt động khi bạn mở thử không có nghĩa là nó ổn định suốt ngày. Một lỗi DNS theo khu vực, chứng chỉ SSL sắp hết hạn, API trả nội dung sai hoặc máy chủ chập chờn có thể kéo dài hàng giờ nếu không có giám sát chủ động. Uptime Kuma là công cụ self-hosted giúp kiểm tra dịch vụ định kỳ, gửi cảnh báo và tạo status page mà không cần xây cả hệ thống observability phức tạp.

Website hoạt động khi bạn mở thử không có nghĩa là nó ổn định suốt ngày. Một lỗi DNS theo khu vực, chứng chỉ SSL sắp hết hạn, API trả nội dung sai hoặc máy chủ chập chờn có thể kéo dài hàng giờ nếu không có giám sát chủ động. Uptime Kuma là công cụ self-hosted giúp kiểm tra dịch vụ định kỳ, gửi cảnh báo và tạo status page mà không cần xây cả hệ thống observability phức tạp.

Hướng dẫn này triển khai Uptime Kuma bằng Docker Compose trên Ubuntu/Debian, đặt sau Nginx và HTTPS. Ví dụ dùng nhánh image major 2; trước production hãy xem release note và thử bản cập nhật trên backup.

Uptime Kuma phù hợp với nhu cầu nào?

Công cụ phù hợp để kiểm tra từ bên ngoài ứng dụng:

HTTP/HTTPS, keyword hoặc JSON response của website và API.
TCP port, ping, DNS và một số dịch vụ hạ tầng.
Ngày hết hạn chứng chỉ TLS.
Heartbeat/push monitor cho cron job hoặc backup job.
Status page công khai hoặc nội bộ.
Cảnh báo qua email, webhook và nhiều nền tảng nhắn tin.

Uptime Kuma không thay thế log, metric, trace hay APM. Nó trả lời “dịch vụ có dùng được từ điểm quan sát này không?”, còn nguyên nhân CPU, query hoặc code nào gây lỗi vẫn cần công cụ khác.

1. Chọn vị trí đặt máy giám sát

Không nên đặt Uptime Kuma trên cùng máy chủ với website duy nhất cần theo dõi. Nếu máy đó mất nguồn hoặc mất mạng, cả dịch vụ và công cụ cảnh báo đều biến mất. Tốt hơn là dùng VPS nhỏ ở nhà cung cấp hoặc vùng mạng khác.

Chuẩn bị:

Máy Linux có Docker Engine và Docker Compose plugin.
Một subdomain riêng, ví dụ status.example.com.
Firewall chỉ mở SSH quản trị, HTTP và HTTPS khi cần.
Nơi lưu backup ngoài máy giám sát.

Không dùng đường dẫn con như example.com/uptime; tài liệu dự án khuyến nghị domain hoặc subdomain riêng.

2. Tạo cấu trúc thư mục

sudo mkdir -p /opt/uptime-kuma/data
cd /opt/uptime-kuma

Thư mục data giữ database, cấu hình monitor và các dữ liệu bền vững. Hãy giới hạn quyền truy cập cho tài khoản quản trị phù hợp và không đưa nó vào Git.

3. Tạo Docker Compose

Tạo file compose.yaml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
    security_opt:
      - no-new-privileges:true

Binding 127.0.0.1 ngăn cổng 3001 lộ trực tiếp ra Internet; người dùng truy cập qua reverse proxy HTTPS. Volume /app/data là phần phải backup. Không gắn Docker socket vào container nếu không dùng chức năng cần đến nó, vì socket có quyền rất mạnh trên host.

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 uptime-kuma

Trên chính server, kiểm tra curl -I http://127.0.0.1:3001. Nếu container restart liên tục, xem log và quyền ghi thư mục data trước khi cấu hình proxy.

4. Cấu hình Nginx reverse proxy và WebSocket

Uptime Kuma dùng WebSocket, vì vậy proxy phải chuyển các header nâng cấp kết nối:

server {
    listen 80;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300;
    }
}

sudo nginx -t
sudo systemctl reload nginx

Tạo record DNS cho subdomain trỏ về VPS, sau đó cấp chứng chỉ bằng Certbot hoặc công cụ quản lý TLS phù hợp. Chỉ mở trang quản trị qua HTTPS. Nếu đặt sau Cloudflare hay proxy khác, xác nhận WebSocket được bật và kiểm tra IP nguồn trong log.

5. Khởi tạo tài khoản quản trị an toàn

Mở https://status.example.com, tạo tài khoản quản trị với mật khẩu dài và duy nhất. Bật xác thực hai bước nếu phiên bản đang dùng hỗ trợ, lưu recovery code ngoài server và không chia sẻ chung tài khoản.

Trang quản trị chứa URL nội bộ, token, webhook và lịch sử sự cố. Nếu không cần truy cập công khai, hãy hạn chế bằng VPN, allowlist IP hoặc lớp xác thực bổ sung. Status page công khai nên tách khỏi quyền quản trị.

6. Tạo monitor website đúng cách

Với website, monitor HTTPS tới một endpoint nhẹ nhưng kiểm tra được dependency quan trọng. Trang chủ có thể trả 200 từ cache ngay cả khi database hỏng. Một health endpoint tốt nên phản ánh khả năng phục vụ thật nhưng không tiết lộ secret.

URL: dùng HTTPS và hostname thật.
Interval: thường 60 giây là đủ; kiểm tra quá dày gây tải và nhiễu.
Retries: 2–3 lần giúp tránh cảnh báo vì packet loss thoáng qua.
Timeout: thấp hơn interval và phù hợp SLA.
Accepted status: chỉ chấp nhận code phản ánh thành công thực sự.
Certificate expiry: bật cảnh báo sớm để có thời gian sửa renewal.

Đừng tự động coi mọi redirect là thành công. Redirect loop hoặc chuyển sang trang đăng nhập có thể che giấu lỗi endpoint.

7. Giám sát API bằng nội dung phản hồi

Một API có thể trả HTTP 200 nhưng body chứa lỗi. Dùng keyword hoặc JSON query để kiểm tra tín hiệu nghiệp vụ ổn định, ví dụ trường status bằng ok.

GET https://api.example.com/health

{
  "status": "ok",
  "database": "ok"
}

Health endpoint không nên gọi dịch vụ đắt tiền mỗi phút hoặc trả thông tin phiên bản, stack trace và credential. Nếu cần header xác thực, dùng token chỉ đọc, phạm vi tối thiểu và có kế hoạch rotation.

8. Monitor cron và backup bằng Push

Với job chạy theo lịch, monitor Push hữu ích hơn ping máy chủ. Job gọi URL được cấp sau khi hoàn thành thành công:

#!/usr/bin/env sh
set -eu

/usr/local/bin/run-backup
curl --fail --retry 3 \
  "https://status.example.com/api/push/REDACTED?status=up&msg=OK"

Đặt expected interval và grace period lớn hơn thời gian chạy thông thường. URL push là secret: không ghi vào log công khai, ảnh chụp hoặc repository. Chỉ gửi tín hiệu thành công sau khi đã kiểm tra backup thực sự hoàn tất.

9. Cấu hình cảnh báo có khả năng hành động

Tạo notification channel rồi dùng nút test trước khi gắn vào monitor. Nên có ít nhất một kênh không phụ thuộc hạ tầng đang được giám sát. Ví dụ, nếu giám sát mail server nội bộ thì đừng chỉ gửi cảnh báo qua chính mail server đó.

Giảm alert fatigue bằng cách:

Retry trước khi chuyển trạng thái DOWN.
Đặt maintenance window cho thời gian triển khai có kế hoạch.
Phân nhóm theo production, staging, internal và mức độ quan trọng.
Chỉ đánh thức người trực với dịch vụ có runbook và tác động rõ.
Kiểm thử cảnh báo DOWN và RECOVERY định kỳ.

10. Tạo status page

Status page nên trình bày dịch vụ theo ngôn ngữ người dùng hiểu, chẳng hạn Website, API, Thanh toán, Email, thay vì hostname nội bộ. Chỉ công khai monitor phù hợp; đừng để lộ IP, tên server hoặc endpoint quản trị.

Trạng thái tự động không thay thế cập nhật sự cố. Khi có incident, đăng thông báo ngắn về phạm vi ảnh hưởng, thời điểm bắt đầu và lần cập nhật tiếp theo. Không suy đoán nguyên nhân khi chưa xác minh.

11. Backup dữ liệu Uptime Kuma

Backup thư mục được mount vào /app/data. Để có bản sao nhất quán, dừng container ngắn trước khi sao chép:

cd /opt/uptime-kuma
docker compose stop uptime-kuma
tar -czf /srv/backups/uptime-kuma-$(date +%F).tar.gz data
docker compose start uptime-kuma

Chuyển backup sang máy khác, mã hóa và áp dụng retention. Định kỳ restore vào máy thử nghiệm để xác nhận file dùng được. Backup giám sát cũng chứa cấu hình notification và token, nên cần bảo vệ như secret.

12. Cập nhật có rollback

Đọc release note, đặc biệt khi đổi major version. Tạo backup trước mỗi lần cập nhật:

cd /opt/uptime-kuma
docker compose pull
docker compose up -d
docker compose logs --tail=100 uptime-kuma

Kiểm tra login, monitor, notification và status page sau cập nhật. Tránh dùng tag không cố định trong môi trường cần thay đổi có kiểm soát; có thể pin phiên bản đã kiểm thử rồi nâng theo lịch. Nếu phải rollback image, xác nhận database/data format vẫn tương thích với phiên bản cũ.

13. Các lỗi thường gặp

Dashboard mất kết nối: reverse proxy thiếu header WebSocket hoặc timeout quá ngắn.
Monitor báo DOWN nhưng trình duyệt mở được: kiểm tra DNS, firewall và route từ bên trong container, không phải từ laptop.
Chỉ lỗi IPv6: Docker network chưa bật IPv6 hoặc DNS trả AAAA không dùng được.
SSL sắp hết hạn dù đã renew: proxy/CDN vẫn phục vụ certificate cũ hoặc monitor đi qua endpoint khác.
Không có cảnh báo: channel chưa được test, token hết hạn hoặc monitor chưa gắn notification.
Mất cấu hình sau khi tạo lại container: volume chưa mount đúng vào /app/data.

Checklist production

Đặt Uptime Kuma ngoài hạ tầng chính cần giám sát.
Bind cổng ứng dụng vào localhost và dùng HTTPS reverse proxy.
Bảo vệ admin bằng mật khẩu mạnh, 2FA, VPN hoặc allowlist phù hợp.
Dùng retry, timeout và interval theo SLA để giảm false positive.
Test cảnh báo bằng một sự cố có kiểm soát.
Backup /app/data ra hệ thống khác và thử restore.
Đọc release note, pin phiên bản đã kiểm thử và chuẩn bị rollback.
Giám sát chính Uptime Kuma từ một dịch vụ độc lập nếu uptime là quan trọng.

Kết luận

Uptime Kuma giúp xây dựng lớp giám sát bên ngoài gọn nhẹ cho website, API, SSL và job định kỳ. Giá trị không chỉ nằm ở dashboard xanh, mà ở việc điểm giám sát độc lập, cảnh báo đến đúng người, có runbook xử lý và bản thân hệ thống giám sát cũng được backup, cập nhật và kiểm thử như một dịch vụ production.