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://momo.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()。