--- title: "使用 Vibe Coding 打造 Uptime Kuma 集群系統：從單機到高可用監控平台" description: "用 Vibe Coding 方法，手把手帶你把 Uptime Kuma 從單機版升級成支援集群的高可用監控系統，包含 Docker Compose、負載平衡、資料庫共享到 Failover 全攻略。" canonical_url: "https://blog.markkulab.net/post/implement-uptime-kuma-cluster-vibe-coding" author: "Mark Ku" author_url: "https://blog.markkulab.net/author/mark-ku" site: "Mark Ku's Blog" date_published: "2025-08-19 02:30:00 +0800" category: "DevOps" tags: ["uptime kuma", "cluster", "vibe coding", "docker", "mariadb", "load balancer", "monitoring", "high availability", "openresty"] language: "zh-TW" license: "CC BY 4.0" license_url: "https://creativecommons.org/licenses/by/4.0/" attribution: "轉載或引用請註明作者並附上原文連結" --- # 使用 Vibe Coding 打造 Uptime Kuma 集群系統：從單機到高可用監控平台 ## 前言 Uptime Kuma 是一個開源監控軟體，本來就很好用，但如果你要監控超過 1000 個以上的 API，單個實體運行，其實會開始卡卡的。這篇我想用 **Vibe Coding** 的方式，帶大家一步步把 Uptime Kuma 升級成支援 **分片 (Sharding)** 跟 **Cluster** 的版本，還會加上 API 讓它更方便自動化。 ## 為什麼要搞叢集(Cluster)？ 先講需求。 Uptime Kuma 是開源監控軟體，[之前我已經分享過怎麼改成用 MariaDB 當後端](https://blog.markkulab.net/uptime-kuma-mariadb-restful-api/)。我們將預設的 SQLite 替換為 MariaDB，並獨立部署為 `kuma-mariadb` 服務，以支援更高的併發讀寫。 然而，當監控規模超過 1000 個 API 之後，效能就會明顯下降，實際測試下來數量一多就開始卡頓。Uptime Kuma 本身是 Node.js 應用，而 Node.js 是單執行緒架構，遇到大量並行任務時天生就有效能瓶頸，這也讓我順便研究了一下 [Node.js 單執行緒效能問題的幾種實戰解法](https://blog.markkulab.net/post/nodejs-worker-threads-bun-performance)。 再加上我們部門系統的需求有將近 4000 支 API，單個 Uptime Kuma 肯定不夠了。 對需要依據服務水準 (SLA) 付費的服務來說，一旦監控斷掉，就可能直接被判定為違約賠錢，因此監控平台本身也必須保持高可用。 另外，開源的 Uptime Kuma 不支援 RESTful API，對於需要實現「API 自動化上架即監控」的場景來說非常不方便。為了減少額外容器的部署成本，我們自行擴充了 RESTful API 功能，直接整合到 Uptime Kuma 中。 基於以上這些需求與限制，我們自然就要往 **Cluster 架構** 走，確保： * **容錯 / 自動移轉**：節點掛掉也能自動切換，不怕中斷 * **負載分散**：多台一起跑，效能更穩 * **高可用**：避免單點失效，數據透明可靠 * **自動化**：能用 API 自動建監控，方便 DevOps ## 拆解需求，整理思路，請用 Vibe Coding 規劃及實作 用 Vibe Coding 的精神，把需求拆細，然後一段一段做，通常較大複雜的專案，會請AI 撰寫計劃或規範指引，在不斷覆盤 AI 寫的計畫，最後在請AI 執行 ### 1. 分片 (Sharding) 支援 不同的監控器要分散到不同節點去跑： * 可以新增 / 修改 / 刪除節點 * 清楚標示每個監控器是跑在哪個節點 * 容器啟動時會自動註冊節點到資料庫 ### 2. 健康檢查 (Health Check) 用 **Nginx / OpenResty + Lua (`health_check.lua`)** 做節點健康檢查： #### Nginx Job 機制 OpenResty 提供了強大的定時任務機制，可以輕鬆利用 **`ngx.timer.at()`** 來實作週期性的健康檢查： * **`init_worker_by_lua_block`**：在每個 worker 進程啟動時執行，初始化健康檢查的定時器 * **`ngx.timer.at(delay, callback)`**：創建一個一次性定時器，在指定延遲後執行回調函數 * **遞迴定時器**：在 `health_check_worker` 回調函數中，執行完健康檢查後再次調用 `ngx.timer.at()`，形成週期性循環 * **避免重複執行**：使用 `ngx.shared.DICT` 或標記變數確保每個 worker 只啟動一個健康檢查任務 這樣的設計讓健康檢查完全在 Nginx worker 內部運行，不需要額外的外部進程或 cron job，既高效又可靠。 #### 健康檢查流程 * 由 OpenResty 的 worker 週期性呼叫 `health_check_worker`，固定間隔執行 `run_health_check` * 針對每個節點呼叫 `/api/v1/health` 進行 HTTP 健康檢查 * 連續多次失敗 → 將該節點在 DB `node` 表中的狀態改成 `offline` * 連續多次成功 → 將 `node.status` 更新回 `online`，並啟動「監控還原」流程 ### 3. 容錯移轉 (Failover) 節點掛了，監控任務要自動轉移，這一塊由 `health_check.lua` 搭配資料庫完成： * 在 DB 加上專門的 `node` 表與與節點相關欄位，紀錄每個節點的 `status`、`last_seen` * 監控資料表 `monitor` 會記錄每個監控目前的 `node_id`（以及必要時的 `assigned_node`） * 當某個節點連續數次健康檢查失敗： * health_check 會把該節點標記為 `offline` * 呼叫 `redistribute_monitors_from_node(node_id)`，把原本由這個節點負責的監控平均分配到其他 `online` 節點上 * 當節點恢復健康（連續幾次檢查成功）： * health_check 會把節點標記為 `online` * 呼叫 `revert_monitors_to_node(node_id)`，把先前自動轉移出去的監控搬回原節點，避免長期失衡 ### 4. 節點復原 (Recovery) 節點恢復之後要能自動回來： * 重啟後自動註冊，狀態改 `online` * 系統會把移轉走的監控器搬回來 * 確保不會重複執行，避免資料衝突 * 也提供 **手動復原**，讓管理員自己決定要不要搬回去 ### 5.Restful API 擴充 自動化擴充 (RESTful API Extension)：由於原生的 Uptime Kuma 缺乏對外的 API 介面，為了實現「服務一上線即監控」的自動化目標，我們自行擴充了 RESTful API 功能，讓日後上架API 時，自動監控。 Uptime Kuma 其實內建不少邏輯，只是沒開放 API，都是透過Web socket 去調用，既然知道這些，我們可以請AI把 Service 暴露成 API，讓自動化更方便。 ### 6. OpenResty 統一入口與負載平衡 為了讓外部只面對單一入口、內部由多個 Kuma 節點分擔流量，我們以 OpenResty 作為統一代理與路由層。此入口會依節點的健康與負載狀態動態選擇目標節點，同時承載即時通訊、API 與靜態內容的代理。當某節點故障時自動避讓、恢復後回流，確保整體具備擴展性與容錯能力。 ### 7. 手動切換節點 (Manual Node Switching) 在自動負載平衡與 Failover 之上，再提供一組「手動切換節點」能力：管理員可以把單一或多個監控任務切到指定節點、在維護前先排空某個節點，或暫時把整體流量鎖定／固定到特定節點（含透過 Cookie 固定節點），並且這些手動操作會與現有的健康檢查與自動遷移機制協同運作，不會互相打架。 ## 系統架構圖 ``` 系統架構圖 ┌────────────────────────────┐ │ OpenResty (Nginx + Lua) │ │ ─ 負載平衡 (monitor_router) │ │ ─ 健康檢查 (health_check) │ └─────────┬──────────────────┘ │ ┌──────────────────┼────────────────────┐ │ │ │ ┌───────────▼─────────┐ ┌─────▼────────────┐ ┌─────▼────────────┐ │ Uptime Kuma │ │ Uptime Kuma │ │ Uptime Kuma │ │ Node 1 │ │ Node 2 │ │ Node 3 │ │ (Port 3001) │ │ (Port 3001) │ │ (Port 3001) │ │ (Host: 9091) │ │ (Host: 9092) │ │ (Host: 9093) │ └─────────┬───────────┘ └─────┬────────────┘ └──────┬───────────┘ │ │ │ └───────────────────┼─────────────────────┘ │ ┌─────────▼─────────┐ │ MariaDB │ │ (Port 3306) │ │ (Host: 9090) │ └───────────────────┘ ``` 這裡有幾個重點元件： - **OpenResty / Nginx**：只在 `nginx.conf` 裡定義一個虛擬的 `upstream uptime_kuma_cluster`，實際的節點選擇交給 Lua。 - **`monitor_router.lua`**：在 `balancer_by_lua_block` 中被呼叫，提供 `pick_node_for_request()`，依據每個節點目前「正在執行的監控數量」動態挑選最空閒的節點，並透過 `ngx.balancer.set_current_peer()` 導流到對應的 `uptime-kuma-nodeX` 容器。 - **`health_check.lua`**：定期掃描各節點健康狀態，更新 DB `node` 表，並在節點故障/恢復時觸發監控任務的自動移轉與還原。 ## 流程圖 ### 1. 負載平衡與路由流程（monitor_router.lua） ``` 請求流程 Client Request │ ▼ Nginx / OpenResty (location /, /api/, /socket.io/ → proxy_pass 到 uptime_kuma_cluster) │ ▼ balancer_by_lua_block 呼叫 monitor_router.pick_node_for_request() │ ▼ 查詢 DB： SELECT n.node_id, COUNT(m.id) AS monitor_count FROM node n LEFT JOIN monitor m ON m.node_id = n.node_id AND m.active = 1 WHERE n.status = 'online' GROUP BY n.node_id ORDER BY monitor_count ASC, node_id ASC │ ▼ 選出監控數量最少的 online 節點 (例如 node2) │ ▼ 組合 upstream：uptime-kuma-node2:3001 │ ▼ ngx.balancer.set_current_peer("uptime-kuma-node2", 3001) │ ▼ 請求實際被轉發到對應的 Uptime Kuma 節點處理 ``` ### 2. 健康檢查與 Failover / Recovery 流程（health_check.lua） ``` 健康檢查與自動移轉流程 健康檢查 worker 週期性執行 run_health_check() │ ▼ 查詢 DB 取得所有節點 (node 表) │ ▼ 逐一對每個節點呼叫 /api/v1/health │ ├── 健康：更新 node.status = 'online'，重置失敗次數；連續多次成功時觸發 revert_monitors_to_node(node_id) │ └── 失敗：累積失敗次數；達到門檻時將 node.status = 'offline'，並觸發 redistribute_monitors_from_node(node_id)，把監控平均分配到其他 online 節點 │ ▼ 健康狀態與統計資訊寫入 DB + ngx.shared.health_checker │ ▼ 透過 /health、/api/health-status、/lb/health、/lb/capacity 等 API 對外暴露目前整體狀態 ``` ## 成果展示 ![Uptime Kuma 監控儀表板顯示服務狀態與統計資訊](https://blog.markkulab.net/content/markku/posts/implement-uptime-kuma-cluster-vibe-coding/images/螢幕截圖1.jpg) ![Uptime Kuma 節點設定介面顯示三個線上節點](https://blog.markkulab.net/content/markku/posts/implement-uptime-kuma-cluster-vibe-coding/images/螢幕截圖2.jpg) ![Uptime Kuma API 的 Swagger UI 介面，展示健康與監控端](https://blog.markkulab.net/content/markku/posts/implement-uptime-kuma-cluster-vibe-coding/images/螢幕截圖3.jpg) 最後和主管討論，因取之於社群用之於社群，所以公開相關的程式碼： [Uptime Kuma Cluster GitHub 相關程式碼](https://github.com/markku636/uptime-kuma-cluster) ## 心得 AI 時代雖然讓生產力可能提升了5~10 倍，不用再手敲程式碼，但事後維護時卻發現對程式碼的熟悉度不足。這讓我深刻體會到，無論工具如何進化，最終還是需要有人真正理解並維護這些程式碼，技術深度與理解力仍然是不可或缺的。 ## 延伸資源 * [解決 Node.js 單執行緒效能瓶頸的幾種實戰解法](https://blog.markkulab.net/post/nodejs-worker-threads-bun-performance) * [Uptime Kuma 官方文件](https://github.com/louislam/uptime-kuma) * [Docker Compose 官方文件](https://docs.docker.com/compose/) * [OpenResty 官方文件](https://openresty.org/) * [MariaDB 官方文件](https://mariadb.org/) * [Lua 程式語言](https://www.lua.org/) --- ## 關於本文與作者 本文出自 [Mark Ku's Blog](https://blog.markkulab.net/post/implement-uptime-kuma-cluster-vibe-coding) 授權條款： [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — 轉載或引用請註明作者並附上原文連結 ### 關於作者 **[Mark Ku](https://blog.markkulab.net/author/mark-ku)** — Software Solution Provider - 10+ 年資深軟體工程師，現為 AI 應用 Builder - 專注大型平台架構設計，從北美電商到AI SaaS訂閱收費系統 - 結合 AI Agent 與自動化，打造高效可演進的產品技術基礎 ### 作者開發的免費工具 以下工具皆可免費使用： - [免費 PDF 簽名工具](https://blog.markkulab.net/tools/pdf-sign): 線上 PDF 簽名工具，瀏覽器內完成手繪、打字、上傳簽名，可拖曳放置、縮放、下載。所有處理都在你的裝置完成，檔案不會上傳。 - [VS Code Refactory](https://blog.markkulab.net/tools/refactory): Refactory 是一款 VS Code 重構擴充套件：34 個重構動作、37 條 code smell 檢查、Code Health 儀表板、18 種語言、534 支測試。懂你的專案慣例：介面放哪、DI 註冊寫在哪、'use client' 該不該加；還會用 git 修改頻率 × 複雜度排出「該先修哪個檔案」，並一鍵把壞味道交給你自己電腦上的 Claude Code 修。免費使用，原始碼不離開你的機器。 - [DB-Kit 資料庫管理工具](https://blog.markkulab.net/tools/db-kit): DB-Kit 是一個用 Tauri + Rust + React 打造的輕量跨平台資料庫管理工具，用單一一致的介面同時管理 MySQL、MariaDB、PostgreSQL、SQL Server、Oracle、SQLite、MongoDB、Redis、Kafka、Elasticsearch 與 RabbitMQ 十一種資料來源：連線密碼以 OS keychain 加密、SSH Tunnel、完整 CRUD、視覺化查詢建構器、多結果集同時顯示、跨連線資料傳輸與比對同步、Excel / CSV 匯入匯出、執行計畫視覺化、ER 圖、排程備份、SQL 壓力測試（p50～p99 延遲百分位）、15 條規則的 SQL 審查、Kafka 訊息瀏覽與監控告警；繁中 / 英文雙語介面，內建 AI 助手（自然語言生成 SQL、AI 審查與調校建議）與命令列工具 dbk。免費開源（MIT），提供 Windows / macOS / Linux 安裝檔。 - [VS Code Super Mermaid](https://blog.markkulab.net/tools/super-mermaid): Super Mermaid 是一款 VS Code 擴充套件：開箱即用的漂亮 Mermaid 圖表，自動上色、即時預覽、滑鼠平移縮放、PNG / SVG 高解析匯出，內建 21 種範本與多種主題。免費開源（MIT）。 - [React Super Mermaid](https://blog.markkulab.net/tools/react-super-mermaid): react-super-mermaid 是一個開源 React 元件庫：一行 即可渲染漂亮的 Mermaid 圖表，內建 colorful / sketch 主題、平移縮放、圖內搜尋、SVG / PNG 高解析匯出。輕量、SSR 安全、完整 TypeScript 型別。免費開源（MIT）。 - [Jira / Confluence Super Mermaid](https://blog.markkulab.net/tools/jira-super-mermaid): Atlassian Forge app：在 Jira issue 與 Confluence 內文直接寫 Mermaid 語法，畫流程圖、時序圖、狀態機與甘特圖。11 種圖表、SVG / PNG 匯出、明暗主題、完整中日韓文字支援。取得 Runs on Atlassian 資格：圖表存在你自己的站台，app 不呼叫任何第三方服務。免費，即將上架 Atlassian Marketplace。 - [Mermaid 線上預覽](https://blog.markkulab.net/tools/mermaid-preview): 在瀏覽器裡寫 Mermaid、即時看圖，整張圖表壓進網址就能分享。免註冊、不上傳伺服器，相容 mermaid.live 的分享連結。 - [React Intl Phone Number](https://blog.markkulab.net/tools/react-intl-phone-number): react-intl-phone-number 是一個開源 React 元件：framework-agnostic、不依賴 antd，提供 E.164 進出、可搜尋國旗 / 國碼下拉、可配置驗證等級（strict / mobile-strict / loose）、可主題化 CSS 與 i18n，電話邏輯由 google-libphonenumber 驅動。輕量、完整 TypeScript 型別。免費開源（MIT）。 - [Uptime Kuma Cluster](https://blog.markkulab.net/tools/uptime-kuma-cluster): 把單機版 Uptime Kuma 改造成高可用叢集：OpenResty + Lua 智慧負載平衡、MariaDB 共享狀態、健康檢查與自動 Failover，附叢集管理 REST API，一行 Docker Compose 啟動。免費開源（MIT）。 - [特教專案](https://blog.markkulab.net/education): 為特殊教育學生製作的學習教材 ### 每日 Podcast - [科技新鮮事](https://blog.markkulab.net/category/tech-news): 每日精選 AI 與科技趨勢，透過語音摘要快速掌握最新技術動態，涵蓋 AI 應用、軟體架構、DevOps 與工程實戰。 — RSS: https://blog.markkulab.net/feed.xml - [AI股市蝦聊](https://blog.markkulab.net/category/ai-stock-chat): 每個交易日用 AI 分析台股盤勢，以雙人對話聊當天的盤中觀察與隔日預測。 — RSS: https://blog.markkulab.net/ai-stock-chat/feed.xml ### 電子報 [訂閱電子報](https://blog.markkulab.net/subscribe) — 第一時間收到新文章通知，無垃圾信、隨時可取消訂閱。