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>
343 lines
8.3 KiB
Markdown
343 lines
8.3 KiB
Markdown
# Momo Pro System 部署指南
|
||
|
||
## 目錄
|
||
1. [環境資訊](#環境資訊)
|
||
2. [部署流程概覽](#部署流程概覽)
|
||
3. [本地開發環境](#本地開發環境)
|
||
4. [UAT 環境部署](#uat-環境部署)
|
||
5. [部署腳本說明](#部署腳本說明)
|
||
6. [常用指令](#常用指令)
|
||
7. [故障排除](#故障排除)
|
||
|
||
---
|
||
|
||
## 環境資訊
|
||
|
||
### 本地開發環境
|
||
- **路徑**: `/Users/ogt/momo_pro_system`
|
||
- **平台**: macOS (Darwin)
|
||
|
||
### UAT 伺服器
|
||
- **主機**: `192.168.0.110`
|
||
- **用戶**: `wooo`
|
||
- **路徑**: `/home/wooo/momo_pro_system`
|
||
- **存取 URL**: http://192.168.0.110:5000
|
||
|
||
### Docker 資訊
|
||
- **映像名稱**: `wooo/momo-pro-system:latest`
|
||
- **容器名稱**: `momo-pro-system`
|
||
- **暴露埠號**: 5000
|
||
|
||
---
|
||
|
||
## 部署流程概覽
|
||
|
||
```
|
||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||
│ 本地開發 │ ──▶ │ Git 提交 │ ──▶ │ 部署到 UAT │
|
||
│ 修改程式碼 │ │ 版本控制 │ │ Docker 重建 │
|
||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||
```
|
||
|
||
### 標準部署步驟
|
||
|
||
1. **本地修改並測試**
|
||
2. **Git 提交變更**
|
||
```bash
|
||
git add .
|
||
git commit -m "描述變更內容"
|
||
```
|
||
3. **執行部署腳本**
|
||
```bash
|
||
./deploy_docker_uat.sh deploy
|
||
```
|
||
|
||
---
|
||
|
||
## 本地開發環境
|
||
|
||
### 專案結構
|
||
```
|
||
momo_pro_system/
|
||
├── app.py # Flask 主應用
|
||
├── auth.py # 認證模組
|
||
├── config.py # 配置檔案
|
||
├── scheduler.py # 排程器
|
||
├── requirements.txt # Python 依賴
|
||
├── Dockerfile # Docker 映像定義
|
||
├── docker-compose.yml # Docker Compose 配置
|
||
├── .dockerignore # Docker 忽略檔案
|
||
├── .env # 環境變數（不上傳）
|
||
├── .env.example # 環境變數範例
|
||
├── *.html # 前端模板
|
||
├── static/ # 靜態資源
|
||
│ └── images/ # 圖片資源
|
||
│ ├── logo.png # 原始 Logo
|
||
│ ├── logo_navbar.svg # 導航列圓形 Logo
|
||
│ └── logo_circle.svg # 圓形 Logo
|
||
├── services/ # 服務模組
|
||
├── database/ # 資料庫模組
|
||
├── utils/ # 工具模組
|
||
├── web/ # Web 模板
|
||
├── docker/ # Docker 相關配置
|
||
├── deploy_scripts/ # 部署腳本
|
||
├── docs/ # 文件
|
||
└── data/ # 資料庫檔案
|
||
```
|
||
|
||
### 本地啟動
|
||
|
||
#### 方式一：直接執行
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
#### 方式二：Docker Compose
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## UAT 環境部署
|
||
|
||
### 前置要求
|
||
|
||
1. **SSH 金鑰設定**
|
||
- 確保本地有 SSH 金鑰（`~/.ssh/id_rsa` 或 `~/.ssh/uat_key`）
|
||
- 公鑰已加入 UAT 伺服器的 `~/.ssh/authorized_keys`
|
||
|
||
2. **UAT 伺服器環境**
|
||
- Docker 已安裝
|
||
- Docker Compose 已安裝（可選）
|
||
- 專案目錄已建立：`/home/wooo/momo_pro_system`
|
||
|
||
### 一鍵部署
|
||
|
||
```bash
|
||
./deploy_docker_uat.sh deploy
|
||
```
|
||
|
||
### 部署流程詳解
|
||
|
||
執行 `deploy_docker_uat.sh` 腳本會自動完成以下步驟：
|
||
|
||
#### 步驟 1/6: 同步檔案到 UAT
|
||
```bash
|
||
# 上傳 Docker 配置
|
||
scp Dockerfile wooo@192.168.0.110:/home/wooo/momo_pro_system/
|
||
scp docker-compose.yml wooo@192.168.0.110:/home/wooo/momo_pro_system/
|
||
scp .dockerignore wooo@192.168.0.110:/home/wooo/momo_pro_system/
|
||
|
||
# 上傳 Docker 目錄
|
||
scp -r docker wooo@192.168.0.110:/home/wooo/momo_pro_system/
|
||
|
||
# 上傳核心 Python 檔案
|
||
scp app.py auth.py config.py scheduler.py requirements.txt wooo@192.168.0.110:/home/wooo/momo_pro_system/
|
||
|
||
# 上傳 HTML 模板
|
||
scp *.html wooo@192.168.0.110:/home/wooo/momo_pro_system/
|
||
|
||
# 上傳模組目錄
|
||
scp -r services database utils static web wooo@192.168.0.110:/home/wooo/momo_pro_system/
|
||
```
|
||
|
||
#### 步驟 2/6: 停止現有服務
|
||
```bash
|
||
ssh wooo@192.168.0.110 "sudo systemctl stop momo 2>/dev/null || true"
|
||
ssh wooo@192.168.0.110 "docker stop momo-pro-system 2>/dev/null || true"
|
||
ssh wooo@192.168.0.110 "docker rm momo-pro-system 2>/dev/null || true"
|
||
```
|
||
|
||
#### 步驟 3/6: 建置 Docker Image
|
||
```bash
|
||
ssh wooo@192.168.0.110 "cd /home/wooo/momo_pro_system && docker build -t wooo/momo-pro-system:latest ."
|
||
```
|
||
|
||
#### 步驟 4/6: 啟動 Docker 容器
|
||
```bash
|
||
ssh wooo@192.168.0.110 "cd /home/wooo/momo_pro_system && docker run -d \
|
||
--name momo-pro-system \
|
||
-p 5000:5000 \
|
||
-v ./data:/app/data \
|
||
-v ./logs:/app/logs \
|
||
-v ./config:/app/config \
|
||
-v ./backups:/app/backups \
|
||
--env-file .env \
|
||
--restart unless-stopped \
|
||
wooo/momo-pro-system:latest"
|
||
```
|
||
|
||
#### 步驟 5/6: 等待服務啟動
|
||
等待 30 秒讓服務完全啟動
|
||
|
||
#### 步驟 6/6: 驗證部署
|
||
```bash
|
||
# 檢查容器狀態
|
||
ssh wooo@192.168.0.110 "docker ps --filter name=momo-pro-system"
|
||
|
||
# 測試健康檢查端點
|
||
ssh wooo@192.168.0.110 "curl -s http://localhost:5000/health"
|
||
|
||
# 測試首頁
|
||
ssh wooo@192.168.0.110 "curl -s -o /dev/null -w '%{http_code}' http://localhost:5000/"
|
||
```
|
||
|
||
---
|
||
|
||
## 部署腳本說明
|
||
|
||
### deploy_docker_uat.sh
|
||
|
||
主要的 UAT 部署腳本，支援以下指令：
|
||
|
||
| 指令 | 說明 |
|
||
|------|------|
|
||
| `./deploy_docker_uat.sh deploy` | 執行完整部署（預設） |
|
||
| `./deploy_docker_uat.sh status` | 檢查 UAT 容器狀態 |
|
||
| `./deploy_docker_uat.sh logs` | 查看容器日誌 |
|
||
| `./deploy_docker_uat.sh restart` | 重啟容器 |
|
||
| `./deploy_docker_uat.sh stop` | 停止容器 |
|
||
| `./deploy_docker_uat.sh help` | 顯示說明 |
|
||
|
||
### 其他部署腳本
|
||
|
||
| 腳本 | 說明 |
|
||
|------|------|
|
||
| `deploy.sh` | GCP 部署腳本（使用 gcloud） |
|
||
| `sync_env.sh` | 環境同步腳本 |
|
||
| `deploy_scripts/setup_autostart.sh` | 設定 systemd 自動啟動 |
|
||
|
||
---
|
||
|
||
## 常用指令
|
||
|
||
### UAT 伺服器操作
|
||
|
||
```bash
|
||
# SSH 連線到 UAT
|
||
ssh wooo@192.168.0.110
|
||
|
||
# 查看容器狀態
|
||
ssh wooo@192.168.0.110 'docker ps'
|
||
|
||
# 查看容器日誌（即時）
|
||
ssh wooo@192.168.0.110 'docker logs -f momo-pro-system'
|
||
|
||
# 查看最近 100 行日誌
|
||
ssh wooo@192.168.0.110 'docker logs --tail 100 momo-pro-system'
|
||
|
||
# 重啟容器
|
||
ssh wooo@192.168.0.110 'docker restart momo-pro-system'
|
||
|
||
# 停止容器
|
||
ssh wooo@192.168.0.110 'docker stop momo-pro-system'
|
||
|
||
# 進入容器 shell
|
||
ssh wooo@192.168.0.110 'docker exec -it momo-pro-system /bin/bash'
|
||
```
|
||
|
||
### Docker 相關
|
||
|
||
```bash
|
||
# 查看所有映像
|
||
docker images
|
||
|
||
# 清理未使用的映像
|
||
docker image prune -f
|
||
|
||
# 查看容器資源使用
|
||
docker stats momo-pro-system
|
||
|
||
# 查看容器詳細資訊
|
||
docker inspect momo-pro-system
|
||
```
|
||
|
||
### Git 相關
|
||
|
||
```bash
|
||
# 查看變更
|
||
git status
|
||
git diff
|
||
|
||
# 提交變更
|
||
git add .
|
||
git commit -m "描述變更"
|
||
|
||
# 查看提交歷史
|
||
git log --oneline -10
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### 常見問題
|
||
|
||
#### 1. SSH 連線失敗
|
||
```bash
|
||
# 檢查 SSH 連線
|
||
ssh -v wooo@192.168.0.110
|
||
|
||
# 確認金鑰權限
|
||
chmod 600 ~/.ssh/id_rsa
|
||
chmod 644 ~/.ssh/id_rsa.pub
|
||
```
|
||
|
||
#### 2. Docker 建置失敗
|
||
```bash
|
||
# 檢查 Docker 狀態
|
||
ssh wooo@192.168.0.110 'docker info'
|
||
|
||
# 查看建置錯誤
|
||
ssh wooo@192.168.0.110 'cd /home/wooo/momo_pro_system && docker build --no-cache -t wooo/momo-pro-system:latest .'
|
||
```
|
||
|
||
#### 3. 容器啟動失敗
|
||
```bash
|
||
# 查看容器日誌
|
||
ssh wooo@192.168.0.110 'docker logs momo-pro-system'
|
||
|
||
# 檢查 .env 檔案
|
||
ssh wooo@192.168.0.110 'cat /home/wooo/momo_pro_system/.env'
|
||
```
|
||
|
||
#### 4. 服務無法存取
|
||
```bash
|
||
# 檢查容器是否運行
|
||
ssh wooo@192.168.0.110 'docker ps -a'
|
||
|
||
# 檢查埠號綁定
|
||
ssh wooo@192.168.0.110 'docker port momo-pro-system'
|
||
|
||
# 檢查防火牆
|
||
ssh wooo@192.168.0.110 'sudo ufw status'
|
||
```
|
||
|
||
#### 5. 資料庫問題
|
||
```bash
|
||
# 進入容器檢查資料庫
|
||
ssh wooo@192.168.0.110 'docker exec -it momo-pro-system ls -la /app/data/'
|
||
```
|
||
|
||
---
|
||
|
||
## 部署紀錄
|
||
|
||
### 2026-01-18: 導航列 Logo 更新
|
||
- **變更內容**: 更新所有 HTML 頁面的導航列 Logo 為圓形 SVG 設計
|
||
- **Commit**: `037bba3`
|
||
- **部署時間**: 13:31:43
|
||
- **部署結果**: 成功
|
||
- **驗證結果**:
|
||
- 容器狀態: healthy
|
||
- 健康檢查: HTTP 200
|
||
- 首頁: HTTP 200
|
||
|
||
---
|
||
|
||
## 維護人員
|
||
|
||
- WOOO TECH 開發團隊
|
||
- 最後更新: 2026-01-18
|