# TODO管理系統 - 生產環境部署指南 ## 📋 概述 本文件提供TODO管理系統的完整生產環境部署指南,使用單一容器架構,簡化部署和維護。 ## 🏗️ 系統架構 ``` ┌─────────────────────────────────────┐ ┌─────────────────┐ │ 單一容器應用 │ │ MySQL DB │ │ ┌─────────────┐ ┌─────────────────┐ │ │ theaken.com │ │ │Next.js 靜態 │ │ Flask API │ │◄───┤ Port: 33306 │ │ │ 文件 │ │ Port: 12011 │ │ │ │ │ └─────────────┘ └─────────────────┘ │ └─────────────────┘ │ 統一 Port: 12011 │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────┐ │ LDAP/AD │ │ panjit.com.tw │ │ Port: 389 │ └─────────────────┘ ``` ## 🚀 快速部署 ### Windows 環境 ```batch # 1. 克隆專案(如果尚未克隆) git clone cd TODOLIST # 2. 執行部署腳本 deploy.bat # 或使用管理腳本 manage.bat ``` ### Linux/Mac 環境 ```bash # 1. 克隆專案(如果尚未克隆) git clone 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. **階段1**: 構建 Next.js 靜態文件 2. **階段2**: 設置 Flask 環境 + Gunicorn 生產服務器 3. **階段3**: 複製靜態文件到 Flask 容器 4. **最終**: 單一容器同時提供前後端服務 (Gunicorn驅動) ### 生產服務器配置 **Gunicorn 配置參數**: ```bash --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. 停止現有服務 ```bash # 停止並移除現有容器 docker-compose down ``` ### 2. 建置Docker鏡像 ```bash # 建置單一容器鏡像 docker-compose build --no-cache ``` ### 3. 啟動服務 ```bash # 使用Docker Compose啟動 docker-compose up -d ``` ### 4. 驗證部署 ```bash # 檢查容器狀態 docker-compose ps # 檢查服務健康 curl http://localhost:12011/api/health curl http://localhost:12011 ``` ## 🧪 測試與驗證 ### 服務訪問測試 ```bash # 前端頁面測試 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) ```batch # 執行管理腳本 manage.bat # 選項包括: # 1. 部署應用程式 # 2. 停止服務 # 3. 檢視服務狀態 # 4. 檢視日誌 # 5. 重啟服務 # 6. 清理舊映像檔 ``` ### 日誌查看 ```bash # 查看服務日誌 docker-compose logs -f # 查看最近日誌 docker-compose logs --tail=50 ``` ### 服務管理 ```bash # 重啟服務 docker-compose restart # 停止服務 docker-compose down # 更新並重啟 docker-compose down docker-compose up -d --build ``` ### 資源監控 ```bash # 查看容器狀態 docker-compose ps # 查看資源使用 docker stats # 查看容器詳情 docker inspect todolist-single-prod ``` ## 🚨 故障排除 ### 常見問題 #### 1. 容器無法啟動 ```bash # 檢查日誌 docker-compose logs # 檢查端口占用 netstat -ano | findstr :12011 ``` #### 2. 靜態文件無法載入 ```bash # 檢查文件是否正確複製 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格式 **解決方案**: ```bash # 重新構建應用(此問題已在最新版本修復) docker-compose down docker-compose up -d --build ``` **技術詳情**: - 修復了 `app.py` 中404錯誤處理器,只對API路徑返回JSON錯誤 - 非API路徑(SPA路由)現在正確返回 `index.html` - 修復了SPA路由處理邏輯,確保靜態文件與路由正確分離 #### 6. Flask開發服務器警告 (已升級為生產服務器) 🆕 **問題**: 使用Flask開發服務器在生產環境,顯示警告且無法支撐多人使用 **影響**: 200人規模使用時會出現嚴重延遲和請求超時 **解決方案**: ```bash # 系統已升級為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` ## 🔒 安全考量 ### 生產環境安全設置 1. **更改默認密鑰**: - 修改 `SECRET_KEY` 和 `JWT_SECRET_KEY` - 使用強密碼策略 2. **網路安全**: - 考慮使用反向代理(Nginx) - 配置HTTPS證書 - 限制外部訪問 3. **監控與日誌**: - 設置日誌輪轉 - 監控系統資源 - 設置告警機制 ## 📞 支援聯繫 - **系統管理員**: `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問題 - ✅ 完善錯誤處理和健康檢查機制 ## 🔄 從舊版本升級 如果從分離式部署升級: 1. 停止舊的分離式服務 ```bash docker stop todo-backend-prod todo-frontend-prod docker rm todo-backend-prod todo-frontend-prod ``` 2. 部署新的單一容器 ```bash ./deploy.sh # 或 deploy.bat ``` 3. 驗證服務正常 ```bash curl http://localhost:12011/api/health curl http://localhost:12011 ``` --- **注意**: 本文件包含敏感配置資訊,請妥善保管,僅限授權人員查看。