diff --git a/docker-compose.yml b/docker-compose.yml index 8d8cdceb..c656b020 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -80,7 +80,7 @@ services: OPENCLAW_TG_USER_WHITELIST: "5619078117" # External Services (使用 host.docker.internal 存取宿主機服務) OLLAMA_URL: http://host.docker.internal:11434 - CLAWBOT_URL: http://host.docker.internal:8089 + OPENCLAW_URL: http://host.docker.internal:8088 depends_on: postgres: condition: service_healthy diff --git a/docs/RED_ZONES.md b/docs/RED_ZONES.md new file mode 100644 index 00000000..dcff7bed --- /dev/null +++ b/docs/RED_ZONES.md @@ -0,0 +1,259 @@ +# AWOOOI 紅區治理手冊 + +> 代碼防區化治理 (Codebase Zoning) 與爆炸半徑鎖死 (Blast Radius Containment) + +--- + +## 文件資訊 + +| 欄位 | 值 | +|------|-----| +| **版本** | v1.0 | +| **建立日期** | 2026-03-26 12:30 (台北) | +| **建立者** | Claude Code | +| **最後修改** | 2026-03-26 12:30 (台北) | +| **修改者** | Claude Code | +| **審查週期** | 每月第一個週一 | + +### 變更紀錄 + +| 版本 | 日期 | 執行者 | 變更內容 | +|------|------|--------|----------| +| v1.0 | 2026-03-26 | Claude Code | 初始建立 - 紅區治理機制 | + +--- + +## 紅區分級定義 + +| 等級 | 名稱 | 圖示 | 定義 | 變更後果 | +|------|------|------|------|----------| +| **Tier 3** | 核心大腦 | 🔴 | AI 決策、狀態機、Multi-Sig | 系統決策失靈 | +| **Tier 2** | 基礎設施 | 🟠 | DB Schema、K8s、CI/CD | 部署/資料異常 | +| **Tier 1** | 業務邏輯 | 🟢 | API 路由、UI 組件 | 功能異常 (可快速修復) | + +--- + +## Tier 3 紅區清單 (8 個檔案) + +### 1. 決策狀態機 +``` +檔案: apps/api/src/services/decision_manager.py +功能: OpenClaw AI 的決策核心，控制 PENDING→APPROVED→EXECUTED 狀態流轉 +影響: + - AI 無法做出決策 + - 審批流程卡死 + - 所有待處理告警無法推進 +``` + +### 2. 信任評分引擎 +``` +檔案: apps/api/src/services/trust_engine.py +功能: 計算操作的信任分數，決定是否需要 Multi-Sig 審批 +影響: + - 危險操作被自動執行 (信任分數錯誤) + - 低風險操作被過度審批 + - Multi-Sig 機制失效 +``` + +### 3. 共識引擎 +``` +檔案: apps/api/src/services/consensus_engine.py +功能: Multi-Sig 多方簽核邏輯，確保關鍵操作需多人同意 +影響: + - 單點簽核繞過安全機制 + - 審批人數計算錯誤 + - 共識達成判斷失靈 +``` + +### 4. 事件處理引擎 +``` +檔案: apps/api/src/services/incident_engine.py +功能: 告警接收、分類、派發的核心引擎 +影響: + - 告警無法被接收 + - 事件分類錯誤 + - Telegram 通知失敗 +``` + +### 5. 分散式鎖服務 +``` +檔案: apps/api/src/services/multi_sig_redis.py +功能: Redis 分散式鎖，防止併發競爭 +影響: + - 同一事件被多次處理 + - 死鎖導致系統卡死 + - 資料不一致 +``` + +### 6. 安全攔截器 +``` +檔案: apps/api/src/services/security_interceptor.py +功能: 權限驗證、危險操作攔截 +影響: + - 權限繞過漏洞 + - 危險操作未被攔截 + - 安全審計失效 +``` + +### 7. 環境配置中心 +``` +檔案: apps/api/src/core/config.py +功能: 所有服務的連線配置 (Redis/PostgreSQL/Ollama/Telegram) +影響: + - 所有外部連線中斷 + - 服務無法啟動 + - 環境變數解析失敗 +``` + +### 8. OTEL 監控核心 +``` +檔案: apps/api/src/core/telemetry.py +功能: OpenTelemetry 追蹤與指標收集 +影響: + - SignOz 無法收到追蹤數據 + - 系統可觀測性失明 + - 問題排查極度困難 +``` + +--- + +## Tier 2 橙區清單 + +### K8s 正式環境 +``` +目錄: k8s/awoooi-prod/*.yaml +功能: Kubernetes 正式環境部署檔案 +影響: 正式環境部署失敗、NetworkPolicy 錯誤 +``` + +### 資料庫 Schema +``` +檔案: apps/api/src/db/models.py +功能: SQLAlchemy ORM 模型定義 +影響: 資料庫結構不一致、Migration 衝突 +``` + +### CI/CD Pipeline +``` +目錄: .github/workflows/*.yml +功能: GitHub Actions 自動化流程 +影響: 自動部署中斷、可能產生帳單費用 +``` + +### Redis 連線池 +``` +檔案: apps/api/src/core/redis_client.py +功能: Redis 連線管理與 Stream 操作 +影響: 快取服務中斷、Worker 無法接收任務 +``` + +### Telegram 閘道 +``` +檔案: apps/api/src/services/telegram_gateway.py +功能: Telegram Bot 訊息收發 +影響: 告警通知無法送達、審批按鈕失效 +``` + +--- + +## 🏛️ 首席架構師審查流程 + +### 警告觸發時 + +當 Git commit 觸及紅區/橙區檔案時，pre-commit hook 會顯示警告，並**強制啟動首席架構師審查流程**： + +``` +╔══════════════════════════════════════════════════════════════╗ +║ 🔴 TIER 3 紅區變更警告 ║ +╚══════════════════════════════════════════════════════════════╝ + +[Tier 3 紅區] 決策狀態機 +功能: OpenClaw AI 的決策核心 +影響: ... + +╔══════════════════════════════════════════════════════════════╗ +║ 🏛️ 首席架構師審查必要 ║ +╠══════════════════════════════════════════════════════════════╣ +║ 1. 停止 commit，呼叫首席架構師介入 ║ +║ 2. 首席架構師進行架構與代碼 Review ║ +║ 3. 確認變更必要性、影響範圍、替代方案 ║ +║ 4. 首席架構師簽核後，方可繼續 ║ +╚══════════════════════════════════════════════════════════════╝ +``` + +### 首席架構師審查檢查項 + +| 項目 | 說明 | +|------|------| +| **變更必要性** | 為什麼需要修改此核心檔案？有無其他方案？ | +| **影響範圍** | 此變更會影響哪些上下游模組？ | +| **風險評估** | 最壞情況是什麼？如何緩解？ | +| **回滾計畫** | 若出問題，如何快速回滾？ | +| **測試覆蓋** | 是否有足夠的測試保護此變更？ | + +### 首席架構師簽核格式 + +```markdown +## 🏛️ 首席架構師審查簽核 + +**審查時間**: 2026-03-26 13:00 (台北) +**審查者**: 首席架構師 / Claude Code + +### 變更摘要 +- 檔案: decision_manager.py +- 原因: [說明] + +### 審查結論 +- [x] 變更必要性確認 +- [x] 影響範圍可控 +- [x] 回滾計畫完備 +- [x] 測試覆蓋充足 + +### 簽核結果 +✅ **批准** - 可繼續 commit +``` + +### Claude Code 看到警告後必須 + +1. **立即停止自動 commit** +2. **呼叫首席架構師介入** +3. **首席架構師進行審查**: + - 變更必要性 + - 影響範圍評估 + - 替代方案評估 + - 回滾計畫 +4. **首席架構師簽核後**才能繼續 commit + +--- + +## 定期審查機制 + +### 審查週期 + +| 項目 | 週期 | 負責人 | 下次審查 | +|------|------|--------|----------| +| **紅區清單** | **每週一** | 首席架構師 | 2026-03-31 | +| **Hook 腳本** | **每月第一個週一** | 首席架構師 | 2026-04-06 | +| 違規統計 | 每週一 | Claude Code | 2026-03-31 | + +### 審查檢查項 + +- [ ] 是否有新的核心模組需要加入紅區？ +- [ ] 是否有紅區檔案已重構/移除？ +- [ ] Hook 警告訊息是否仍然準確？ +- [ ] 是否有誤報需要調整？ + +### 更新流程 + +1. 修改 `scripts/hooks/pre-commit` 中的 `TIER3_ZONES` 或 `TIER2_ZONES` +2. 執行 `bash scripts/setup-hooks.sh` 重新安裝 +3. 更新本文件 `docs/RED_ZONES.md` +4. 更新 Memory: `feedback_red_zone_governance.md` + +--- + +## 相關文件 + +- [HARD_RULES.md](HARD_RULES.md) - 絕對禁止規則 +- [CLAUDE.md](../CLAUDE.md) - AI 開發憲法 +- [scripts/hooks/pre-commit](../scripts/hooks/pre-commit) - Hook 腳本 diff --git a/docs/guidelines/ARCHITECTURE.md b/docs/guidelines/ARCHITECTURE.md index ad4a20e4..2bf9a9db 100644 --- a/docs/guidelines/ARCHITECTURE.md +++ b/docs/guidelines/ARCHITECTURE.md @@ -2,6 +2,27 @@ > 架構相關的核心原則與規範 +--- + +## 文件資訊 + +| 欄位 | 值 | +|------|-----| +| **版本** | v1.1 | +| **建立日期** | 2026-03-22 (台北) | +| **建立者** | Claude Code | +| **最後修改** | 2026-03-25 23:59 (台北) | +| **修改者** | Claude Code | + +### 變更紀錄 + +| 版本 | 日期 | 執行者 | 變更內容 | +|------|------|--------|----------| +| v1.0 | 2026-03-22 | Claude Code | 初始建立 | +| v1.1 | 2026-03-25 | Claude Code | 加入文件資訊區塊 | + +--- + ## 快速索引 | 主題 | 核心原則 | 詳細章節 | @@ -37,7 +58,7 @@ Signal → IncidentEngine → DecisionManager → Telegram/UI ### 命名規範 - ✅ 正確: OpenClaw, openclaw -- ❌ 禁止: ClawBot, clawbot (舊稱) +- ❌ 禁止: OpenClaw, clawbot (舊稱) --- diff --git a/docs/infrastructure/DEPLOYMENT_CONTRACTS.md b/docs/infrastructure/DEPLOYMENT_CONTRACTS.md index 52031aa3..ff569aa3 100644 --- a/docs/infrastructure/DEPLOYMENT_CONTRACTS.md +++ b/docs/infrastructure/DEPLOYMENT_CONTRACTS.md @@ -31,7 +31,7 @@ | Namespace | `awoooi-prod` | `wooo-aiops` | | Frontend Port | 32335 | 31235 | | API Port | 32334 | 31234 | -| ClawBot Port | 8089 | 8088 | +| OpenClaw Port | 8089 | 8088 | | Redis DB | 10-15 | 0-9 | --- @@ -324,7 +324,7 @@ spec: - protocol: TCP port: 11434 - # 允許訪問 ClawBot AWOOOI (192.168.0.188:8089) + # 允許訪問 OpenClaw AWOOOI (192.168.0.188:8089) - to: - ipBlock: cidr: 192.168.0.188/32 diff --git a/docs/infrastructure/DEPLOYMENT_TOPOLOGY.md b/docs/infrastructure/DEPLOYMENT_TOPOLOGY.md index 6e632b18..3346f79c 100644 --- a/docs/infrastructure/DEPLOYMENT_TOPOLOGY.md +++ b/docs/infrastructure/DEPLOYMENT_TOPOLOGY.md @@ -45,8 +45,8 @@ │ │ │ [Docker] │ │ ├─ Ollama :11434 │ -│ ├─ ClawBot AWOOOI :8089 │ -│ ├─ ClawBot Legacy :8088 (凍結) │ +│ ├─ OpenClaw :8089 │ +│ ├─ OpenClaw Legacy :8088 (凍結) │ │ ├─ Redis Stack :6380 │ │ └─ SigNoz :3301 │ └─────────────────────────────────────────────────────────────────────────────┘ @@ -122,8 +122,8 @@ services: | **Nginx** | **Host 直裝** | 443 | SSL Gateway，路由分流 | | **PostgreSQL** | **Host 直裝** | 5432 | 主資料庫 | | **Ollama** | Docker | 11434 | 本地 LLM 推理 | -| **ClawBot AWOOOI** | Docker | 8089 | AI Agent (新) | -| **ClawBot Legacy** | Docker | 8088 | AI Agent (舊，凍結) | +| **OpenClaw** | Docker | 8089 | AI 大腦 (唯一決策中心) | +| **OpenClaw Legacy** | Docker | 8088 | 凍結版本 | | **Redis Stack** | Docker | 6380 | 快取 + 向量搜尋 | | **SigNoz** | Docker | 3301 | APM / 觀測平台 | @@ -167,16 +167,16 @@ services: devices: - capabilities: [gpu] - clawbot-awoooi: - image: 192.168.0.110:5000/awoooi/clawbot:latest + openclaw: + image: 192.168.0.110:5000/awoooi/openclaw:latest ports: - "8089:8089" environment: - OLLAMA_URL=http://localhost:11434 - REDIS_URL=redis://localhost:6380/10 - clawbot-legacy: - image: 192.168.0.110:5000/wooo-aiops/clawbot:frozen + openclaw-legacy: + image: 192.168.0.110:5000/wooo-aiops/openclaw:frozen ports: - "8088:8088" # 凍結版本，不再更新 @@ -278,8 +278,8 @@ spec: value: "redis://192.168.0.188:6380/10" - name: OLLAMA_URL value: "http://192.168.0.188:11434" - - name: CLAWBOT_URL - value: "http://192.168.0.188:8089" + - name: OPENCLAW_URL + value: "http://192.168.0.188:8088" resources: requests: cpu: "200m" @@ -337,7 +337,7 @@ spec: │ ▼ ┌─────────────┐ - │ ClawBot │ + │ OpenClaw │ │ 188:8089 │ │ (Docker) │ └─────────────┘ @@ -423,7 +423,7 @@ spec: - protocol: TCP port: 11434 # Ollama - protocol: TCP - port: 8089 # ClawBot + port: 8089 # OpenClaw # 允許訪問 112 安全掃描 - to: - ipBlock: @@ -516,7 +516,7 @@ server { 2. 192.168.0.188 (Docker 服務) └─ docker-compose up -d redis-stack └─ docker-compose up -d ollama - └─ docker-compose up -d clawbot-awoooi + └─ docker-compose up -d openclaw-awoooi └─ docker-compose up -d signoz 3. 192.168.0.110 (DevOps) @@ -541,9 +541,9 @@ systemctl status postgresql psql -U postgres -c "SELECT 1" # 2. 驗證 Docker 服務 (188) -docker ps | grep -E "(ollama|clawbot|redis|signoz)" +docker ps | grep -E "(ollama|openclaw|redis|signoz)" curl http://localhost:11434/api/tags -curl http://localhost:8089/health +curl http://localhost:8088/health redis-cli -p 6380 PING # 3. 驗證 K3s 服務 diff --git a/scripts/setup-hooks.sh b/scripts/setup-hooks.sh new file mode 100644 index 00000000..a1284d00 --- /dev/null +++ b/scripts/setup-hooks.sh @@ -0,0 +1,34 @@ +#!/bin/bash +# ============================================================ +# AWOOOI Git Hooks Setup Script +# Version: 1.0 +# Created: 2026-03-26 12:30 (台北時區) +# Created by: Claude Code +# Description: 安裝 Git Hooks 到本地環境 +# ============================================================ + +set -e + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" + +echo "🔧 安裝 AWOOOI Git Hooks..." + +# 安裝 pre-commit hook +if [ -f "$SCRIPT_DIR/hooks/pre-commit" ]; then + cp "$SCRIPT_DIR/hooks/pre-commit" "$PROJECT_ROOT/.git/hooks/pre-commit" + chmod +x "$PROJECT_ROOT/.git/hooks/pre-commit" + echo "✅ pre-commit hook 安裝完成" +else + echo "❌ 找不到 pre-commit hook" + exit 1 +fi + +echo "" +echo "🎉 Git Hooks 安裝完成！" +echo "" +echo "紅區保護已啟用:" +echo " - Tier 3 (核心大腦): 8 個檔案" +echo " - Tier 2 (基礎設施): 15+ 個檔案" +echo "" +echo "更多資訊請參閱: docs/RED_ZONES.md"