Uvicorn不提供传统连接池,而是基于事件循环复用TCP连接;关键参数为--backlog(调TCP等待队列)、--limit-concurrency(控并发请求数)和--timeout-keep-alive(设HTTP空闲超时),需结合ulimit与异步代码协同优化。

Uvicorn 本身没有传统意义上的“连接池”概念——它不维护数据库或 HTTP 客户端那种可复用的长连接池,而是通过事件循环 + 复用 TCP 连接(keep-alive)来管理客户端连接。所谓“调连接池大小”,实际是调 backlog、limit-concurrency 和底层异步 I/O 的并发承载能力。
为什么不能直接设 connection_pool_maxsize
你可能从 kubernetes 或 requests 库里熟悉 connection_pool_maxsize,但 Uvicorn 的 ASGI 服务器模型完全不同:它不为每个上游服务建连接池,也不暴露类似参数。误以为存在这个配置,容易在 config.py 或启动命令里白折腾。
- Uvicorn 的核心是单个事件循环处理成百上千并发连接,靠的是操作系统 TCP 队列和 asyncio 的协程调度,不是预分配连接对象
- 如果你在 FastAPI 里用
httpx.AsyncClient调外部 API,那才需要配它的limits;Uvicorn 不管那一层 - 试图给 Uvicorn 加
--connection-pool-size这类参数会报错:unrecognized arguments
真正该调的三个关键参数
这些参数控制的是“能同时接受多少新连接”“允许多少并发请求处理中”“连接空闲多久断开”,直接影响高并发下的排队、超时和资源占用。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
-
--backlog:TCP 连接等待队列长度,默认 100,建议设为2048(尤其在 Nginx 前置或直面公网时),避免 SYN 包被丢弃 -
--limit-concurrency:限制**当前正在处理的请求数**(不是连接数),防止内存爆掉;设太小会导致请求被拒绝并返回 503,设太大可能触发 OOM;生产建议从1000起步,按 P99 内存曲线调整 -
--timeout-keep-alive:HTTP keep-alive 空闲超时,默认 5 秒;设太长(如 60 秒)会让连接长期挂起,占满ulimit -n;Dify 等场景明确要求 ≤5 秒
多进程下每个 worker 的连接承载怎么算
加 --workers 8 并不等于并发能力 ×8,因为每个 worker 是独立进程+独立事件循环,但共享同一监听 socket,且受系统 ulimit -n 和内核 net.core.somaxconn 限制。
- 总并发连接上限 ≈
min(ulimit -n, net.core.somaxconn),不是workers × backlog - 每个 worker 的
--backlog是各自 accept 队列长度,但内核层面只有一个全连接队列,所以设太高无意义 - 如果你发现日志频繁出现
ConnectionResetError或Too many open files,先查ulimit -n,再调--backlog,最后考虑加 workers
异步代码写法不当会让“连接池”形同虚设
即使你把 --limit-concurrency 设到 2000,只要有一个路由里写了 time.sleep(3) 或用了同步数据库驱动(如 psycopg2),整个 worker 就会卡住——因为 asyncio 事件循环被阻塞,其他协程无法调度。
- 必须用
asyncpg、httpx.AsyncClient、aioredis这类真正异步库 - 同步操作务必包在
loop.run_in_executor里,否则--workers再多也救不了 - 检查中间件是否含阻塞调用;比如某些 JWT 解析库默认用同步 RSA 签名,会悄悄拖垮并发
最常被忽略的一点:Uvicorn 的“连接管理”效果,最终取决于你写的 ASGI 应用是否真异步。参数只是边界,代码才是瓶颈。调完 --backlog 和 --limit-concurrency 后,务必用 ab 或 hey 实测,看 Failed requests 和 Time per request 是否随参数变化而改善——而不是只盯着配置文件改数字。

















