# 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()`。