egg/TODOLIST
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backup

Browse Source
This commit is contained in:
beabigegg
2025-09-12 07:37:26 +08:00
commit a2f024704c
82 changed files with 26304 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

380
DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,380 @@
# 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
```
---
**注意**: 本文件包含敏感配置資訊，請妥善保管，僅限授權人員查看。