wooo/awoooi
1
1
Fork 0
Code Issues 2 Pull Requests 1 Actions 3 Packages Projects Releases Wiki Activity

docs: 紅區治理 + 部署文檔更新

Browse Source 
- RED_ZONES.md: Tier 3/2 紅區清單
- setup-hooks.sh: Git Hook 安裝腳本
- infrastructure docs: 部署拓撲更新

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OG T
2026-03-26 09:55:58 +08:00
parent 604e38cf07
commit 496c569d51
6 changed files with 333 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docker-compose.yml
View File

@@ -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

259
docs/RED_ZONES.md Normal file
View File

@@ -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 腳本

23
docs/guidelines/ARCHITECTURE.md
View File

@@ -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 (舊稱)
---

4
docs/infrastructure/DEPLOYMENT_CONTRACTS.md
View File

@@ -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

30
docs/infrastructure/DEPLOYMENT_TOPOLOGY.md
View File

@@ -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 服務

34
scripts/setup-hooks.sh Normal file
View File

@@ -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"