awoooi/docs/architecture/ARCHITECTURE.md

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() - 關閉時清理

關鍵配置

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 整合

# 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

五主機架構

主機	IP	角色	服務
DevOps	192.168.0.110	CI/CD	Harbor, GH Runner
Security	192.168.0.112	安全掃描	Kali Scanner
K3s Master	192.168.0.120	容器編排	K3s API Server
K3s Worker	192.168.0.121	工作負載	App Pods
AI+Web	192.168.0.188	AI/DB/Web	Ollama, PostgreSQL, Redis, SignOz

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)

Ollama (local) → Gemini (cloud) → Claude (cloud) → mock_fallback
     ↓              ↓                 ↓                ↓
   免費           $0.001/1K        $0.003/1K        開發用
   188:11434     API Key          API Key          無 LLM

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 設計語言

/* 主色調 */
--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