awoooi/docs/architecture/ALERT_FLOW_COMPLETE.md

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