diff --git a/docs/adr/ADR-045-telegram-gateway-consolidation.md b/docs/adr/ADR-045-telegram-gateway-consolidation.md new file mode 100644 index 00000000..066dee16 --- /dev/null +++ b/docs/adr/ADR-045-telegram-gateway-consolidation.md @@ -0,0 +1,89 @@ +# ADR-045: Telegram Gateway 統一到 K8s AWOOOI API + +## 狀態 +**已實施** (2026-03-31) + +## 背景 + +系統存在 Telegram 雙軌問題: +- **OpenClaw (188)**: Long Polling 模式,處理 Incident 告警 +- **K8s AWOOOI API**: 也有 Telegram 端點,但未啟用 + +雙軌導致: +1. Token 競爭風險 +2. 回調路由不明確 +3. 維運複雜度高 + +## 決策 + +**方案 A: 統一到 K8s AWOOOI API (Webhook 模式)** + +### 架構 + +``` +Telegram API + │ + ▼ (Webhook) +awoooi.wooo.work/api/v1/telegram/webhook + │ + ▼ +K8s AWOOOI API Pod + │ + ├─→ Incident 處理 + ├─→ Approval 回調 + └─→ AI 對話 (未來) +``` + +### 優點 +- 業界標準 (Webhook > Polling) +- 單一入口,易於監控 +- 自動擴展 (K8s) +- 統一日誌 (SignOz) + +## 實施步驟 + +### 1. 設定 Webhook ✅ +```bash +curl "https://api.telegram.org/bot${TOKEN}/setWebhook?url=https://awoooi.wooo.work/api/v1/telegram/webhook" +# {"ok":true,"result":true,"description":"Webhook was set"} +``` + +### 2. 停用 OpenClaw Telegram Polling ✅ +```bash +# .env +TELEGRAM_ENABLED=false + +# app/bot/telegram.py - 加入檢查 +if os.getenv('TELEGRAM_ENABLED', 'true').lower() == 'false': + logger.info("Telegram Bot disabled via TELEGRAM_ENABLED=false (ADR-045)") + return +``` + +### 3. 重啟 OpenClaw +```bash +sudo systemctl restart clawbot +``` + +## 驗證清單 + +- [x] Webhook URL 已設定 +- [x] K8s 端點 HTTP 200 +- [x] OpenClaw 代碼已 Patch +- [ ] OpenClaw 已重啟 +- [ ] 發送測試訊息確認 + +## 回滾計畫 + +如需回滾到 Polling 模式: +```bash +# 1. 刪除 Webhook +curl "https://api.telegram.org/bot${TOKEN}/deleteWebhook" + +# 2. 恢復 OpenClaw +# .env: TELEGRAM_ENABLED=true +sudo systemctl restart clawbot +``` + +## 相關文件 +- [ADR-035](ADR-035-telegram-alert-chain-enforcement.md) - Telegram 告警鏈路 +- [feedback_telegram_token_disaster.md](../../.claude/projects/-Users-ogt-awoooi/memory/feedback_telegram_token_disaster.md) - Token 災難鐵律