863fc5a426
內容: - 8 層架構圖 (ASCII) - 工具/服務清單表格 - 配置/代碼檔案清單 - 完整資料流說明 - E2E 驗證機制 (ADR-025/035) - 故障排查指南 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
249 lines
13 KiB
Markdown
249 lines
13 KiB
Markdown
# 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
|