必须用gunicorn调用uvicorn.workers.UvicornWorker，否则FastAPI异步路由退化为同步、await失效、QPS降至单进程uvicorn的1/3；因FastAPI是ASGI应用而gunicorn默认syncworker仅支持WSGI协议，无法解析ASGI的scope/receive/send三元组。
必须用 gunicorn 调用 uvicorn.workers.UvicornWorker，否则 FastAPI 的异步路由会退化成同步执行，await 失效，QPS 可能只剩单进程 uvicorn 的 1/3。
为什么不能直接用 gunicorn 默认 worker 启动 FastAPI
FastAPI 是 ASGI 应用，而 gunicorn 默认的 syncworker 只支持 WSGI 协议。强行使用会导致：
-
RuntimeWarning: coroutine 'xxx' was never awaited或直接返回 500 错误 - 所有
@app.get("/async")路由被阻塞执行，await不起作用 - 并发能力掉回单线程水平，压测时连接堆积、响应延迟飙升
根本原因：Gunicorn 主进程把请求交给 syncworker 后，worker 自己解析、分发、执行——它根本不认识 ASGI 的 scope/receive/send 三元组。只有 uvicorn.workers.UvicornWorker 才会在每个子进程中真正启动一个 Uvicorn 实例来处理 ASGI 生命周期。
gunicorn 启动命令里 main:app 到底怎么写
冒号前是 Python 模块路径（不含 .py），冒号后是模块内定义的 FastAPI 实例变量名。常见错误包括：
- 文件叫
main.py，但里面写的是fastapi_app = FastAPI()，却运行gunicorn main:app→ 应该是main:fastapi_app - 入口在
src/app/main.py，没把src加进PYTHONPATH→ 启动报ImportError: No module named 'app' - 用了子包结构（如
app.main:app），但当前目录不是项目根目录，或没加--chdir /path/to/project
验证方式：在 shell 中运行 python -c "from main import app; print(app)"，能成功 import 就说明路径和变量名是对的。
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
worker 数量和超时参数怎么设才不翻车
多进程不是越多越好，关键看 CPU 核心数和 I/O 特性。默认公式是 workers = (2 × CPU核心数) + 1，但需结合实际调整：
- 8 核服务器上设
-w 17常见，但若应用重度依赖数据库或外部 HTTP 调用，反而应减少到-w 8避免上下文切换开销 -
--timeout 120必须设，否则慢查询或长轮询可能让 worker 卡死；但别设太短（如30），否则正常上传大文件会中断 -
--keep-alive 5推荐保留，HTTP/1.1 持久连接能降低 TCP 握手开销；Kubernetes 环境下可酌情调低 - 禁用
--preload除非你确认所有初始化逻辑是进程安全的（比如 DB 连接池在 fork 后会失效）
线上建议用配置文件而非命令行，避免参数遗漏：gunicorn -c gunicorn.conf.py main:app，其中 gunicorn.conf.py 至少包含 worker_class、workers、timeout 和 bind。
Nginx 反代时最容易漏掉的三个请求头
FastAPI 在 Gunicorn+Uvicorn 组合下，若没配对 Nginx 请求头，request.url 会变成 http://localhost:8000，app.url_path_for() 生成的链接全错，WebSockets 直接失败：
- 必须透传
X-Forwarded-For：否则request.client.host拿到的是 Nginx 内网 IP - 必须透传
X-Forwarded-Proto：否则 HTTPS 环境下重定向变成http:// - 必须透传
Host：否则request.url域名丢失，OpenAPI 文档里的 Try-it-out 按钮指向错误地址
对应 Nginx 配置段要包含：
proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme;
同时 FastAPI 初始化时得加 trust_headers=True，例如 app = FastAPI(trust_headers=True)，否则 Uvicorn Worker 会忽略这些头。
