# 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`