2026.09.08

Uptime Kuma：用 Docker 建立網站與內部服務監控

網站偶爾打不開，使用者通常只會回報「剛剛連不上」，但資訊人員需要知道中斷發生時間、持續多久，以及是網站、網路、DNS 還是後端服務異常。Uptime Kuma 是可自行架設的監控工具，能檢查公開網站，也能從同一個內部網路檢查 TCP 服務、Ping 與特定頁面。以下以 Linux 主機與 Docker Compose 示範。

一、準備 Docker Compose

先在管理用主機安裝 Docker Engine 與 Compose Plugin。以 Ubuntu 為例，建議依 Docker 官方文件設定套件來源後安裝；完成後執行 docker compose version，應顯示 Compose 版本。接著建立專用目錄：

sudo mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma
sudo nano compose.yaml

將下列內容貼入 compose.yaml。資料會寫入命名磁碟區，容器重新建立後仍可保留監控項目。

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - kuma-data:/app/data

volumes:
  kuma-data:

啟動並檢查狀態：

sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=50 uptime-kuma

預期 docker compose ps 顯示服務為 running。由於連接埠只綁定在 127.0.0.1，外部電腦不能直接連入；可在主機上以 SSH 通道暫時開啟管理介面：ssh -L 3001:127.0.0.1:3001 user@monitor-host，再用瀏覽器搜尋 http://127.0.0.1:3001。

二、建立網站與內部服務監控

第一次開啟先建立管理員帳號。按「Add Monitor」後，依服務類型選擇監控方式：

HTTP(s) – Website：填入完整網址，例如 https://www.example.com/health，間隔可先設 60 秒；若服務有固定回應文字，可設定關鍵字檢查。
TCP Port：填入內部主機名稱或 IP 與連接埠，例如 10.10.20.15:5432，適合確認資料庫或應用程式是否正在監聽。
Ping：檢查主機是否可達，但只能代表網路層回應，不代表網站功能正常。

Uptime Kuma 跑在容器內，因此監控設定中的 localhost 指的是 Kuma 容器本身，不是 Docker 主機。若要檢查同一台主機上的服務，請使用主機在區網中的 IP；若監控另一個 Compose 服務，則使用該服務名稱與容器連接埠。儲存後，預期項目顯示綠色「Up」，並可在事件紀錄看到回應時間。

三、設定通知並實際測試

在「Settings」的通知設定新增公司允許使用的管道，例如 Email、Discord、Slack 或 Webhook。依管道填入 SMTP、Webhook URL 或 Token，按「Test」確認收到測試訊息；不要把 Token 貼在公開工單或版本庫。接著對測試監控項目暫時填入不存在的網址，或把 TCP 連接埠改成未使用的連接埠，等待一個檢查週期。

預期流程是先變成紅色「Down」、通知管道收到中斷訊息，恢復正確設定後再變成「Up」並收到恢復通知。測試完成要立刻還原網址或連接埠，避免留下誤報。

四、維護、限制與安全設定

每月檢查 docker compose ps、容器日誌與磁碟空間；更新前先閱讀 Uptime Kuma 發行說明，再執行 docker compose pull && docker compose up -d。
不要直接把管理介面暴露到公網。若必須遠端使用，前方應放置 HTTPS 反向代理、公司防火牆與來源 IP 限制，並啟用強密碼及多因素驗證（若版本提供）。
監控主機本身故障時，所有監控與通知也會同時停止；重要環境應放在不同主機或不同網路位置，並保留另一個獨立告警途徑。
Ping 成功不等於應用程式可用；關鍵服務應同時設定 HTTP 狀態碼、關鍵字或 TCP 檢查，並調整逾時與重試，降低短暫網路抖動造成的誤報。

五、停止、移除與回復

暫停服務但保留監控資料：

cd /opt/uptime-kuma
sudo docker compose down
sudo docker compose up -d

這樣重新啟動後，監控項目與通知設定應仍存在。若要完全移除容器與資料，確認不再需要後才執行 sudo docker compose down -v；這會刪除 kuma-data 命名磁碟區，無法靠重新建立容器找回。要回復服務，重新建立相同的 compose.yaml 後執行 sudo docker compose up -d；若仍使用原命名磁碟區，資料會被重新掛載。