docs: 添加详细的生产部署文档（Gunicorn + Systemd + Nginx）

- WSGI 生产服务器配置说明 - 完整的 Systemd service 配置 - Nginx 反向代理 + SSL 配置示例 - 生产环境检查清单 - 优雅关闭特性说明
2026-07-17 00:10:25 +08:00
parent 76dca88ee7
commit 70b6da45c2
1 changed files with 126 additions and 29 deletions
@@ -177,38 +177,135 @@ SOCKS5 协议（RFC 1929）本身采用明文传输密码。本项目服务端

 所有 API 需要登录认证（Session Cookie），未登录返回 401。

-## 生产建议
+## 生产部署
+
+### 1. WSGI 生产服务器（Gunicorn）
+
+Flask 内置开发服务器不适合生产环境。使用 **Gunicorn**（生产级 WSGI 服务器）：

 ```bash
-# 1. 安装生产依赖
-pip install -r requirements.txt --break-system-packages
+# 安装 gunicorn
+pip install gunicorn --break-system-packages

-# 2. 设置强密钥
-export SM_SECRET_KEY=$(openssl rand -hex 32)
-export SM_ADMIN_PASSWORD=你的强密码
+# 启动（4 worker 进程，适合 4 核服务器）
+gunicorn -w 4 -b 0.0.0.0:5000 --timeout 120 run:app

-# 3. 使用 gunicorn 部署
-gunicorn -w 4 -b 0.0.0.0:5000 run:app
-
-# 4. 前置 Nginx 反向代理 + Let's Encrypt SSL
-# nginx.conf 示例：
-# location / {
-#     proxy_pass http://127.0.0.1:5000;
-#     proxy_set_header Host $host;
-#     proxy_set_header X-Real-IP $remote_addr;
-#     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-#     proxy_set_header X-Forwarded-Proto $scheme;
-# }
-
-# 5. HTTPS 时开启 Secure Cookie
-export SM_COOKIE_SECURE=true
-
-# 6. 多服务器跨域访问时设置 SESSION_DOMAIN（必须与浏览器 URL 一致）
-export SM_SESSION_DOMAIN=你的域名或IP
+# 推荐参数（更长超时 + 优雅关闭）
+gunicorn -w 2 -b 0.0.0.0:5000 \
+  --timeout 300 \
+  --graceful-timeout 30 \
+  --max-requests 10000 \
+  --max-requests-jitter 1000 \
+  run:app
 ```

-其他建议：
- 确保 `.env` 文件在 `.gitignore` 中（已配置），**不要提交到 git 仓库**
- 设置 `SM_LOG_LEVEL=WARN` 减少日志量
- 配置 crontab 定期备份数据库
- 使用 Daemon 或 systemd 管理进程
+> **注意**：SOCKS5 代理实例运行在独立的 asyncio 线程中，不受 Gunicorn worker 数量影响。
+
+---
+
+### 2. Systemd 服务配置（推荐）
+
+创建 `/etc/systemd/system/socks-manager.service`：
+
+```ini
+[Unit]
+Description=SOCKS5 Proxy Manager
+After=network.target
+
+[Service]
+Type=notify
+User=root
+WorkingDirectory=/opt/socks-manager
+Environment="PATH=/usr/local/bin:/usr/bin:/bin"
+
+# 生产环境变量（按需修改）
+Environment="SM_ADMIN_PASSWORD=你的强密码"
+Environment="SM_SECRET_KEY=生产环境用openssl rand -hex 32生成"
+Environment="SM_LOG_LEVEL=WARN"
+# Environment="SM_COOKIE_SECURE=true"  # HTTPS 时开启
+# Environment="SM_SESSION_DOMAIN=你的域名或IP"  # 跨域时设置
+
+ExecStart=/usr/local/bin/gunicorn -w 2 -b 0.0.0.0:5000 \
+  --timeout 300 \
+  --graceful-timeout 30 \
+  run:app
+
+# 优雅关闭：先给 SOCKS5 实例时间关闭活跃连接
+ExecStop=/bin/kill -s TERM $MAINPID
+TimeoutStopSec=60
+
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启动服务：
+```bash
+systemctl daemon-reload
+systemctl enable --now socks-manager
+systemctl status socks-manager
+journalctl -u socks-manager -f  # 查看实时日志
+```
+
+---
+
+### 3. Nginx 反向代理 + SSL
+
+```nginx
+server {
+    listen 80;
+    server_name 你的域名;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name 你的域名;
+
+    ssl_certificate /etc/letsencrypt/live/你的域名/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/你的域名/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:5000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+        proxy_request_buffering off;
+        proxy_http_version 1.1;
+    }
+}
+```
+
+---
+
+### 4. 生产环境检查清单
+
+✅ **强制修改默认密码**
+```bash
+# 生成强密钥
+export SM_SECRET_KEY=$(openssl rand -hex 32)
+```
+
+✅ **数据库备份**
+- 配置 crontab 每日备份 `socks_manager.db`
+- 定期测试恢复流程
+
+✅ **日志级别**
+- 生产环境设置 `SM_LOG_LEVEL=WARN` 减少日志量
+
+✅ **HTTPS**
+- 启用 Let's Encrypt SSL 证书
+- 设置 `SM_COOKIE_SECURE=true`
+
+✅ **防火墙**
+- 只开放需要的端口：Web 面板(5000) + SOCKS5 代理端口
+- SOCKS5 端口建议限制源 IP
+
+✅ **优雅关闭**
+- v1.1+ 版本已修复 SOCKS5 实例的优雅关闭逻辑
+- 停止服务时最多等待 5 秒让活跃连接正常关闭
+- 避免 `GeneratorExit` 和 `Task was destroyed` 警告