Uptime Kuma 完整教學 2026：91K 星自架監控神器，Docker 安裝、10 種監控類型、狀態頁與 Telegram 通知一次學會

Uptime Kuma 是一套 MIT 授權、GitHub 91,221 星的開源自架監控工具，用一個 Docker 容器就能監控網站、API、資料庫、DNS、Docker 容器與遊戲伺服器，最低 20 秒檢查一次，內建 108 種通知整合與多組公開狀態頁——完全免費、資料留在自己手上。 這篇教學從安裝、新增監控、通知設定，到 Caddy 反向代理與 kuma.db 備份陷阱，全部附可直接複製執行的指令。

什麼是 Uptime Kuma？

Uptime Kuma 由開發者 Louis Lam 於 2021 年 7 月開源，採用 MIT 授權、以 Node.js + Vue 3 撰寫。它的定位非常明確：「簡單易用的自架版 UptimeRobot」。

作者在 README 裡直白寫下動機：他想要一套華麗 UI 的自架監控工具，但當時最接近的 statping 已不再維護，於是乾脆自己寫一套。這個「順手做」的專案，五年後長成了 91,221 顆星、8,396 個 fork 的基礎設施級工具，最新版本為 2.5.3（2026 年 8 月 22 日發布）。

它跟 Grafana + Prometheus 那類 Metrics 系統最大的差別是：Uptime Kuma 只回答一個問題——「這個服務現在活著嗎？」，而且用最好懂的介面回答你。 你不需要寫 exporter、不需要學 PromQL，開瀏覽器點兩下就能加一個監控。

flowchart TB
    subgraph VPS["你的 VPS / 家用主機"]
        UK["Uptime Kuma 容器<br/>:3001<br/>/app/data/kuma.db"]
    end
    UK -->|HTTP 檢查| A["網站 most.tw"]
    UK -->|HTTP 檢查| B["外部 API"]
    UK -->|TCP 檢查| C["PostgreSQL :5432"]
    UK -->|Ping| D["路由器 / 內網主機"]
    UK -->|DNS 查詢| E["MX / A 記錄"]
    UK -->|Push 心跳| F["cron job / 備份腳本"]
    UK -->|docker.sock| G["其他容器狀態"]
    UK -->|108 種通知| H["Telegram / Discord<br/>LINE / Ntfy / Email"]
    I["公開狀態頁<br/>status.most.tw"] --> J["客戶 / 使用者"]
    UK -.->|Caddy 反向代理 + WebSocket| I

為什麼要自架？跟 UptimeRobot 差在哪

一句話總結：UptimeRobot 的價值在「全球多節點」——從外部多個地點確認服務是否活著；Uptime Kuma 的價值在「免費、無限、資料自持」。如果你同時想監控外網網站與內網設備（例如家裡的 NAS、內網資料庫），Uptime Kuma 是唯一能在同一介面裡搞定的選擇，因為它就跑在你的內網裡。

Docker Compose 安裝（推薦）

官方 Compose 檔只有 9 行，先建目錄再下載啟動：

mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

compose.yaml 官方內容如下：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      # <Host Port>:<Container Port>
      - "3001:3001"

啟動後打開 http://你的主機IP:3001 就能看到首次設定畫面。這裡有個資安細節：上面的 -p "3001:3001" 會把介面曝露在所有網路介面上。 如果你打算用反向代理搭配網域存取，建議改成只綁本機：

    ports:
      - "127.0.0.1:3001:3001"

不想用 Compose？一行 docker run 也可以

docker run -d --restart=always -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma louislam/uptime-kuma:2

⚠️ 官方明確警告：不支援 NFS 等網路檔案系統。 Uptime Kuma 內部用 SQLite（kuma.db）儲存資料，掛在 NFS 上很容易遇到資料庫鎖定與損毀。請務必映射到本地目錄或本地 Docker volume。

第一步：開帳號與 2FA

首次登入時建立管理員帳號，接著立刻做兩件事：

1. 設定 → 安全性 → 啟用 2FA：Uptime Kuma 支援 Two-Factor Authentication。若日後遺失驗證器，可以透過官方 CLI 工具重置。
2. 更改預設監控間隔：預設 60 秒，最低可以調到 20 秒。注意調越短，對目標網站與你自己 VPS 的負擔越大，內網服務可以短，外部網站建議 60 秒就好。

支援的 10 種監控類型

新增方式：右上角「+ 新增監控」→ 輸入名稱、選類型、填 URL／主機 → 設定心跳間隔（Heartbeat Interval）與重試次數（Retries）。

⚠️ 重試次數是最容易被忽略的設定。若設為 0，一次網路抖動就會觸發告警，一個晚上可能收上百則通知。建議外部網站設 Retries = 2～3、重試間隔 60 秒，確認真的掛了才通知。

Push 監控：讓 cron job 自己回報

這是 Uptime Kuma 最有價值的功能之一。新增一個 Push 類型監控後，它會給你一組專屬 URL，只要在腳本結尾打一個 HTTP 請求就完成回報：

# 例如每日備份腳本的最後一行
curl -fsS -m 10 --retry 5 \
  "http://127.0.0.1:3001/api/push/你的PushToken?status=up&msg=OK&ping=5"

如果某天腳本沒跑完、沒送出心跳，Uptime Kuma 會在設定的寬限期後發出告警。「排程沒跑」這種靜默失敗，只有 Push 監控能抓到。

通知整合：108 種，這裡教最常用的四個

Uptime Kuma 內建 108 種通知管道（實際是 src/components/notifications/ 下的 108 個整合），從 Telegram、Discord、Slack、Ntfy、Gotify、Pushover、PagerDuty，到 LINE、HomeAssistant、Google Sheets 通通有。

實戰建議：設定兩層通知。 第一層用免費、即時的 Telegram／Ntfy；第二層用 Email 當備援。如果第一層的通道本身掛了（例如你的 Telegram Bot 被限流），第二層還能救你一次。

公開狀態頁：給客戶看的那一面

狀態頁（Status Page）是 Uptime Kuma 的另一個殺手級功能：

• 支援多個獨立狀態頁（自 v1.13.0 起）
• 支援依網域對應不同狀態頁（自 v1.14.0 起），例如 status.example.com 給 A 客戶、status.example.org 給 B 客戶
• 預設 slug 是 default，所以 https://你的網域/status 實際會導到 /status/default

⚠️ 狀態頁有快取。 為了降低負載，公開狀態頁的結果會快取 5 分鐘、頁面每 5 分鐘自動刷新一次。也就是說管理後台已經紅燈了，客戶看到狀態頁可能還要再等幾分鐘才會變色。這是設計取捨，不是 bug。

搭配 Caddy 反向代理（含 WebSocket）

Uptime Kuma 前端是 SPA，透過 **WebSocket（Socket.io）**與後端即時通訊。反向代理必須正確轉發 HTTP Upgrade 與 Connection 標頭，否則介面會連不上、數據不會更新。

Caddy 2 的 reverse_proxy 預設就會處理 WebSocket 升級，所以設定只要三行：

status.most.tw {
    reverse_proxy 127.0.0.1:3001
}

Nginx 就必須手動補上：

location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
}

Host 與 X-Forwarded-Host 一定要轉發，否則 Uptime Kuma 無法辨識請求來自哪個網域，多網域狀態頁對應就會失效。若你前面還掛了 authentik 之類的 SSO，記得把 /status/*、/api/status-page/*、/assets/* 設為免驗證路徑，並在 Uptime Kuma 裡把 Trust Proxy 打開。

（延伸：Caddy 的完整設定與 HTTPS 自動化可參考站內的 Caddy 完整教學 2026。）

監控 Docker 容器：方便但危險

想在 Uptime Kuma 裡直接看到其他容器狀態，需要把 Docker socket 掛進去：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock   # 監控容器用
    ports:
      - "127.0.0.1:3001:3001"

⚠️ 掛載 /var/run/docker.sock 等於把主機的極高權限交給這個容器。 任何能存取 Uptime Kuma 管理介面的人，理論上都能透過 Docker API 做更多事。如果你只需要監控 HTTP／TCP 服務，官方建議把這行移除。 若真的需要，請務必搭配 2FA 與只綁 127.0.0.1。

備份與升級（最多人踩雷的地方）

備份正確做法：

# 1. 先停容器，避免 SQLite WAL 寫入中
docker stop uptime-kuma

# 2. 打包整個資料目錄
tar czf uptime-kuma-backup-$(date +%F).tar.gz ./data

# 3. 再啟動
docker start uptime-kuma

⚠️ 陷阱：不要只依賴「設定 → 備份」匯出的 JSON 檔。 那只是設定備份，無法用來做完整災難復原。真正的資料是 /app/data/kuma.db（以及 kuma.db-wal、kuma.db-shm 與 uploads/ 目錄）。SQLite 在線熱備份容易損毀，務必先停容器再打包。

升級方式：

cd uptime-kuma
docker compose pull
docker compose up -d

升級前請先備份 data/ 目錄。建議加個 Docker Hub 的版本標籤檢視，確認鏡像 :2 對應的最新版本（目前為 2.5.3）。

常見陷阱速查

小結：三十分鐘就能補上的可觀測性底線

多數自架族的監控是「服務掛了、客戶先發現、你才發現」。Uptime Kuma 的價值不在於它能做到 Prometheus 那種深度指標分析，而在於它把「服務活著嗎」這件事的成本降到接近零——9 行程式碼、一個容器、三十分鐘設定，就換到 20 秒級的可用性檢查、Push 心跳、以及一個能給客戶看的公開狀態頁。

建議的下一步順序是：先監控你的網域與 VPS（HTTP + Ping），接著補上資料庫的 TCP 檢查，再加一個 Push 監控給每日備份腳本。等你收到第一則「備份沒跑」的 Telegram 通知，就會知道這三十分鐘有多划算。

延伸閱讀

• Caddy 完整教學 2026：75K 星自動 HTTPS 網頁伺服器，反向代理到 Docker 部署一次學會
• Docker 完整教學 2026：什麼是容器？從安裝、Dockerfile、Compose 多階段構建到安全部署
• Vaultwarden 完整教學 2026：自架 Bitwarden 相容密碼管理器（Docker 安裝＋HTTPS 設定）
• Tailscale 完整教學 2026：從 MagicDNS、Subnet Router 到遠端連回家中自架服務

資料來源

• Uptime Kuma 官方 GitHub（91,221 stars / MIT）
• 官方 compose.yaml
• Uptime Kuma 2.5.3 Release Notes
• Uptime Kuma 官方 Wiki（安裝與反向代理）
• Uptime Kuma 線上 Demo