170 lines
7.5 KiB
Markdown
170 lines
7.5 KiB
Markdown
# ADR-075：Telegram 告警通知格式標準化與完整流程修復
|
||
|
||
> **狀態**: 🟡 批准實作中
|
||
> **建立日期**: 2026-04-12（台北時間）
|
||
> **決策者**: 統帥 ogt + Claude Sonnet 4.6
|
||
> **相關 ADR**: ADR-071（四種通知類型）、ADR-073（飛輪修復）、ADR-074（監控補全）
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
ADR-071（2026-04-11）設計了 TYPE-1/2/3/4/4D 五種通知類型，並實作了 `classify_alert_early()`、`_build_inline_keyboard()` 等函數。但在 2026-04-12 的全面盤點中，發現整條資料流存在 **4 個斷點**，導致動態分類按鈕從未真正生效，所有 TYPE-3 告警一律 fallback 到通用的 [批准][拒絕][靜默] 三鍵。
|
||
|
||
同時，在與 Gemini 的架構討論中，確認了 8 種通知類型矩陣（TYPE-1 到 TYPE-8M）以及雙頻道發送策略。
|
||
|
||
---
|
||
|
||
## 問題診斷：4 個斷點
|
||
|
||
```
|
||
斷點 A：decision_manager._push_decision_to_telegram()
|
||
呼叫 send_approval_card() 時沒有傳入 alert_category
|
||
|
||
斷點 B：telegram_gateway.send_approval_card()
|
||
呼叫 _build_inline_keyboard() 時沒有傳入 alert_category/notification_type
|
||
|
||
斷點 C：telegram_gateway._send_approval_card_to_group()
|
||
含 Callback Button 的 TYPE-3 卡片也發到 SRE 群組 → nonce 洩漏安全漏洞
|
||
|
||
斷點 D：classify_alert_early() 輸出 "kubernetes"
|
||
但 _build_inline_keyboard 期待 "k8s_workload" → 永遠不命中
|
||
另有 10 個告警分類錯誤（host_resource/devops_tool/ssl_cert 等全落入 general）
|
||
```
|
||
|
||
---
|
||
|
||
## 決策
|
||
|
||
### D1：統一 Category 命名
|
||
|
||
- `k8s_workload` → 改為 `kubernetes`（語義更廣，涵蓋 Node/Service/Ingress）
|
||
- `Host*` 告警從 `infrastructure` 分離為 `host_resource`
|
||
- `Docker*` 告警保留 `infrastructure`
|
||
|
||
### D2：新增 7 個 Category
|
||
|
||
| Category | 告警 | 說明 |
|
||
|---------|------|------|
|
||
| `alertchain_health` | AlertChainBroken_* / NoAlertsReceived2Hours / AlertChainUnhealthy | meta-monitoring，優先度最高 |
|
||
| `flywheel_health` | AutoRepairLowSuccessRate / PermanentFixRequired / Flywheel* | 飛輪自身健康 |
|
||
| `storage` | MinIODown | 物件儲存 |
|
||
| `devops_tool` | GiteaDown / HarborDown / SignOzDown / OpenClawDown / SentryDown / AlertmanagerDown | DevOps 工具鏈 |
|
||
| `external_site` | MoWoooWorkDown / TsenyangWebsiteDown / StockWoooWorkDown / BitanWoooWorkDown | 外部業務網站 |
|
||
| `ssl_cert` | ExternalSiteSSL* / TLSCert* | SSL 憑證 |
|
||
| `security_tool` | KaliScannerDown | 資安掃描工具 |
|
||
|
||
### D3：8 種通知類型矩陣（完整版）
|
||
|
||
| 類型 | 適用場景 | 按鈕 | 發送目標 |
|
||
|-----|---------|------|---------|
|
||
| TYPE-1 | 純資訊、備份成功、心跳 | 無 | SRE 群組 |
|
||
| TYPE-2 | AI 自動修復完成 | 無（結果通知）| SRE 群組 |
|
||
| TYPE-3 | 需人工審核（預設）| 依 category 動態 ≤4 個 | SRE 群組 |
|
||
| TYPE-4 | AI 無法判斷 | [手動記錄][查面板][忽略] | SRE 群組 |
|
||
| TYPE-4D | Config Drift | [查Diff][採納][回滾][忽略] | SRE 群組 |
|
||
| TYPE-5S | 資安防禦 | [隔離][封鎖IP][驅逐Pod][確認授權]；危險動作先記授權/多簽 | SRE 群組 |
|
||
| TYPE-6B | 業務/FinOps（未來）| [暫停][查SignOz][忽略] | SRE 群組 |
|
||
| TYPE-7E | 重大事故升級 / auto-repair unavailable | 無 ghost callback；人工/AI 接手先靠卡片與 timeline/AOL 留痕，按鈕需有 dispatcher 後才可開 | SRE 群組 |
|
||
| TYPE-8M | 飛輪/告警鏈路健康 | [觸發診斷][查看面板][靜默] | SRE 群組 |
|
||
|
||
### D4：雙頻道路由規則
|
||
|
||
```
|
||
2026-04-30 起，正式告警收件通道統一為 AwoooI SRE 戰情室群組
|
||
SRE_GROUP_CHAT_ID=-1003711974679
|
||
|
||
OPENCLAW_TG_CHAT_ID 僅作 SRE_GROUP_CHAT_ID 缺失時的 fail-soft fallback。
|
||
```
|
||
|
||
### D5：Telegram 卡片格式防腐規則
|
||
|
||
```python
|
||
# telegram_gateway.py 頂部常數（ADR-075 鎖定）
|
||
NOTIFICATION_TYPE_RULES = {
|
||
"TYPE-1": "無按鈕，可有 URL Button，嚴禁 Callback Button",
|
||
"TYPE-2": "無按鈕，可有 URL Button，嚴禁 Callback Button",
|
||
"TYPE-3": "最多 4 個 Callback Button，依 alert_category 動態選擇",
|
||
"TYPE-4": "固定 3 個按鈕：[手動記錄][查看面板][忽略]",
|
||
"TYPE-4D": "固定 4 個按鈕：[查看Diff][採納][回滾][忽略]",
|
||
"TYPE-5S": "固定 4 個按鈕：[隔離][封鎖IP][驅逐Pod][確認授權]，危險動作只記授權/多簽",
|
||
"TYPE-6B": "最多 3 個按鈕：[暫停][查看SignOz][忽略]",
|
||
"TYPE-7E": "無 ghost callback；未落地 dispatcher 前不顯示 callback button",
|
||
"TYPE-8M": "固定 3 個按鈕：[觸發診斷][飛輪面板][靜默]",
|
||
}
|
||
```
|
||
|
||
2026-05-01 補充：TYPE-7E 已用於 `auto_repair_unavailable` 與
|
||
`drift_auto_adopt_blocked` 緊急通道。Telegram 卡片本身不是閉環；每次升級
|
||
必須寫入 `alert_operation_log` 與 `timeline_events`，讓 WarRoom、KM 與
|
||
learning loop 能反查。TYPE-5S 的 `record_authorization` 也必須寫 Redis TTL
|
||
和 AOL/timeline；不得只回 Telegram toast。
|
||
|
||
---
|
||
|
||
## 實施計畫
|
||
|
||
完整計畫書：`docs/superpowers/plans/2026-04-12-adr075-telegram-alert-notification.md`
|
||
|
||
**Phase 1（斷點修復，同一 PR）**：
|
||
- Task 1-2：重寫 `classify_alert_early()`（斷點 D）
|
||
- Task 3：`_build_inline_keyboard` 字典對齊（斷點 D）
|
||
- Task 4：`send_approval_card()` 接收並傳遞 `alert_category`（斷點 B）
|
||
- Task 5：雙頻道路由修正（斷點 C）
|
||
- Task 6：`decision_manager` 傳入 `alert_category`（斷點 A）
|
||
|
||
**Phase 2（TYPE-8M 擴充）**：
|
||
- Task 7-8：新增 `send_meta_alert()` + decision_manager 路由
|
||
|
||
**Phase 3（Prometheus 規則，獨立）**：
|
||
- Task 9：新增 6 個欠缺告警規則
|
||
|
||
---
|
||
|
||
## 驗收標準
|
||
|
||
| 驗收項目 | 驗收方式 |
|
||
|---------|---------|
|
||
| HostHighCpuLoad 出現 [查程序][重啟服務][清Log] | 送測試告警驗收 |
|
||
| KubePodCrashLooping 出現 [重啟][擴容][縮容][回滾] | 送測試告警驗收 |
|
||
| AlertChainBroken_* 出現 [啟動緊急診斷] | 送測試告警驗收 |
|
||
| TYPE-3 卡片不發 SRE 群組 | 確認群組無帶按鈕訊息 |
|
||
| TYPE-1 卡片只發 SRE 群組 | 確認個人 DM 無純資訊通知 |
|
||
| 全部單元測試通過 | pytest >620 passed |
|
||
|
||
---
|
||
|
||
## 範疇外（本 ADR 不包含）
|
||
|
||
- TYPE-5S SecOps 卡片（待 SecOps Prometheus 規則完備後）
|
||
- TYPE-6B Business 卡片（待 MomoScraper metrics 接入後）
|
||
- TYPE-7E Escalation Monitor Service
|
||
- FlywheelPlaybookZero 告警（依賴 ADR-074 Exporter）
|
||
|
||
|
||
---
|
||
|
||
## 實作記錄（2026-04-12）
|
||
|
||
| Phase | Commit | 內容 |
|
||
|-------|--------|------|
|
||
| Phase 1 | 2cef209 | 4 斷點修復 + classify_alert_early 13 規則 + _CATEGORY_BUTTONS 更新 |
|
||
| Phase 2 | 561c1d8 | send_meta_alert() + decision_manager TYPE-8M elif |
|
||
| CR 修補 | 1cb654c | TYPE_8M 加入 enum + 死碼清理 + docstring 更新 |
|
||
|
||
**測試覆蓋**：52 classify_alert_early tests + 664 total passed
|
||
|
||
**CR 評分**：7/10（首席架構師審查通過，P0/P1 全修補）
|
||
|
||
**Phase 3（Prometheus 規則）**：尚未實作，不阻擋 Phase 1/2 上線
|
||
|
||
---
|
||
|
||
## 更新引用（2026-04-24）
|
||
|
||
| ADR | 影響 | 說明 |
|
||
|-----|------|------|
|
||
| [ADR-093](ADR-093-telegram-group-migration.md) | 🔄 更新 D4 雙頻道路由 | 加「群組 Callback Button 授權模式」子條款：TYPE-3/4/4D/8M 解除 `_interactive_types` 黑名單，改以 callback_data + user_id binding + Approvers 白名單保護（P0-1 修）|
|
||
| [ADR-094](ADR-094-hermes-nl-interface.md) | ➕ 新增 NL 對話入口 | Hermes 透過 @mention 在群組處理自然語言對話，輸出仍遵守 ADR-075 D5 格式規則 |
|
||
| [ADR-095](ADR-095-12agent-sdk-integration.md) | ➕ 12-Agent 視覺分派 | TG 訊息加 `@hermes-*` 前綴 + emoji + hashtag 三件套，符合 ADR-086 UI 清洗後的視覺規範 |
|