# AWOOOI 架構文檔 > 統帥鐵律：嚴禁臨時方案，所有架構決策必須符合長期維護性 ## 核心架構原則 ### Four Iron Laws (四大鐵律) 1. **Async-First** - 所有 Handler 必須是 `async def` 2. **CORS Whitelist** - 嚴格來源控制，禁止 wildcard (*) 3. **Pydantic Config** - 類型安全的設定驗證 4. **structlog** - 結構化 JSON 日誌 ## HTTP Client 架構 (2026-03-21 架構回歸) ### 問題背景 原始實作使用 `subprocess.run(["curl", ...])` 作為 httpx 404 問題的臨時解法。 統帥明令禁止此類臨時方案，要求回歸原生 httpx AsyncClient。 ### 永久解決方案 ``` src/core/http_client.py - Lifespan 管理的連線池 ├── get_clickhouse_client() - ClickHouse 專用 Client ├── get_general_client() - Ollama/Gemini/Claude 通用 Client ├── init_all_http_clients() - 啟動時初始化 └── close_all_http_clients() - 關閉時清理 ``` ### 關鍵配置 ```python httpx.AsyncClient( base_url=settings.CLICKHOUSE_URL, timeout=httpx.Timeout(30.0, connect=10.0), trust_env=False, # 🔧 禁止 HTTP_PROXY 干擾 limits=httpx.Limits(max_connections=100, max_keepalive_connections=20), ) ``` ### Lifespan 整合 ```python # src/main.py @asynccontextmanager async def lifespan(_app: FastAPI): # Startup await init_all_http_clients() # ✅ 連線池建立 yield # Shutdown await close_all_http_clients() # ✅ 連線池回收 ``` ### 驗證結果 ``` Status: 200 Elapsed: 28.71ms (< 50ms 目標) Method: httpx_native ``` ## 五主機架構 (2026-03-28 K-HA 更新) | 主機 | IP | 角色 | 服務 | |-----|-----|------|------| | DevOps | 192.168.0.110 | CI/CD + 監控 | Harbor:5000, GH Runner, Sentry:9000, Langfuse:3100 | | Security | 192.168.0.112 | 安全掃描 | Kali Scanner:8080 | | K3s Server #1 | 192.168.0.120 | **Control-Plane MASTER** | keepalived (priority=101) | | K3s Server #2 | 192.168.0.121 | **Control-Plane BACKUP** | keepalived (priority=100) | | **VIP** | **192.168.0.125** | **HA Endpoint** | **K3s API:6443 + NodePort (32334/32335)** | | AI+Web | 192.168.0.188 | AI/DB/Web | Ollama:11434, OpenClaw:8089, **PostgreSQL:5432 (K3s Datastore)**, Redis:6380, SignOz:3301 | ## K3s 高可用架構 (ADR-033) ``` VIP 192.168.0.125 (keepalived) ↓ ┌──────────────┼──────────────┐ ▼ ▼ ▼ mon(120) mon1(121) PostgreSQL(188) K3s MASTER K3s BACKUP K3s Datastore priority=101 priority=100 (Kine protocol) ``` ### 關鍵變更 (2026-03-28) - ✅ 雙 Control-Plane (120+121) - ✅ 外接 PostgreSQL Datastore (188:5432) - ✅ VIP 192.168.0.125 (keepalived VRRP) - ✅ CI/CD kubeconfig 指向 VIP - ✅ 故障轉移 < 3 秒 ## SignOz 整合架構 ``` ┌─────────────────────────────────────────────┐ │ AWOOOI API │ │ (port 8000) │ ├─────────────────────────────────────────────┤ │ signoz_client.py │ │ └── get_clickhouse_client() │ │ └── httpx.AsyncClient (Lifespan) │ └─────────────────┬───────────────────────────┘ │ HTTP POST (< 50ms) ▼ ┌─────────────────────────────────────────────┐ │ ClickHouse HTTP API │ │ 192.168.0.188:8123 │ ├─────────────────────────────────────────────┤ │ signoz_metrics.distributed_samples_v4 │ │ - signoz_calls_total (RPS) │ │ - signoz_latency_count (P99) │ └─────────────────────────────────────────────┘ ``` ## AI Fallback 策略 (ADR-006 v1.3 + ADR-036) ### 一般對話任務 ``` Ollama (local) → Gemini (cloud) → Claude (cloud) → mock_fallback ↓ ↓ ↓ ↓ 免費 $0.001/1K $0.003/1K 開發用 188:11434 API Key API Key 無 LLM ``` ### Tool Calling 任務 (ADR-036 - 待批准) ``` Nemotron (cloud) → Gemini (cloud) → Claude (cloud) → 拒絕執行 ↓ ↓ ↓ 免費 tier $0.001/1K $0.003/1K 精準度 83% API Key API Key 延遲 11-45s ``` ### Provider 對照表 | Provider | 用途 | 延遲 | 精準度 | 成本 | |----------|------|------|--------|------| | **Ollama** | 即時對話、簡單查詢 | < 5s | 中 | $0 | | **Nemotron** | Tool Calling、K8s 操作 | 11-45s | 高 (83%) | 免費 tier | | **Gemini** | 通用備援 | 2-5s | 中高 | 低 | | **Claude** | 複雜推理、CRITICAL | 2-5s | 最高 | 高 | ## Phase 7: 視覺主權組件 ### 已完成組件 | 組件 | 路徑 | 功能 | |-----|------|------| | GlobalPulseChart | `components/charts/global-pulse-chart.tsx` | 4 指標卡片 + Sparkline | | AIProcessStepper | `components/charts/ai-process-stepper.tsx` | 5 步 AI 決策流程 | | TimeSeriesChart | `components/charts/time-series-chart.tsx` | 通用趨勢圖 | ### Nothing.tech 設計語言 ```css /* 主色調 */ --nothing-white: #FFFFFF; --nothing-gray-50: #FAFAFA; --nothing-gray-900: #171717; --nothing-red: #EF4444; /* 玻璃效果 */ .glass-card { background: rgba(255, 255, 255, 0.7); backdrop-filter: blur(16px); border: 1px solid rgba(0, 0, 0, 0.05); } ``` ## Phase 6: 架構硬化 ✅ (2026-03-23) > **來源**: `docs/ARCHITECTURE_CODE_REVIEW.md` 技術債審查 | 項目 | 現狀 | 目標 | 優先級 | |------|------|------|--------| | Multi-Sig 持久化 | ~~In-Memory dict~~ | ✅ Redis Hash + Redlock | 🔴 P0 | | GraphRAG 遷移 | ~~In-Memory dict~~ | ✅ Neo4j / Redis Graph | 🔴 P0 | | SSE 容錯驗證 | ~~ADR-004 已規劃~~ | ✅ 驗證實作 | 🟢 P2 | | 水平擴展 | ~~單實例~~ | ✅ Redis Pub/Sub + Sticky Session | 🟡 P1 | ## Phase 8-10: 生產修復與監控 ✅ - Phase 8: OTEL/SignOz v3/Telegram UX/Worker 分離 - Phase 9: OpenClaw Agent Teams (多專家共識) - Phase 10: Sentry Self-Hosted 整合 (192.168.0.110:9000) ## Phase 11: 對話式 AI UI/UX ✅ | 組件 | 路徑 | 功能 | |-----|------|------| | ConversationalView | `components/conversational-view.tsx` | ChatGPT 風格雙欄 | | BatchModeSelector | `components/batch-mode-selector.tsx` | 批次處理 + 風險過濾 | | useKeyboardShortcuts | `hooks/useKeyboardShortcuts.ts` | Y/N 長按 + 方向鍵 | ## Phase 12: Ollama 深度整合 ✅ - 12.1 Tool Calling 優化 (準確率 100%) - 12.2 本地模型優化 (Qwen2.5:7b + ModelRouter) ## Phase 13: Enterprise AIOps (規劃中) ``` ┌─────────────────────────────────────────────────────────────┐ │ Phase 13 Enterprise AIOps │ ├─────────────────────────────────────────────────────────────┤ │ 13.1 CI/CD 整合 │ │ ├── GitHub Webhook → OpenClaw │ │ ├── CI 失敗 → AI 診斷 │ │ └── AI 自動修復 (風險分級) │ │ │ │ 13.2 Tool 實作 (P0 - Mock → 真實) │ │ ├── SignOz MCP (Trace/Logs/Metrics) │ │ ├── Kubernetes MCP (kubectl exec) │ │ ├── PostgreSQL MCP (歷史查詢) │ │ └── 維運手冊 RAG (Markdown 向量化) │ │ │ │ 13.3 智能路由 │ │ ├── Intent Classifier (意圖判別) │ │ ├── Complexity Scorer (難度評分) │ │ └── AI Router (動態模型選擇) │ └─────────────────────────────────────────────────────────────┘ ``` ## 變更紀錄 | 日期 | 版本 | 變更 | |-----|------|------| | 2026-03-25 | 1.3 | 新增 Phase 8-13 完整進度，ClawBot → OpenClaw | | 2026-03-22 | 1.1 | 新增 Phase 6 架構硬化 Roadmap (Code Review 來源) | | 2026-03-21 | 1.0 | 架構回歸：移除 subprocess+curl，實作 httpx Lifespan | | 2026-03-21 | 1.0 | Phase 7 視覺組件：GlobalPulseChart, AIProcessStepper |