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: 架構硬化 Roadmap (規劃中)

來源: 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 5 (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