Uptime Kuma Cluster
把單機版 Uptime Kuma 升級成高可用叢集 — 智慧負載平衡、自動 Failover、健康檢查，一行 Docker Compose 就能啟動。
核心功能
為了在大規模監控下維持高可用而生的設計
智慧負載平衡
OpenResty + Lua 兩階段路由，依各節點目前的監控數量與狀態，動態把新監控分配到最閒的節點。
自動故障移轉
節點掛掉時自動把它的監控重新分配到健康節點；節點恢復後再還原，過程不中斷。
健康檢查
週期性檢查每個節點的 /api/v1/health 端點，連續失敗即判定故障並觸發移轉（預設 30 秒）。
共享資料庫
以 MariaDB 取代本機 SQLite 作為共享狀態，支援多節點同時讀寫。
水平擴展
可動態增減 Uptime Kuma 節點，監控規模成長時加機器即可，不必砍掉重練。
RESTful API
補上原生版沒有的 /api/v1 REST API：監控、節點、狀態頁與群組都能用 HTTP 增刪改查，另有 /lb 叢集維運端點。
固定節點除錯
用 cookie 把流量釘到指定節點方便除錯；該節點離線時自動解除釘選。
Docker 一鍵啟動
docker-compose-cluster.yaml 一行指令拉起 OpenResty、多個節點與 MariaDB。
原生版 vs 叢集版
本專案相對於原生 Uptime Kuma 補強了什麼
| 項目 | 原生 Uptime Kuma | 本專案（Cluster） |
|---|---|---|
| 架構 | 單機 | 多節點 HA 叢集 |
| 資料庫 | SQLite（本機） | MariaDB（共享） |
| 負載平衡 | 無 | OpenResty + Lua 智慧路由 |
| 故障處理 | 服務中斷 | 自動重新分配監控 |
| 水平擴展 | 不支援 | 可動態增減節點 |
| 健康檢查 | 無 | 週期性端點檢查 |
| 叢集管理 API | 無 | /lb 端點查狀態、觸發檢查與重新分配 |
| RESTful API | 無（監控增刪改只能透過網頁的 Socket.IO） | /api/v1 增刪改查＋Swagger 文件 |
叢集管理 API
全部以 /lb 為前綴，方便自動化監控與管理
/lb/ping存活檢查
/lb/health叢集健康狀態
/lb/system-status完整系統狀態報告
/lb/available-nodes列出可用節點與負載指標
/lb/fixed-node/{node}把流量釘到指定節點
/lb/trigger-health-check手動觸發一次健康掃描
/lb/trigger-rebalancing強制重新分配監控
/lb/rebalancing-status查看重新分配進度
RESTful API（/api/v1）
原生 Uptime Kuma 只能在網頁上管理監控；這組 API 讓 CI/CD、腳本或內部系統用一般 HTTP 請求與 JSON 管理整個叢集。
/api/v1/monitors列出所有監控
/api/v1/monitors新增監控；未指定 node_id 時自動分配到監控數最少的線上節點
/api/v1/monitors/{id}查詢單一監控
/api/v1/monitors/{id}修改監控設定
/api/v1/monitors/{id}刪除監控
/api/v1/monitors/{id}/heartbeats取回指定時段的心跳紀錄
/api/v1/nodes列出叢集節點（另有 POST／PUT／DELETE 管理節點）
/api/v1/nodes/{id}/monitors查看某個節點負責哪些監控
/api/v1/status-pages列出狀態頁（另有 POST／PUT／DELETE，以 slug 管理）
/api/v1/groups建立監控群組（另有 GET／PUT /api/v1/groups/{id}）
/api/v1/notifications列出通知設定
/api/v1/health節點存活檢查（免登入、不限流）
- 認證：請求帶 Authorization: Bearer <JWT>，伺服器會驗證 token 並確認帳號仍為啟用狀態；/api/v1/status 與 /api/v1/health 免登入。
- 限流：預設每個 IP 每 15 分鐘 100 次，超過回 429；可用環境變數 API_RATE_LIMIT 調整。
- 容量：每個節點最多 1,000 個啟用中的監控，全部節點都滿時 API 會直接回錯誤，不會硬塞。
- 回應格式統一為 { ok, msg, data }，欄位驗證失敗會在 errors 列出原因。
- 文件：/api-docs 是 Swagger UI，可在瀏覽器直接試打；/api-docs.json 是 OpenAPI 3.0 規格，可用來產生用戶端程式。
範例：用 curl 新增一個 HTTP 監控
curl -X POST http://localhost:8084/api/v1/monitors \
-H "Authorization: Bearer $UPTIME_KUMA_JWT" \
-H "Content-Type: application/json" \
-d '{"name":"Website","type":"http","url":"https://example.com","interval":60}'
# 201 => {"ok":true,"msg":"Monitor created successfully","data":{"monitor_id":42,"node_id":"node2"}}快速啟動
- 1
git clone https://github.com/markku636/uptime-kuma-cluster 並進入專案目錄。
- 2
執行下方 Docker Compose 指令，一次拉起 OpenResty、三個 Uptime Kuma 節點與 MariaDB。
- 3
用 curl http://localhost:8084/lb/health 與 /lb/available-nodes 確認叢集正常運作。
需要 Docker 與 Docker Compose；節點數、健康檢查間隔等皆可在環境變數調整。