129 lines
3.8 KiB
Markdown
129 lines
3.8 KiB
Markdown
# TODO 管理系統 - 生產環境部署指南（最新架構）
|
||
|
||
## 概述
|
||
|
||
本文件說明最新部署架構：以 Nginx 為對外入口（Port 12011），反向代理至後端 Gunicorn（容器內 12011），前端由 Flask 靜態目錄提供。此架構提升穩定度與擴充性，支援約 200 位同時使用者。
|
||
|
||
## 架構總覽
|
||
|
||
- 對外入口：Nginx（容器 `nginx`），監聽並對外開放 `12011`
|
||
- 應用服務：Flask + Gunicorn（容器 `todolist-app`），僅容器網路內提供 `12011`
|
||
- 前端：Next.js 靜態輸出，隨應用容器打包（Flask 靜態目錄 `frontend/out`）
|
||
- CORS：允許 `http://localhost:12011`、`http://127.0.0.1:12011`
|
||
|
||
## 專案結構（摘要）
|
||
|
||
```
|
||
TODOLIST/
|
||
├─ backend/ # 後端程式（Flask）
|
||
│ ├─ app.py # Flask 應用（含 SPA 靜態路由）
|
||
│ └─ requirements.txt # Python 依賴
|
||
├─ frontend/ # 前端（Next.js 靜態輸出）
|
||
├─ nginx/
|
||
│ └─ nginx.conf # Nginx 反向代理設定（listen 12011）
|
||
├─ Dockerfile # 應用容器建置檔（含 Gunicorn 啟動）
|
||
├─ docker-compose.yml # Compose：nginx + todolist-app
|
||
└─ .env.production # 生產環境變數
|
||
```
|
||
|
||
## 主要環境變數（.env.production）
|
||
|
||
- Database：`MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE`
|
||
- LDAP/AD：`LDAP_SERVER, LDAP_PORT, LDAP_USE_SSL, LDAP_SEARCH_BASE, LDAP_BIND_USER_DN, LDAP_BIND_USER_PASSWORD, LDAP_USER_LOGIN_ATTR`
|
||
- SMTP：`SMTP_SERVER, SMTP_PORT, SMTP_USE_TLS, SMTP_USE_SSL, SMTP_AUTH_REQUIRED, SMTP_SENDER_EMAIL, SMTP_SENDER_PASSWORD`
|
||
- Flask/JWT：`SECRET_KEY, JWT_SECRET_KEY`
|
||
- CORS：`CORS_ORIGINS=http://localhost:12011,http://127.0.0.1:12011`
|
||
|
||
## Docker 服務（最新）
|
||
|
||
- `todolist-app`（應用容器）
|
||
- 對外不開放 Port；內部提供 `12011`
|
||
- 健康檢查：`GET /api/health/`
|
||
- 重啟策略：`unless-stopped`
|
||
|
||
- `nginx`（反向代理）
|
||
- 對外 Port：`12011:12011`
|
||
- 代理規則：`/api/*` 與其餘路由 → `todolist-app:12011`
|
||
- 設定檔：`nginx/nginx.conf`
|
||
|
||
## Gunicorn 生產設定（現行）
|
||
|
||
Dockerfile 已內建以下啟動參數：
|
||
|
||
```bash
|
||
--bind 0.0.0.0:12011
|
||
--worker-class gthread
|
||
--workers 4
|
||
--threads 8
|
||
--timeout 120
|
||
--keep-alive 10
|
||
--max-requests 2000
|
||
--max-requests-jitter 200
|
||
--forwarded-allow-ips *
|
||
```
|
||
|
||
並發估算：4 workers × 8 threads ≈ 32 併發（可依 CPU 核心數調整）。
|
||
|
||
## 部署步驟
|
||
|
||
Windows：
|
||
```batch
|
||
git clone <repository-url>
|
||
cd TODOLIST
|
||
deploy.bat
|
||
```
|
||
|
||
Linux/Mac：
|
||
```bash
|
||
git clone <repository-url>
|
||
cd TODOLIST
|
||
chmod +x deploy.sh
|
||
./deploy.sh
|
||
```
|
||
|
||
或直接使用 Compose：
|
||
```bash
|
||
docker-compose up --build -d
|
||
```
|
||
|
||
## 驗證與測試
|
||
|
||
```bash
|
||
curl http://localhost:12011 # 前端首頁
|
||
curl http://localhost:12011/api/health # 健康檢查
|
||
```
|
||
|
||
## 維運常用指令
|
||
|
||
```bash
|
||
docker-compose ps
|
||
docker-compose logs -f
|
||
docker-compose restart
|
||
docker-compose down
|
||
docker-compose up -d --build
|
||
docker stats
|
||
docker inspect todolist-nginx
|
||
docker inspect todolist-single-prod
|
||
```
|
||
|
||
## 疑難排解（重點）
|
||
|
||
- 端口占用：`netstat -ano | findstr :12011`
|
||
- SPA 404：由 Flask 回傳 `index.html` 已處理；若異常請重建鏡像
|
||
- 後端 URL 與重導：已加 `ProxyFix` 並信任代理標頭
|
||
- 大量連線：由 Nginx 保持連線與緩衝，Gunicorn gthread 提升併發
|
||
|
||
## 安全建議
|
||
|
||
- 更換強度足夠的 `SECRET_KEY` 與 `JWT_SECRET_KEY`
|
||
- 若需 TLS/443，可在 `nginx/nginx.conf` 新增對應 server 與憑證設定
|
||
- 適度設定 `client_max_body_size`、基本安全標頭與 Rate Limit（視需求）
|
||
|
||
## 版本資訊（摘要）
|
||
|
||
- 架構：Nginx 反向代理 + Gunicorn 應用容器（對外 Port 12011）
|
||
- 應用服務器：Gunicorn 21.2.0
|
||
- 併發能力：預設約 32（可依硬體調整）
|
||
- 訪問端點：`http://localhost:12011`
|
||
|