1b4f3a7bbe
Some checks failed
CD Pipeline / deploy (push) Failing after 59s
- 建立 Gitea Actions CD pipeline (.gitea/workflows/cd.yaml) - 部署模式: rsync Python 檔案至 188 → docker restart (volume mount) - Dockerfile/requirements 變動時自動重建 Docker image - 部署通知: Telegram (開始/成功/失敗) - 健康檢查: https://mo.wooo.work/health (最多 5 次重試) - 同步最新 CLAUDE.md / ADR-008 / memory (2026-04-19) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
420 lines
11 KiB
Markdown
420 lines
11 KiB
Markdown
# 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
|