docs: 补充内存限流与登录防爆破多进程局限及部署建议

2026-09-19 08:49:50 +00:00
parent c0bcf1d851
commit c2c4752856
2 changed files with 65 additions and 0 deletions
@@ -165,3 +165,59 @@ cat backup.sql | docker exec -i profeto-postgres psql -U football football
 - `/health`: 存活检查
 - 日志:容器 stdout(`docker compose logs -f api`)
 - 评估汇总:`GET /api/v1/eval/summary`(准确率/RMSAE/校准度)
+
+## 安全与限流
+
+### 内存限流(按进程)
+
+`/api/v1/predict` 与登录防爆破均使用**进程内内存**计数:
+
+| 机制 | 位置 | 局限 |
+|------|------|------|
+| `/predict` 限流 | `_RateLimiter`(内存) | 每 worker 独立计数,不共享 |
+| 登录防爆破 | `_fail_times`(内存) | 同上 |
+
+**多 worker 部署时**(如 `uvicorn --workers 4`),每进程各自计数,实际限额为 `N × 单进程限制`。
+
+### 公网部署建议
+
+```
+┌─────────┐     ┌──────────┐     ┌──────────┐
+│  Client │────▶│  Nginx   │────▶│  API     │
+│         │     │ 限流层    │     │ 内存限流  │
+└─────────┘     └──────────┘     └──────────┘
+```
+
+**推荐配置**:
+
+1. **Nginx 层限流**(第一道防线):
+   ```nginx
+   limit_req_zone $binary_remote_addr zone=predict:10m rate=10r/m;
+   location /api/v1/predict {
+       limit_req zone=predict burst=20 nodelay;
+       proxy_pass http://api:8000;
+   }
+   ```
+
+2. **TRUST_PROXY_HEADERS=True** 时必须由可信反代设置 `X-Forwarded-For`:
+   ```nginx
+   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+   ```
+   - 若为 `False`: 仅用 `request.client.host`,忽略 `X-Forwarded-For`,防伪造
+   - 若为 `True`: 解析 `X-Forwarded-For` 第一个 IP,反代后方可信
+
+3. **生产环境必须配置管理鉴权**:
+   ```bash
+   APP_ENV=production
+   REQUIRE_ADMIN_AUTH=True
+   ADMIN_PASSWORD=your_secure_password
+   ```
+   未配置时 `/admin` 等管理接口返回 503。
+
+### 参数调优
+
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| `_predict_limiter.max_requests` | 10 | 每分钟每 IP 最大请求数 |
+| `_predict_limiter.window_seconds` | 60 | 滑动窗口时长 |
+| `ADMIN_SESSION_TTL_HOURS` | 168 | 管理会话有效期(天) |