根本原因是workers和worker_class配置错位或误将Uvicorn当独立服务器：workers应设为2×CPU核数（如4核设8），必须显式指定worker_class="uvicorn.workers.UvicornWorker"，漏写或拼错会退化为同步模式，导致async路由报TypeError。
为什么Gunicorn + Uvicorn组合启动后CPU打不满、QPS上不去
根本原因通常是 workers 和 worker_class 配置错位，或者误把 Uvicorn 当成独立服务器来用。Gunicorn 的 workers 控制的是进程数，而每个 Uvicorn Worker 本身是异步的，能并发处理数百甚至上千请求——不是“一个 worker = 一个请求”。盲目堆高 workers（比如设成 16）反而引发进程调度开销和内存争抢，压测时 CPU 利用率卡在 40% 就不动了。
实操建议：
-
workers推荐设为2 × CPU 核数（例如 4 核机器设workers = 8），超过 8 后吞吐增长极不明显 - 必须显式指定
worker_class = "uvicorn.workers.UvicornWorker"，漏写或拼错（如写成uvicor.workers...）会导致退化为同步模式，async def路由直接报TypeError: 'coroutine' object is not callable - Uvicorn 自身的
--workers参数在 Gunicorn 模式下完全失效，命令行里写uvicorn ... --workers 4会冲突，启动失败或静默退出
gunicorn.conf.py 里哪三个参数设错就直接挂
配置文件里最容易抄错又难排查的三个参数： bind、worker_class、preload。它们不报错，但会让服务要么起不来，要么跑着跑着就 502。
常见错误现象：
立即学习“Python免费学习笔记（深入）”；
-
bind = "0.0.0.0:8000"和 Nginx 反向代理共用端口 → 启动时报Address already in use；推荐改用 Unix socket：bind = "unix:/tmp/gunicorn.sock"，再让 Nginxproxy_pass unix:/tmp/gunicorn.sock -
worker_class缺失或值不对 → 日志里看不到UvicornWorker字样，所有 async 路由都变成阻塞调用，压测时延迟陡增 -
preload = False（默认值）→ 每个 worker 进程各自 import 一遍应用，容易触发模块级竞态（比如数据库连接池重复初始化），导致内存暴涨或连接耗尽；生产环境务必设preload = True
压测时出现 502 / timeout / connection reset 怎么定位
这类问题八成出在超时链路没对齐。Gunicorn、Uvicorn、Nginx、客户端四层 timeout 必须形成严格递减关系，否则必然断连。
关键参数对照：
- Gunicorn 的
timeout = 120（单位秒）：worker 处理单个请求最长等待时间，超时则杀掉该 worker 进程 - Gunicorn 的
keepalive = 5：HTTP keep-alive 连接空闲保持秒数，要小于 Nginx 的keepalive_timeout - Nginx 的
proxy_read_timeout 115：必须比 Gunicorntimeout小（留出缓冲），否则 Nginx 先断连，返回 502 - Uvicorn 自身不暴露 timeout 参数——它完全受 Gunicorn 控制，别在
uvicorn_config.py里设timeout，无效
部署后必查日志线索：errorlog = "-" 开启后，看是否有 Worker failed to boot 或 Timeout when reading response headers。
UvicornWorker 启动失败：ImportError 或 RuntimeError 怎么解
两种高频报错：ImportError: cannot import name 'application' 和 RuntimeError: There is no current event loop in thread，本质都是入口模块不符合 ASGI 协议。
核心要求只有一个：入口文件末尾必须有可调用的 app 对象，且不能是 async def app() 这种协程函数。
- ✅ 正确写法：
app = FastAPI()或app = get_asgi_application()（Django） - ❌ 错误写法：
async def app(): ...（这是协程，不是 ASGI callable） - ❌ 错误写法：
if __name__ == "__main__": uvicorn.run("main:app", ...)（Gunicorn 会自己调用，重复 run 导致端口冲突或事件循环混乱） - ⚠️ 注意路径：Gunicorn 加载的是
main:app，确保main.py在当前工作目录，或通过PYTHONPATH正确设置
复杂点在于：Django/Starlette/FastAPI 默认满足 ASGI，但手写 minimal ASGI 应用时，scope/receive/send 三参数签名缺一不可，少一个就会触发 RuntimeWarning: coroutine 'app' was never awaited。
