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

docs: 新增稽核報告 + 靈感實驗室 + Runbook 更新

Browse Source 
- AWOOOI_COMPREHENSIVE_AUDIT_2026Q1.md 全維度稽核
- INSPIRATION_LAB.md 靈感收集
- K3S-OPTIMIZATION-RUNBOOK.md 優化指南
- ADR-006 AI Fallback 策略更新

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OG T
2026-03-29 16:03:41 +08:00
parent 01d76df383
commit 95b46af986
6 changed files with 1713 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

783
docs/AWOOOI_COMPREHENSIVE_AUDIT_2026Q1.md Normal file
View File

@@ -0,0 +1,783 @@
# AWOOOI 全維度盤點暨長期解決方案總報告
> **文件類型**: 首席架構師全面稽核報告
> **建立日期**: 2026-03-29 12:21 (台北)
> **建立者**: Antigravity (Google DeepMind)
> **版本**: v1.0
> **保密等級**: 統帥級
---
## 執行摘要 (Executive Summary)
AWOOOI 平台已完成 **Phase 21 (Day 12)**，整體架構已從「Agent 指揮艙」成功升級為「獨立 SaaS AI 智能運維平台」。本報告對五大主軸進行深度盤點：**基礎設施、工具鏈、前端 UI/UX、後端服務、AI/觀測性**，並針對每個痛點提供長期解決方案路線圖。
**AWOOOI 當前總評**: `87/100` — **強健 (Robust，接近卓越)**
---
## 第一章：基礎設施盤點 (Infrastructure Inventory)
### 1.1 五大主機現況
| 主機 IP | 代號 | 職責 | 健康狀態 | 備註 |
|---------|------|------|---------|------|
| **192.168.0.110** | DevOps 金庫 | Harbor:5000 / Sentry:9000 / Langfuse:3100 / GH Runner | ✅ 健康 | 雙 Prometheus (188+110) |
| **192.168.0.112** | Kali Security | Scanner API:8080 | ⚠️ **低活躍** | 幾乎無 ADR 覆蓋，未整合進主流程 |
| **192.168.0.188** | AI+Web 中心 | Nginx / Ollama:11434 / OpenClaw:8089 / SigNoz:3301 / PostgreSQL:5432 / Redis:6380 / MinIO:9000 | ✅ 健康 | **核心大腦節點** |
| **192.168.0.120** | K3s Master (mon) | AWOOOI Prod (API:32334 / Web:32335) / VIP 入口 | ✅ 健康 | K3s v1.34.5+k3s1 |
| **192.168.0.121** | K3s Worker (mon1) | K3s Control-Plane 2 | ✅ 健康 | PostgreSQL Datastore HA |
| **192.168.0.125** | VIP | keepalived 虛擬 IP | ✅ 已整合 CI/CD | K8s API Entry |
### 1.2 已部署服務清單 (60+ 服務)
#### K8s Workloads (awoooi-prod namespace)
| 服務 | 副本 | 監控 | 告警 | 自動修復 | 優先級 |
|------|------|------|------|---------|-------|
| awoooi-api | 2 (HPA 2-6) | P/S/O/L | ✅ 全覆蓋 | restart/scale | **P0** |
| awoooi-web | 2 (HPA 2-6) | P/S/O | ✅ 全覆蓋 | restart | **P0** |
| awoooi-worker | 1 | P/S/O/L | worker_stuck | restart | P1 |
| argocd-server | - | P | sync_failed | - | P1 |
| prometheus | - | - | service_down | - | P0 |
| alertmanager | - | P | service_down | - | P0 |
| VPA/Descheduler/Kured | - | P | - | - | P2 |
> 圖例: P=Prometheus, S=Sentry, O=OTEL, L=Langfuse
#### Docker 服務 (192.168.0.188)
| 服務 | Port | 優先級 | 自動修復 |
|------|------|-------|---------|
| Ollama | 11434 | P0 | ✅ 自動重啟 |
| OpenClaw | 8089 | P0 | ✅ 自動重啟 |
| Redis Stack | 6380 | P0 | ❌ 謹慎處理 |
| PostgreSQL | 5432 | P0 | ❌ 謹慎處理 |
| MinIO | 9000/9001 | P1 | - |
| SigNoz UI | 3301 | P2 | - |
| SigNoz Collector | 24317 | P1 | - |
| ClickHouse | 8123 | P1 | - |
#### Docker 服務 (192.168.0.110)
| 服務 | Port | 優先級 | 整合狀態 |
|------|------|-------|---------|
| Harbor Registry | 5000 | P0 | ✅ CI/CD 整合 |
| Sentry | 9000 | P1 | ✅ Webhook 整合 |
| Langfuse | 3100 | P2 | ✅ LLMOps 整合 |
| GitHub Runner | systemd | P0 | ✅ 自動修復 |
### 1.3 基礎設施問題清單
#### 🔴 嚴重問題 (P0)
| # | 問題 | 根因 | 風險 |
|---|------|------|------|
| I-01 | **192.168.0.112 (Kali) 幾乎未整合** | 只有 Scanner API，無 ADR 覆蓋，無自動告警 | 安全掃描能力閒置，投資浪費 |
| I-02 | **K3s Worker liveness 探針依賴 heartbeat mtime** | 非標準方式，若 touch 失敗會誤殺 Pod | 服務不穩定性 |
| I-03 | **單一 GPU 節點 (.188) 無備援** | Ollama 跑在唯一的 62GB RAM 機器 | 單點故障導致 AI 能力全失 |
#### 🟡 警告問題 (P1)
| # | 問題 | 根因 | 風險 |
|---|------|------|------|
| I-04 | **PostgreSQL 無主從複製** | K3s HA 的 Datastore 沒有 PostgreSQL 副本 | DB 故障時 K3s 控制面崩潰 |
| I-05 | **Redis 無持久化驗證** | RDB/AOF 配置未在監控覆蓋 | 重啟後 Signing State 可能丟失 |
| I-06 | **MinIO 無 GC 機制** | Velero 備份積累 30 天不清理 | 磁碟滿 (MinIO 在 .188 上) |
| I-07 | **雙 Prometheus 未合併** | .188 和 .110 各跑一個 Prometheus，無聯邦查詢 | 監控數據碎片化，無統一視圖 |
### 1.4 長期解決方案
```
📌 路線圖：基礎設施長期戰略
Phase I-A (立即執行, 2週):
├── I-01: 建立 Kali Scanner ADR，整合到 AWOOOI 安全掃描流程
├── I-04: PostgreSQL Streaming Replication 到備援機器
└── I-07: 建立 Prometheus Federation，統一指向 .188 查詢
Phase I-B (中期執行, 1月):
├── I-02: 重新設計 Worker 健康檢查 (HTTP + /tmp 雙重)
├── I-05: Redis AOF 配置驗證 + 告警覆蓋
└── I-06: MinIO Lifecycle Policy (>30天自動刪除)
Phase I-C (長期規劃, Q2):
└── I-03: 評估第二 GPU 節點或 Cloud GPU 熱備用策略
```
---
## 第二章：工具鏈與 CI/CD 盤點
### 2.1 CI/CD 管線現況
| 環節 | 工具 | 狀態 |
|------|------|------|
| 原始碼 | GitHub | ✅ 正常 |
| CI | GitHub Actions (self-hosted, .110) | ✅ 正常 |
| 映像建置 | Harbor (192.168.0.110:5000) | ✅ 不可變標籤 {sha}-{run_id} |
| CD | ArgoCD + kubectl | ✅ ApplicationSet 修復完成 |
| VIP | keepalived 192.168.0.125 | ✅ CI/CD 整合 |
| 告警鏈路驗證 | alert_chain_smoke_test.py | ✅ CD 後自動執行 |
| Telegram Secrets | kubectl patch secret | ✅ 三層防護 |
### 2.2 工具生態系盤點
#### 已整合工具
| 工具 | 用途 | 整合深度 |
|------|------|---------|
| **ArgoCD** | GitOps CD | ✅ ApplicationSet 部署 |
| **Velero + MinIO** | K8s 備份還原 | ✅ 每日 02:00 備份 |
| **Kured** | 自動節點重啟 | ✅ 維護窗口 02:00-04:00 |
| **VPA** | 垂直 Pod 自動擴縮 | ✅ 已部署 |
| **Descheduler** | 負載均衡 | ✅ 每 2 小時 threshold 30% |
| **kube-state-metrics** | K8s 狀態指標 | ✅ v2.10.1 @ :30888 |
| **Langfuse** | LLMOps 追蹤 | ✅ 整合 Ollama/Gemini |
| **Sentry** | 錯誤追蹤 + Webhook | ✅ 完整整合 |
| **SigNoz** | OTEL APM | ✅ 整合所有後端 |
| **Prometheus/Alertmanager** | 指標告警 | ✅ 25/25 targets UP |
| **Grafana** | 視覺化 | ✅ K3s + NVIDIA Dashboard |
| **MCP Protocol** | AI 工具橋接 | ✅ ADR-001 |
#### 未整合 / 弱整合工具
| 工具/能力 | 現況 | 缺口 |
|---------|------|------|
| **Kali Scanner (.112)** | 🔴 孤立 | 無 AWOOOI Webhook 整合 |
| **GraphRAG** | 🟡 實作但未整合 | `graph_rag.py` 存在但無持久化 |
| **Knowledge Base** | 🟡 頁面存在但無後端 | `/knowledge-base` 頁面空白 |
| **Omni-Terminal 後端** | 🟡 前端殼已建 | FastAPI 端點未完全對接 |
| **NVIDIA Nemotron** | ✅ Phase 20 已完成 | Circuit Breaker 已部署 |
| **Playwright E2E** | 🟡 測試已寫 | 缺少 CI/CD 定期執行 |
| **Cost Analyzer** | 🔴 FinOps 引擎閒置 | cost_analyzer.py 有實作但無 UI |
### 2.3 CI/CD 問題
#### 🔴 嚴重問題
| # | 問題 | 影響 |
|---|------|------|
| C-01 | **OpenAPI Spec 未自動驗證** | 前後端契約可能悄悄偏離 |
| C-02 | **E2E Playwright 測試未在 CI 定期跑** | UI 回歸無保障 |
| C-03 | **CD timeout 僅 20min** | 大型部署可能超時失敗 |
#### 🟡 警告問題
| # | 問題 | 影響 |
|---|------|------|
| C-04 | **無藍綠部署** | 每次部署都有短暫 downtime |
| C-05 | **SBOM / 軟體物料清單缺失** | 依賴安全掃描盲區 |
### 2.4 長期解決方案
```
📌 路線圖：工具鏈長期戰略
Phase C-A (立即執行, 1週):
├── C-02: 加入 Playwright Weekly E2E 排程 (weekly.yaml)
└── C-01: 整合 spectral lint 到 CI (spectral.yaml 已存在！)
Phase C-B (中期, 1月):
├── C-04: 實作 K8s Blue-Green 部署策略
├── 整合 Kali Scanner 到 CI (每次 PR 做安全掃描)
└── 整合 FinOps 看板到 Dashboard
Phase C-C (長期規劃, Q2):
└── C-05: 整合 Trivy/Syft SBOM 生成到 CD
```
---
## 第三章：前端 UI/UX 深度審查 ⚠️ 核心痛點
> **統帥點名**：前端缺陷是此次盤點最核心的痛點，必須有徹底的解決方案。
### 3.1 現況診斷
#### 已完成的前端建設
| 頁面/組件 | 狀態 | 品質 |
|---------|------|------|
| Dashboard (首頁) | ✅ 運行 | 真實 SSE 數據 |
| Authorizations (簽核) | ✅ 運行 | ConversationalView + CSRF |
| Action Logs | ✅ 運行 | 真實 API |
| Error Tracking | ✅ 運行 | Sentry 整合 |
| Omni-Terminal | 🟡 外殼已建 | 後端未完全對接 |
| Settings | 🟡 部分功能 | - |
| Knowledge Base | 🔴 空白頁 | 無後端 |
| Topological Canvas | 🔴 未建 | AWOOOI Roadmap P2 |
#### 技術債盤點
**i18n 違規 (GLOBAL_RULES 第二章)：**
根據 `docs/TECHNICAL_DEBT_PHASE2.md`，截至 2026-03-20 仍有 40+ 處違規，主要集中在：
| 優先級 | 檔案 | 違規數 | 狀態 |
|-------|------|-------|------|
| 🔴 P0 | `approval-card.tsx` | 20+ | 部分修復 |
| 🔴 P0 | `data-pincer.tsx` | 5 | **未修復** |
| 🔴 P0 | `status-orb.tsx` | 4 | **未修復** |
| 🔴 P0 | `connection-status.tsx` | 10 | **未修復** |
| 🟡 P1 | `thinking-terminal.tsx` | 15+ | **未修復** |
| 🟡 P1 | `live-host-card.tsx` | 1 | **未修復** |
**視覺規範違規：**
- Omni-Terminal 外殼：白玻璃效果已實現，但後端 SSE 事件類型未完全對接
- 部分頁面仍存在 `shadcn/ui` 預設樣式 (已廢除)
### 3.2 🚨 Claude Code 前端弱點：根本問題診斷
Claude Code (以及類似 AI 工具) 在前端 UI/UX 領域存在**結構性弱點**，必須正視：
| 弱點 | 具體表現 | 影響 |
|------|---------|------|
| **視覺感知盲區** | AI 無法「看到」最終渲染效果 | 代碼看起來正確，但視覺效果差 |
| **CSS層疊語境失憶** | 修改一個組件不知道影響全局 | 修了A壞了B |
| **動畫設計能力薄弱** | 無法感受 150ms vs 300ms 的區別 | 動畫要麼太慢要麼太生硬 |
| **設計意圖無法推斷** | Nothing.tech 審美需要視覺參照 | 生成的 UI 趨向平庸/安全 |
| **瀏覽器兼容性盲點** | Safari glassmorphism bugs 難以捕捉 | 交付物在某些瀏覽器崩潰 |
### 3.3 🎯 前端 UI/UX 徹底解決方案 (The Frontend Sovereignty Plan)
#### 戰略框架：三元驅動模型
```
┌─────────────────────────────────────────────────────────────────────┐
│ AWOOOI 前端主權計畫 (Frontend Sovereignty) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: 設計系統主權 (Design System Sovereignty) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Nothing.tech Design Tokens → Tailwind Config → │ │
│ │ Storybook 組件庫 → AI 可引用的視覺規格文檔 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ↕ 雙向同步 │
│ Layer 2: AI 賦能層 (AI-Augmented Development) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Cursor/Claude Code → 視覺截圖回饋 → 自動 QA → │ │
│ │ Playwright Screenshot Diff (視覺回歸測試) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ↕ 品質門 │
│ Layer 3: 統帥審美主控 (Commander Aesthetic Control) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ AI 生成 → 截圖存檔 → 統帥批准 → 鎖定 Snapshot → │ │
│ │ 後續 AI 修改必須通過 Visual Regression Test │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
#### 具體解決方案：9 大行動
**🔴 緊急 (立即執行)**
**行動 1: 建立 Storybook 組件庫 (Component Bible)**
```bash
# 在 apps/web 建立 Storybook
pnpm add -D @storybook/nextjs @storybook/addon-essentials
```
目標：將所有核心組件 (GlassCard, StatusOrb, ApprovalCard, OmniTerminal 等) 上架 Storybook，讓 AI 有可引用的「視覺字典」。每個組件附上：
- 設計規格截圖
- Nothing.tech 視覺 Token 標注
- 各狀態的 Stories (Loading/Error/Success/CRITICAL)
**行動 2: 建立 Visual Regression Testing**
```yaml
# .github/workflows/visual-regression.yaml
# 使用 Playwright Screenshot Diff
# 每次 PR 自動截圖並與 baseline 比對
# 差異超過 阈值 → PR 阻擋
```
這直接解決 AI「視覺感知盲區」問題。AI 修了代碼，如果像素不對，CI 就攔截。
**行動 3: 完成 i18n 清零 (技術債閃電戰)**
策略：一次性全掃描，批量修復所有 40+ 違規，而非逐一修復。
```bash
# 腳本化搜索所有硬編碼字串
grep -rn "\"[A-Z][A-Z]" apps/web/src --include="*.tsx" | grep -v "//.*\"" > i18n_violations.txt
```
**🟠 中期 (2-4 週)**
**行動 4: Omni-Terminal 後端全接通**
根據 `AWOOOI_AGENTIC_WORKSPACE_ROADMAP.md` 的神經連接藍圖，實現三大 SSE 事件類型：
- `event: thought` → Agent 思考流
- `event: tool_call` → 工具調用微動畫
- `event: render_ui` → GenUI 動態渲染
這是 AWOOOI 區別於傳統監控後台的**決定性功能**。
**行動 5: 建立 GenUI 組件動態註冊系統**
```typescript
// apps/web/src/components/genui/registry.ts
// 已有基礎，需要擴充
const GENUI_COMPONENTS = {
'MetricsCard': () => import('./cards/MetricsCard'),
'K8sPodCard': () => import('./cards/K8sPodCard'),
'SqlQueryCard': () => import('./cards/SqlQueryCard'), // 新增
'NetworkTopologyCard': () => import('./cards/NetworkTopologyCard'), // 新增
'IncidentTimelineCard': () => import('./cards/IncidentTimelineCard'), // 新增
'FinOpsCard': () => import('./cards/FinOpsCard'), // 新增
}
```
**行動 6: Knowledge Base 頁面後端建設**
建立 Knowledge Base API (`/api/v1/knowledge-base/`):
- 整合 GraphRAG (`graph_rag.py`)
- 事件記憶回廊 (Episodic Memory Vault)
- Playbook 搜尋與管理
**🟡 長期 (1-2 個月)**
**行動 7: Topological Canvas 建設**
實現 `AWOOOI_AGENTIC_WORKSPACE_ROADMAP.md` 中的「拓撲因果畫布」：
- 使用 `react-flow` 或類似庫
- 爆炸半徑高光 (Blast Radius Highlight)
- 時光倒流 Time-Travel 功能
**行動 8: 視覺靈魂注入 (Phase 4)**
啟動條件：所有 API 穩定、i18n 清零後。
- Q 版 OpenClaw 品牌 3D 資產
- 微動畫升級 (150ms 快閃動畫)
- 打字機效果 Token Buffer 優化
**行動 9: 建立 AI 視覺審查 SOP**
```markdown
## AI 前端開發 SOP (新增)
1. AI 修改前端代碼
2. AI 執行 `pnpm exec tsc --noEmit` (已有)
3. 🆕 AI 執行瀏覽器截圖: `playwright screenshot`
4. 🆕 截圖存至 `docs/screenshots/{date}/{component}.png`
5. 🆕 更新 LOGBOOK: "已截圖，視覺狀態 XX"
6. 統帥審核截圖後批准或提供反饋
```
### 3.4 前端路線圖時間表
```
2026 Q1 (即時):
Week 1: i18n 清零全掃描 + 一次性修復
Week 2: Storybook 建立 + 10 核心組件上架
2026 Q2 前半:
Week 3-4: Omni-Terminal 後端全接通
Week 5-6: GenUI Registry 擴充 + 5 張新卡片
Week 7-8: Visual Regression Testing CI 整合
2026 Q2 後半:
Month 2: Knowledge Base 後端建設
Month 3: Topological Canvas MVP
2026 Q3:
Phase 4: 視覺靈魂注入 (品牌資產 + 微動畫)
```
---
## 第四章：後端服務盤點
### 4.1 leWOOOgo 積木化現況
| 積木類別 | 實作狀態 | 品質評分 |
|---------|---------|---------|
| **INPUT** | ✅ Webhook/Cron/Alert 全覆蓋 | 9/10 |
| **BRAIN** | ✅ LLM Router/RAG/Triage | 9/10 |
| **OUTPUT** | ✅ Telegram Gateway | 9/10 |
| **ACTION** | ✅ K8s/SSH Executor | 8/10 |
| **DATA** | ✅ Redis/PostgreSQL | 8/10 |
| **UI** | 🟡 GenUI 部分完成 | 6/10 |
### 4.2 核心服務健康度
| 服務 | 版本 | 測試覆蓋 | ADR | 問題 |
|------|------|---------|-----|------|
| `decision_manager.py` | - | 🟡 | ADR-003 | 首席架構師 Tier 3，修改需授權 |
| `trust_engine.py` | - | ✅ | ADR-003 | 穩健 |
| `telegram_gateway.py` | - | ✅32/32 | ADR-035 | 方法名稱曾出錯 (已修復) |
| `model_router.py` | - | ✅ | ADR-006/016 | 穩健 |
| `nvidia_provider.py` | - | ✅34/34 | ADR-036 | Circuit Breaker 完成 |
| `anomaly_counter.py` | v1.0 | ✅ | ADR-037 | 新完成，觀察期 |
| `learning_service.py` | v1.1 | ✅ | ADR-030 | Phase G 擴展完成 |
| `stats_service.py` | - | ✅ | ADR-024 | 已重構 (Router 層薄轉發) |
### 4.3 後端問題清單
#### 🔴 嚴重 (P0)
| # | 問題 | 根因 | 狀態 |
|---|------|------|------|
| B-01 | **Sentry Comment 回寫未完成** | Phase D 中 `post_sentry_comment` 是 TODO | 🚧 待實作 |
| B-02 | **GraphRAG 無持久化** | `graph_rag.py` 拓撲在記憶體中，重啟消失 | 🔴 技術債 |
| B-03 | **Knowledge Base 無後端** | 前端頁面空白，無對應 API | 🔴 缺失 |
#### 🟡 警告 (P1)
| # | 問題 | 根因 |
|---|------|------|
| B-04 | **CSRF Token 未驗證在所有敏感端點** | Phase 20 只覆蓋 Approvals，其他端點未驗證 |
| B-05 | **Slow Query 監控只有 5s/10s 警告，無自動優化** | `stats_service.py` 只有日誌，無動作 |
| B-06 | **Worker 只有 1 副本，無備援** | HPA 未設定 Worker，單點故障 |
### 4.4 長期解決方案
```
📌 路線圖：後端長期戰略
Phase B-A (立即執行, 1週):
├── B-01: 完成 Sentry Comment 回寫 (Phase D 文件已有代碼)
├── B-06: Worker HPA 設定 (min:1, max:3)
└── Phase E: SignOz Webhook Handler 部署
Phase B-B (中期, 1月):
├── B-02: GraphRAG 整合 Redis/Neo4j 持久化
├── B-03: Knowledge Base API 建設
└── B-04: CSRF 全站推廣
Phase B-C (長期, Q2):
├── B-05: 自動 Slow Query 優化建議 (AI 分析)
└── 完整 Learning Service 閉環 (自動更新 Playbook)
```
---
## 第五章：AI / 可觀測性盤點
### 5.1 AI 能力矩陣
| 能力 | 狀態 | 提供商 | 備援 |
|------|------|-------|------|
| **一般對話/RCA** | ✅ | Ollama → Gemini → Claude | 四層備援 |
| **Tool Calling** | ✅ | NVIDIA Nemotron → Gemini → Claude | Circuit Breaker |
| **LLMOps 追蹤** | ✅ | Langfuse | Traces 完整 |
| **OTEL 分佈追蹤** | ✅ | SigNoz | 25 targets |
| **錯誤追蹤** | ✅ | Sentry Self-Hosted | Webhook 整合 |
| **Prometheus 指標** | ✅ | 25/25 targets | - |
| **AI 信心透明化** | ✅ | confidence 真實值 | provider 標記 |
| **FinOps 成本追蹤** | 🟡 | cost_analyzer.py | 無 UI |
| **私有知識 RAG** | 🔴 | 實作但未上線 | - |
| **AI 自治率指數** | 🔴 | Autonomy Index 未建 | - |
### 5.2 可觀測性三支柱評分
| 支柱 | 完成度 | 問題 |
|------|-------|------|
| **Metrics (Prometheus)** | 95% | 雙 Prometheus 未聯邦 |
| **Logs (Structlog + Sentry)** | 90% | 少數服務無 trace_id 關聯 |
| **Traces (SigNoz OTEL)** | 85% | CI/CD OTEL 端點固定，難以切換環境 |
### 5.3 監控覆蓋率 (Phase 21 結果)
```
整體覆蓋率: 88.0%
├── Prometheus: 94.1% ✅
├── Sentry: 75% 🟡
├── OTEL: 80% 🟡
└── Auto-Repair: 40% 🔴 (需要加強)
└── 主要缺口: 資料庫 (Redis/PostgreSQL) 自動修復過於保守
```
### 5.4 AI 重大事故回顧
| 日期 | 事故 | 教訓 | 已防護 |
|------|------|------|-------|
| 2026-03-23 | Telegram logOut 災難 | 禁止 logOut | ✅ HARD_RULES |
| 2026-03-26 | Alertmanager 路徑錯誤 (2天無告警) | 指向 AWOOOI API 非 OpenClaw | ✅ ADR-025 |
| 2026-03-28 | SignOz OTEL 端點配置錯誤 | CI 檢查 OTEL 端點 | ✅ |
| 2026-03-29 | K8s Secrets 未注入 (長時間無告警) | 三層防護機制 | ✅ ADR-035 |
### 5.5 長期解決方案
```
📌 路線圖：AI & 可觀測性長期戰略
Phase A-A (立即執行, 1週):
├── 建立 Prometheus Federation (合併 .110 和 .188)
├── FinOps Dashboard 整合到前端 (cost_analyzer.py → UI)
└── 完成 Auto-Repair 覆蓋率 40% → 70%
Phase A-B (中期, 1月):
├── 建立 AI 自治率指數 (Autonomy Index Dashboard)
├── RAG 知識庫上線 (GraphRAG + Knowledge Base 整合)
└── Sentry Comment 回寫完成 (AI 分析回饋到 Issue)
Phase A-C (長期, Q2):
├── 實現「事件記憶迴廊」(Episodic Memory Vault)
├── Multi-Agent Debate 可視化 (@Investigator/@Strategist/@Guardrail)
└── AI 自動 Playbook 更新閉環 (Learning Service Phase G)
```
---
## 第六章：安全性盤點
### 6.1 安全機制現況
| 機制 | 狀態 | 評分 |
|------|------|------|
| **RBAC** (4 角色) | ✅ 實作 | 9/10 |
| **Multi-Sig** (多重簽核) | ✅ TOCTOU 防護 | 9/10 |
| **CSRF 防護** | 🟡 只覆蓋 Approvals | 7/10 |
| **Privacy Shield** (資料脫敏) | ✅ Consistent Hashing | 9/10 |
| **NetworkPolicy** | ✅ 命名空間隔離 | 8/10 |
| **Secrets Management** | ✅ K8s Secrets + 三層防護 | 9/10 |
| **Zero Trust (CORS)** | ✅ 白名單 | 9/10 |
| **Dry-Run 強制** | ✅ 所有 K8s 操作 | 9/10 |
| **Blast Radius 評估** | ✅ 風險矩陣 | 8/10 |
| **TLS 憑證監控** | ✅ 30d/7d/過期 告警 | 8/10 |
| **Kali 安全掃描** | 🔴 **未整合** | 2/10 |
### 6.2 安全缺口
| # | 缺口 | 風險等級 |
|---|------|---------|
| S-01 | **Kali 安全掃描孤立，未整合到 CI/CD** | 🔴 高 |
| S-02 | **CSRF 未覆蓋所有寫入端點** | 🟠 中 |
| S-03 | **Worker 節點直接 SSH 到其他主機** | 🟡 低 (有 RBAC) |
| S-04 | **SBOM (軟體物料清單) 缺失** | 🟡 低 |
---
## 第七章：未整合節點全清單
以下是所有**已建立但未完整整合**的節點，需要進行「最後一哩路」連接：
### 7.1 技術節點
| 節點 | 實作狀態 | 缺口 | 工時估算 |
|------|---------|------|---------|
| **Kali Security Scanner** | Docker 服務存在 | 無 AWOOOI Webhook | 2h |
| **GraphRAG 持久化** | `graph_rag.py` 完整 | 拓撲存在記憶體 | 4h |
| **FinOps Dashboard** | `cost_analyzer.py` 完整 | 無前端 UI | 8h |
| **Sentry Comment 回寫** | 框架已建 | TODO 片段 | 2h |
| **SignOz Webhook Handler** | 框架已建 | 部署未完成 | 2h |
| **Knowledge Base API** | 頁面存在 | 無後端 | 16h |
| **Omni-Terminal 全接通** | 前端殼完整 | GenUI SSE 事件 | 8h |
| **AI 自治率指數** | 概念設計 | 無實作 | 12h |
| **Worker HPA** | API/Web 已有 | Worker 未設定 | 1h |
| **Prometheus Federation** | 雙 Prom 運行 | 無聯邦配置 | 4h |
| **CSRF 全站覆蓋** | Approvals 有 | 其他端點缺 | 4h |
| **Visual Regression Test** | 無 | 全新建立 | 8h |
| **Storybook** | 無 | 全新建立 | 16h |
| **E2E CI 排程** | 測試已寫 | 無排程執行 | 1h |
**未整合節點總工時估算**: ~88 小時 (約 11 工作天)
### 7.2 優先度分級
```
🔴 P0 (立即 - 本週):
1. 完成 Sentry Comment 回寫 (2h)
2. SignOz Webhook 部署 (2h)
3. Worker HPA (1h)
4. E2E CI 排程 (1h)
5. i18n 違規一次性清零 (4h)
🟠 P1 (短期 - 本月):
6. Omni-Terminal GenUI 全接通 (8h)
7. Prometheus Federation (4h)
8. CSRF 全站覆蓋 (4h)
9. FinOps Dashboard UI (8h)
10. Kali Scanner 整合 (2h)
🟡 P2 (中期 - Q2):
11. Storybook 組件庫 (16h)
12. Visual Regression Testing (8h)
13. Knowledge Base 後端全建 (16h)
14. GraphRAG 持久化 (4h)
15. AI 自治率指數 (12h)
```
---
## 第八章：ADR 完整性稽核
### 8.1 ADR 覆蓋矩陣
| ADR | 標題 | 實作狀態 |
|-----|------|---------|
| ADR-001 | MCP Protocol 採用 | ✅ |
| ADR-002 | Nothing.tech 設計系統 | ✅ |
| ADR-003 | leWOOOgo 模組架構 | ✅ |
| ADR-004 | State Management (Zustand) | ✅ |
| ADR-005 | BFF 架構 | ✅ |
| ADR-006 | AI Fallback 策略 | ✅ |
| ADR-007 | 資料保留策略 | ✅ |
| ADR-008 | Python 模組化套件 | ✅ |
| ADR-009 | OpenClaw Agent Teams | ✅ |
| ADR-010 | Secrets 管理 | ✅ |
| ADR-011 | NetworkPolicy 治理 | ✅ |
| ADR-012 | 危險操作治理 | ✅ |
| ADR-013 | 代碼注解標準 | ✅ |
| ADR-014 | 依賴治理 | ✅ |
| ADR-015 | MCP 模組化架構 | ✅ |
| ADR-016 | K8s 資源命名 | ✅ |
| ADR-017 | LLMOps 可觀測性 | ✅ |
| ADR-018 | LLM 測試策略 | ✅ |
| ADR-019 | System Prompt 管理 | ✅ |
| ADR-020 | E2E 驗收框架 | 🟡 CI 未定期執行 |
| ADR-021 | Playbook 更新驗證 | ✅ |
| ADR-022 | Sentry 整合架構 | ✅ |
| ADR-023 | Smart Routing 架構 | ✅ |
| ADR-024 | API 層架構 | ✅ |
| ADR-025 | 告警鏈路 E2E 驗證 | ✅ |
| ADR-026 | CoreDNS GitOps | ✅ |
| ADR-027 | Incident-Approval 同步 | ✅ |
| ADR-028 | Auto-Repair Loop | ✅ |
| ADR-029 | CI/CD AI 整合 | ✅ |
| ADR-030 | 智能自動修復 | ✅ |
| ADR-031 | Omni-Terminal SSE 架構 | 🟡 後端未全接通 |
| ADR-032 | GenUI 動態渲染 | 🟡 Registry 部分完成 |
| ADR-033 | K3s HA 架構 | ✅ |
| ADR-034 | GitOps ArgoCD | ✅ |
| ADR-035 | Telegram 告警鏈路強制 | ✅ |
| ADR-036 | NVIDIA Nemotron Tool Calling | ✅ |
| ADR-037 | 監控增強架構 | ✅ |
**缺失的 ADR (建議新增)**:
| 建議 ADR | 主題 |
|---------|------|
| ADR-038 | Storybook 組件庫治理標準 |
| ADR-039 | Visual Regression Testing 策略 |
| ADR-040 | Kali 安全掃描整合架構 |
| ADR-041 | Knowledge Base RAG 架構 |
| ADR-042 | FinOps Dashboard 架構 |
---
## 第九章：總體評分卡
### 9.1 六維度評分
| 維度 | 分數 | 說明 |
|------|------|------|
| **基礎設施穩健性** | 88/100 | K3s HA + VIP + Velero 完整，但 Kali 孤立 |
| **後端工程品質** | 90/100 | 積木化優良，測試覆蓋高，少數 TODO |
| **前端 UI/UX 完整性** | 70/100 | **⚠️ 核心痛點**：i18n 違規 + GenUI 未接通 + Storybook 缺失 |
| **AI/可觀測性能力** | 90/100 | 五層 AI 備援 + 88% 監控覆蓋，FinOps 閒置 |
| **安全治理** | 85/100 | Multi-Sig/CSRF/NetworkPolicy 完整，Kali 未整合 |
| **DevOps/CI-CD** | 88/100 | 全自動 CD + 三層 Telegram 防護，E2E 未定期跑 |
**AWOOOI 整體評分**: **`87/100` — 強健 (Robust)**
### 9.2 三大戰略優先級
```
🎯 戰略優先級一：前端 UI/UX 主權計畫
目標：從「能用」升級到「驚艷」
方法：Storybook + Visual Regression + GenUI 全接通
工時：~50h
影響：AWOOOI 從監控工具蛻變為真正 AI 協作空間
🎯 戰略優先級二：後端最後一哩路
目標：從「已實作」升級到「已整合」
方法：完成 8 個孤立節點連接
工時：~24h
影響：整體功能覆蓋率 88% → 97%
🎯 戰略優先級三：安全主權強化
目標：將 Kali 整合進主流程
方法：建立 Scanner ADR + CI 掃描步驟
工時：~6h
影響：安全評分 85 → 95
```
---
## 第十章：執行路線圖 (Master Roadmap)
### Phase 22: 最後一哩路 (Phase of Integration)
```
Week 1 (3월 30일 - 4월 5일):
┌─────────────────────────────────────────────────┐
│ [P0] i18n 一次性閃電清零 (4h) │
│ [P0] Sentry Comment 回寫 Phase D 完成 (2h) │
│ [P0] SignOz Webhook Handler 部署 Phase E (2h) │
│ [P0] Worker HPA 設定 (1h) │
│ [P0] E2E Playwright CI 排程 (1h) │
└─────────────────────────────────────────────────┘
Week 2 (4월 6일 - 4월 12일):
┌─────────────────────────────────────────────────┐
│ [P1] Omni-Terminal GenUI 全接通 Phase 22A (8h) │
│ [P1] Prometheus Federation 合併 (4h) │
│ [P1] CSRF 全站覆蓋 (4h) │
└─────────────────────────────────────────────────┘
Week 3-4 (4월 13일 - 4월 26일):
┌─────────────────────────────────────────────────┐
│ [P1] FinOps Dashboard 前端整合 (8h) │
│ [P1] Kali Scanner ADR + CI 整合 (6h) │
│ [P2] Storybook 組件庫 MVP (16h) │
└─────────────────────────────────────────────────┘
Month 2-3 (5월 - 6월):
┌─────────────────────────────────────────────────┐
│ [P2] Visual Regression Testing (8h) │
│ [P2] Knowledge Base 後端全建 (16h) │
│ [P2] GraphRAG 持久化 (4h) │
│ [P2] AI 自治率指數 Dashboard (12h) │
│ [P2] Topological Canvas MVP (24h) │
└─────────────────────────────────────────────────┘
Q3 (Phase 4 啟動):
┌─────────────────────────────────────────────────┐
│ [視覺靈魂注入] 品牌資產 + 微動畫升級 │
│ [開源準備] README + 商業化包裝 │
└─────────────────────────────────────────────────┘
```
---
## 附錄 A：快速參考索引
| 主題 | 文件 |
|------|------|
| 基礎設施參考 | `docs/reference/SERVICE-ENDPOINTS.md` |
| K3s 維運手冊 | `docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md` |
| 監控完整策略 | `docs/MONITORING_COMPLETE_STRATEGY.md` |
| ADR 目錄 | `docs/adr/` (ADR-001 ~ ADR-037) |
| 服務註冊表 | `ops/monitoring/service-registry.yaml` |
| 技術債清單 | `docs/TECHNICAL_DEBT_PHASE2.md` |
| Agentic Workspace 藍圖 | `docs/AWOOOI_AGENTIC_WORKSPACE_ROADMAP.md` |
| 首席架構師 K3s 審查 | `memory/project_k3s_full_arch_review.md` |
| 未竟 Phase 計畫 | `docs/proposals/IMPLEMENTATION_STEPS_REMAINING_PHASES.md` |
---
## 附錄 B：關鍵決策記錄
| 決策 | 選擇 | 原因 |
|------|------|------|
| **腦架構** | 單一大腦 (.188) + 分散感測器 | 防腦分裂，記憶不同步 |
| **設計風格** | Nothing.tech 純白工業風 | 2026-03-20 戰略轉向，廢深色駭客風 |
| **UAT 環境** | 禁止，只有 Dev + Prod | 簡化複雜度，快速迭代 |
| **AI 備援** | Ollama → Gemini → Claude (一般) / NVIDIA → Gemini → Claude (Tool Call) | Zero-Cost First |
| **測試策略** | 禁止 Mock，只允許真實 DB | 統帥 2026-03-24 明確指示 |
| **映像標籤** | 唯一不可變 {sha}-{run_id} | 防 Ghost Rollback |
| **Telegram** | 三層防護 (Pre-flight/Deploy/Post-Deploy) | ADR-035 |
---
*報告完整涵蓋了 AWOOOI Phase 21 (Day 12) 截至 2026-03-29 的全部已知狀態。*
*建議每季更新此報告，並在 LOGBOOK 中記錄盤點節點。*
**「AI Sees. AI Acts. You Approve.」** 🦞

351
docs/INSPIRATION_LAB.md Normal file
View File

@@ -0,0 +1,351 @@
# AWOOOI Inspiration Lab
> **版本**: 1.0
> **建立日期**: 2026-03-28 (台北時間)
> **建立者**: Claude Code
> **用途**: 收集所有學習、模仿、發想、討論未定案的內容
---
## 使用說明
這個文件是 **靈感實驗室**，用於收集：
- 從外部學習/模仿的設計
- 突發奇想但尚未決定的功能
- 討論中但未定案的架構
- 未來可能採用的工具/服務
**注意**: 這裡的內容都是 **待評估** 狀態，採用前需統帥批准。
---
## 目錄
1. [視覺設計 (Visual)](#1-視覺設計-visual)
2. [UI/UX 互動](#2-uiux-互動)
3. [風格參考 (Style)](#3-風格參考-style)
4. [功能構想 (Features)](#4-功能構想-features)
5. [工具評估 (Tools)](#5-工具評估-tools)
6. [服務/平台 (Services)](#6-服務平台-services)
7. [突發奇想 (Wild Ideas)](#7-突發奇想-wild-ideas)
8. [待討論 (Pending Discussion)](#8-待討論-pending-discussion)
---
## 1. 視覺設計 (Visual)
### 1.1 NVIDIA Build 卡片網格 ✨ NEW
> **來源**: https://build.nvidia.com/search?categories=models&q=Nemotron
> **新增日期**: 2026-03-28
> **狀態**: 🟡 待整合至 Nothing.tech 風格
> **統帥指示**: 「這網頁的視覺呈現、風格、卡片樣式等等的、UI/UX，就是我們要參考的！」
#### 🔴 整合原則 (最重要!)
**統帥明確指示**: 不要變動原本定義的視覺呈現風格規範，要把學習模仿到的這些整合進去，但是還是以原本的定義規範為主！
| 層級 | 來源 | 說明 |
|------|------|------|
| **主** | Nothing.tech 純白工業風 | 見 `01-awoooi-frontend-aesthetics.md` |
| **從** | NVIDIA Build | 本節內容，僅供參考整合 |
#### 整合對照表
| NVIDIA 元素 | 採用? | 整合方式 |
|-------------|-------|----------|
| 深色主題 (`manitoulinLightBlack`) | ❌ 衝突 | 維持 `bg-white/70 backdrop-blur-[20px]` |
| 半透明邊框 (`white/20`) | ⚠️ 轉換 | 改為 `border-nothing-black/20` |
| 卡片結構/排版 | ✅ 參考 | 套用至純白磨砂玻璃卡片 |
| 間距系統 | ✅ 採用 | `px-4 pt-4 lg:px-8` |
| 最大寬度 | ✅ 採用 | `max-w-[1920px]` |
| 篩選器多維度設計 | ✅ 參考 | 改為白色風格 + Glacier Blue 強調 |
| 導航結構 | ✅ 參考 | 頂部導航 + 側邊篩選 |
| 響應式斷點 | ✅ 採用 | Mobile/lg/超寬 |
| Hover 效果 | ⚠️ 轉換 | 改為 `hover:text-glacier-blue` |
| 字體 | ❌ 衝突 | 維持 `VT323` 點陣風格 |
#### NVIDIA 原版設計規格
**1. 配色系統**
| 元素 | 設計 |
|------|------|
| 背景色 | 深色主題 (Deep Black)，營造專業科技感 |
| 主色調 | 黑色 + 深灰色為基礎 |
| 強調色 | 白色文字、半透明邊框 (`border-white/20`) |
| 對比 | 高對比度，文字清晰易讀 |
**2. 卡片設計**
- 邊框: 細微半透明邊框 (`border-white/20`)
- 背景: 略淺於頁面背景，創造層次感
- 圓角: 現代感圓角設計
- Hover 效果: 文字變亮 (`hover:text-n000`)
- 陰影: 低調陰影，不喧賓奪主
**3. 排版布局**
- 最大寬度: 1920px (超寬螢幕適配)
- Grid 系統: Flexbox + Grid 混合
- 間距: Mobile `px-4 pt-4` / Desktop `lg:px-8`
- 響應式: 完整行動裝置適配
**4. 字體風格**
- 標題: 粗體、大尺寸、高對比
- 內文: 清晰可讀、適當行高
- 技術感: Sans-serif 字體為主
**5. 搜尋/篩選介面**
- 多層篩選機制: Use Case / Provider / Publisher
- 即時搜尋: 支援快捷鍵 (⌘K)
- 標籤/Badge: 清楚標示分類
**6. 導航結構**
- 頂部導航: Explore | Models | Blueprints | GPUs | Docs
- 層級清晰: 主導航 + 側邊篩選 + 內容區
- 快捷鍵支援: ⌘K 快速搜尋
#### 🔄 風格轉換範例
**卡片 (NVIDIA → Nothing.tech)**
```tsx
// ❌ NVIDIA 原版 (深色)
<div className="bg-manitoulinLightBlack border-white/20 hover:text-n000">
// ✅ AWOOOI 轉換 (純白工業風)
<div className="bg-white/70 backdrop-blur-[20px] border-2 border-nothing-black shadow-lg/20 hover:border-glacier-blue">
```
**篩選器 Badge (NVIDIA → Nothing.tech)**
```tsx
// ❌ NVIDIA 原版
<span className="bg-n700 text-n000 text-xs">Provider</span>
// ✅ AWOOOI 轉換
<span className="bg-glacier-blue/10 text-nothing-black border border-glacier-blue font-vt323 text-xs">Provider</span>
```
**導航連結 (NVIDIA → Nothing.tech)**
```tsx
// ❌ NVIDIA 原版
<a className="text-n500 hover:text-n000">Models</a>
// ✅ AWOOOI 轉換
<a className="text-nothing-black/70 hover:text-glacier-blue font-vt323">Models</a>
```
#### 應用場景
| 場景 | 參考元素 |
|------|----------|
| Dashboard 卡片 | 卡片結構、間距、Grid |
| 模型/服務列表 | 卡片網格、標籤系統 |
| 篩選介面 | 多維度篩選 UI |
| 導航結構 | 頂部導航 + 側邊欄 |
---
### 1.2 (預留位置)
<!-- 未來新增視覺參考時填入 -->
---
## 2. UI/UX 互動
### 2.1 NVIDIA 多維度篩選器
> **來源**: build.nvidia.com
> **狀態**: 🟡 可參考
> **關聯**: 見 [1.1 NVIDIA Build 卡片網格](#11-nvidia-build-卡片網格--new)
**設計模式**:
```
┌─────────────────────────────────────────────┐
│ Sidebar Filters │
│ ┌─────────────────────────────────────────┐│
│ │ Use Case ││
│ │ □ Object Detection ││
│ │ □ RAG ││
│ │ □ Text Embedding ││
│ └─────────────────────────────────────────┘│
│ ┌─────────────────────────────────────────┐│
│ │ Provider ││
│ │ □ Deep Infra ││
│ │ □ Together AI ││
│ └─────────────────────────────────────────┘│
│ ┌─────────────────────────────────────────┐│
│ │ Publisher ││
│ │ □ NVIDIA ││
│ │ □ Mistral AI ││
│ └─────────────────────────────────────────┘│
└─────────────────────────────────────────────┘
```
**AWOOOI 風格轉換**:
```tsx
// ✅ 篩選器容器 (Nothing.tech 風格)
<aside className="w-64 bg-white/50 backdrop-blur-sm border-r border-nothing-black/10 p-4">
<div className="space-y-4">
{/* 篩選群組 */}
<div className="border border-nothing-black/20 rounded-lg p-3">
<h3 className="font-vt323 text-sm text-nothing-black mb-2">Use Case</h3>
<label className="flex items-center gap-2 text-sm">
<input type="checkbox" className="accent-glacier-blue" />
<span className="font-vt323">Object Detection</span>
</label>
</div>
</div>
</aside>
```
**可應用場景**:
- Knowledge Base 文件篩選
- Action Log 多條件過濾
- 模型/服務列表
- Incident 歷史查詢
---
### 2.2 快捷鍵搜尋 (⌘K)
> **來源**: build.nvidia.com, Linear, Notion
> **狀態**: 🟢 已有類似實作 (Omni-Terminal)
**增強方向**:
- 全局搜尋 (跨頁面)
- 命令面板 (Command Palette)
- 模糊搜尋 + 熱鍵提示
---
## 3. 風格參考 (Style)
### 3.1 企業級深色主題
> **來源**: NVIDIA, Vercel, Linear
> **狀態**: ❌ 不採用 (與 Nothing.tech 衝突)
**記錄原因**: 統帥明確指示維持純白工業風
---
### 3.2 (預留位置)
<!-- 未來新增風格參考時填入 -->
---
## 4. 功能構想 (Features)
### 4.1 (預留位置)
<!-- 未來新增功能構想時填入 -->
---
## 5. 工具評估 (Tools)
### 5.1 (預留位置)
<!-- 未來評估工具時填入，例如:
- 新的監控工具
- 新的 CI/CD 工具
- 新的測試框架
-->
---
## 6. 服務/平台 (Services)
### 6.1 NVIDIA NIM APIs ✅ 已實測
> **來源**: build.nvidia.com
> **狀態**: 🟢 **評估通過，建議整合**
> **測試日期**: 2026-03-28
**說明**: NVIDIA 提供的雲端 AI 模型 API 服務
**可用模型** (Nemotron 系列):
- `nvidia/nemotron-mini-4b-instruct` - 輕量、Tool Calling 專用
- `nvidia/llama-3.1-nemotron-70b-instruct` - 複雜推理
- Nemotron-3 系列 (MoE 架構)
**實測結果 (2026-03-28)**:
| 指標 | Nemotron (NIM) | Ollama (CPU) |
|------|----------------|--------------|
| **Tool Calling 精準度** | 83.3% (5/6) | ~50% |
| **平均延遲** | 11-23 秒 | 100+ 秒 |
| **最慢延遲** | 45 秒 | 超時 |
| **繁中支援** | ✅ 良好 | ✅ 良好 |
| **成本** | 免費 tier | 免費 |
**結論**:
- ✅ Tool Calling 精準度比 Ollama 高
- ✅ 延遲比 CPU Ollama 快 5-10 倍
- ⚠️ 免費 tier 有排隊延遲 (11-45 秒)
- ⚠️ 不適合即時對話，適合背景/批次任務
**建議用途**:
- OpenClaw Tool Calling 決策
- Incident 分析 (背景任務)
- Playbook 生成
**整合提案**: [NEMOTRON-INTEGRATION-PROPOSAL.md](proposals/NEMOTRON-INTEGRATION-PROPOSAL.md)
---
### 6.2 (預留位置)
<!-- 未來評估服務時填入 -->
---
## 7. 突發奇想 (Wild Ideas)
### 7.1 (預留位置)
<!-- 記錄任何突發奇想，不論可行性
格式範例:
> **想法**: xxx
> **來源**: 統帥/Claude/外部
> **日期**: 2026-xx-xx
> **可行性**: 🟢/🟡/🔴
> **備註**: xxx
-->
---
## 8. 待討論 (Pending Discussion)
### 8.1 (預留位置)
<!-- 需要與統帥討論確認的項目
格式範例:
> **議題**: xxx
> **背景**: xxx
> **選項**:
> - A: xxx
> - B: xxx
> **建議**: xxx
> **狀態**: 待討論
-->
---
## 狀態圖例
| 圖示 | 狀態 | 說明 |
|------|------|------|
| 🟢 | 已採用/已實作 | 已整合至專案 |
| 🟡 | 待整合 | 已批准，待實作 |
| 🔵 | 觀察中 | 持續評估 |
| 🔴 | 不採用 | 已決定不使用 |
| ⚪ | 未評估 | 尚未開始評估 |
---
## 變更紀錄
| 日期 | 執行者 | 變更內容 |
|------|--------|----------|
| 2026-03-28 | Claude Code | 初始建立，加入 NVIDIA Build 參考 |

43
docs/adr/ADR-006-ai-fallback-strategy.md
View File

@@ -405,6 +405,48 @@ GET /api/v1/health/ai-usage
---
---
## 8. NVIDIA Nemotron 整合 (v1.3)
> 參考: [ADR-036 Nemotron Tool Calling 整合](ADR-036-nemotron-tool-calling-integration.md)
### 背景
2026-03-28 統帥指示評估 NVIDIA Nemotron 模型。實測結果 Tool Calling 精準度 83.3%，顯著優於 CPU Ollama (~50%)。
### Provider 更新
| Provider | 用途 | 延遲 | 精準度 | 成本 |
|----------|------|------|--------|------|
| **Ollama** | 即時對話、簡單查詢 | < 5s | 中 | $0 |
| **Nemotron** | Tool Calling、K8s 操作 | 11-45s | 高 (83%) | 免費 tier |
| **Gemini** | 通用備援 | 2-5s | 中高 | 低 |
| **Claude** | 複雜推理、CRITICAL | 2-5s | 最高 | 高 |
### 路由規則更新
```
任務類型 → 路由目標
────────────────────────────────
Tool Calling → Nemotron (精準度高)
即時對話 → Ollama (低延遲)
複雜推理 → Claude (最強)
通用備援 → Gemini (平衡)
```
### Fallback 鏈
```
Tool Calling 任務:
Nemotron → Gemini → Claude → 拒絕執行
一般對話任務 (不變):
Ollama → Gemini → Claude → Static Response
```
---
## 變更記錄
| 日期 | 版本 | 變更 | 作者 |
@@ -412,6 +454,7 @@ GET /api/v1/health/ai-usage
| 2026-03-20 | v1.0 | 初版建立 | CTO |
| 2026-03-26 | v1.1 | 新增智能路由整合章節 (Phase 13.3) | 首席架構師 |
| 2026-03-26 | v1.2 | 新增 Rate Limiter 實作章節 | 首席架構師 |
| 2026-03-29 | v1.3 | 新增 NVIDIA Nemotron 整合章節 (待統帥批准) | 首席架構師 |
---

26
docs/meetings/2026-03-28-k3s-optimization-deep-dive.md
View File

@@ -602,10 +602,10 @@ Week 3 (2026-04-11 ~ 04-17)
| # | 決策點 | 選項 | 建議 | 狀態 |
|---|--------|------|------|------|
| 1 | HA 架構選擇 | A: 3-Master / B: 外接 PostgreSQL / C: 維持現狀 | B | ⏳ 待統帥決策 |
| 2 | Longhorn 部署時機 | 立即 / 等有狀態需求 | 等待 | ⏳ 待統帥決策 |
| 3 | Legacy Namespace 清理 | 立即 / 觀察 1 個月 | 觀察後清理 | ⏳ 待統帥決策 |
| 4 | K0 執行時機 | 今天 / 週末維護窗口 | 今天開始 | ⏳ 待統帥決策 |
| 1 | HA 架構選擇 | A: 3-Master / B: 外接 PostgreSQL / C: 維持現狀 | B | ✅ **方案 B 已執行** (2026-03-28) |
| 2 | Longhorn 部署時機 | 立即 / 等有狀態需求 | 等待 | ⏳ 延後 (無狀態需求) |
| 3 | Legacy Namespace 清理 | 立即 / 觀察 1 個月 | 觀察後清理 | 🟡 待 Velero 部署後執行 |
| 4 | K0 執行時機 | 今天 / 週末維護窗口 | 今天開始 | ✅ **已完成** (2026-03-28) |
---
@@ -622,15 +622,15 @@ AWOOOI K3s 環境已具備 **41% 的生產級優化項目**，包括：
### 8.2 主要差距
| 差距 | 風險等級 | 處理建議 |
|------|---------|---------|
| 單 Master 架構 | 🔴 高 | 短期接受，中期改善 |
| Swap 開啟 | 🔴 高 | **立即關閉** |
| 無資源預留 | 🔴 高 | **立即設定** |
| 無 etcd 備份 | 🔴 高 | **立即設定** |
| 無 GitOps | 🔴 高 | 2 週內部署 ArgoCD |
| 無 PDB | 🔴 高 | **立即建立** |
| 無 Startup Probe | ⚠️ 中 | **立即新增** |
| 差距 | 風險等級 | 處理建議 | 狀態 |
|------|---------|---------|------|
| 單 Master 架構 | 🔴 高 | 短期接受，中期改善 | ✅ **雙 CP 已完成** |
| Swap 開啟 | 🔴 高 | **立即關閉** | ✅ **已關閉** |
| 無資源預留 | 🔴 高 | **立即設定** | ✅ **已設定** |
| 無 etcd 備份 | 🔴 高 | **立即設定** | ✅ **已設定** |
| 無 GitOps | 🔴 高 | 2 週內部署 ArgoCD | ❌ K2 待執行 |
| 無 PDB | 🔴 高 | **立即建立** | ✅ **已建立** |
| 無 Startup Probe | ⚠️ 中 | **立即新增** | ✅ **已新增** |
### 8.3 下一步行動

551
docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md
View File

@@ -1,11 +1,11 @@
# K3s 優化實施 Runbook
> **版本**: 1.2
> **版本**: 2.0
> **建立日期**: 2026-03-28 (台北時間)
> **建立者**: Claude Code (首席架構師)
> **最後修改**: 2026-03-28 21:00 (台北時間)
> **最後修改**: 2026-03-28 20:45 (台北時間)
> **修改者**: Claude Code
> **狀態**: ✅ Phase K0 + K-NET + K-CLEAN 已完成
> **狀態**: ✅ K0/K-NET/K-HA/K-CLEAN 完成 | 📋 K1-K4 待執行 (~36h)
---
@@ -16,6 +16,8 @@
| 1.0 | 2026-03-28 | Claude Code | 初始建立 |
| 1.1 | 2026-03-28 | Claude Code | 新增安全執行順序、Alertmanager 靜音、穩定性驗證 |
| 1.2 | 2026-03-28 | Claude Code | **標記完成狀態**: K0 ✅ + K-NET ✅ + K-CLEAN ✅ |
| 1.3 | 2026-03-28 | Claude Code | **K-HA 完成**: 雙 Control-Plane + PostgreSQL Datastore |
| 2.0 | 2026-03-28 | Claude Code | **新增 K1-K4 完整實作步驟** + 15 項異常修復記錄 |
---
@@ -25,10 +27,14 @@
1. [環境基線](#1-環境基線)
2. [Phase K0: 緊急修復](#2-phase-k0-緊急修復) ✅ **已完成**
3. [Phase K-NET: 網路架構 (keepalived)](#3-phase-k-net-網路架構) ✅ **已完成**
4. [Phase K-HA: HA 升級](#4-phase-k-ha-ha-升級) 📋 **待規劃**
4. [Phase K-HA: HA 升級](#4-phase-k-ha-ha-升級) ✅ **已完成**
5. [Phase K-CLEAN: 清理腳本](#5-phase-k-clean-清理腳本) ✅ **已完成**
6. [驗證檢查清單](#6-驗證檢查清單)
7. [回滾程序](#7-回滾程序)
6. [Phase K1: 災難恢復 (Velero)](#6-phase-k1-災難恢復) ❌ **待執行**
7. [Phase K2: 自動化維運 (ArgoCD/VPA/NPD)](#7-phase-k2-自動化維運) ❌ **待執行**
8. [Phase K3: 儲存與 HPA](#8-phase-k3-儲存與-hpa) ❌ **待執行**
9. [Phase K4: 進階優化 (Kured/Descheduler)](#9-phase-k4-進階優化) ❌ **待執行**
10. [驗證檢查清單](#10-驗證檢查清單)
11. [回滾程序](#11-回滾程序)
---
@@ -991,9 +997,49 @@ curl -sk https://192.168.0.125:6443/healthz
---
## 4. Phase K-HA: HA 升級 📋 待規劃
## 4. Phase K-HA: HA 升級 ✅ 已完成
> **狀態**: ✅ 2026-03-28 19:35 完成
> **執行者**: Claude Code + 統帥
> **停機時間**: ~20 分鐘
### K-HA 執行結果摘要
| 步驟 | 說明 | 狀態 |
|------|------|------|
| K-HA.1 | PostgreSQL 建立 (188:5432) | ✅ k3s_datastore + k3s_admin |
| K-HA.2 | SQLite 備份 | ✅ state.db.pre-ha-* |
| K-HA.3 | 120 datastore-endpoint 配置 | ✅ 重啟成功 |
| K-HA.4 | 121 Agent→Server 升級 | ✅ 雙 Control-Plane |
| K-HA.5 | 服務重部署 | ✅ CD force_deploy |
| K-HA.6 | 健康驗證 | ✅ 所有組件 up |
### 架構變更
```
遷移前:
120 (Server/Control-Plane) ─── SQLite (Kine)
121 (Agent/Worker)
遷移後:
120 (Server/Control-Plane) ─┬─ PostgreSQL (188:5432/k3s_datastore)
121 (Server/Control-Plane) ─┘
VIP: 192.168.0.125 (keepalived)
```
### 修復過程中的問題
| 問題 | 解決方案 |
|------|----------|
| SENTRY_DSN "CHANGE_ME" | 改為空字串 |
| DATABASE_URL 缺 +asyncpg | 修正為 `postgresql+asyncpg://` |
| awoooi DB 密碼不符 | 更新 PostgreSQL 使用者密碼 |
| kubeconfig 權限 | K3s 重啟後需重新設定 |
---
### K-HA 原規劃內容 (已執行)
> **狀態**: 另案規劃 (需維護窗口 30+ 分鐘)
> **前置條件**: PostgreSQL 準備、完整備份、通知用戶
> **風險等級**: 🔴 高風險
@@ -1191,9 +1237,384 @@ echo "=== 清理完成 ==="
---
## 6. 驗證檢查清單
## 6. Phase K1: 災難恢復 (P1) - 8h ❌ 未開始
### 6.1 Phase K0 驗證
> **狀態**: 📋 待執行
> **前置條件**: K0 完成 ✅
> **預估時間**: 8 小時
### 6.1 K1.1 - 部署 Velero 備份系統
#### 6.1.1 建立 MinIO 儲存 (188) - 30m
```bash
# SSH 到 188
ssh ollama@192.168.0.188
# 建立 MinIO 目錄
sudo mkdir -p /data/minio
sudo chown -R 1000:1000 /data/minio
# Docker Compose 方式部署
cat > ~/minio/docker-compose.yml << 'EOF'
version: '3.8'
services:
minio:
image: minio/minio:RELEASE.2024-03-26T22-10-45Z
container_name: minio
command: server /data --console-address ":9001"
environment:
MINIO_ROOT_USER: minio_admin
MINIO_ROOT_PASSWORD: Minio_Secure_2026!
volumes:
- /data/minio:/data
ports:
- "9000:9000"
- "9001:9001"
restart: unless-stopped
EOF
cd ~/minio && docker-compose up -d
# 驗證
curl http://192.168.0.188:9000/minio/health/live
```
#### 6.1.2 安裝 Velero CLI - 10m
```bash
# 在 120 (Master) 上執行
wget https://github.com/vmware-tanzu/velero/releases/download/v1.13.0/velero-v1.13.0-linux-amd64.tar.gz
tar -xvf velero-v1.13.0-linux-amd64.tar.gz
sudo mv velero-v1.13.0-linux-amd64/velero /usr/local/bin/
velero version
```
#### 6.1.3 部署 Velero 到 K3s - 20m
```bash
# 建立 credentials 檔案
cat > /tmp/credentials-velero << 'EOF'
[default]
aws_access_key_id=minio_admin
aws_secret_access_key=Minio_Secure_2026!
EOF
# 安裝 Velero
velero install \
--provider aws \
--plugins velero/velero-plugin-for-aws:v1.9.0 \
--bucket velero-backups \
--secret-file /tmp/credentials-velero \
--backup-location-config region=minio,s3ForcePathStyle=true,s3Url=http://192.168.0.188:9000 \
--use-volume-snapshots=false
# 驗證
kubectl get pods -n velero
velero backup-location get
```
#### 6.1.4 配置備份 Schedule - 15m
```bash
# 每日凌晨 3 點備份 awoooi-prod
velero schedule create awoooi-daily \
--schedule="0 3 * * *" \
--include-namespaces awoooi-prod \
--ttl 168h
# 驗證
velero schedule get
```
#### 6.1.5 測試備份/還原 - 30m
```bash
# 手動觸發備份
velero backup create awoooi-test-$(date +%Y%m%d) --include-namespaces awoooi-prod
# 查看備份狀態
velero backup describe awoooi-test-$(date +%Y%m%d)
# 模擬災難：刪除一個 ConfigMap (僅測試用)
kubectl get cm -n awoooi-prod
# 還原
velero restore create --from-backup awoooi-test-$(date +%Y%m%d)
# 驗證還原
velero restore describe <restore-name>
```
---
## 7. Phase K2: 自動化維運 (P2) - 12h ❌ 未開始
> **狀態**: 📋 待執行
> **前置條件**: K0 完成 ✅
> **預估時間**: 12 小時
### 7.1 K2.1 - 部署 ArgoCD (GitOps)
#### 7.1.1 安裝 ArgoCD - 15m
```bash
# 建立 namespace
kubectl create namespace argocd
# 安裝 ArgoCD
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# 暴露為 NodePort
kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "NodePort", "ports": [{"port": 443, "nodePort": 30443}]}}'
# 取得初始密碼
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
# 存取 UI: https://192.168.0.125:30443
```
#### 7.1.2 連接 Git Repo - 30m
```bash
# 下載 ArgoCD CLI
curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x /usr/local/bin/argocd
# 登入
argocd login 192.168.0.125:30443
# 新增 AWOOOI repo
argocd repo add https://github.com/your-org/awoooi.git \
--username <github-user> \
--password <github-token>
```
#### 7.1.3 建立 Application - 30m
```yaml
# argocd-awoooi-prod.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: awoooi-prod
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/your-org/awoooi.git
targetRevision: main
path: k8s/awoooi-prod
destination:
server: https://kubernetes.default.svc
namespace: awoooi-prod
syncPolicy:
automated:
prune: true
selfHeal: true
```
### 7.2 K2.2 - 部署 Sealed Secrets
```bash
# 安裝 kubeseal CLI
wget https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.26.0/kubeseal-0.26.0-linux-amd64.tar.gz
tar -xvf kubeseal-0.26.0-linux-amd64.tar.gz
sudo mv kubeseal /usr/local/bin/
# 部署 Controller
kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.26.0/controller.yaml
# 加密現有 Secret
kubeseal --format yaml < k8s/awoooi-prod/03-secrets.yaml > k8s/awoooi-prod/03-sealed-secrets.yaml
```
### 7.3 K2.3 - 部署 VPA
```bash
# 安裝 VPA
git clone https://github.com/kubernetes/autoscaler.git
cd autoscaler/vertical-pod-autoscaler
./hack/vpa-up.sh
# 建立 VPA 資源 (Off 模式 - 僅建議)
cat > k8s/awoooi-prod/11-vpa.yaml << 'EOF'
apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
name: awoooi-api-vpa
namespace: awoooi-prod
spec:
targetRef:
apiVersion: apps/v1
kind: Deployment
name: awoooi-api
updatePolicy:
updateMode: "Off"
EOF
kubectl apply -f k8s/awoooi-prod/11-vpa.yaml
```
### 7.4 K2.4 - 部署 Node Problem Detector
```bash
# 安裝 NPD
kubectl apply -f https://raw.githubusercontent.com/kubernetes/node-problem-detector/master/deployment/node-problem-detector.yaml
# 驗證
kubectl get pods -n kube-system -l app=node-problem-detector
```
---
## 8. Phase K3: 儲存與 HPA (P3) - 10h ❌ 未開始
> **狀態**: 📋 待執行
> **前置條件**: K0 完成 ✅
> **預估時間**: 10 小時
### 8.1 K3.1 - Longhorn 評估
| 評估項 | 現況 | 決策 |
|--------|------|------|
| 有狀態需求 | AWOOOI 全無狀態 | 延後 |
| OpenClaw 遷入 | 保持容器層部署 | 暫不需要 |
**結論**: Longhorn 暫不部署，待有狀態需求時再評估
### 8.2 K3.2 - 配置 HPA
```yaml
# k8s/awoooi-prod/10-hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: awoooi-api-hpa
namespace: awoooi-prod
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: awoooi-api
minReplicas: 2
maxReplicas: 4
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
- type: Resource
resource:
name: memory
target:
type: Utilization
averageUtilization: 80
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: awoooi-web-hpa
namespace: awoooi-prod
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: awoooi-web
minReplicas: 2
maxReplicas: 4
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
```
```bash
kubectl apply -f k8s/awoooi-prod/10-hpa.yaml
kubectl get hpa -n awoooi-prod
```
---
## 9. Phase K4: 進階優化 (P4) - 6h ❌ 未開始
> **狀態**: 📋 待執行
> **前置條件**: K2 完成
> **預估時間**: 6 小時
### 9.1 K4.1 - 部署 Kured
```bash
# 安裝 Kured
kubectl apply -f https://github.com/weaveworks/kured/releases/latest/download/kured-1.14.1-dockerhub.yaml
# 配置維護窗口 (凌晨 3-5 點)
kubectl patch daemonset kured -n kube-system --type=json -p='[
{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--start-time=03:00"},
{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--end-time=05:00"},
{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--time-zone=Asia/Taipei"}
]'
```
### 9.2 K4.2 - 部署 Descheduler
```yaml
# descheduler-policy.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: descheduler-policy
namespace: kube-system
data:
policy.yaml: |
apiVersion: "descheduler/v1alpha2"
kind: "DeschedulerPolicy"
profiles:
- name: default
pluginConfig:
- name: "RemoveDuplicates"
args:
excludeOwnerKinds:
- "DaemonSet"
- name: "LowNodeUtilization"
args:
thresholds:
cpu: 20
memory: 20
targetThresholds:
cpu: 50
memory: 50
```
### 9.3 K4.3 - 清理 Legacy Namespace
```bash
# 步驟 1: 先用 Velero 備份
velero backup create legacy-wooo-aiops-$(date +%Y%m%d) \
--include-namespaces wooo-aiops-uat,wooo-aiops-prod
# 步驟 2: 確認備份成功
velero backup describe legacy-wooo-aiops-$(date +%Y%m%d)
# 步驟 3: 停用服務 (觀察 1 週)
kubectl scale deploy --all -n wooo-aiops-uat --replicas=0
kubectl scale deploy --all -n wooo-aiops-prod --replicas=0
# 步驟 4: 確認無依賴後刪除
kubectl delete ns wooo-aiops-uat
kubectl delete ns wooo-aiops-prod
```
---
## 10. 驗證檢查清單
### 10.1 Phase K0 驗證
| # | 檢查項目 | 命令 | 預期結果 |
|---|---------|------|---------|
@@ -1206,7 +1627,7 @@ echo "=== 清理完成 ==="
| 7 | 無異常 Pod | `kubectl get pods -n awoooi-prod` | 全部 Running |
| 8 | 孤立 RS 清理 | `kubectl get rs -n awoooi-prod \| wc -l` | ≤ 9 |
### 6.2 Phase K-HA 驗證
### 10.2 Phase K-HA 驗證
| # | 檢查項目 | 命令 | 預期結果 |
|---|---------|------|---------|
@@ -1217,9 +1638,9 @@ echo "=== 清理完成 ==="
---
## 7. 回滾程序
## 11. 回滾程序
### 7.1 K0 回滾 (低風險)
### 11.1 K0 回滾 (低風險)
```bash
# 還原 fstab (重新啟用 Swap)
@@ -1231,7 +1652,7 @@ sudo mv /etc/rancher/k3s/config.yaml.backup /etc/rancher/k3s/config.yaml
sudo systemctl restart k3s
```
### 7.2 K-HA 回滾 (高風險)
### 11.2 K-HA 回滾 (高風險)
```bash
# 步驟 1: 停止 K3s (兩節點)
@@ -1261,7 +1682,7 @@ curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="agent" sh -s - \
### ✅ 實際執行紀錄 (2026-03-28)
```
Day 0 (2026-03-28) - Phase K0 + K-NET + K-CLEAN ✅ 全部完成
Day 0 (2026-03-28) - Phase K0 + K-NET + K-CLEAN + K-HA ✅ 全部完成
├── 09:00 - 統帥批准 Phase K0 ✅
├── 09:30 - K0.1 關閉 Swap (120 + 121) ✅
├── 10:00 - K0.2 config.yaml + registries.yaml ✅
@@ -1274,32 +1695,96 @@ Day 0 (2026-03-28) - Phase K0 + K-NET + K-CLEAN ✅ 全部完成
├── 15:00 - K-NET.3 VIP 192.168.0.125 啟用 ✅
├── 16:00 - K-VIP CI/CD 整合 (GitHub Secret) ✅
├── 18:00 - K-CLEAN 清理 (9 RS + 1 Job) ✅
├── 19:00 - Phase 20 CSRF 防護完成 ✅
├── 20:30 - SignOz OTEL 配置修正 ✅
└── 21:00 - Runbook 狀態更新 ✅
├── 19:00 - K-HA.1 PostgreSQL k3s_datastore 建立 ✅
├── 19:15 - K-HA.2 SQLite 完整備份 ✅
├── 19:25 - K-HA.3 120 遷移至 PostgreSQL ✅
├── 19:35 - K-HA.4 121 升級為 Control-Plane ✅
├── 19:45 - K-HA 驗證 (雙節點 + Kine 552 records) ✅
├── 20:00 - 服務重部署 (CD force_deploy) ✅
├── 20:30 - 15 項異常長期修復完成 ✅
└── 21:00 - Runbook + Memory 狀態更新 ✅
```
### 📋 待規劃 (K-HA 需維護窗口)
### ✅ K-HA 已完成 (2026-03-28 19:35)
```
未定日期 - Phase K-HA (外接 PostgreSQL)
├── ?? - 維護窗口開始 (建議週末凌晨)
├── +15m - K-HA.1 PostgreSQL 準備 (188)
├── +30m - K-HA.2 完整備份
├── +60m - K-HA.3 120 遷移至 PostgreSQL
├── +90m - K-HA.4 121 升級為 Server
├── +120m - 驗證 + 故障轉移測試
└── +150m - 維護窗口結束
2026-03-28 19:00-20:00 - Phase K-HA (外接 PostgreSQL) ✅ 完成
├── 19:00 - K-HA.1 PostgreSQL 準備 (188) ✅
├── 19:15 - K-HA.2 完整備份 ✅
├── 19:25 - K-HA.3 120 遷移至 PostgreSQL ✅
├── 19:35 - K-HA.4 121 升級為 Server ✅
├── 19:45 - 驗證 (Kine 552 records) ✅
└── 20:00 - 服務重部署成功 ✅
```
Day 3+ (2026-03-31 ~ 04-03)
├── Phase K1: Velero
├── Phase K2: ArgoCD, VPA
└── Phase K-NET.3-4: Ingress
### 📋 待規劃 (會議目標尚未完成)
```
Week 2 (2026-03-31 ~ 04-04)
├── Phase K1: Velero 備份系統 (P1 - 6h)
│ ├── K1.1 部署 MinIO (188)
│ ├── K1.2 安裝 Velero
│ ├── K1.3 配置備份 Schedule
│ └── K1.4 測試備份/還原
│
├── Phase K2: 自動化維運 (P2 - 12h)
│ ├── K2.1 部署 ArgoCD (GitOps)
│ ├── K2.2 部署 Sealed Secrets
│ ├── K2.3 部署 VPA (Off 模式)
│ └── K2.4 部署 NPD
│
└── Phase K3: 儲存與 HPA (P3 - 10h)
├── K3.1 評估 Longhorn (可延後)
└── K3.2 配置 HPA (API/Web 2-4)
Week 3 (2026-04-07 ~ 04-11)
└── Phase K4: 進階優化 (P4 - 6h)
├── K4.1 部署 Kured
├── K4.2 部署 Descheduler
└── K4.3 清理 Legacy NS
```
---
**Runbook 完成**: 2026-03-28 04:00 (台北時間)
---
## 附錄 B: K-HA 完成後異常修復 (15 項永久方案)
> **執行日期**: 2026-03-28 20:30 (台北時間)
> **範圍**: K-HA 遷移後全面日誌清查
| # | 異常 | 永久方案 | 狀態 |
|---|------|---------|------|
| 1 | ContainerHighMemory +Inf | 修復 alerts.yml 公式 (除零防護) | ✅ |
| 2 | WebsiteDown 誤報 | 移除錯誤 probe target | ✅ |
| 3 | Blackbox TCP 指向舊 IP | 更新為 VIP 192.168.0.125 | ✅ |
| 4 | ClawBot 8088 舊端口 | 改為 OpenClaw 8089 | ✅ |
| 5 | lewooogo-core exports 順序 | types 放最前 | ✅ |
| 6 | ConfigMap OTEL gRPC | 改為 HTTP 24318 | ✅ |
| 7 | Web Deployment 無 secretRef | 新增 Sentry DSN 存取 | ✅ |
| 8 | stats.py Router 層違規 | 完整 Service 層重構 | ✅ |
| 9 | Mock 測試殘留 | 刪除不合規測試 | ✅ |
| 10 | StatsService 無 Interface | 新增 IStatsService Protocol | ✅ |
| 11 | Worker 心跳機制 | 每 30 秒 touch 檔案 | ✅ |
| 12 | Worker liveness 探針 | 改為 mtime 檢查 | ✅ |
| 13 | AI_FALLBACK_ORDER 錯誤 | 改回 Ollama 優先 | ✅ |
| 14 | 架構文檔過時 | K-HA 章節全面更新 | ✅ |
| 15 | 服務端點分散 | 建立 SERVICE-ENDPOINTS.md | ✅ |
---
## 附錄 C: 已知限制
| 限制 | 說明 | 解決方案 |
|------|------|---------|
| VIP:32334 無回應 | keepalived 只做 L3 VIP 漂移 | 需 MetalLB 或 HAProxy |
| 120:32334 間歇性 | Pod 可能只在 121 運行 | AntiAffinity 已確保分散 |
| K3s API 401 | /healthz 需要認證是正常行為 | 使用 kubeconfig |
**結論**: 現有架構符合設計目標，VIP 主要保障 K3s API (6443) 高可用
---
**Runbook 完成**: 2026-03-28 21:00 (台北時間)
**建立者**: Claude Code (首席架構師)
**狀態**: 待統帥批准執行
**狀態**: ✅ Phase K0 + K-NET + K-HA + K-CLEAN 執行完成

10
docs/security/SECRETS_REFERENCE.md
View File

@@ -27,7 +27,7 @@
| **OpenClaw AWOOOI** | `192.168.0.188:8089` | (新) AI Agent |
| **Redis Stack** | `192.168.0.188:6380` | 快取/向量 |
| **SigNoz** | `192.168.0.188:3301` | 觀測平台 |
| **K8s API** | `192.168.0.120:6443` | K3s 叢集 |
| **K8s API (VIP)** | `192.168.0.125:6443` | K3s 叢集 HA (keepalived) |
---
@@ -100,17 +100,17 @@ SELECT 10
### .env.local 範本
```bash
# 資料庫
DATABASE_URL=postgresql://user:pass@192.168.0.188:5432/awoooi
# 資料庫 (必須使用 +asyncpg 驅動)
DATABASE_URL=postgresql+asyncpg://user:pass@192.168.0.188:5432/awoooi
REDIS_URL=redis://192.168.0.188:6380/10
# 認證
JWT_SECRET=your-jwt-secret-here
JWT_ALGORITHM=HS256
# AI 服務
# AI 服務 (2026-03-28 更新)
OLLAMA_URL=http://192.168.0.188:11434
OPENCLAW_URL=http://192.168.0.188:8088
OPENCLAW_URL=http://192.168.0.188:8089 # 注意: 8088 是 Legacy (凍結), 8089 是 AWOOOI
# 外部服務
HARBOR_URL=http://192.168.0.110:5000