# 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
