# MOMO Pro System - 一鍵部署指南 v2.0

> 將 MOMO Pro System 完整部署到新的 VM 環境
> 支援 Docker Compose、Kubernetes、Harbor Registry、監控堆疊

## 目錄

- [快速開始](#快速開始)
- [部署模式](#部署模式)
- [K8s 部署](#k8s-部署)
- [Harbor 管理](#harbor-管理)
- [監控堆疊](#監控堆疊)
- [Systemd 服務](#systemd-服務)
- [環境需求](#環境需求)
- [配置說明](#配置說明)
- [備份與還原](#備份與還原)
- [SSL 憑證](#ssl-憑證)
- [故障排除](#故障排除)

---

## 快速開始

### Docker Compose 部署（最簡單）

```bash
# 1. 進入部署目錄
cd deploy

# 2. 執行部署腳本
chmod +x deploy.sh
./deploy.sh deploy

# 3. 依照提示完成配置
```

### Kubernetes 部署

```bash
# 部署到 K8s（含 Harbor 映像推送）
./deploy.sh --k8s deploy

# 或分步驟執行
./deploy.sh harbor-push      # 建構並推送映像
./deploy.sh k8s-deploy       # 部署到 K8s
```

### 完整部署流程（生產環境）

```bash
# 1. 環境檢查
./deploy.sh check

# 2. 部署應用 + 設定開機自動啟動
./deploy.sh --with-systemd deploy

# 3. 設定 SSL 憑證
./deploy.sh -d mo.wooo.work ssl

# 4. 部署監控堆疊
./deploy.sh monitoring-deploy

# 5. 健康檢查
./deploy.sh health
```

---

## 部署模式

### 模式 A: Docker Compose 本地部署

```bash
./deploy.sh deploy
# 或
./deploy.sh --local deploy
```

**適用場景：**
- 開發/測試環境
- 單機部署

### 模式 B: Kubernetes 部署

```bash
./deploy.sh --k8s deploy
```

**適用場景：**
- 生產環境
- 需要高可用性
- 需要自動擴展

### 模式 C: SSH 遠端部署

```bash
./deploy.sh --ssh \
    -h 192.168.1.100 \
    -u wooo \
    -p /opt/momo-pro-system \
    deploy
```

**前置需求：**
- SSH 金鑰已設定（無密碼登入）
- 遠端主機已安裝 Docker

### 模式 D: 匯出部署包

```bash
# 不含資料
./deploy.sh --export

# 含資料庫備份
./deploy.sh --export --with-data
```

**輸出檔案：**
```
momo-pro-system_20260129_143000.tar.gz
```

---

## K8s 部署

### K8s 命令

| 命令 | 說明 |
|------|------|
| `./deploy.sh k8s-deploy` | 部署到 Kubernetes |
| `./deploy.sh k8s-status` | 查看部署狀態 |
| `./deploy.sh k8s-logs` | 查看應用日誌 |
| `./deploy.sh k8s-rollback` | 回滾到上一版本 |
| `./deploy.sh k8s-cleanup` | 清理所有 K8s 資源 |

### K8s 選項

| 選項 | 說明 |
|------|------|
| `-n, --namespace` | K8s 命名空間（預設: momo） |

### K8s 部署流程

```bash
# 1. 建構並推送映像
./deploy.sh harbor-push

# 2. 部署到 K8s
./deploy.sh -n momo k8s-deploy

# 3. 查看狀態
./deploy.sh k8s-status

# 4. 查看日誌
./deploy.sh k8s-logs
```

### K8s 回滾

```bash
# 回滾 momo-app
./deploy.sh k8s-rollback

# 回滾特定 deployment
kubectl rollout undo deployment/momo-scheduler -n momo
```

---

## Harbor 管理

### Harbor 命令

| 命令 | 說明 |
|------|------|
| `./deploy.sh harbor-install` | 安裝 Harbor Registry |
| `./deploy.sh harbor-push` | 建構並推送映像 |
| `./deploy.sh harbor-scan` | 執行容器安全掃描 |
| `./deploy.sh harbor-health` | 檢查 Harbor 健康狀態 |

### Harbor 選項

| 選項 | 說明 |
|------|------|
| `--registry` | Harbor URL（預設: harbor.wooo.work） |
| `--harbor-user` | Harbor 用戶名（預設: admin） |
| `--harbor-pass` | Harbor 密碼 |

### 使用 Harbor

```bash
# 登入 Harbor
docker login harbor.wooo.work -u admin

# 建構並推送映像
./deploy.sh harbor-push

# 安全掃描
./deploy.sh harbor-scan
```

---

## 監控堆疊

### 監控命令

| 命令 | 說明 |
|------|------|
| `./deploy.sh monitoring-deploy` | 部署監控堆疊 |
| `./deploy.sh monitoring-status` | 查看監控狀態 |

### 監控組件

| 組件 | 端口 | 用途 |
|------|------|------|
| Prometheus | 9090 | 指標收集 |
| Grafana | 3000 | 視覺化儀表板 |
| Alertmanager | 9093 | 告警管理 |
| Node Exporter | 9100 | 主機監控 |
| cAdvisor | 8080 | 容器監控 |
| Loki | 3100 | 日誌收集 |

### 部署監控

```bash
# Docker 環境
./deploy.sh monitoring-deploy

# K8s 環境（使用 Helm）
./deploy.sh --k8s monitoring-deploy
```

### 存取監控

| 服務 | URL | 帳號 |
|------|-----|------|
| Grafana | http://localhost:3000 | admin / Wooo_Grafana_2026 |
| Prometheus | http://localhost:9090 | - |

---

## Systemd 服務

### Systemd 命令

| 命令 | 說明 |
|------|------|
| `./deploy.sh systemd-setup` | 設定開機自動啟動 |
| `./deploy.sh systemd-status` | 查看服務狀態 |

### 設定開機啟動

```bash
# 方法一：部署時設定
./deploy.sh --with-systemd deploy

# 方法二：單獨設定
./deploy.sh systemd-setup
```

### 服務管理

```bash
# 查看服務狀態
systemctl status momo-pro-system

# 重啟服務
sudo systemctl restart momo-pro-system

# 停止服務
sudo systemctl stop momo-pro-system
```

### 建立的 Systemd 服務

| 服務 | 說明 |
|------|------|
| `momo-pro-system.service` | 主應用程式 |
| `harbor.service` | Harbor Registry |
| `gitlab.service` | GitLab CE |
| `n8n.service` | n8n 自動化 |
| `momo-monitoring.service` | 監控堆疊 |
| `momo-health-check.timer` | 健康監控定時器 |

---

## 環境需求

### 硬體需求

| 項目 | 最低需求 | 建議配置 |
|------|----------|----------|
| CPU | 4 核心 | 8 核心 |
| RAM | 8 GB | 16 GB |
| 硬碟 | 50 GB SSD | 100 GB SSD |

### 軟體需求

| 軟體 | 版本 | 說明 |
|------|------|------|
| Docker | 20.10+ | 容器運行環境 |
| Docker Compose | v2.0+ | 容器編排 |
| kubectl | 1.28+ | K8s 客戶端（K8s 模式） |
| Helm | 3.0+ | K8s 套件管理（監控用） |
| curl | - | HTTP 請求 |

### 端口需求

| 端口 | 服務 | 必要 |
|------|------|------|
| 80/443 | Nginx | ✓ |
| 5001 | Flask App | ✓（Docker 模式） |
| 5432 | PostgreSQL | ✓ |
| 3000 | Grafana | 選填 |
| 9090 | Prometheus | 選填 |
| 5678 | n8n | 選填 |
| 5050 | Harbor | 選填 |

---

## 配置說明

### 互動式配置

部署時會提示輸入以下配置：

```
資料庫配置
──────────────────────────────────
PostgreSQL 用戶名 [momo]:
PostgreSQL 密碼 [自動生成]:

應用程式配置
──────────────────────────────────
Flask Secret Key [自動生成]:

Ollama AI 配置
──────────────────────────────────
Ollama Host [http://192.168.0.188:11434]:

通知服務配置
──────────────────────────────────
Telegram Bot Token []:
Telegram Chat ID []:
```

### 使用預設配置

```bash
./deploy.sh -y deploy
```

### 使用自訂配置檔

```bash
# 複製模板
cp deploy/configs/.env.template .env

# 編輯配置
nano .env

# 使用自訂配置部署
./deploy.sh -e .env deploy
```

---

## 備份與還原

### 完整備份

```bash
./deploy.sh backup
```

**備份內容：**
- PostgreSQL 完整資料庫（SQL 格式）
- 所有資料表的 CSV 匯出
- 配置檔案（.env, docker-compose.yml）
- n8n 工作流程

**輸出位置：**
```
backups/momo_backup_20260129_143000.tar.gz
```

### 從備份還原

```bash
./deploy.sh -b backups/momo_backup_20260129.tar.gz restore
```

### 定時備份

```bash
# 每天凌晨 2 點備份
0 2 * * * cd /opt/momo-pro-system && ./deploy/deploy.sh -y backup
```

---

## SSL 憑證

### 申請 Let's Encrypt 憑證

```bash
./deploy.sh -d momo.example.com ssl
```

**前置需求：**
1. 域名已解析到此伺服器
2. 端口 80 可被外部存取

### 手動續期

```bash
certbot renew --force-renewal
docker restart momo-nginx
```

---

## 命令參考

### 基本命令

| 命令 | 說明 |
|------|------|
| `deploy` | 執行完整部署 |
| `backup` | 備份現有環境 |
| `restore` | 從備份還原 |
| `check` | 環境檢查 |
| `health` | 健康檢查 |
| `ssl` | 設定 SSL 憑證 |
| `export` | 匯出部署包 |

### K8s 命令

| 命令 | 說明 |
|------|------|
| `k8s-deploy` | 部署到 K8s |
| `k8s-status` | 查看 K8s 狀態 |
| `k8s-logs` | 查看 K8s 日誌 |
| `k8s-rollback` | 回滾 K8s 部署 |
| `k8s-cleanup` | 清理 K8s 資源 |

### Harbor 命令

| 命令 | 說明 |
|------|------|
| `harbor-install` | 安裝 Harbor |
| `harbor-push` | 推送映像 |
| `harbor-scan` | 安全掃描 |
| `harbor-health` | 健康檢查 |

### 監控命令

| 命令 | 說明 |
|------|------|
| `monitoring-deploy` | 部署監控 |
| `monitoring-status` | 監控狀態 |

### Systemd 命令

| 命令 | 說明 |
|------|------|
| `systemd-setup` | 設定服務 |
| `systemd-status` | 服務狀態 |

---

## 選項參考

| 選項 | 說明 |
|------|------|
| `--local` | Docker Compose 部署 |
| `--k8s` | Kubernetes 部署 |
| `--ssh` | SSH 遠端部署 |
| `--export` | 匯出部署包 |
| `-h, --host` | SSH 目標主機 |
| `-u, --user` | SSH 用戶名 |
| `-p, --path` | 遠端路徑 |
| `-n, --namespace` | K8s 命名空間 |
| `--registry` | Harbor URL |
| `-e, --env-file` | 環境變數檔案 |
| `-d, --domain` | 域名 |
| `-b, --backup` | 備份檔案路徑 |
| `--no-monitoring` | 不部署監控 |
| `--with-data` | 包含資料 |
| `--with-systemd` | 設定開機啟動 |
| `-y, --yes` | 跳過確認 |

---

## 故障排除

### Docker 連線失敗

```bash
sudo systemctl restart docker
```

### K8s 部署失敗

```bash
# 查看 Pod 狀態
kubectl get pods -n momo

# 查看詳細事件
kubectl describe pod <pod-name> -n momo

# 查看日誌
kubectl logs deployment/momo-app -n momo
```

### Harbor 登入失敗

```bash
# 確認 Harbor 運行中
docker ps | grep harbor

# 重啟 Harbor
cd /home/wooo/devops/harbor/harbor
docker compose restart
```

### 服務無法啟動

```bash
# 查看容器日誌
docker compose logs

# 查看 systemd 日誌
journalctl -u momo-pro-system -f
```

---

## 目錄結構

```
deploy/
├── deploy.sh              # 主入口腳本 v2.0
├── README.md              # 本文件
├── lib/
│   ├── common.sh          # 通用函數
│   ├── check.sh           # 環境檢查
│   ├── config.sh          # 配置生成
│   ├── docker.sh          # Docker 操作
│   ├── database.sh        # 資料庫備份/還原
│   ├── ssl.sh             # SSL 憑證
│   ├── health.sh          # 健康檢查
│   ├── k8s.sh             # K8s 部署（新增）
│   ├── harbor.sh          # Harbor 管理（新增）
│   ├── monitoring.sh      # 監控堆疊（新增）
│   └── systemd.sh         # Systemd 服務（新增）
└── configs/
    └── .env.template      # 環境變數模板
```

---

## 更新記錄

- **2026-01-29**: v2.0.0
  - 新增 Kubernetes 部署支援
  - 新增 Harbor Registry 整合
  - 新增監控堆疊部署 (Prometheus/Grafana/Loki)
  - 新增 Systemd 服務管理
  - 新增容器安全掃描功能
  - 增強健康監控和自動修復

- **2026-01-26**: v1.0.0
  - 初始版本
  - 支援本地、SSH、匯出三種部署模式
  - 完整資料庫備份/還原
  - Let's Encrypt SSL 自動化