9.6 KiB
9.6 KiB
TODO管理系統 - 生產環境部署指南
📋 概述
本文件提供TODO管理系統的完整生產環境部署指南，使用單一容器架構，簡化部署和維護。
🏗️ 系統架構
┌─────────────────────────────────────┐ ┌─────────────────┐
│ 單一容器應用 │ │ MySQL DB │
│ ┌─────────────┐ ┌─────────────────┐ │ │ theaken.com │
│ │Next.js 靜態 │ │ Flask API │ │◄───┤ Port: 33306 │
│ │ 文件 │ │ Port: 12011 │ │ │ │
│ └─────────────┘ └─────────────────┘ │ └─────────────────┘
│ 統一 Port: 12011 │
└─────────────────────────────────────┘
│
▼
┌─────────────────┐
│ LDAP/AD │
│ panjit.com.tw │
│ Port: 389 │
└─────────────────┘
🚀 快速部署
Windows 環境
# 1. 克隆專案（如果尚未克隆）
git clone <repository-url>
cd TODOLIST
# 2. 執行部署腳本
deploy.bat
# 或使用管理腳本
manage.bat
Linux/Mac 環境
# 1. 克隆專案（如果尚未克隆）
git clone <repository-url>
cd TODOLIST
# 2. 設置執行權限並執行部署腳本
chmod +x deploy.sh
./deploy.sh
📁 部署文件結構
TODOLIST/
├── backend/ # 後端代碼
│ ├── app.py # Flask應用（含靜態文件服務）
│ ├── requirements.txt # Python依賴
│ └── ...
├── frontend/ # 前端代碼
│ ├── next.config.js # Next.js配置（靜態導出）
│ ├── package.json # Node.js依賴
│ └── ...
├── Dockerfile # 單一容器構建文件
├── docker-compose.yml # Docker Compose配置
├── .env.production # 生產環境變量配置
├── deploy.bat # Windows部署腳本
├── deploy.sh # Linux/Mac部署腳本
├── manage.bat # Windows管理腳本
└── DEPLOYMENT.md # 部署說明文件
🔧 環境配置
生產環境變量 (.env.production)
本系統使用以下生產環境配置：
🗄️ 資料庫配置
- MySQL主機:
mysql.theaken.com:33306 - 資料庫:
db_A060 - 用戶:
A060
🔐 LDAP認證配置
- LDAP服務器:
panjit.com.tw:389 - 搜索基礎:
OU=PANJIT,DC=panjit,DC=com,DC=tw - 認證方式: Active Directory集成
📧 郵件服務配置
- SMTP服務器:
mail.panjit.com.tw:25 - 發送者:
todo-system@panjit.com.tw
🌐 服務端口
- 統一端口:
12011(前端 + 後端API)
🐳 Docker配置
單一容器架構
todolist-app: 整合式應用容器
- 端口映射:
12011:12011 - 健康檢查:
/api/health - 自動重啟:
unless-stopped - 包含: Flask API + Next.js 靜態文件
構建過程
- 階段1: 構建 Next.js 靜態文件
- 階段2: 設置 Flask 環境 + Gunicorn 生產服務器
- 階段3: 複製靜態文件到 Flask 容器
- 最終: 單一容器同時提供前後端服務 (Gunicorn驅動)
生產服務器配置
Gunicorn 配置參數:
--bind 0.0.0.0:12011 # 綁定地址和端口
--workers 4 # 4個工作進程
--threads 2 # 每進程2個線程
--timeout 120 # 請求超時120秒
--keep-alive 2 # 保持連線時間
--max-requests 1000 # 進程處理請求上限後自動重啟
--max-requests-jitter 100 # 隨機化重啟時機
總並發能力: 4 workers × 2 threads = 8個同時請求
🔍 手動部署步驟
如果需要手動部署，請按以下步驟執行：
1. 停止現有服務
# 停止並移除現有容器
docker-compose down
2. 建置Docker鏡像
# 建置單一容器鏡像
docker-compose build --no-cache
3. 啟動服務
# 使用Docker Compose啟動
docker-compose up -d
4. 驗證部署
# 檢查容器狀態
docker-compose ps
# 檢查服務健康
curl http://localhost:12011/api/health
curl http://localhost:12011
🧪 測試與驗證
服務訪問測試
# 前端頁面測試
curl http://localhost:12011
# API健康檢查
curl http://localhost:12011/api/health
# API功能測試
curl -X POST http://localhost:12011/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"test","password":"test"}'
🛠️ 維護指令
使用管理腳本 (Windows)
# 執行管理腳本
manage.bat
# 選項包括：
# 1. 部署應用程式
# 2. 停止服務
# 3. 檢視服務狀態
# 4. 檢視日誌
# 5. 重啟服務
# 6. 清理舊映像檔
日誌查看
# 查看服務日誌
docker-compose logs -f
# 查看最近日誌
docker-compose logs --tail=50
服務管理
# 重啟服務
docker-compose restart
# 停止服務
docker-compose down
# 更新並重啟
docker-compose down
docker-compose up -d --build
資源監控
# 查看容器狀態
docker-compose ps
# 查看資源使用
docker stats
# 查看容器詳情
docker inspect todolist-single-prod
🚨 故障排除
常見問題
1. 容器無法啟動
# 檢查日誌
docker-compose logs
# 檢查端口占用
netstat -ano | findstr :12011
2. 靜態文件無法載入
# 檢查文件是否正確複製
docker exec -it todolist-single-prod ls -la /app/frontend/out
# 重新構建並啟動
docker-compose down
docker-compose up -d --build
3. 資料庫連接失敗
- 確認網路連通性到
mysql.theaken.com:33306 - 驗證資料庫憑證
- 檢查防火牆設置
4. LDAP認證失敗
- 確認網路連通性到
panjit.com.tw:389 - 驗證LDAP服務帳號憑證
- 檢查搜索基礎設置
5. Dashboard/SPA頁面404錯誤 🆕
問題: 前端SPA路由（如 /todos/, /dashboard/）返回404 JSON錯誤
原因: Flask 404錯誤處理器攔截了所有404響應並返回JSON格式
解決方案:
# 重新構建應用（此問題已在最新版本修復）
docker-compose down
docker-compose up -d --build
技術詳情:
- 修復了
app.py中404錯誤處理器，只對API路徑返回JSON錯誤 - 非API路徑（SPA路由）現在正確返回
index.html - 修復了SPA路由處理邏輯，確保靜態文件與路由正確分離
6. Flask開發服務器警告 (已升級為生產服務器) 🆕
問題: 使用Flask開發服務器在生產環境，顯示警告且無法支撐多人使用 影響: 200人規模使用時會出現嚴重延遲和請求超時 解決方案:
# 系統已升級為Gunicorn生產服務器
docker-compose down
docker-compose up -d --build
升級詳情:
- ✅ Gunicorn生產服務器: 4 workers × 2 threads = 8個同時請求處理能力
- ✅ 支持200+用戶: 完全滿足企業級使用需求
- ✅ 自動重啟機制: 防止記憶體洩漏，提高穩定性
- ✅ 無開發服務器警告: 生產就緒配置
- ✅ 120秒超時設置: 適合複雜查詢操作
- ✅ 自動負載平衡: 多進程處理請求分配
性能對比:
| 項目 | Flask開發服務器 | Gunicorn生產服務器 |
|---|---|---|
| 並發處理 | 1個請求 | 8個同時請求 |
| 適用規模 | 5-10人 | 200+人 |
| 穩定性 | 低 | 高 |
| 生產就緒 | ❌ | ✅ |
健康檢查端點
- 應用健康檢查:
GET http://localhost:12011/api/health - 前端頁面檢查:
GET http://localhost:12011
🔒 安全考量
生產環境安全設置
-
更改默認密鑰：
- 修改
SECRET_KEY和JWT_SECRET_KEY - 使用強密碼策略
- 修改
-
網路安全：
- 考慮使用反向代理（Nginx）
- 配置HTTPS證書
- 限制外部訪問
-
監控與日誌：
- 設置日誌輪轉
- 監控系統資源
- 設置告警機制
📞 支援聯繫
- 系統管理員:
ymirliu@panjit.com.tw - 技術支援: 參考專案文檔或聯繫開發團隊
📝 版本資訊
- 系統版本: 2.1.0 🆕
- 架構: 單一容器部署
- 應用服務器: Gunicorn 21.2.0 (生產級WSGI服務器)
- 並發能力: 4 workers × 2 threads = 8個同時請求
- 支持規模: 200+用戶
- Docker映像:
todolist-single:latest - 訪問地址:
http://localhost:12011
🚀 v2.1.0 更新內容
- ✅ 升級為Gunicorn生產服務器，支持大規模用戶使用
- ✅ 修復SPA路由404錯誤問題
- ✅ 優化Badge圓形顯示問題
- ✅ 修復所有hardcoded API URL問題
- ✅ 完善錯誤處理和健康檢查機制
🔄 從舊版本升級
如果從分離式部署升級：
- 停止舊的分離式服務
docker stop todo-backend-prod todo-frontend-prod
docker rm todo-backend-prod todo-frontend-prod
- 部署新的單一容器
./deploy.sh # 或 deploy.bat
- 驗證服務正常
curl http://localhost:12011/api/health
curl http://localhost:12011
注意: 本文件包含敏感配置資訊，請妥善保管，僅限授權人員查看。