From 19342a0044fffdbbefb85cd2d1920f8f63320c85 Mon Sep 17 00:00:00 2001 From: ogt Date: Sun, 19 Apr 2026 16:31:50 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A3=9C=E5=85=A5=20docs/external+guid?= =?UTF-8?q?es+memory=20=E7=9B=AE=E9=8C=84=E8=87=B3=E7=89=88=E6=8E=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 包含: - docs/external/aiops_saas.md - docs/guides/deployment_sop.md / devops_handbook.md / google_drive_setup.md - docs/memory/credentials_passbook.md / history_logs.md Co-Authored-By: Claude Sonnet 4.6 --- docs/external/aiops_saas.md | 34 ++++++++++++++++++ docs/guides/deployment_sop.md | 37 +++++++++++++++++++ docs/guides/devops_handbook.md | 56 +++++++++++++++++++++++++++++ docs/guides/google_drive_setup.md | 32 +++++++++++++++++ docs/memory/credentials_passbook.md | 35 ++++++++++++++++++ docs/memory/history_logs.md | 39 ++++++++++++++++++++ 6 files changed, 233 insertions(+) create mode 100644 docs/external/aiops_saas.md create mode 100644 docs/guides/deployment_sop.md create mode 100644 docs/guides/devops_handbook.md create mode 100644 docs/guides/google_drive_setup.md create mode 100644 docs/memory/credentials_passbook.md create mode 100644 docs/memory/history_logs.md diff --git a/docs/external/aiops_saas.md b/docs/external/aiops_saas.md new file mode 100644 index 0000000..5313764 --- /dev/null +++ b/docs/external/aiops_saas.md @@ -0,0 +1,34 @@ +# 🚀 WOOO AIOps - 智能運維 SaaS 產品 (存檔) + +> **注意**：本文件內容屬於 WOOO AIOps SaaS 產品範疇，非 EwoooC (MOMO Pro System) 核心邏輯。移出 `CLAUDE.md` 以優化模型 Context 消耗。 + +## 產品概覽 +| 項目 | 說明 | +|------|------| +| 產品名稱 | WOOO AIOps (AI Operations Platform) | +| 目標客戶 | 需要快速建立監控的中小型網站 | +| 技術棧 | FastAPI + React/Next.js + K8s + Prometheus | + +## 核心架構 +- **Deploy Engine**: 支援 4 種框架的 K8s 部署。 +- **Monitor Engine**: Prometheus + Grafana + Alertmanager 整合。 +- **Repair Engine**: 8 種自動修復策略（重啟、擴容、回滾等）。 +- **Web Portal**: 基於 React/Next.js 的管理後台。 + +## API 端點摘要 +- `/api/auth/`: 認證與用戶管理 +- `/api/apps/`: 應用程式 CRUD +- `/api/deployments/`: 佈署歷史與觸發 +- `/api/monitoring/`: 監控數據與告警 +- `/api/repairs/`: 自動修復執行紀錄 + +## 自動修復映射表 +| 告警類型 | 修復動作 | +|---------|---------| +| `HighCpuUsage` | scale_up | +| `HighMemoryUsage` | increase_memory | +| `PodCrashLoopBackOff` | restart | +| `HighErrorRate` | rollback | + +--- +*本文件由 Antigravity 於 2026-04-19 從 CLAUDE.md 遷移。* diff --git a/docs/guides/deployment_sop.md b/docs/guides/deployment_sop.md new file mode 100644 index 0000000..43d945b --- /dev/null +++ b/docs/guides/deployment_sop.md @@ -0,0 +1,37 @@ +# 🚀 EwoooC 部署標準作業程序 (SOP) + +> **版本日期**: 2026-04-18 (依 ADR-008 修訂) +> **目標主機**: `ollama@192.168.0.188` (經 `192.168.0.110` 跳板) + +## 🛠️ 開發同步流程 +由於正式環境使用 Docker Compose + Volume Mount，部署邏輯如下： + +### 1. 本地開發與測試 +在 Mac 本地完成功能開發，並確認 `./app.py` 執行無誤。 + +### 2. 同步程式碼 (SCP) +使用 110 作為跳板機，將本地檔案推送至 188 正式目錄： +```bash +# 同步單一檔案 +scp -o ProxyJump=wooo@192.168.0.110 app.py ollama@192.168.0.188:/home/ollama/momo-pro/ + +# 同步目錄 +scp -o ProxyJump=wooo@192.168.0.110 -r services/ ollama@192.168.0.188:/home/ollama/momo-pro/ +``` + +### 3. 重啟容器 +檔案進入掛載目錄後，重啟容器以加載變更： +```bash +ssh -J wooo@192.168.0.110 ollama@192.168.0.188 "docker restart momo-pro-system" +``` + +## 🏗️ 重大變更 (Rebuild) +若修改了 `Dockerfile` 或新增了 `requirements.txt` 套件： +```bash +ssh -J wooo@192.168.0.110 ollama@192.168.0.188 "cd /home/ollama/momo-pro && docker compose build momo-app && docker compose up -d momo-app" +``` + +## 🔍 維運指令 +- **查看日誌**: `docker logs -f momo-pro-system --tail 100` +- **進入資料庫**: `docker exec -it momo-db psql -U momo -d momo_analytics` +- **檢查磁碟**: `df -h` diff --git a/docs/guides/devops_handbook.md b/docs/guides/devops_handbook.md new file mode 100644 index 0000000..a11b630 --- /dev/null +++ b/docs/guides/devops_handbook.md @@ -0,0 +1,56 @@ +# EwoooC 運維與自動化手冊 (DevOps Handbook) + +## 🌐 伺服器連線 +| 環境 | 主機 | 指令 | +|---|-|---| +| **正式 (EwoooC)** | 192.168.0.188 | `ssh -J wooo@192.168.0.110 ollama@192.168.0.188` | +| **周邊 (UAT)** | 192.168.0.110 | `ssh wooo@192.168.0.110` | +| **安全 (Kali)** | 192.168.0.112 | `ssh kali@192.168.0.112` | + +--- + +## 🐋 Docker & Docker Compose 指令 (188 主機) +執行路徑：`/home/ollama/momo-pro` + +### 常用操作 +- **查看狀態**: `docker ps | grep momo` +- **查看日誌**: `docker logs -f momo-pro-system --tail 100` +- **重啟主應用**: `docker restart momo-pro-system` +- **全面啟動**: `docker compose up -d` +- **進入資料庫**: `docker exec -it momo-db psql -U momo` + +### 影像管理 +- **重建影像**: `docker compose build --no-cache momo-pro-system` +- **清理過期資源**: `docker system prune -f` + +--- + +## 🌐 Nginx 反向代理 (110 主機) +配置路徑：`/etc/nginx/sites-enabled/momo` + +- **重新載入**: `sudo systemctl reload nginx` +- **語法檢查**: `sudo nginx -t` + +--- + +## 🤖 n8n 工作流程管理 (188 主機) +- **進入容器**: `docker exec -it n8n /bin/sh` +- **手動執行 Workflow**: `docker exec n8n n8n execute --id=` +- **列出 Workflow**: `docker exec n8n n8n list:workflow` + +--- + +## ❄️ K8s 相關指令 (已撤除，備份存檔) +- **查看 Pod**: `kubectl get pods -n momo` +- **重啟 Deployment**: `kubectl rollout restart deployment/momo-app -n momo` +- **查看日誌**: `kubectl logs -f deployment/momo-app -n momo` + +--- + +## 🏥 健康檢查與自動修復 +**監控腳本**: `/home/wooo/scripts/domain-health-monitor.sh` (於 110 執行) +**頻率**: 每 5 分鐘 +- `https://mo.wooo.work/health` -> 200 +- `https://momo.wooo.work/health` -> 200 +- `https://monitor.wooo.work/` -> 200 +- `https://registry.wooo.work/v2/` -> 401 diff --git a/docs/guides/google_drive_setup.md b/docs/guides/google_drive_setup.md new file mode 100644 index 0000000..9cdaa39 --- /dev/null +++ b/docs/guides/google_drive_setup.md @@ -0,0 +1,32 @@ +# Google Drive API 設定指南 + +## 📋 功能說明 +系統自動化流程： +1. **每 30 分鐘**檢查 Google Drive `當日業績匯入` 資料夾。 +2. **自動下載** `即時業績_當日.xlsx`。 +3. **自動匯入** 至資料庫 `daily_sales_snapshot`。 +4. **歸檔** 原始檔案。 + +--- + +## 🔑 認證資訊庫 +| 項目 | 值 | +|-----|-----| +| Google Cloud 專案名 | `wooo-481204` | +| Client ID | `132823079326-h9cvj5eahigm8hp9q0b7t5rk77bhu3gp...` | +| 認證帳號 | `owen.tsai@gmail.com` | + +--- + +## 🛠️ 首次認證步驟 +若 `config/google_token.pickle` 遺失或過期，執行以下指令： +```bash +python3 -c "from services.google_drive_service import drive_service; drive_service.authenticate()" +``` +執行後會彈出瀏覽器要求授權。 + +--- + +## 📁 資料夾結構要求 +Google Drive 根目錄必須存在： +`我的雲端硬碟/業績報表/當日業績/` diff --git a/docs/memory/credentials_passbook.md b/docs/memory/credentials_passbook.md new file mode 100644 index 0000000..7bf268f --- /dev/null +++ b/docs/memory/credentials_passbook.md @@ -0,0 +1,35 @@ +# 🔐 系統憑證與環境手冊 (Credentials Passbook) + +> **警告**：本文件包含生產環境敏感資訊，僅限開發與維運校對使用。 + +## 🌐 伺服器矩陣 +| 主機別名 | 內網 IP | 角色 | 部署方式 | +|---------|---------|------|---------| +| **UAT / Gateway** | `192.168.0.110` | Nginx 反向代理、Registry、n8n、Superset | Docker | +| **Production / AI** | `192.168.0.188` | EwoooC App、Clawdbot、Ollama、pgvector | Docker Compose | +| **DevSecOps** | `192.168.0.112` | Kali Linux (掃描主機)、WG-Easy | Docker | + +## 🔑 關鍵認證 +### Docker Registry (registry.wooo.work) +- **User**: `admin` +- **Password**: `Wooo_Registry_2026` + +### n8n 自動化 +- **User**: `admin` +- **Password**: `Wooo_N8n_2026` + +### Google Drive API +- 參閱 `docs/guides/google_drive_setup.md` + +## 📡 埠號分配 (Port Mapping) +- **80/443**: Nginx (UAT) +- **5000/5001**: EwoooC App +- **5002**: Private Registry +- **5678**: n8n +- **8088**: Apache Superset +- **11434**: Ollama API (188) +- **3000**: Open WebUI (188) +- **51820**: WireGuard VPN + +--- +*詳細內容請對照 `.env` 檔案。* diff --git a/docs/memory/history_logs.md b/docs/memory/history_logs.md new file mode 100644 index 0000000..c12ce3d --- /dev/null +++ b/docs/memory/history_logs.md @@ -0,0 +1,39 @@ +# EwoooC 專案歷史紀錄 (History Logs) + +## 📌 重大里程碑 +- **2026-04-18**: 專案正式正名為 **EwoooC**，AI 治理架構 Phase 4 結案（V10.3）。 +- **2026-02-13**: WOOO AIOps SaaS 核心模組完成。 +- **2026-01-24**: 曾嘗試遷移至 K3s（後於 04-18 審計確認回歸 Docker Compose）。 +- **2026-01-12**: 專案啟動，MOMO 監控系統初版。 + +--- + +## 📅 詳細更新日誌 (考古存檔) + +### 2026-02-13：重開機服務修復與 Clawdbot 整合 +- 更新 `system_startup.sh` v2.0，移除 Harbor 相關邏輯。 +- 重新設計 Monitor 首頁，移除不存在的服務連結。 +- 實作 Ollama Server 端的 `Clawdbot` 整合腳本。 + +### 2026-02-09：域名健康監控與服務修復 +- 新增 `domain-health-monitor.sh`，每 5 分鐘自動巡檢。 +- 修復 n8n Task Runner 403 錯誤。 + +### 2026-02-07：CI/CD Dashboard 與 Registry 遷移 +- 完全移除 Harbor，改用輕量級 Docker Registry。 +- 開發 CI/CD Dashboard 頁面 (`/cicd`)。 + +### 2026-01-28：核心問題修復 +- **502 Bad Gateway**: 發現 Docker 網路棧故障，新增自動重啟機制。 +- **OOM 問題**: 修復業績匯入進程因記憶體消耗過大被 SIGKILL 的問題。 +- **Ollama 監控**: 實作 AI 服務器健康專項監控。 + +--- + +## 🛠️ 過往技術爭議與決策 (ADR 前身) +- **資料流向**: 確立 `daily_sales_snapshot` 為 SOT，同步至 `realtime_sales_monthly`。 +- **快取機制**: 使用 `FileLock` 解決 Gunicorn 多 Worker 重建快取競爭。 +- **時區處理**: 強制使用 `Asia/Taipei` 並於 SQLite 存儲 naive datetime。 + +--- +*詳細原始紀錄請參閱 Git Commit History 或 110 主機備份目錄。*