ewoooc/DEPLOYMENT_WORKFLOW.md

MOMO 監控系統 - 開發測試部署流程

版本： 1.0 制定日期： 2026-01-13 最後更新： 2026-01-13

---

🏗️ 環境架構

環境分層

環境	位置	用途	網址	運行方式
開發環境 (Dev)	/Users/ogt/momo_pro_system	本地開發、程式碼修改	http://127.0.0.1:80	直接運行 python app.py
測試環境 (Test)	同開發環境	功能測試、安全測試	同開發環境	執行測試腳本

環境特性

開發環境 (macOS Local)

• 系統：macOS (Darwin)
• Python：pyenv 管理的 Python 3.11.7
• 資料庫：本地 SQLite
• 用途：
  • 程式碼開發
  • 快速測試
  • UI/UX 調整
  • 新功能實驗

正式環境 (GCP VM)

• 系統：Ubuntu 22.04 LTS
• Python：系統 Python 或 venv
• 服務管理：systemd (momo.service)
• 反向代理：可能使用 nginx
• 域名：DuckDNS (momo.wooo.work)
• 用途：
  • 生產服務
  • 24/7 運行
  • 爬蟲任務排程
  • 使用者訪問

---

📋 完整開發部署流程

階段 1：需求與規劃

graph LR
    A[需求確認] --> B[功能設計]
    B --> C[技術評估]
    C --> D[風險評估]
    D --> E[制定計劃]

檢查清單：

• 需求文檔完整
• 技術方案可行
• 評估對現有功能的影響
• 確認是否需要爬蟲修改（若是，參照憲法第四章）
• 確認是否影響安全（若是，參照憲法第二章）

---

階段 2：本地開發 (Dev)

2.1 環境準備

# 確保在開發環境
cd /Users/ogt/momo_pro_system

# 確認虛擬環境
source venv/bin/activate

# 確認依賴最新
pip list

2.2 程式碼開發

# 1. 創建功能分支（重大修改）
git checkout -b feature/功能名稱

# 2. 開發程式碼
# - 遵守憲法第三章程式碼規範
# - 使用繁體中文註解
# - 添加錯誤處理
# - 記錄詳細日誌

# 3. 本地測試
python app.py
# 訪問 http://127.0.0.1:80 測試功能

開發規範：

• ✅ 所有註解使用繁體中文
• ✅ 所有輸入經過驗證
• ✅ 使用 safe_join() 處理路徑
• ✅ POST 請求包含 CSRF token
• ✅ 敏感資訊使用環境變數
• ✅ 完整的錯誤處理和日誌

2.3 Git 提交

# 查看修改
git status
git diff

# 提交修改
git add 相關檔案
git commit -m "[模組] 繁體中文描述"

# 範例：
# git commit -m "[UI] 為廠商缺貨系統所有子頁面添加返回主頁按鈕"
# git commit -m "[Crawler] [MOMO] 修復商品價格選擇器失效"
# git commit -m "[Security] 強化檔案上傳驗證"

---

階段 3：本地測試 (Test)

3.1 功能測試

# 手動測試
python app.py
# 1. 測試新功能正常運作
# 2. 測試現有功能未受影響
# 3. 測試邊界情況
# 4. 測試錯誤處理

3.2 安全測試（如涉及安全）

# 執行完整安全測試套件
./run_security_tests.sh

# 或個別測試
python test_sql_security.py
python test_path_traversal.py
python test_file_upload.py

必須通過：

• ✅ 所有安全測試通過
• ✅ 無新增安全漏洞
• ✅ 日誌記錄完整

3.3 爬蟲測試（如涉及爬蟲）

# 執行爬蟲測試
python test_crawler_specific.py

# 測試項目：
# 1. 選擇器有效性
# 2. 資料完整性
# 3. 錯誤處理
# 4. 效能測試

必須通過：

• ✅ 選擇器正確抓取資料
• ✅ 資料格式正確
• ✅ 錯誤處理完整
• ✅ 執行時間合理

3.4 回歸測試

# 確認現有功能未受影響
# 1. 測試主要功能流程
# 2. 測試業績分析
# 3. 測試爬蟲任務
# 4. 測試廠商缺貨系統
# 5. 測試 Google Drive 自動匯入

---

階段 4：部署前準備

4.1 程式碼檢查

檢查清單：

• 所有測試通過
• 程式碼遵守規範
• 註解完整清晰
• 無硬編碼敏感資訊
• 日誌記錄完整
• Git commit 完成
• 文檔更新完成

4.2 確認修改檔案清單

# 查看本次修改的所有檔案
git status
git diff --name-only

# 列出修改清單，確認需要部署的檔案
# 範例：
# - sales_analysis.html
# - vendor_stockout_list.html
# - vendor_stockout_import.html
# - vendor_stockout_send_email.html
# - vendor_stockout_history.html

4.3 備份正式環境

# 連接到 GCP VM
gcloud compute ssh momo-server --zone=asia-east1-a

# 在 VM 上執行備份
cd /home/ogt/momo_pro_system
./deploy_scripts/backup.sh
# 或手動備份
tar -czf backup_$(date +%Y%m%d_%H%M%S).tar.gz \
    --exclude='venv' \
    --exclude='__pycache__' \
    --exclude='*.log' \
    .

---

階段 5：部署到正式環境

方法 A：完整部署（推薦用於大改動）

# 在本地執行
cd /Users/ogt/momo_pro_system

# 使用部署腳本自動上傳

# 腳本會：
# 1. 檢查 gcloud 登入狀態
# 2. 檢查 VM 狀態
# 3. 上傳所有檔案（排除 venv、__pycache__、logs）
# 4. 提示後續步驟

然後連接到 VM：

# 連接到 VM
gcloud compute ssh momo-server --zone=asia-east1-a

# 在 VM 上執行
cd ~/momo_pro_system

# 安裝/更新依賴（如有新依賴）
source venv/bin/activate
pip install -r requirements.txt

# 重啟服務
sudo systemctl restart momo.service

# 檢查服務狀態
sudo systemctl status momo.service

# 查看日誌
sudo journalctl -u momo.service -f

方法 B：快速更新（用於小改動，僅 HTML/CSS/JS）

# 在本地執行
cd /Users/ogt/momo_pro_system

# 僅上傳修改的檔案
gcloud compute scp --zone=asia-east1-a \
    sales_analysis.html \
    vendor_stockout_list.html \
    vendor_stockout_import.html \
    vendor_stockout_send_email.html \
    vendor_stockout_history.html \
    momo-server:~/momo_pro_system/

# HTML 模板檔案不需要重啟服務
# Flask 會自動重新載入模板

注意：

• HTML/CSS/JS 檔案：不需重啟服務
• Python 檔案（.py）：需要重啟服務
• 配置檔案（.env）：需要重啟服務
• 依賴更新（requirements.txt）：需要重新安裝並重啟

---

階段 6：部署後驗證

6.1 服務狀態檢查

# 在 GCP VM 上執行
sudo systemctl status momo.service

# 查看最近的日誌
sudo journalctl -u momo.service -n 100

# 檢查是否有錯誤
sudo journalctl -u momo.service -p err -n 50

6.2 功能驗證

# 測試網站訪問
curl -I https://momo.wooo.work

# 測試特定功能頁面
curl -I https://momo.wooo.work/vendor-stockout/send-email
curl -I https://momo.wooo.work/vendor-stockout/history

手動驗證：

• 訪問 https://momo.wooo.work
• 測試修改的功能
• 確認新功能正常運作
• 確認現有功能未受影響
• 檢查是否有 JavaScript 錯誤（瀏覽器 Console）
• 測試在不同瀏覽器（Chrome, Safari）

6.3 監控檢查

# 監控系統日誌（持續 10 分鐘）
tail -f /home/ogt/momo_pro_system/logs/system.log

# 檢查是否有錯誤或異常

監控項目：

• 無錯誤訊息
• 爬蟲任務正常執行
• 資料庫操作正常
• 記憶體使用正常
• CPU 使用正常

6.4 24 小時監控

重要：部署後必須監控 24 小時

• 定期檢查日誌
• 確認排程任務正常執行
• 確認通知正常發送
• 監控系統資源使用

---

🔄 回滾流程

何時需要回滾

• ❌ 部署後發現嚴重錯誤
• ❌ 核心功能失效
• ❌ 爬蟲完全失敗
• ❌ 系統崩潰或無法啟動
• ❌ 資料庫損壞

回滾步驟

# 1. 連接到 GCP VM
gcloud compute ssh momo-server --zone=asia-east1-a

# 2. 停止服務
sudo systemctl stop momo.service

# 3. 還原備份
cd /home/ogt/momo_pro_system
mv momo_pro_system momo_pro_system_failed
tar -xzf backup_20260113_HHMMSS.tar.gz

# 4. 重啟服務
sudo systemctl start momo.service

# 5. 驗證服務恢復
sudo systemctl status momo.service
curl -I https://momo.wooo.work

# 6. 記錄問題
# 在本地環境修復問題，重新測試後再次部署

---

📝 部署檢查清單總表

部署前檢查（Pre-Deployment）

• 功能開發完成
• 本地測試通過
• 安全測試通過（如涉及）
• 爬蟲測試通過（如涉及）
• 回歸測試通過
• 程式碼遵守規範
• Git commit 完成
• 文檔更新完成
• 正式環境已備份

部署中檢查（During Deployment）

• 檔案上傳成功
• 依賴安裝成功（如需要）
• 服務重啟成功（如需要）
• 無錯誤訊息

部署後檢查（Post-Deployment）

• 服務狀態正常
• 網站可以訪問
• 新功能正常運作
• 現有功能未受影響
• 日誌無異常
• 排程任務正常
• 監控 24 小時
• 更新部署日誌

---

🔧 常用命令速查

本地開發

# 啟動開發環境
cd /Users/ogt/momo_pro_system
source venv/bin/activate
python app.py

# 執行測試
./run_security_tests.sh
python test_specific.py

# Git 操作
git status
git add .
git commit -m "[模組] 描述"
git push

📊 環境差異注意事項

路徑差異

項目	開發環境	正式環境
專案路徑	/Users/ogt/momo_pro_system	/home/ogt/momo_pro_system
Python	/Users/ogt/.pyenv/versions/3.11.7/bin/python	/home/ogt/momo_pro_system/venv/bin/python
資料庫	data/momo_database.db	data/momo_database.db
日誌	logs/	logs/

服務運行差異

項目	開發環境	正式環境
運行方式	直接 python app.py	systemd service
Port	80	80
網址	http://127.0.0.1:80	https://momo.wooo.work
自動重啟	否	是（systemd）
日誌管理	檔案	systemd journal + 檔案

注意事項

1. 程式碼差異：

   • 開發環境和正式環境的程式碼必須保持同步
   • 避免在正式環境直接修改程式碼
   • 所有修改必須經過開發→測試→部署流程

2. 資料庫差異：

   • 開發環境和正式環境使用不同的資料庫
   • 不要混用資料庫檔案
   • 測試時使用測試資料，避免污染正式資料

3. 環境變數：

   • .env 檔案在兩個環境中可能不同
   • 確保正式環境的憑證正確配置
   • 不要將 .env 上傳到 Git

---

🎯 最佳實踐

DO ✅

• ✅ 小步提交，頻繁部署
• ✅ 每次部署前備份
• ✅ 完整測試後再部署
• ✅ 部署後立即驗證
• ✅ 監控 24 小時
• ✅ 記錄部署日誌
• ✅ 遵守憲法規範

DON'T ❌

• ❌ 直接在正式環境改程式碼
• ❌ 跳過測試直接部署
• ❌ 部署後不驗證
• ❌ 不備份就部署
• ❌ 在高峰時段部署重大更新
• ❌ 同時部署多個大改動

---

📈 持續改進

定期檢視

• 每月檢視部署流程效率
• 收集部署中遇到的問題
• 優化自動化腳本
• 更新文檔

自動化目標

未來可考慮的自動化：

• CI/CD 流程（GitHub Actions）
• 自動化測試流程
• 自動化部署腳本
• 自動化回滾機制
• 部署通知（Telegram/Line）

---

版本歷史：

• v1.0 (2026-01-13): 初版發布，定義完整開發測試部署流程