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 已內建以下啟動參數：

--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：

git clone <repository-url>
cd TODOLIST
deploy.bat

Linux/Mac：

git clone <repository-url>
cd TODOLIST
chmod +x deploy.sh
./deploy.sh

或直接使用 Compose：

docker-compose up --build -d

驗證與測試

curl http://localhost:12011            # 前端首頁
curl http://localhost:12011/api/health # 健康檢查

維運常用指令

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

3.8 KiB Raw Blame History Unescape Escape