Recovery Runbook · Google Cloud

讓 Uptime Kuma
自動救回 GCE

從偵測服務失聯，到安全呼叫 Compute Engine API。這份手冊把 Service Account、Cloud Function、Secret Manager 與 Uptime Kuma 串成一條可驗證的復原流程。

服務失聯
→
Kuma 判定 DOWN
→
HTTPS Webhook
→
啟動／重設 VM
0先填好你的環境

一次填寫，下面指令自動代入

資料只保存在這個瀏覽器，不會上傳。
執行位置以下 gcloud 指令請在已安裝 Google Cloud CLI、且已登入管理帳號的電腦執行。
1Identity & Access

建立最小權限的執行身分

Function 不使用你的個人帳號，而是使用專用 Service Account。它只需要查看、啟動與重設 Compute Engine 的權限。

Shell · 環境變數

        
Shell · 建立帳號與自訂角色

        
權限邊界程式會把 VM 名稱固定在環境變數中，Webhook 不能任意指定其他 VM。若同一專案有多台關鍵主機，可再用 IAM Condition 或獨立專案縮小範圍。

      


      

        
2Recovery Logic

        
建立判斷與復原程式

        
Webhook 只接受正確 Bearer Token、正確 Monitor ID，而且只處理 DOWN。VM 已停止就啟動；VM 還顯示 RUNNING 則執行硬重設。

        

          
TERMINATED
啟動 VM
呼叫 instances.start，適合被手動停止或異常關機的 VM。

          
RUNNING
硬重設 VM
呼叫 instances.reset，適合作業系統或服務完全失去回應。

        

        
建立專案目錄

        
Shell

        
main.py

        
Python

        
requirements.txt

        
Text

      


      

        
3Secret Manager

        
產生並保存 Webhook 密鑰

        
Token 不寫進程式碼，也不要貼到公開對話。它會存在 Secret Manager，由 Function 執行身分在啟動時讀取。

        
Shell · 先產生 Token

        
複製輸出結果，代入下一段的 在這裡貼上Token：

        
Shell · 建立 Secret

      


      

        
4Deploy

        
部署 HTTP Cloud Function

        
Shell · Gen 2 Function

        
為什麼允許 unauthenticated？Uptime Kuma 不會替你簽 GCP OIDC Token，因此入口需公開；實際授權由程式中的隨機 Bearer Token、Monitor ID 白名單及固定 VM 名稱共同保護。

      


      

        
5Uptime Kuma

        
將 DOWN 通知送到 Function

        
    
          
  1. 開啟 Settings → Notifications → Setup Notification → Webhook。
    2. 
          
  2. Webhook URL 貼上部署後取得的 Function URL。
    3. 
          
  3. Request Method 選 POST，Body Encoding 使用 application/json。
    4. 
          
  4. Additional Headers 加入下方 JSON，Token 必須與 Secret Manager 中的值相同。
    5. 
          
  5. 回到目標 Monitor，把這個 Notification 指派給它。
    6. 
        

        
JSON · Additional Headers

        
建議 Monitor 參數

        

          
設定建議值目的

          
            
Heartbeat interval60 秒避免檢查太密集

            
Retries3～5 次排除短暫封包遺失

            
Retry interval30～60 秒給服務恢復的時間

            
Resend notification停用或 15～30 分鐘避免重複硬重設

          
        

      


      

        
6Verification

        
先測拒絕，再做受控故障測試

        
不要一開始就關正式服務。依序確認入口安全、測試通知被忽略、最後才安排維護時段做真正 DOWN 測試。

        
    
          
  1. 錯誤 Token：用 curl 呼叫 Function，應回傳 HTTP 401。
    2. 
          
  2. Kuma Test：一般測試通知沒有真正 DOWN heartbeat，應回傳 ignored，VM 不應重啟。
    3. 
          
  3. 查看日誌：在 Cloud Logging 確認請求結果與錯誤。
    4. 
          
  4. 受控測試：維護時段暫停目標服務，等待 Kuma 重試次數走完。
    5. 
          
  5. 確認復原：Compute Engine Operations 出現 start/reset，服務恢復後 Kuma 轉回 UP。
    6. 
        

        
Shell · 檢查拒絕行為

      


      

        
Production Safety

        
上線前必讀

        
instances.reset 是硬重設它近似按下實體主機 Reset 鍵，不會等待作業系統正常卸載磁碟。資料庫與正在寫入的檔案可能需要 crash recovery，甚至有資料遺失風險。

        
服務掛掉，真的需要重開整台 VM 嗎？
若只是 Nginx、Docker container 或單一應用程式失效，優先做服務層自動復原，例如 Docker restart policy、systemd Restart 或容器 healthcheck。整台 VM reset 應是最後一道防線。

        
如果只是 DNS、Firewall 或外部網路故障呢？
Kuma 可能誤判 VM 故障。提高 retries，並考慮由第二個地點做交叉監控。Function 雖然會先查 GCE 狀態，但 GCE 顯示 RUNNING 不代表應用程式可用。

        
Kuma 可以裝在被監控的 VM 裡嗎？
不建議。目標 VM 掛掉時，Kuma 也無法送出 Webhook。應放在不同主機、不同雲端或至少不同故障域。

        
更原生的 GCP 作法？
若工作負載可重建，使用 Managed Instance Group、Health Check 與 Autohealing 會更穩定，因為偵測與復原都在 GCP 內完成。

        
官方參考

        
Uptime Kuma Webhook 實作
Google Cloud：Reset a VM
Google Cloud：Stop and start a VM