wooo/awoooi
1
1
Fork 0
Code Issues 2 Pull Requests 1 Actions 2 Packages Projects Releases Wiki Activity

docs: 新增監控告警完整流程文檔 (2026-03-29 ogt)

Browse Source 
內容:
- 8 層架構圖 (ASCII)
- 工具/服務清單表格
- 配置/代碼檔案清單
- 完整資料流說明
- E2E 驗證機制 (ADR-025/035)
- 故障排查指南

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OG T
2026-03-28 22:25:14 +08:00
parent 0b68352fc2
commit 863fc5a426
1 changed files with 248 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

248
docs/architecture/ALERT_FLOW_COMPLETE.md Normal file
View File

@@ -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