必须用Gunicorn调用Uvicorn ASGI worker部署FastAPI，因FastAPI是ASGI应用而Gunicorn默认仅支持WSGI；启动命令需含--worker-class uvicorn.workers.UvicornWorker，Nginx反代须转发Host、X-Forwarded-For、X-Forwarded-Proto请求头并配合FastAPI启用trust_headers。
不能直接用 Gunicorn 托管 FastAPI，因为 FastAPI 是 ASGI 应用，而 Gunicorn 默认只支持 WSGI。必须让 Gunicorn 调用 Uvicorn 的 ASGI worker，再由 Nginx 做反向代理——这才是生产可用的组合。
Gunicorn 启动命令必须指定 Uvicorn worker
在宝塔面板或手动部署时，启动命令里一定要包含 --worker-class uvicorn.workers.UvicornWorker，否则会报错或静默失败：
- 正确写法：gunicorn main:app --workers 2 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000 --timeout 120
- main.py 是入口文件名，app 是 FastAPI 实例变量名，需严格一致
- --workers 数值建议设为 CPU 核心数的 2 倍（如 2 核服务器设为 4），内存 ≤2GB 时建议用 2
- --bind 地址必须是 0.0.0.0:8000（不是 127.0.0.1），否则宝塔内部网络无法通信
Nginx 反向代理要转发关键请求头
仅 proxy_pass 不够，不加 header 转发会导致 FastAPI 拿不到真实 IP、协议和主机名，影响鉴权、重定向、WebSockets 等功能：
- 在 server 块中添加以下三项（缺一不可）：
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- 如果用了 Cloudflare 或 CDN，还需加 proxy_set_header X-Real-IP $remote_addr;
- FastAPI 中启用 trust_headers=True（如使用 Starlette 的 TrustedHostMiddleware 或自定义中间件）才能信任这些头
端口与进程管理要避免冲突
Nginx 和 Gunicorn 的端口、权限、运行用户需协调一致：
立即学习“Python免费学习笔记（深入）”；
- Nginx 通常监听 80/443，proxy_pass 指向 Gunicorn 的 8000、8001 等内部端口，二者端口不能重叠
- Gunicorn 进程建议用非 root 用户运行（如 www-data 或宝塔创建的项目用户），避免权限过高风险
- 若用 supervisor 或 systemd 管理 Gunicorn，确保其配置中的 working_dir、user、environment 与项目路径匹配
- 日志中看到 Booting worker with pid 和 Uvicorn running on http://0.0.0.0:8000 才算真正启动成功
