Files
TODOLIST/DEPLOYMENT.md
beabigegg a2f024704c backup
2025-09-12 07:37:26 +08:00

380 lines
9.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 <repository-url>
cd TODOLIST
# 2. 執行部署腳本
deploy.bat
# 或使用管理腳本
manage.bat
```
### Linux/Mac 環境
```bash
# 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. **階段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
```
---
**注意**: 本文件包含敏感配置資訊,請妥善保管,僅限授權人員查看。