必须用uvicorn.workers.UvicornWorker，否则FastAPI异步路由退化为同步、await失效、QPS降至单进程uvicorn的1/3；因FastAPI是ASGI应用，而gunicorn默认syncworker仅支持WSGI协议，无法解析ASGI的scope/receive/send三元组。
必须用 uvicorn.workers.UvicornWorker，否则异步全失效
FastAPI 是 ASGI 应用，而 Gunicorn 默认用的是 syncworker，它只认 WSGI 协议。一旦你漏写 -k uvicorn.workers.UvicornWorker，就会出现：RuntimeWarning: coroutine 'xxx' was never awaited、500 Internal Server Error、所有 @app.get("/async") 路由变成串行执行——await 形同虚设，QPS 掉到单进程 uvicorn 的 1/3 左右。
根本原因不是“没启动好”，而是 Gunicorn 主进程把请求扔给 syncworker 后，worker 自己解析 HTTP、分发路由、执行函数，压根不理解 ASGI 的 scope/receive/send 三元组。只有 UvicornWorker 才会在每个子进程中真正拉起一个 Uvicorn 实例，完整跑通 ASGI 生命周期。
main:app 中的路径和变量名怎么写才不报 ImportError
这个错误几乎占部署失败的一半：明明文件叫 main.py，里面定义的是 fastapi_app = FastAPI()，却运行 gunicorn main:app ——结果报 ImportError: cannot import name 'app'。
- 冒号前是 Python 模块路径（不含
.py），当前目录需能直接import；比如入口在src/app/main.py，就得先确保src在PYTHONPATH里，或加--chdir /path/to/project - 冒号后是模块内实际变量名，不是固定写
app；查清你代码里FastAPI()赋值给了哪个变量（app、application、fastapi_app…） - 验证方式最可靠：在 shell 里执行
python -c "from main import app; print(app)"，能成功 import 就说明路径和变量名都对
进程数别套公式，得看负载类型和硬件限制
--workers 2×CPU核心数+1 这个公式在文档里很常见，但实操中常翻车：8 核机器设了 17 个 worker，CPU 利用率卡在 40%，QPS 却没涨。问题出在三重叠加：Python GIL 对 CPU 密集型任务的限制、Uvicorn 进程间完全隔离（模型加载开销翻倍）、容器 cgroups 或 GPU 显存的实际约束。
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
推荐按业务类型调整：
- CPU 密集型（如模型推理）：6～8 个 worker（避免进程切换反拖慢响应）
- I/O 密集型（如调外部 API、数据库）：12～16 个 worker
- 混合型：10 个左右起步，再配合
ps aux | grep gunicorn、lsof -i :8000和top -Hp验证是否真生效
几个关键配置不设，高可用就只是摆设
Gunicorn + Uvicorn 组合里，真正影响线上稳定性的就那几个参数，设错一个，集群可能形同虚设。
-
--timeout 120必须设：防止长连接或慢查询卡住整个 worker，导致后续请求排队甚至雪崩；但别设太短（如 5 秒），否则正常文件上传或聚合查询会被误杀 -
--keep-alive 5推荐设为 5–30 秒：减少客户端频繁建连开销；注意别超过 Nginx 的proxy_read_timeout，否则连接被反向代理提前中断 -
--preload要慎用：它让主进程提前加载代码和模型，能缓解冷启动，但也会让环境变量（如os.getenv("DB_URL")）在子进程里读不到——改用raw_env在配置文件里显式注入更稳妥
真正容易被忽略的是：Uvicorn Worker 本身不接管 --timeout 或 --keep-alive，这些全是 Gunicorn 主进程控制的。哪怕你在 gunicorn.conf.py 里写了 timeout = 120，但命令行又传了 --timeout 30，最终生效的是命令行值——优先级比配置文件高。
