# MOMO Pro System - CI/CD 與部署指南

> 完整的 CI/CD 流程與一鍵部署自動化指南
> 最後更新: 2026-02-06

---

## 目錄

1. [架構總覽](#架構總覽)
2. [CI/CD 流程](#cicd-流程)
3. [一鍵部署到新主機](#一鍵部署到新主機)
4. [手動部署步驟](#手動部署步驟)
5. [自動啟動機制](#自動啟動機制)
6. [故障排除](#故障排除)

---

## 架構總覽

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         MOMO Pro System 部署架構                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   開發環境 (Mac)                    UAT 環境 (192.168.0.110)                 │
│  ┌──────────────┐                 ┌────────────────────────────────────┐    │
│  │ 本地開發      │                 │ K3s Kubernetes 叢集                 │    │
│  │ git push     │───────────────►│                                    │    │
│  └──────────────┘     CI/CD       │  ┌────────────────────────────┐   │    │
│                                   │  │ momo-app (Flask)           │   │    │
│  ┌──────────────┐                 │  │ momo-scheduler (爬蟲)      │   │    │
│  │ GitLab       │◄───────────────►│  │ momo-postgres (PostgreSQL) │   │    │
│  │ :8929        │                 │  └────────────────────────────┘   │    │
│  └──────────────┘                 │                                    │    │
│                                   │  ┌────────────────────────────┐   │    │
│                                   │  │ 監控: Prometheus/Grafana   │   │    │
│                                   │  │ 告警: Alertmanager/Telegram│   │    │
│                                   │  └────────────────────────────┘   │    │
│                                   └────────────────────────────────────┘    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## CI/CD 流程

### 流程圖

```
git push
    │
    ▼
┌───────────────────┐
│  GitLab CI 觸發    │
│  .gitlab-ci.yml   │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐     ┌───────────────────┐
│  Stage: test      │────►│  Stage: deploy    │
│  • pytest 測試    │     │  • rsync 同步     │
│  • 允許失敗       │     │  • docker build   │
└───────────────────┘     │  • k3s import     │
                          │  • kubectl restart│
                          │  • 健康檢查       │
                          └─────────┬─────────┘
                                    │
                                    ▼
                          ┌───────────────────┐
                          │  Telegram 通知    │
                          │  成功 ✅ / 失敗 ❌ │
                          └───────────────────┘
```

### GitLab CI 配置 (.gitlab-ci-simple.yml)

此配置**不依賴 Harbor**，直接在 K3s 主機建置映像：

```yaml
stages:
  - test
  - deploy

variables:
  K3S_HOST: "192.168.0.110"
  K3S_USER: "wooo"
  IMAGE_NAME: "momo-pro-system"

deploy:
  stage: deploy
  script:
    # 1. 同步程式碼
    - rsync -avz --delete --exclude='.git' ./ ${K3S_USER}@${K3S_HOST}:/home/wooo/momo_pro_system/

    # 2. 在 K3s 主機建置
    - ssh ${K3S_USER}@${K3S_HOST} "cd /home/wooo/momo_pro_system && docker build -t momo-pro-system:local ."

    # 3. 匯入到 K3s containerd
    - ssh ${K3S_USER}@${K3S_HOST} "docker save momo-pro-system:local | sudo k3s ctr images import -"

    # 4. 重啟服務
    - ssh ${K3S_USER}@${K3S_HOST} "sudo kubectl rollout restart deployment/momo-app deployment/momo-scheduler -n momo"
```

### 手動觸發部署

```bash
# 方法 1: 推送到 GitLab
git add .
git commit -m "feat: 新功能"
git push gitlab main

# 方法 2: 使用部署腳本
./scripts/deploy/build-and-deploy.sh
```

---

## 一鍵部署到新主機

### 前置需求

| 項目 | 需求 |
|------|------|
| 作業系統 | Ubuntu 22.04 / Debian 12 |
| CPU | 4 核心以上 |
| 記憶體 | 8GB 以上 |
| 硬碟 | 50GB SSD |
| 網路 | 開放 80, 443 端口 |

### 方法 1: SSH 遠端部署

```bash
# 從本地部署到新主機
./deploy/deploy.sh --ssh -h <新主機IP> -u root deploy

# 例如:
./deploy/deploy.sh --ssh -h 192.168.0.200 -u wooo deploy
```

### 方法 2: 匯出部署包

```bash
# 1. 在開發機匯出
./deploy/deploy.sh --export --with-data

# 2. 複製到新主機
scp momo-pro-system_*.tar.gz root@新主機:/opt/

# 3. 在新主機解壓並執行
ssh root@新主機
cd /opt
tar -xzf momo-pro-system_*.tar.gz
cd momo-pro-system
./deploy/deploy.sh deploy
```

### 方法 3: K8s 部署

```bash
# 1. 確保 K3s 已安裝
curl -sfL https://get.k3s.io | sh -

# 2. 套用 K8s 配置
kubectl apply -f k8s/00-namespace.yaml
kubectl apply -f k8s/01-secrets.yaml
kubectl apply -f k8s/02-configmap.yaml
kubectl apply -f k8s/03-postgres.yaml
kubectl apply -f k8s/04-momo-app.yaml
kubectl apply -f k8s/05-scheduler.yaml

# 3. 建置並匯入映像
docker build -t momo-pro-system:local .
docker save momo-pro-system:local | sudo k3s ctr images import -

# 4. 重啟服務
kubectl rollout restart deployment/momo-app deployment/momo-scheduler -n momo
```

---

## 手動部署步驟

### Step 1: 準備環境

```bash
# 安裝 Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 安裝 K3s (可選)
curl -sfL https://get.k3s.io | sh -
```

### Step 2: 複製程式碼

```bash
git clone http://192.168.0.110:8929/root/momo-pro-system.git
cd momo-pro-system
```

### Step 3: 配置環境變數

```bash
cp deploy/configs/.env.template .env
# 編輯 .env 填入實際值
```

### Step 4: 建置映像

```bash
docker build -t momo-pro-system:local .
```

### Step 5: 部署服務

**Docker Compose 方式:**
```bash
docker compose up -d
```

**K8s 方式:**
```bash
# 匯入映像
docker save momo-pro-system:local | sudo k3s ctr images import -

# 套用配置
kubectl apply -f k8s/

# 重啟
kubectl rollout restart deployment/momo-app -n momo
```

### Step 6: 設定 SSL

```bash
# 使用 Certbot
sudo certbot --nginx -d mo.yourdomain.com
```

### Step 7: 驗證

```bash
# 健康檢查
curl https://mo.yourdomain.com/health
```

---

## 自動啟動機制

### systemd 服務

系統重開機後自動啟動所有服務：

```bash
# 安裝服務
sudo cp scripts/tools/momo-startup-complete.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable momo-startup-complete.service

# 查看狀態
systemctl status momo-startup-complete.service
```

### 啟動順序

```
系統啟動
    │
    ▼ (60秒延遲)
Docker 服務啟動
    │
    ▼
Harbor Registry (可選)
    │
    ▼
K8s Services
├── PostgreSQL (先啟動)
├── momo-app (等待 PostgreSQL)
└── momo-scheduler (等待 momo-app)
    │
    ▼
健康檢查 + Telegram 通知
```

### 啟動腳本

```bash
# 手動執行啟動腳本
sudo /home/wooo/momo_pro_system/scripts/tools/system_startup_complete.sh

# 查看日誌
sudo journalctl -u momo-startup-complete.service
```

---

## 故障排除

### CI/CD Pipeline 失敗

| 錯誤 | 原因 | 解決方案 |
|------|------|---------|
| SSH 連線失敗 | SSH key 未設定 | 設定 GitLab CI/CD 變數中的 SSH_PRIVATE_KEY |
| Docker build 失敗 | 磁碟空間不足 | 執行 `docker system prune -af` |
| kubectl 權限錯誤 | kubeconfig 問題 | 使用 `sudo kubectl` |

### K8s Pod 問題

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

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

# 進入 Pod 除錯
kubectl exec -it deployment/momo-app -n momo -- /bin/bash

# 強制重啟
kubectl delete pod -n momo -l app=momo-app
```

### 資料庫連線問題

```bash
# 檢查 PostgreSQL
kubectl logs momo-postgres-0 -n momo

# 測試連線
kubectl exec -n momo momo-postgres-0 -- psql -U momo -d momo_analytics -c "SELECT 1"
```

### 健康檢查失敗

```bash
# 檢查服務狀態
curl -v https://mo.wooo.work/health

# 檢查 Nginx
sudo nginx -t
sudo systemctl status nginx

# 檢查 SSL
openssl s_client -connect mo.wooo.work:443 -servername mo.wooo.work
```

---

## 常用命令速查

### 部署

```bash
# 完整部署
./scripts/deploy/build-and-deploy.sh

# 只重啟服務
ssh wooo@192.168.0.110 "sudo kubectl rollout restart deployment/momo-app -n momo"
```

### 監控

```bash
# 查看 Pod 狀態
ssh wooo@192.168.0.110 "sudo kubectl get pods -n momo"

# 查看資源使用
ssh wooo@192.168.0.110 "sudo kubectl top pods -n momo"

# 查看日誌
ssh wooo@192.168.0.110 "sudo kubectl logs -f deployment/momo-app -n momo --tail=100"
```

### 備份

```bash
# 備份資料庫
./deploy/deploy.sh backup

# 匯出部署包（含資料）
./deploy/deploy.sh --export --with-data
```

### 驗證

```bash
# 執行完整驗證
./scripts/verify-cicd.sh

# 健康檢查
curl -s https://mo.wooo.work/health | jq
```

---

## 相關檔案

| 檔案 | 說明 |
|------|------|
| `.gitlab-ci-simple.yml` | 簡化版 CI/CD 配置 (不依賴 Harbor) |
| `scripts/deploy/build-and-deploy.sh` | 本地建置部署腳本 |
| `deploy/deploy.sh` | 一鍵部署主腳本 |
| `scripts/tools/system_startup_complete.sh` | 系統自動啟動腳本 |
| `scripts/verify-cicd.sh` | CI/CD 完整驗證腳本 |
| `k8s/` | K8s 配置檔案目錄 |
| `k8s/optimized/` | 優化版 K8s 配置 |

---

## 聯絡資訊

- **Telegram 告警**: Bot `@wooowooowooobot`
- **GitLab**: http://192.168.0.110:8929
- **Grafana**: http://192.168.0.110:30030
- **正式網址**: https://mo.wooo.work