Uptime Kuma 架設指南:用 Docker 設定可用性監控
用 Docker 架設 Uptime Kuma v2,設定 HTTP 檢查、重試、通知和狀態頁,並在升級前備份 SQLite 儲存卷。
VPC 裡的 Uptime Kuma 顯示訂單 API 正常,客戶卻可能在對外的閘道遇到錯誤。內部的結果仍然有用,它說明哪一條路徑正常。建立監控前,先決定要從哪個網路出發、希望發現哪一種故障。
Uptime Kuma 是自行架設的可用性監控工具。 它會定期檢查服務、傳送通知,也能透過狀態頁公開選定監控項目的結果。以下在 Docker 上部署單一 Kuma v2 執行個體,並從該執行個體所在的網路測試 HTTP。
將資料保留在本機儲存卷
準備可以執行 v2 映像檔的 Docker 主機。若使用預設的 SQLite,/app/data 所在的檔案系統須支援 POSIX 檔案鎖。請使用本機儲存卷或目錄。部分 NFS 環境的檔案鎖相容性問題可能導致資料庫損毀。官方安裝說明(英文)
docker run -d --restart=unless-stopped \
-p 127.0.0.1:3001:3001 \
-v uptime-kuma:/app/data \
--name uptime-kuma \
louislam/uptime-kuma:2
更換容器時,資料會留在儲存卷。只要主機與 Docker 仍在運作,重啟策略就能在容器結束後將其重新啟動。範例把 3001 連接埠綁定至主機的回送位址。Docker Engine 28.0.0 之前的版本中,同一個第二層網路上的其他主機仍可能存取發佈至回送位址的連接埠。在 Docker 主機上開啟 http://127.0.0.1:3001 建立管理員帳號。若從另一部電腦初始化,可透過 SSH 通道。之後若要對外提供 HTTPS,請設定反向代理轉送 WebSocket 升級請求。Docker 連接埠發佈(英文) · Kuma 反向代理設定(英文)
檢查呼叫端實際需要的回應
假設訂單服務有一個唯讀的就緒檢查端點,預期回傳 HTTP 200 和 checkout-ready。用 HTTP(s) - Keyword 同時檢查這兩項條件。一般 HTTP 監控會確認請求成功並取得允許的狀態碼,Keyword 類型還會檢查回應內容是否包含指定字串。請選擇不會出現在代理伺服器錯誤頁、也不會隨發版改變的標記。
| 監控類型 | 檢查成功代表什麼 |
|---|---|
| HTTP(s) / HTTP(s) - Keyword | 回應符合設定的狀態碼條件。Keyword 類型也通過內容檢查。 |
| TCP Port | 可以建立 TCP 連線。資料庫登入或查詢是否成功須另外驗證。 |
| Ping | 目標回應這條路徑送出的 ICMP。網路政策封鎖 ICMP 時,檢查也可能失敗。 |
| DNS | 指定的解析器回應所查詢的記錄類型。 |
| Docker Container | 從指定的 Docker 主機取得容器狀態。若容器提供健康檢查,也會納入判斷。 |
Docker Container 監控需要存取設定好的 Docker 端點。連到 Docker 守護程序可能取得對主機的廣泛控制權,因此請與 HTTP 檢查分開管理並限制存取範圍。Kuma v2.5.9 監控實作 · 保護 Docker 守護程序的存取(英文)
分別驗證故障與恢復通知
先設定探測週期、請求逾時、重試次數和重試間隔。多重試幾次,能讓某些短暫故障在發通知前自行恢復,代價是較晚發現持續性故障。一般 HTTP 監控有設定重試時,失敗的檢查可能先顯示 Pending,重試耗盡後才變成 Down。
設定通知管道並送出測試訊息,再到該監控項目啟用這個管道。接著讓測試端點回傳失敗狀態或省略指定標記,等 Kuma 記錄 Down。恢復正常回應後,確認故障和恢復通知都送到預期位置。這樣除了確認通知管道可用,也能驗證從監控項目到收件端的完整流程。
狀態頁只放讀者需要的資訊
選擇要讓讀者看到的服務,把相應監控項目加到狀態頁。服務名稱要讓營運團隊之外的人也看得懂。分享前先用登出狀態開啟頁面,核對群組、近期紀錄及事故說明。若狀態頁由同一個 Kuma 執行個體提供,它也會受到該執行個體故障的影響。
如果客戶透過對外閘道存取服務,可保留 Kuma 的內部檢查,再加一個獨立的外部 HTTP 檢查。使用觀測雲 HTTP 撥測(簡體中文) 時,可以選擇公網節點,並設定相同的預期狀態碼和回應標記。外部失敗而內部正常時,先比對 DNS、TLS 與閘道路徑。若應用程式已另行接入日誌和追蹤資料,就能查失敗請求走到了哪裡。Kuma v2 也有專門使用支援之外部探測節點的 Globalping 監控類型。這裡的一般 HTTP 與 TCP 檢查仍由 Kuma 執行個體發出。
要監控內部服務,就把 Kuma 放在能連到該服務的網路。要發現 Kuma 本身中斷,可以從另一台主機檢查能連到的 HTTPS 端點或獨立心跳,並使用在 Kuma 停止時仍能送達的通知管道。只檢查 TCP 連接埠,確認的是連線是否建立。可用性監控能回答什麼問題
升級前備份資料卷
若使用範例中的本機 SQLite,先停止寫入資料的容器,再封存整個資料目錄。這段時間內,監控和此執行個體提供的狀態頁會暫停。請在可建立備份檔案的目錄執行指令。
docker stop uptime-kuma &&
docker run --rm \
-v uptime-kuma:/data:ro -v "$PWD:/backup" \
busybox:1 tar -czf /backup/kuma-backup.tar.gz -C /data . &&
tar -tzf kuma-backup.tar.gz &&
docker start uptime-kuma
若封存或驗證失敗,先執行 docker start uptime-kuma 恢復監控,再重新備份。升級前要先確認備份可讀,並另外保存一份在 Docker 主機之外。若使用外部資料庫,還須另外備份資料庫。從 v1 遷移到 v2 時,備份後維持 v1 停止,讓 v2 容器掛載原有的儲存卷,並查看遷移日誌。只讓一個執行個體寫入 SQLite 儲存卷。若需要回復,將升級前的備份還原至另一個儲存卷,再啟動原版本。官方指南建議初次從 v1 遷移到 v2 時先避開 rootless 映像檔。v1 升級 v2 指南(英文)
