解決的問題
監控工具本身若只有單一節點，也可能成為可用性的瓶頸：那台機器一停，所有網站的監控跟著中斷，偏偏這時最需要知道服務是否正常。原生 Uptime Kuma 用本機 SQLite 存資料，無法多台同時運作；新增或修改監控也只能透過網頁介面背後的 Socket.IO，沒有一般 HTTP API 可以讓 CI/CD 或其他系統直接串接。
實作方向
- 01保留 Uptime Kuma 的監控能力，把資料庫換成共享的 MariaDB，讓多個節點讀寫同一份監控設定。
- 02前面放 OpenResty（Nginx + Lua）做負載平衡，定期檢查各節點，節點故障時把它負責的監控移到健康節點，恢復後再還原。
- 03補上一組 RESTful API（/api/v1），監控、節點、狀態頁與群組都能用 HTTP 查詢與增刪改，並附 Swagger 文件（細節見下方）。
- 04透過 Docker Compose 一次啟動 OpenResty、三個 Uptime Kuma 節點與 MariaDB。
RESTful API 能做什麼
原生 Uptime Kuma 的監控管理只能在網頁上操作，要大量建立監控或接進部署流程很不方便。這個專案在每個節點加上 /api/v1 路由，用一般的 HTTP 請求與 JSON 就能管理整個叢集。
- 監控：GET /api/v1/monitors 列出全部、GET /api/v1/monitors/{id} 查單一監控，POST 新增、PUT 修改、DELETE 刪除；GET /api/v1/monitors/{id}/heartbeats 取回指定時段的心跳紀錄。
- 新增監控時自動分配節點：沒有指定 node_id，API 會挑目前線上且監控數最少的節點；也可以指定節點，每個節點上限 1,000 個啟用中的監控，滿了會回錯誤請你換一台。
- 節點：/api/v1/nodes 可查詢、新增、修改與移除叢集節點，GET /api/v1/nodes/{id}/monitors 查看某個節點正在負責哪些監控。
- 狀態頁與群組：/api/v1/status-pages 以 slug 管理公開狀態頁，/api/v1/groups 建立與調整監控群組，對外公告與分組都不必回到網頁介面。
- 叢集維運：/lb 開頭的端點由 OpenResty 提供，可查叢集健康、各節點負載、手動觸發健康檢查或重新分配監控；GET /api/v1/health 給負載平衡器做存活檢查。
認證、限流與文件
- 認證：請求帶 Authorization: Bearer <JWT>，伺服器會驗證 token 並確認帳號仍為啟用狀態；GET /api/v1/status 與 /api/v1/health 不需登入。
- 限流：/api/v1 預設每個 IP 每 15 分鐘 100 次請求，超過回 429，可用環境變數 API_RATE_LIMIT 調整；健康檢查端點不受限制。
- 回應格式統一為 { ok, msg, data }，欄位驗證失敗會在 errors 列出原因，方便程式判斷。
- 文件：/api-docs 提供 Swagger UI 可直接在瀏覽器試打，/api-docs.json 是 OpenAPI 3.0 規格，可拿去產生用戶端程式。
- 常見用法：部署新服務時由 CI 呼叫 POST /api/v1/monitors 自動加上監控、下線時刪除；或由內部系統定期讀取心跳資料做報表。