604e38cf07
- CLAUDE.md: 紅區治理章節 - Skills 01/03: 版本更新 - ADR/Architecture: 標準化 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
194 lines
7.7 KiB
Markdown
194 lines
7.7 KiB
Markdown
# 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
|
||
```
|
||
|
||
## 五主機架構
|
||
|
||
| 主機 | 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 設計語言
|
||
|
||
```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 |
|