ewoooc/docs/DEPLOYMENT_GUIDE.md

Momo Pro System 部署指南

目錄

1. 環境資訊
2. 部署流程概覽
3. 本地開發環境
4. 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 提交變更

   git add .
   git commit -m "描述變更內容"
   

3. 執行部署腳本

   ./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/                   # 資料庫檔案

本地啟動

方式一：直接執行

python app.py

方式二：Docker Compose

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

一鍵部署

./deploy_docker_uat.sh deploy

部署流程詳解

執行 deploy_docker_uat.sh 腳本會自動完成以下步驟：

步驟 1/6: 同步檔案到 UAT

# 上傳 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: 停止現有服務

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

ssh wooo@192.168.0.110 "cd /home/wooo/momo_pro_system && docker build -t wooo/momo-pro-system:latest ."

步驟 4/6: 啟動 Docker 容器

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: 驗證部署

# 檢查容器狀態
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 伺服器操作

# 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 相關

# 查看所有映像
docker images

# 清理未使用的映像
docker image prune -f

# 查看容器資源使用
docker stats momo-pro-system

# 查看容器詳細資訊
docker inspect momo-pro-system

Git 相關

# 查看變更
git status
git diff

# 提交變更
git add .
git commit -m "描述變更"

# 查看提交歷史
git log --oneline -10

---

故障排除

常見問題

1. SSH 連線失敗

# 檢查 SSH 連線
ssh -v wooo@192.168.0.110

# 確認金鑰權限
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub

2. Docker 建置失敗

# 檢查 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. 容器啟動失敗

# 查看容器日誌
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. 服務無法存取

# 檢查容器是否運行
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. 資料庫問題

# 進入容器檢查資料庫
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