awoooi/docs/adr/ADR-035-telegram-alert-chain-enforcement.md

ADR-035: Telegram 告警鏈路強制驗證

狀態: 已批准 建立日期: 2026-03-29 (台北時間) 建立者: Claude Code (首席架構師) 觸發事故: 2026-03-29 Telegram 告警失效 (K8s Secrets 未注入)

---

1. 問題背景

1.1 事故時間線

日期	事件	影響
2026-03-23	Telegram Token 災難 (logOut)	Token 永久失效
2026-03-26	Alertmanager 路徑錯誤	2 天無告警
2026-03-29	K8s Secrets 未注入	長時間無告警

1.2 根本原因

1. CD workflow 未自動注入 K8s Secrets

   • kustomization.yaml 註釋說「secrets 由 CI/CD 單獨處理」
   • 但 CD 實際上沒有處理
   • 導致 OPENCLAW_TG_BOT_TOKEN 保持為模板值 "CHANGE_ME"

2. 缺乏 E2E 驗證機制

   • 部署後沒有驗證告警鏈路是否正常
   • 問題可能數天後才被發現

3. Memory 鐵律未完整執行

   • 已有 feedback_alertchain_e2e_validation.md 記錄
   • 但 CD workflow 沒有實際實施驗證

---

2. 決策

2.1 CD Secrets 自動注入 (強制)

每次部署 必須 同步 K8s Secrets：

- name: "Sync K8s Secrets (ADR-035)"
  run: |
    kubectl patch secret awoooi-secrets -n awoooi-prod --type='merge' -p="{
      \"stringData\": {
        \"OPENCLAW_TG_BOT_TOKEN\": \"${{ secrets.OPENCLAW_TG_BOT_TOKEN }}\",
        \"OPENCLAW_TG_CHAT_ID\": \"${{ secrets.OPENCLAW_TG_CHAT_ID }}\"
      }
    }"

2.2 Pre-flight Secrets 檢查 (強制)

部署前 必須 驗證 Telegram Secrets 存在：

- name: "Check Required Secrets"
  run: |
    if [ -z "${{ secrets.OPENCLAW_TG_BOT_TOKEN }}" ]; then
      echo "❌ 缺少 OPENCLAW_TG_BOT_TOKEN"
      exit 1
    fi

2.3 部署後 E2E 驗證 (強制)

部署完成後 必須 發送測試告警驗證：

- name: "Verify Telegram Alert Chain (ADR-035)"
  run: |
    # 發送測試告警
    # 驗證 API 回應 success: true
    # 失敗則直接發送告警到 Telegram

---

3. 實施檢查清單

3.1 CD Workflow 修改

項目	狀態	檔案
Pre-flight Secrets 檢查	✅	.github/workflows/cd.yaml
K8s Secrets 自動注入	✅	.github/workflows/cd.yaml
部署後 E2E 驗證	✅	.github/workflows/cd.yaml

3.2 GitHub Secrets 必要項目

Secret 名稱	用途	必須
OPENCLAW_TG_BOT_TOKEN	Telegram Bot Token	🔴 是
OPENCLAW_TG_CHAT_ID	Telegram Chat ID	🔴 是
DATABASE_URL	PostgreSQL 連線	🔴 是
REDIS_URL	Redis 連線	🔴 是
SENTRY_DSN	Sentry 錯誤追蹤	🟡 建議

3.3 Memory/文檔更新

項目	狀態	檔案
ADR-035	✅	docs/adr/ADR-035-*.md
Feedback Memory	✅	feedback_telegram_secrets_injection.md
CLAUDE.md 規則	✅	CLAUDE.md
Skills 更新	✅	.agents/skills/04-awoooi-devops-commander.md

---

4. 防止再次發生

4.1 自動化防護層

┌─────────────────────────────────────────────────────────────────┐
│                     告警鏈路防護機制                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Layer 1: Pre-flight                                            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ GitHub Secrets 存在性檢查                                │    │
│  │ - OPENCLAW_TG_BOT_TOKEN 必須存在                        │    │
│  │ - 缺少則 CI 失敗 (exit 1)                               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              │                                   │
│                              ▼                                   │
│  Layer 2: Deploy                                                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ K8s Secrets 自動注入                                     │    │
│  │ - 每次部署都 patch secret                               │    │
│  │ - 確保 Token 永遠是最新的                               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              │                                   │
│                              ▼                                   │
│  Layer 3: Post-Deploy                                           │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ E2E 驗證 (實際發送測試告警)                              │    │
│  │ - 發送測試告警到 API                                    │    │
│  │ - 驗證回應 success: true                                │    │
│  │ - 失敗則繞過 API 直接告警                               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

4.2 Claude Code 強制規則

修改 CLAUDE.md 或 CD workflow 時 必須：

1. 確保 Sync K8s Secrets 步驟存在
2. 確保 Verify Telegram Alert Chain 步驟存在
3. 確保所有 Telegram Secrets 在 Pre-flight 中檢查

---

5. 相關文件

• feedback_alertchain_e2e_validation.md
• feedback_telegram_token_disaster.md
• feedback_telegram_secrets_injection.md

---

審查者: 統帥 (待簽核) 生效日期: 2026-03-29