ewoooc/docs/CICD_DEPLOYMENT_GUIDE.md

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

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

---

目錄

1. 架構總覽
2. CI/CD 流程
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 主機建置映像：

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"

手動觸發部署

# 方法 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 遠端部署

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

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

方法 2: 匯出部署包

# 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 部署

# 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: 準備環境

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

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

Step 2: 複製程式碼

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

Step 3: 配置環境變數

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

Step 4: 建置映像

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

Step 5: 部署服務

Docker Compose 方式:

docker compose up -d

K8s 方式:

# 匯入映像
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

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

Step 7: 驗證

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

---

自動啟動機制

systemd 服務

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

# 安裝服務
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 通知

啟動腳本

# 手動執行啟動腳本
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 問題

# 查看 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

資料庫連線問題

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

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

健康檢查失敗

# 檢查服務狀態
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

---

常用命令速查

部署

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

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

監控

# 查看 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"

備份

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

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

驗證

# 執行完整驗證
./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