FastAPI与Gunicorn高并发优化技巧

FastAPI 本身并不直接处理高并发，其真正的高并发能力依赖于底层 ASGI 服务器（如 Uvicorn）和合理的部署架构——尤其是 Gunicorn 配合 `uvicorn.workers.UvicornWorker` 的正确配置；一旦误用同步 worker、忽略异步数据库驱动（如用 psycopg2 而非 asyncpg）、或 SQLAlchemy 未启用 `AsyncEngine`，整条异步链路就会悄然退化为同步阻塞，导致性能断崖式下降；本文直击生产环境中最易踩坑的配置细节、参数陷阱与排查信号，帮你从“写了 async def 却还是慢”的困惑中突围，真正释放 FastAPI 的异步潜力。

FastAPI 本身不处理并发，靠的是底层 ASGI 服务器和 worker 模式

很多人以为 FastAPI 自带高并发能力，其实它只是个异步 Web 框架，真正扛并发的是运行它的 ASGI 服务器（比如 uvicorn）以及部署时的进程/线程模型。直接用 uvicorn --workers 4 启动看似简单，但和 Gunicorn 配合时容易出问题——Gunicorn 默认是 WSGI 模式，不支持 async，硬套会报 RuntimeError: This event loop is already running。

实操建议：

• 必须用 Gunicorn 的 uvicorn.workers.UvicornWorker worker 类，而不是默认的 sync
• 启动命令里不能同时指定 --workers 和 --threads，否则 UvicornWorker 会忽略 --workers，只用单进程 + 多线程，失去异步优势
• uvicorn 单进程已能高效处理成百上千并发请求；Gunicorn 的作用主要是进程管理、平滑重启、信号转发，不是“加 worker 就一定更稳”

Gunicorn + UvicornWorker 的关键配置项

配置错一个参数，就可能让异步变成同步，或触发死锁。重点盯住这三个：

• workers：建议设为 CPU 核心数 × 2，但不超过 8；超过后上下文切换开销反而上升
• worker-class：必须是 uvicorn.workers.UvicornWorker，写成 uvicorn_worker 或漏掉 uvicorn. 前缀都会失败
• worker-connections：这个对 ASGI 无效，UvicornWorker 忽略它；别被 Nginx 配置习惯带偏

典型 gunicorn.conf.py 片段：

workers = 4
worker_class = "uvicorn.workers.UvicornWorker"
worker_tmp_dir = "/dev/shm"
accesslog = "-"
errorlog = "-"
loglevel = "info"
capture_output = True

为什么不能混用 sync worker 和 async endpoint

如果你不小心用了默认的 sync worker（比如忘了配 worker-class），FastAPI 的 async def 路由会被强制在主线程里同步执行，await 不生效，所有异步 I/O（如数据库查询、HTTP 调用）会阻塞整个 worker 进程。

常见错误现象：

• 并发请求响应时间随 QPS 线性增长，而不是稳定在几十毫秒
• 日志里反复出现 RuntimeWarning: coroutine 'xxx' was never awaited
• ps aux | grep gunicorn 显示全是 sync worker 进程，没有 uvicorn 字样

数据库连接池和 async driver 是异步链路的真正瓶颈

哪怕 Gunicorn+UvicornWorker 配得再准，如果数据库用的是 psycopg2（同步驱动），或者 SQLAlchemy 没配 AsyncEngine，那每个 await db.execute(...) 实际上还是在跑同步阻塞调用，异步框架只是在等 IO。

必须确认：

• PostgreSQL 用 asyncpg 或 psycopg（v3+ 的 async 模式），别用 psycopg2
• SQLModel 或 SQLAlchemy 初始化时显式使用 create_async_engine
• 连接池大小（pool_size）要匹配 workers × worker_connections，否则会排队等待连接

比如 4 个 worker，每个最多处理 1000 并发，连接池至少设为 4000——但实际应结合 DB 承载力压测调整，盲目设大反而耗尽内存

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。