ewoooc/docs/guides/devops_handbook.md

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_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://monitor.wooo.work/ -> 200
• https://registry.wooo.work/v2/ -> 401

---

🆘 故障排除 (Troubleshooting) - 2026-04-28 實戰總結

1. 網站 502 Bad Gateway (Nginx 找不到後端)

• 原因: 110 與 188 之間的 SSH 隧道中斷。
• 檢查: 在 110 執行 curl -I http://127.0.0.1:5003/health。
• 修復: 在 110 執行 ssh -fN -L 5003:127.0.0.1:5003 ollama@192.168.0.188 重啟隧道。
• CD 判斷: 先確認 188 內部 docker exec momo-pro-system curl http://127.0.0.1:80/health，再看外部 https://mo.wooo.work/health；若 internal 已 200 但 external 502，多半是 Nginx/tunnel 短暫延遲。

2. CI/CD 報錯 parent snapshot ... not found

• 原因: Docker Buildx 快取損壞。
• 修復: 在 .gitea/workflows/cd.yaml 中使用 docker compose build --no-cache。

3. CI/CD 報錯 No such container: momo-pro-system

• 原因: Sync 模式使用硬編碼容器名，但容器可能已被重建或改名。
• 修復: 先 docker compose up -d --no-deps momo-app scheduler telegram-bot 確保容器存在，再 docker compose restart momo-app scheduler telegram-bot 讓 bind-mounted Python 檔案重新載入。

4. Telegram Bot 代碼更新無效 (幽靈容器)

• 原因: docker-compose.yml 遺漏了 /app/routes 的 Volume 掛載。
• 檢查: docker inspect momo-telegram-bot | jq '.[0].Mounts'。
• 修復: 確保 volumes 段落包含 - ./routes:/app/routes:ro。

5. Gunicorn 設定更新後仍吃舊版 image 內容

• 原因: gunicorn.conf.py 若沒有 bind mount，容器 restart 會使用 image 內建檔案；host 上新版設定不會自動進入 /app/gunicorn.conf.py。
• 檢查: docker inspect momo-pro-system | jq '.[0].Mounts'，確認有 /app/gunicorn.conf.py。
• 修復: docker-compose.yml 的 momo-app.volumes 必須包含 - ./gunicorn.conf.py:/app/gunicorn.conf.py:ro，再走 CD rebuild 或精準 recreate app/scheduler/bot。

6. /metrics 持續出現 realtime_sales_monthly 欄位不存在 warning

• 原因: 線上表 schema 可能比 ORM 窄，ORM count 會包子查詢並引用不存在欄位。
• 修復: metrics 只需要總筆數時使用 SELECT COUNT(*) FROM realtime_sales_monthly，不要透過 session.query(RealtimeSalesMonthly).count()。

7. Rebuild 模式造成長時間 502

• 原因: CD 若先 docker stop/rm 再 docker compose build --no-cache，build 耗時會全部變成服務中斷時間。
• 修復: rebuild 模式必須先 docker compose build --no-cache momo-app 成功，才短暫 stop/rm/recreate momo-app scheduler telegram-bot。
• 救急: 若 build 已經在跑且三應用容器已被移除，可精準執行 docker compose up -d --no-deps momo-app scheduler telegram-bot 先恢復服務；禁止使用 --remove-orphans。

8. ElephantAlpha NIM 回 404

• 原因: NVIDIA /v1/models 可能列出模型，但帳號未必可呼叫該 hosted function；production 曾對 Ultra 253B 回 Function ... Not found for account。
• 檢查: 在容器內用 NVIDIA_API_KEY 呼叫 https://integrate.api.nvidia.com/v1/models，再用低 max_tokens 測試目標 model。
• 修復: ELEPHANT_ALPHA_MODEL 預設使用 nvidia/llama-3.3-nemotron-super-49b-v1.5，並保留 ELEPHANT_ALPHA_FALLBACK_MODELS。

9. PostgreSQL 連線數快速升高

• 原因: Flask routes 會頻繁建立 DatabaseManager()，若每次都產生新 engine/pool，Gunicorn 多 worker 會快速吃滿 PostgreSQL clients。
• 修復: DatabaseManager 以 (DATABASE_TYPE, DATABASE_PATH) 重用 engine/session，且 PostgreSQL pool 收斂為 pool_size=2/max_overflow=3。
• 檢查: app log 應出現 使用 PostgreSQL 資料庫 (連線池已收斂)，Gunicorn post_fork 仍需 dispose inherited engines。

10. OpenClaw embedding timeout

• 原因: Hermes/Ollama 負載高或舊 /api/embeddings endpoint 慢，會讓 embedding worker 累加 retry。
• 檢查: 看 embedding_retry_queue 的 pending/processing/failed 分布，並測 http://192.168.0.111:11434/api/embed。
• 修復: client 預設使用官方 /api/embed；若舊節點 404/405 才 fallback /api/embeddings。必要時調整 EMBEDDING_TIMEOUT。

11. /health 偶發 000 或容器 unhealthy，但 app log 仍有 200

• 原因: Blackbox 或外部探測打 Dashboard 首頁 /，會觸發商品看板與 PChome 比價重型查詢；少量 sync worker 被長請求佔滿時，輕量 /health 也會排隊逾時。
• 檢查: docker logs momo-pro-system --since 20m | grep 'Blackbox-Exporter' 應只看到 GET /health；docker stats momo-db 若接近多核心滿載，需同步看 pg_stat_activity 的 latest_momo 類查詢。
• 修復: 188 的 monitoring/prometheus.yml 與 110 的 /home/wooo/monitoring/prometheus.yml blackbox HTTP targets 必須使用 /health；Gunicorn 保持 worker_class=gthread、GUNICORN_THREADS=4、preload_app=False。