Posted inHomeLab

Cài đặt và Cấu hình Uptime Kuma trên Docker: Status Page Thời gian thực và Cảnh báo Đa kênh cho HomeLab

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

Vấn đề Sự cố Thầm lặng trong Hệ thống Self-Hosted

Sáu tháng trước, phiên bản Nextcloud self-hosted của tôi bị sập vào một chiều thứ Sáu khi tôi đang vắng nhà. Chẳng ai nhận ra cả. Mười tiếng trôi qua cho đến khi có người cố đồng bộ thư mục khách hàng rồi gặp lỗi. Một đợt cập nhật gói hệ điều hành định kỳ đã âm thầm làm treo container MariaDB. Trong khi đó, Nginx vẫn thản nhiên trả về các trang 502 Bad Gateway trống rỗng.

Các sự cố thầm lặng (silent failure) luôn là nỗi ám ảnh của bất kỳ ai chơi homelab khi vận hành hàng chục container trên các mini-PC và hypervisor. Những dashboard như Homer hay Dashy chỉ đóng vai trò đánh dấu ứng dụng đẹp mắt. Chúng sẽ không báo cho bạn biết khi nào cơ sở dữ liệu bị deadlock, worker nội bộ bị crash, hay chứng chỉ SSL hết hạn vào thứ Ba tới. Các công cụ giám sát đám mây như Better Stack hay UptimeRobot hoạt động rất tốt với tên miền công khai, nhưng chúng không thể tiếp cận các subnet nội bộ như 192.168.1.50:8080 nếu không mở các cổng phức tạp trên tường lửa.

Tôi cần một “chó canh cổng” (watchdog) nội bộ. Nó phải nằm ngay trong mạng LAN, kiểm tra các dịch vụ trọng yếu mỗi 60 giây một lần và gửi thông báo về điện thoại trước khi người dùng kịp phàn nàn.

Khái niệm Cốt lõi: Uptime Kuma Hoạt động Như thế nào

Uptime Kuma là công cụ giám sát mã nguồn mở được xây dựng trên nền tảng Node.js và Vue 3. Các hệ thống observability cấp doanh nghiệp như Prometheus và Grafana đòi hỏi dung lượng lưu trữ riêng biệt và tiêu tốn lượng CPU đáng kể. Ngược lại, Kuma chỉ tiêu thụ khoảng 130MB đến 180MB RAM. Nó mang lại khả năng cập nhật dashboard theo thời gian thực dưới một giây qua WebSockets một cách mượt mà ngay cả trên một chiếc Intel NUC cũ kỹ hay Raspberry Pi 4.

Các loại Monitor và Chiến lược Thăm dò (Probing)

Lệnh ping ICMP chỉ cho bạn biết liệu hệ điều hành có phản hồi hay không, chứ không khẳng định được ứng dụng có đang chạy bình thường. Uptime Kuma hỗ trợ các phương pháp thăm dò có chủ đích, được thiết kế cho các môi trường homelab thực tế:

  • Kiểm tra Từ khóa HTTP(s): Xác thực mã phản hồi như 200 OK và quét nội dung HTML để tìm một chuỗi cụ thể (chẳng hạn như Nextcloud hoặc Dashboard). Việc này xác nhận web server đã render ứng dụng thực sự thay vì trả về một trang trắng tinh hoặc lỗi reverse-proxy.
  • TCP Port và Ping: Theo dõi các cổng hypervisor, switch mạng và các socket cơ sở dữ liệu thô như PostgreSQL trên cổng 5432 hoặc Redis trên cổng 6379.
  • Giám sát Truy vấn DNS: Gửi truy vấn tới các resolver nội bộ như Pi-hole hoặc AdGuard Home. Tính năng này sẽ gắn cờ khi phân giải tên miền thất bại hoặc độ trễ phản hồi vượt quá 150ms.
  • Theo dõi Hạn dùng TLS/SSL: Tự động phân tích thời hạn chứng chỉ. Hệ thống sẽ phát cảnh báo trước 14 ngày phòng trường hợp quá trình tự động gia hạn của Let’s Encrypt bị lỗi mà bạn không hay biết.
  • Push Monitor (Heartbeat): Đóng vai trò như một cơ chế ngắt tự động (dead-man’s switch) cho các cron job và tác vụ sao lưu. Nếu script sao lưu Borg hoặc Restic chạy hàng đêm không gửi lệnh curl tới webhook được chỉ định trong vòng 25 giờ, Kuma sẽ lập tức báo động.

Kiến trúc Thông báo Độc lập (Decoupled)

Kuma tách biệt hoàn toàn giữa logic thăm dò và việc định tuyến cảnh báo. Khi một endpoint vượt quá giới hạn số lần thử lại (retry limit), một sự kiện sẽ được kích hoạt thông qua các driver thông báo độc lập. Bạn có thể gửi cảnh báo đồng thời tới Discord, Telegram, Pushover, Gotify, Signal hoặc webhook tùy biến mà không cần chỉnh sửa cấu hình của từng monitor riêng lẻ.

Thực hành: Triển khai Uptime Kuma bằng Docker

Đóng gói Uptime Kuma bằng container giúp việc nâng cấp trở nên đơn giản và gom toàn bộ dữ liệu trạng thái vào một thư mục duy nhất. Dưới đây là cấu hình Compose chuẩn xác đang chạy trên máy chủ Ubuntu 24.04 của tôi.

Bước 1: Triển khai bằng Docker Compose

Tạo một thư mục dự án trên Docker host của bạn và mở file cấu hình mới:

mkdir -p /opt/uptime-kuma && cd /opt/uptime-kuma
nano docker-compose.yml

Dán nội dung định nghĩa triển khai sau:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: always
    volumes:
      - ./kuma-data:/app/data
    ports:
      - "3001:3001"
    security_opt:
      - no-new-privileges:true

Khởi chạy container ở chế độ chạy nền (detached mode):

docker compose up -d

Kiểm tra trạng thái container để đảm bảo nó đã khởi động bình thường:

docker compose ps

Mở trình duyệt và truy cập http://<your-server-ip>:3001. Trình hướng dẫn thiết lập ban đầu sẽ yêu cầu bạn tạo tên đăng nhập và mật khẩu quản trị viên (admin). Gửi biểu mẫu để vào bảng điều khiển chính.

Bước 2: Cấu hình Monitor với Tính năng Xác thực Chuyên sâu

Đừng chỉ dựa vào mỗi mã trạng thái HTTP thông thường. Một reverse proxy nội bộ như Traefik hay Caddy vẫn có thể trả về 200 OK ngay cả khi container ứng dụng phía sau đã chết hoàn toàn. Hãy sử dụng cơ chế xác thực từ khóa thay thế.

Nhấp vào Add New Monitor trên thanh điều hướng và nhập các thiết lập sau:

  • Monitor Type: HTTP(s) – Keyword
  • Friendly Name: Nextcloud Core
  • URL: https://cloud.local.internal/login
  • Heartbeat Interval: 60 giây
  • Retries: 2 (chờ 2 lần kiểm tra thất bại liên tiếp trước khi gửi cảnh báo để lọc bớt những đợt gián đoạn Wi-Fi ngắn)
  • Keyword: Nextcloud
  • Certificate Expiry Notification: Bật (cảnh báo khi thời hạn chứng chỉ còn dưới 14 ngày)

Nhấn Save. Kuma sẽ bắt đầu lần thăm dò đầu tiên ngay lập tức, cập nhật biểu đồ độ trễ phản hồi và chuyển huy hiệu trạng thái sang màu xanh lục.

Bước 3: Cấu hình Cảnh báo Sự cố qua Discord và Telegram

Một hệ thống giám sát sẽ trở nên vô dụng nếu không gửi cảnh báo theo thời gian thực. Hãy định tuyến các sự cố nghiêm trọng trực tiếp đến các nền tảng chat mà bạn theo dõi hàng ngày.

Đi tới mục Settings > Notifications > Setup Notification.

Tùy chọn A: Cảnh báo qua Telegram Bot

  1. Mở Telegram, bắt đầu trò chuyện với @BotFather và chạy lệnh /newbot để tạo token cho bot của bạn.
  2. Tạo một kênh (channel) hoặc nhóm quản trị, thêm bot vừa tạo vào làm thành viên và gửi một tin nhắn thử nghiệm.
  3. Lấy mã Chat ID dạng số bằng bot @userinfobot hoặc bằng cách gửi lệnh curl tới https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates.
  4. Trên giao diện Kuma, chọn Telegram, nhập token và Chat ID của bạn, rồi nhấn Test. Điện thoại của bạn sẽ rung chuông chỉ trong vòng hai giây.

Tùy chọn B: Tích hợp Discord Webhook

  1. Trong máy chủ Discord của bạn, truy cập Server Settings > Integrations > Webhooks.
  2. Nhấn New Webhook, chọn kênh nhận cảnh báo mục tiêu (ví dụ: #homelab-alerts) và sao chép Webhook URL vừa được tạo.
  3. Trong Kuma, chọn Discord từ danh sách thông báo, dán URL vào và lưu lại.

Bật tùy chọn Default enabled on all existing monitors để các probe được tạo trong tương lai tự động kế thừa các kênh thông báo này.

Bước 4: Xuất bản Status Page Trực quan

Giúp các thành viên trong gia đình và người dùng trong nhà nắm bắt tình trạng dịch vụ mà không cần cấp toàn quyền quản trị dashboard hạ tầng cho họ. Kuma tích hợp sẵn một công cụ tạo status page độc lập và rất gọn gàng.

  1. Nhấn vào Status Pages ở menu trên cùng và chọn New Status Page.
  2. Đặt một URL slug ngắn gọn như services (thao tác này sẽ tạo đường dẫn /status/services).
  3. Đặt tiêu đề, tải lên logo tùy chỉnh và tạo các nhóm dịch vụ như Media Stack (Plex, Jellyfin), Network Core (Pi-hole, Router) và Storage (TrueNAS, Nextcloud).
  4. Thêm mô tả và ghim thông báo bảo trì theo lịch trình bất cứ khi nào bạn có kế hoạch nâng cấp kernel máy chủ hoặc thay thế ổ cứng vật lý.

Bài học Sau 6 Tháng Vận hành Thực tế trong Homelab

Hiện tại, instance Kuma của tôi đang tích cực theo dõi 34 endpoint. Cơ sở dữ liệu SQLite của nó (./kuma-data/kuma.db) chỉ duy trì quanh mức 110MB với chu kỳ lưu trữ (retention window) tiêu chuẩn là 90 ngày. Mức tải CPU trên chip Intel Celeron N5105 luôn ở mức dưới 0.5%.

Một vài kinh nghiệm tinh chỉnh đắt giá rất đáng để bạn áp dụng:

  • Bỏ chu kỳ thăm dò 5 giây: Việc kiểm tra quá dồn dập rất dễ gây báo động giả khi Docker thu dọn tài nguyên (garbage collection) hoặc khi hệ thống đang snapshot sao lưu nặng. Khoảng thời gian 60 giây cùng 2 lần thử lại sẽ loại bỏ hoàn toàn các cảnh báo rác, trong khi vẫn phát hiện sự cố thực sự chỉ trong vòng 3 phút.
  • Tự động hóa sao lưu cơ sở dữ liệu: Mọi thứ Kuma lưu trữ—bao gồm thông tin đăng nhập, lịch sử thăm dò và cấu hình trạng thái—đều nằm trong file kuma.db. Hãy thiết lập một tác vụ rsync hoặc Borg chạy hàng đêm cho thư mục ./kuma-data.
  • Tách biệt việc kiểm tra uptime với đo đạc tài nguyên host: Hãy dùng Kuma thuần túy cho mục đích phát hiện trạng thái (“Dịch vụ này có đang phản hồi không?”). Còn các chỉ số về mức tiêu thụ bộ nhớ, xung đột CPU và biểu đồ IOPS, hãy để Prometheus, Netdata hoặc Grafana xử lý.

Dành ra 30 phút để cấu hình Docker Compose và webhook cảnh báo sẽ giúp bạn tiết kiệm hàng giờ gỡ lỗi sau này. Bạn sẽ phát hiện container bị sập ngay tức thì, chứ không phải đợi đến bữa ăn tối khi có ai đó phàn nàn.

Share:
Tags: