Kết nối Dashboard Self-Hosted với Prometheus, Uptime Kuma, Portainer

Kết nối self-hosted dashboard với Prometheus, Uptime Kuma, Portainer

Self-hosted dashboard → “trung tâm điều khiển” cho homelab/VPS/nội bộ: xem trạng thái dịch vụ, tài nguyên, uptime, container, cảnh báo. Nhưng dashboard chỉ đẹp thôi chưa đủ. Giá trị thật đến từ tích hợp dữ liệu: Prometheus cho metrics, Uptime Kuma cho trạng thái endpoint, Portainer cho container/Docker stack.

Bài này hướng dẫn cách kết nối dashboard tự host với 3 nguồn phổ biến: Prometheus, Uptime Kuma, Portainer. Mục tiêu: có một trang duy nhất để biết dịch vụ nào sống/chết, server có quá tải không, container nào lỗi, cần xử lý gì trước.

Ví dụ dashboard có thể là: Homepage, Homarr, Dashy, Grafana dashboard tự dựng, hoặc app nội bộ. Logic tích hợp tương tự: gọi API/endpoint → parse dữ liệu → hiển thị widget/card/badge.

Kiến trúc tổng quan

Mô hình thường gặp:

– Dashboard: nơi hiển thị tổng hợp. – Prometheus: thu thập metrics từ server/app/exporter. – Uptime Kuma: monitor HTTP/TCP/Ping/DNS, báo uptime. – Portainer: quản lý Docker, container, stack, image, volume. – Reverse proxy: Nginx Proxy Manager, Traefik, Caddy. – Auth: basic auth, OAuth, Authelia, Cloudflare Access, VPN.

Luồng dữ liệu:

– Dashboard → Prometheus API → CPU/RAM/disk/request metrics. – Dashboard → Uptime Kuma status/API → trạng thái dịch vụ. – Dashboard → Portainer API → container/stack status. – Dashboard → hiển thị card tổng hợp.

Khuyến nghị: dashboard không cần quyền ghi. Chỉ dùng token/API key read-only nếu có thể. Với Portainer, hạn chế quyền tối đa.

Chuẩn bị môi trường

Giả sử bạn chạy Docker Compose:

services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

uptime-kuma:
    image: louislam/uptime-kuma
    ports:
      - "3001:3001"
    volumes:
      - ./kuma:/app/data

portainer:
    image: portainer/portainer-ce
    ports:
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./portainer:/data

Nếu có reverse proxy:

– Prometheus: https://prometheus.example.com – Uptime Kuma: https://status.example.com – Portainer: https://portainer.example.com – Dashboard: https://dash.example.com

Lưu ý bảo mật: không public Prometheus/Portainer trần ra internet. Dùng VPN, IP allowlist, SSO, hoặc reverse proxy có auth.

Kết nối Prometheus với dashboard

Prometheus cung cấp HTTP API. Endpoint quan trọng:

GET /api/v1/query?query=<promql>
GET /api/v1/query_range?query=<promql>&start=&end=&step=

Ví dụ kiểm tra Prometheus hoạt động:

curl "http://localhost:9090/api/v1/query?query=up"

Kết quả thường có dạng:

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": []
  }
}

Metrics nên hiển thị

Với node_exporter, các PromQL hữu ích:

100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

100 - ((node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} * 100) / node_filesystem_size_bytes{fstype!~"tmpfs|overlay"})

up

Dashboard có thể hiển thị:

– Server A CPU: 28% – RAM: 61% – Disk: 73% – Prometheus target down: 1 – Alert active: 3

Tích hợp trong Homepage

Nếu dùng Homepage, có thể dùng widget Prometheus:

- Server Metrics:
    widget:
      type: prometheus
      url: http://prometheus:9090
      metrics:
        - label: CPU
          query: 100 - (avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
          format:
            type: percent
        - label: Memory
          query: (1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100
          format:
            type: percent

Tùy version Homepage, cú pháp có thể khác. Nguyên tắc: dashboard gọi Prometheus URL nội bộ qua Docker network → nhanh, không public.

Lưu ý khi dùng Prometheus

– Query nặng → dashboard chậm. – Dùng rate(...[5m]) thay vì range quá dài. – Không refresh quá dày. 15–60 giây đủ. – Nếu nhiều server → filter bằng instance. – Nếu dùng reverse proxy có auth → dashboard cần header/token phù hợp.

Kết nối Uptime Kuma với dashboard

Uptime Kuma mạnh ở phần monitor dịch vụ: HTTP, TCP, ping, DNS, Docker container, push monitor. Cho dashboard, có 2 cách phổ biến:

1. Dùng status page public/internal. 2. Dùng API/WebSocket hoặc integration của dashboard.

Cách dễ nhất: Status page

Tạo status page trong Uptime Kuma:

– Vào Uptime Kuma. – Status Pages → New Status Page. – Chọn monitor muốn hiển thị. – Lấy URL dạng:

https://status.example.com/status/main

Dashboard có thể nhúng link/card tới trang này. Một số dashboard hỗ trợ iframe hoặc service widget.

Ưu điểm:

– Đơn giản. – Không cần token. – Phù hợp hiển thị trạng thái public.

Nhược:

– Dữ liệu chi tiết hạn chế. – Không tùy biến sâu.

Dùng API/endpoint trạng thái

Uptime Kuma không có REST API chính thức ổn định như Prometheus. Nhiều dashboard dùng integration riêng hoặc WebSocket. Nếu dashboard hỗ trợ sẵn Uptime Kuma, cấu hình thường gồm:

widget:
  type: uptimekuma
  url: https://status.example.com
  slug: main

Hoặc:

- Uptime Kuma:
    href: https://status.example.com
    widget:
      type: uptimekuma
      url: https://status.example.com
      slug: main

Ý nghĩa:

– url: domain Uptime Kuma. – slug: status page slug. – dashboard → lấy trạng thái monitor từ status page.

Nên hiển thị gì?

Dashboard nên gom trạng thái thành:

– All systems operational nếu tất cả up. – Degraded nếu có monitor warning. – Down nếu có dịch vụ lỗi. – Uptime 24h/7d/30d. – Latency trung bình. – Incident gần nhất.

Ví dụ card:

API Gateway: UP, 99.98%, 124ms
Database: UP, 100%, 3ms
Website: DOWN, 98.10%, timeout

Best practice với Uptime Kuma

– Tách monitor nội bộ/public. – Với service nội bộ, dùng agent/VPN/internal Docker network. – Đặt retry hợp lý để tránh false positive. – Bật notification: Telegram, Discord, Slack, email. – Dashboard chỉ hiển thị; alert vẫn nên để Uptime Kuma xử lý.

Kết nối Portainer với dashboard

Portainer có API mạnh, cho phép đọc environment, endpoint, container, stack. Đây là phần cần cẩn trọng nhất vì Portainer thường có quyền rất cao với Docker host.

Lấy API token Portainer

Trong Portainer:

– User menu → My account. – Access tokens → Add access token. – Copy token.

Token thường dùng với header:

X-API-Key: <token>

Test:

curl -k 
  -H "X-API-Key: YOUR_TOKEN" 
  https://portainer.example.com/api/endpoints

Lấy danh sách container theo endpoint:

curl -k 
  -H "X-API-Key: YOUR_TOKEN" 
  "https://portainer.example.com/api/endpoints/1/docker/containers/json?all=true"

Kết quả trả về tương tự Docker API:

[
  {
    "Id": "...",
    "Names": ["/nginx"],
    "Image": "nginx:latest",
    "State": "running",
    "Status": "Up 2 hours"
  }
]

Hiển thị container status

Dashboard có thể hiển thị:

– Tổng container: 42 – Running: 39 – Exited: 2 – Restarting: 1 – Stack lỗi: 1 – Image cần update: nếu tích hợp thêm Watchtower/Dockge.

Pseudo-code:

const res = await fetch(${PORTAINER_URL}/api/endpoints/1/docker/containers/json?all=true, {
  headers: { "X-API-Key": PORTAINER_TOKEN }
});

const containers = await res.json();

const running = containers.filter(c => c.State === "running").length;
const exited = containers.filter(c => c.State === "exited").length;

Tích hợp với Homepage/Homarr

Một số dashboard có widget Portainer:

- Portainer:
    href: https://portainer.example.com
    widget:
      type: portainer
      url: https://portainer.example.com
      env: 1
      key: YOUR_TOKEN

Trong đó:

– env/endpoint: ID environment Portainer. – key: API token. – url: URL Portainer.

Không nên commit token vào Git public. Dùng secret/env file nếu dashboard hỗ trợ.

Bảo mật Portainer

Portainer → quyền cao. Sai cấu hình → attacker kiểm soát Docker host.

Khuyến nghị:

– Không expose Portainer public nếu không cần. – Bật 2FA. – Dùng HTTPS. – Dùng SSO/VPN/IP allowlist. – Token riêng cho dashboard. – Xóa token khi không dùng. – Không dùng admin token nếu chỉ cần đọc. – Backup Portainer data.

Thiết kế dashboard hữu ích

Một dashboard tốt không chỉ “nhiều widget”. Cần ưu tiên thông tin hành động được.

Layout gợi ý

– Overall health. – Số service down. – Alert active. – CPU/RAM/Disk trung bình.

– Uptime Kuma summary. – Dịch vụ critical: website, API, DB, VPN, DNS.

– Prometheus metrics. – Node/server card. – Disk sắp đầy.

– Portainer container status. – Stack đang lỗi. – Link nhanh tới logs/console.

Màu sắc rõ nghĩa

– Xanh: OK. – Vàng: degraded/warning. – Đỏ: down/critical. – Xám: unknown/paused.

Tránh dùng quá nhiều biểu đồ nếu bạn chỉ cần biết “có sự cố không”. Biểu đồ chi tiết nên để Grafana.

Đồng bộ dashboard với alerting

Dashboard không thay thế alert. Dashboard cần trả lời: “Hiện tại có gì sai?”. Alert cần trả lời: “Khi nào cần đánh thức tôi?”.

Gợi ý:

– Prometheus Alertmanager → cảnh báo metrics. – Uptime Kuma → cảnh báo endpoint down. – Portainer/Docker event → cảnh báo container restart/exited. – Dashboard → tổng hợp trạng thái.

Ví dụ rule Prometheus:

groups:
  - name: node
    rules:
      - alert: HighDiskUsage
        expr: node_filesystem_avail_bytes / node_filesystem_size_bytes < 0.1
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Disk còn dưới 10%"

Dashboard có thể đọc alert từ Alertmanager hoặc Prometheus query để hiển thị số alert active.

Troubleshooting thường gặp

Dashboard không gọi được Prometheus

Nguyên nhân:

– Sai hostname Docker network. – Prometheus bind localhost. – Reverse proxy chặn. – Auth thiếu header.

Cách kiểm tra:

docker exec -it dashboard curl http://prometheus:9090/api/v1/query?query=up

Uptime Kuma widget không hiện

Kiểm tra:

– Status page có public/internal access chưa. – Slug đúng chưa. – Dashboard hỗ trợ version Uptime Kuma hiện tại không. – CORS/proxy có chặn không.

Portainer API lỗi 401/403

Nguyên nhân:

– Token sai/hết hạn. – User không có quyền endpoint. – Sai header X-API-Key. – Sai endpoint ID.

Test lại:

curl -k -H "X-API-Key: TOKEN" https://portainer.example.com/api/endpoints

Kết luận thực tế

Self-hosted dashboard mạnh nhất khi nó gom đúng dữ liệu từ đúng nguồn. Prometheus cho metrics sâu, Uptime Kuma cho trạng thái dịch vụ dễ hiểu, Portainer cho tình trạng container/stack. Kết hợp 3 công cụ này, bạn có một màn hình vận hành gọn: biết server có quá tải không, dịch vụ nào down, container nào lỗi.

Cách triển khai tốt nhất: dùng network nội bộ cho kết nối dashboard → service, hạn chế public API, dùng token riêng, refresh vừa phải, chỉ hiển thị thông tin cần hành động. Dashboard đẹp là tốt; dashboard giúp xử lý sự cố nhanh mới thật sự đáng giá.