Uvicorn单worker在高负载下易卡死,因其仅用一个事件循环,同步阻塞操作会拖垮全部请求;必须用Gunicorn管理多个Uvicorn worker进程实现真正并发,且需合理配置timeout、keepalive及协议解析器。

Uvicorn 在高负载下表现优秀,但前提是配置得当;默认单 worker 启动(uvicorn main:app)在真实高并发场景中会迅速成为瓶颈,不是它不行,而是你没让它“多干活”。
为什么单 worker 会卡死在 100 并发左右
Uvicorn 默认只起一个进程、一个事件循环,所有请求都在同一个协程调度器里排队。即使全是 async 接口,一旦某个请求触发了同步阻塞(比如没加 await 的数据库调用、模型加载、或 time.sleep()),整个 worker 就挂住——后续所有请求都得等它释放事件循环。
- 典型现象:
503 Service Unavailable或响应延迟突增至数秒,top显示 CPU 不高但请求堆积 - 根本原因:单 worker 没有进程隔离,一个坏请求拖垮全部
- 验证方式:用
ab -n 100 -c 100 http://localhost:8000/health压测,观察uvicorn进程的 CPU 和内存变化
必须开启多 worker:用 Gunicorn 管理 Uvicorn
Uvicorn 自身不提供多进程管理能力,生产环境必须套一层 Gunicorn,由它 fork 多个 Uvicorn worker 进程。直接加 --workers 4 参数无效(那是 uvicorn 的伪多 worker,仅限开发模式,且不真正隔离)。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
- 正确做法:写
gunicorn_conf.py,设worker_class = "uvicorn.workers.UvicornWorker" - worker 数量公式:推荐
multiprocessing.cpu_count() * 2 + 1,但 GPU 计算密集型服务(如 M2LOrder)应限制为 CPU 核心数,避免显存争抢 - 关键超时配置:
timeout = 120(防长推理任务被杀),keepalive = 5(复用连接减少握手开销)
httptools vs h11:协议解析层性能差一倍
Uvicorn 默认用 httptools(C 扩展)解析 HTTP,比纯 Python 的 h11 快 30%~50%。但在某些容器环境(如旧版 Alpine Linux)可能因缺失编译依赖而自动 fallback 到 h11,导致吞吐骤降。
- 确认当前使用的解析器:启动时看日志是否含
using httptools;没有则大概率是h11 - 强制启用
httptools:uvicorn main:app --http httptools - 若报错
ModuleNotFoundError: No module named 'httptools',需安装:pip install httptools(注意 Alpine 需先apk add gcc musl-dev)
uvloop 是默认但不是万能:Windows 和调试场景要绕开
Uvicorn 默认启用 uvloop(基于 libuv 的高性能事件循环),Linux/macOS 下吞吐提升明显。但它不支持 Windows,也不兼容某些调试工具(如 PyCharm 的断点调试、asyncio.run() 直接调用)。
- 开发期想稳定调试:启动加
--loop asyncio,避免协程调度异常 - 生产期禁用 uvloop:只在明确知道环境不支持时才加
--loop asyncio,否则损失性能 - 检查是否生效:运行中执行
import asyncio; print(asyncio.get_event_loop_policy()),输出含uvloop即成功
高负载下的真实瓶颈往往不在 Uvicorn 本身,而在它和下游的协同:Nginx 的 proxy_read_timeout 设太短会主动断流,数据库连接池没配够会导致 worker 在 await db.execute() 上集体等待,甚至模型加载逻辑没做单例缓存,每个请求都重复 init。Uvicorn 是把好刀,但砍什么、怎么砍,得看整个链路怎么搭。

















