From 863fc5a426a33a9c59b34b71da80357750bd184b Mon Sep 17 00:00:00 2001 From: OG T Date: Sat, 28 Mar 2026 22:25:14 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E7=9B=A3=E6=8E=A7?= =?UTF-8?q?=E5=91=8A=E8=AD=A6=E5=AE=8C=E6=95=B4=E6=B5=81=E7=A8=8B=E6=96=87?= =?UTF-8?q?=E6=AA=94=20(2026-03-29=20ogt)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 內容: - 8 層架構圖 (ASCII) - 工具/服務清單表格 - 配置/代碼檔案清單 - 完整資料流說明 - E2E 驗證機制 (ADR-025/035) - 故障排查指南 Co-Authored-By: Claude Opus 4.5 --- docs/architecture/ALERT_FLOW_COMPLETE.md | 248 +++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 docs/architecture/ALERT_FLOW_COMPLETE.md diff --git a/docs/architecture/ALERT_FLOW_COMPLETE.md b/docs/architecture/ALERT_FLOW_COMPLETE.md new file mode 100644 index 000000000..e8f81582f --- /dev/null +++ b/docs/architecture/ALERT_FLOW_COMPLETE.md @@ -0,0 +1,248 @@ +# AWOOOI 監控告警完整流程 + +> **建立日期**: 2026-03-29 (台北時區) +> **建立者**: Claude Code +> **版本**: v1.0 + +--- + +## 1. 架構圖 (ASCII) + +``` +┌──────────────────────────────────────────────────────────────────────────────┐ +│ AWOOOI 監控告警架構 (E2E) │ +└──────────────────────────────────────────────────────────────────────────────┘ + +Layer 1: 告警生產端 +═══════════════════════════════════════════════════════════════════════════════ + + Prometheus K8s Event Sentry SignOz + (Alertmanager) Watcher (Error Tracking) (Observability) + │ │ │ │ + └──────┬───────────┴─────────────────┴────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────────────────┐ + │ 告警接收層 (Alert Reception) │ + │ - /api/v1/webhooks/alerts (Prometheus) │ + │ - /api/v1/webhooks/sentry (Sentry Issues) │ + │ - /api/v1/signals (SignOz Metrics) │ + └─────────────────────────────────────────────────────────┘ + │ + ▼ +Layer 2: 告警聚合與去重 +═══════════════════════════════════════════════════════════════════════════════ + + ┌──────────────────────────────────────────────────────────┐ + │ Signal Producer (Redis Streams) │ + │ - 告警指紋生成 (SHA256 Hash) │ + │ - 10 分鐘 TTL 去重 │ + │ - Trace Context 注入 (Phase 15.2) │ + └────────┬─────────────────────────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────────────────────────────────┐ + │ Incident Engine v1.2 (DualMemory) │ + │ - 事件聚合 (30 分鐘時間窗口) │ + │ - Lua 原子操作 (消除 Race Condition) │ + │ - Working Memory: Redis (7天TTL) + Episodic: PostgreSQL│ + └────────┬─────────────────────────────────────────────────┘ + │ + ▼ +Layer 3: AI 決策與分析 +═══════════════════════════════════════════════════════════════════════════════ + + ┌──────────────────────────────────────────────────────────┐ + │ OpenClaw AI Decision Engine (True LLM) │ + │ │ + │ 備援順序: Gemini → Ollama → Claude → Mock │ + │ │ + │ 整合 SignOz Gold Metrics: │ + │ - RPS (流量趨勢) │ + │ - Error Rate (錯誤率) │ + │ - P99 Latency (99百分位延遲) │ + │ │ + │ 輸出結構化決策: │ + │ - 根本原因分析 (root_cause) │ + │ - 責任判定 (FE/BE/INFRA/DB/COLLAB) │ + │ - 信心度評分 (0.0-1.0) ← LLM 真實計算 │ + │ - 修復建議 (kubectl 命令) │ + │ - 風險等級 (LOW/MEDIUM/HIGH/CRITICAL) │ + └────────┬─────────────────────────────────────────────────┘ + │ + ▼ +Layer 4: 批准簽核 +═══════════════════════════════════════════════════════════════════════════════ + + ┌──────────────────────────────────────────────────────────┐ + │ Approval Manager │ + │ - 建立待簽核卡片 (Approval Records) │ + │ - 存入 PostgreSQL + Redis (Working Memory) │ + │ - Incident-Approval 同步 (ADR-027) │ + └────────┬─────────────────────────────────────────────────┘ + │ + ▼ +Layer 5: Telegram 通知 +═══════════════════════════════════════════════════════════════════════════════ + + ┌──────────────────────────────────────────────────────────┐ + │ Telegram Gateway │ + │ │ + │ 訊息格式 (SOUL.md): │ + │ ┌───────────────────────────────────────┐ │ + │ │ 🚨 CRITICAL | harbor-core │ │ + │ │ ═══════════════════════════════════ │ │ + │ │ 🤖 AI 仲裁判定 │ │ + │ │ 👥 責任: BE (後端) │ │ + │ │ 📊 信心: 🟢 88% │ │ + │ │ 💰 Tokens: 1,234 / $0.0012 │ ← 新增! │ + │ │ 💡 原因: JVM Heap 配置不當 │ │ + │ │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │ │ + │ │ 📊 SignOz 指標 │ │ + │ │ ├ RPS: 150.2 📈 │ │ + │ │ ├ Error: 🟢 0.5% │ │ + │ │ └ P99: 245ms ➡️ │ │ + │ │ │ │ + │ │ [✅ 簽核] [❌ 拒絕] │ │ + │ └───────────────────────────────────────┘ │ + └────────┬─────────────────────────────────────────────────┘ + │ + ▼ +Layer 6: 執行與觀測 +═══════════════════════════════════════════════════════════════════════════════ + + ┌──────────────────────────────────────────────────────────┐ + │ K8s Executor + Observability │ + │ - 簽核通過後執行 kubectl 指令 │ + │ - Shadow Mode: 日誌輸出，不執行 │ + │ - SignOz + Sentry + Langfuse 三層觀測 │ + └──────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. 工具/服務清單 + +| 工具/服務 | IP:Port | 用途 | 狀態 | +|----------|---------|------|------| +| **Prometheus** | 192.168.0.188:9090 | 指標收集 + 告警規則 | ✅ | +| **Alertmanager** | 192.168.0.188:9093 | 告警路由 + 去重 | ✅ | +| **SignOz** | 192.168.0.188:3301 | Traces/Metrics/Logs | ✅ | +| **Sentry** | 192.168.0.110:9000 | 錯誤追蹤 + Session Replay | ✅ | +| **Langfuse** | 192.168.0.188:3100 | LLMOps (Token/Cost) | ✅ | +| **OpenClaw** | 192.168.0.188:8088 | AI 根因分析 | ✅ | +| **Ollama** | 192.168.0.188:11434 | 本地 LLM (備援) | ✅ | +| **Telegram** | api.telegram.org | 行動戰情室 | ✅ | +| **PostgreSQL** | 192.168.0.110:5432 | Incident/Approval 持久化 | ✅ | +| **Redis** | 192.168.0.112:6379 | Working Memory | ✅ | +| **K3s** | 192.168.0.125 (VIP) | 容器編排 | ✅ | + +--- + +## 3. 配置檔案清單 + +| 檔案路徑 | 用途 | 關鍵配置 | +|---------|------|---------| +| `k8s/awoooi-prod/03-secrets.yaml` | K8s Secrets | OPENCLAW_TG_BOT_TOKEN | +| `k8s/awoooi-prod/04-configmap.yaml` | ConfigMap | AI_FALLBACK_ORDER, OTEL 端點 | +| `k8s/awoooi-prod/02-network-policy.yaml` | NetworkPolicy | DNS 規則 | +| `.github/workflows/cd.yaml` | CD Pipeline | ADR-035 三層驗證 | + +--- + +## 4. 代碼檔案清單 + +| 檔案路徑 | 功能 | 關鍵邏輯 | +|---------|------|---------| +| `apps/api/src/api/v1/webhooks.py` | 告警接收 Router | HMAC 驗證, 指紋去重 | +| `apps/api/src/services/openclaw.py` | AI 決策引擎 | LLM 備援, Token 追蹤 | +| `apps/api/src/services/telegram_gateway.py` | Telegram 推送 | SOUL.md 格式 | +| `apps/api/src/services/consensus_engine.py` | 多專家共識 | Expert System | +| `apps/api/src/models/ai.py` | AI 模型定義 | OpenClawDecision | +| `apps/api/src/core/prompts.py` | LLM Prompt | OPENCLAW_SYSTEM_PROMPT v7.1 | + +--- + +## 5. 資料流說明 + +### 5.1 Prometheus 告警流程 + +``` +Prometheus Alert 觸發 + ↓ +Alertmanager 聚合 + ↓ +HTTP POST → /api/v1/webhooks/alerts + ↓ +[webhooks.py] HMAC 驗證 + 指紋去重 + ├─ 重複告警 → hit_count+1, 跳過 LLM + └─ 新告警 → 繼續 + ↓ +[openclaw.py] AI 分析 + ├─ SignOz Gold Metrics 擷取 + ├─ LLM 呼叫 (Gemini → Ollama → Claude) + ├─ Token/Cost 追蹤 ← 新增! + └─ 輸出: OpenClawDecision + ↓ +[approval_db.py] 建立待簽核卡片 + ↓ +[telegram_gateway.py] 推送通知 + ├─ 💰 Tokens: X / $Y.YYYY ← 新增! + └─ SignOz 指標嵌入 +``` + +### 5.2 Confidence 信心分數 (2026-03-29 修復) + +**之前**: +- `models/ai.py` 有 `default=0.8` +- LLM 沒輸出 confidence 時，Pydantic 填入預設值 +- 結果: 信心分數永遠是 80% + +**現在**: +- `confidence` 改為 REQUIRED (無預設值) +- LLM 沒輸出時，強制設為 0.5 + COLLAB +- 結果: 信心分數是 LLM 真實計算 + +--- + +## 6. 告警鏈路 E2E 驗證 (ADR-025/035) + +``` +Layer 1: Pre-flight + └─ GitHub Secrets 存在性檢查 + +Layer 2: Deploy + └─ K8s Secrets 自動注入 (kubectl patch) + +Layer 3: Post-Deploy + └─ 發送測試告警驗證 success: true + +Layer 4: 監控 + └─ 連續 1 小時無告警 → 觸發 CRITICAL +``` + +--- + +## 7. 常見故障排查 + +| 故障現象 | 根本原因 | 排查步驟 | +|---------|---------|---------| +| **Telegram 無通知** | Token 失效 / Secret 未注入 | `kubectl get secret awoooi-secrets -o yaml` | +| **告警 404** | URL 路徑錯誤 | 確認 `/api/v1/webhooks/alerts` (複數!) | +| **信心分數永遠 80%** | Pydantic 預設值 | 已修復: d469a23 | +| **OpenClaw 超時** | Ollama 加載慢 | `curl http://192.168.0.188:11434/api/tags` | + +--- + +## 8. 相關 ADR + +| ADR | 主題 | +|-----|------| +| ADR-025 | 告警鏈路 E2E 驗證 | +| ADR-027 | Incident-Approval 同步 | +| ADR-035 | Telegram Secrets 自動注入 | + +--- + +**維護者**: Claude Code +**最後更新**: 2026-03-29