From 95b46af98685e58f625377a08050d6544b4e60ba Mon Sep 17 00:00:00 2001 From: OG T Date: Sun, 29 Mar 2026 16:03:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E7=A8=BD=E6=A0=B8?= =?UTF-8?q?=E5=A0=B1=E5=91=8A=20+=20=E9=9D=88=E6=84=9F=E5=AF=A6=E9=A9=97?= =?UTF-8?q?=E5=AE=A4=20+=20Runbook=20=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AWOOOI_COMPREHENSIVE_AUDIT_2026Q1.md 全維度稽核 - INSPIRATION_LAB.md 靈感收集 - K3S-OPTIMIZATION-RUNBOOK.md 優化指南 - ADR-006 AI Fallback 策略更新 Co-Authored-By: Claude Opus 4.5 --- docs/AWOOOI_COMPREHENSIVE_AUDIT_2026Q1.md | 783 ++++++++++++++++++ docs/INSPIRATION_LAB.md | 351 ++++++++ docs/adr/ADR-006-ai-fallback-strategy.md | 43 + .../2026-03-28-k3s-optimization-deep-dive.md | 26 +- docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md | 551 +++++++++++- docs/security/SECRETS_REFERENCE.md | 10 +- 6 files changed, 1713 insertions(+), 51 deletions(-) create mode 100644 docs/AWOOOI_COMPREHENSIVE_AUDIT_2026Q1.md create mode 100644 docs/INSPIRATION_LAB.md diff --git a/docs/AWOOOI_COMPREHENSIVE_AUDIT_2026Q1.md b/docs/AWOOOI_COMPREHENSIVE_AUDIT_2026Q1.md new file mode 100644 index 00000000..9368ce8d --- /dev/null +++ b/docs/AWOOOI_COMPREHENSIVE_AUDIT_2026Q1.md @@ -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.」** 🦞 diff --git a/docs/INSPIRATION_LAB.md b/docs/INSPIRATION_LAB.md new file mode 100644 index 00000000..7c35450a --- /dev/null +++ b/docs/INSPIRATION_LAB.md @@ -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 原版 (深色) +
+ +// ✅ AWOOOI 轉換 (純白工業風) +
+``` + +**篩選器 Badge (NVIDIA → Nothing.tech)** +```tsx +// ❌ NVIDIA 原版 +Provider + +// ✅ AWOOOI 轉換 +Provider +``` + +**導航連結 (NVIDIA → Nothing.tech)** +```tsx +// ❌ NVIDIA 原版 +Models + +// ✅ AWOOOI 轉換 +Models +``` + +#### 應用場景 + +| 場景 | 參考元素 | +|------|----------| +| 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 風格) + +``` + +**可應用場景**: +- 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 (預留位置) + + + +--- + +## 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 (預留位置) + + + +--- + +## 8. 待討論 (Pending Discussion) + +### 8.1 (預留位置) + + + +--- + +## 狀態圖例 + +| 圖示 | 狀態 | 說明 | +|------|------|------| +| 🟢 | 已採用/已實作 | 已整合至專案 | +| 🟡 | 待整合 | 已批准，待實作 | +| 🔵 | 觀察中 | 持續評估 | +| 🔴 | 不採用 | 已決定不使用 | +| ⚪ | 未評估 | 尚未開始評估 | + +--- + +## 變更紀錄 + +| 日期 | 執行者 | 變更內容 | +|------|--------|----------| +| 2026-03-28 | Claude Code | 初始建立，加入 NVIDIA Build 參考 | diff --git a/docs/adr/ADR-006-ai-fallback-strategy.md b/docs/adr/ADR-006-ai-fallback-strategy.md index 34918da8..9896c312 100644 --- a/docs/adr/ADR-006-ai-fallback-strategy.md +++ b/docs/adr/ADR-006-ai-fallback-strategy.md @@ -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 整合章節 (待統帥批准) | 首席架構師 | --- diff --git a/docs/meetings/2026-03-28-k3s-optimization-deep-dive.md b/docs/meetings/2026-03-28-k3s-optimization-deep-dive.md index b52a26fa..6a4b9a12 100644 --- a/docs/meetings/2026-03-28-k3s-optimization-deep-dive.md +++ b/docs/meetings/2026-03-28-k3s-optimization-deep-dive.md @@ -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 下一步行動 diff --git a/docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md b/docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md index 4ca430c3..925c438c 100644 --- a/docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md +++ b/docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md @@ -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 +``` + +--- + +## 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 \ + --password +``` + +#### 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 執行完成 diff --git a/docs/security/SECRETS_REFERENCE.md b/docs/security/SECRETS_REFERENCE.md index c1c1a102..d7be7da3 100644 --- a/docs/security/SECRETS_REFERENCE.md +++ b/docs/security/SECRETS_REFERENCE.md @@ -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