Uvicorn连接超时是客户端、反向代理、Uvicorn三方超时参数错位导致的链路断裂;--timeout-keep-alive仅控长连接空闲时长,设过大(如30秒)会耗尽文件描述符,合理值为5~12秒;真正关键的是proxy_read_timeout、--timeout-graceful-shutdown及下游服务读写超时,需构成递减链条;请求级超时须由应用层用asyncio.wait_for()实现;Linux TCP重传机制存在约63秒硬限制,无法通过Uvicorn参数绕过。

Uvicorn连接超时不是单点问题,而是客户端、反向代理、Uvicorn自身三者超时参数错位导致的“链路断裂”。直接调大--timeout-keep-alive或--limit-concurrency往往无效,甚至让故障更隐蔽。
为什么--timeout-keep-alive设成30秒反而更糟?
这个参数只控制HTTP长连接空闲时长,和“建立连接失败”或“请求处理超时”完全无关。它影响的是TCP连接复用效率,而非业务响应时间。设得过大(比如30秒)会导致连接池中堆积大量空闲但未释放的连接,在高并发下快速耗尽文件描述符(Too many open files),进而引发新的连接拒绝或延迟上升。
- 典型误操作:
uvicorn main:app --timeout-keep-alive 30→ 实际加剧连接资源争抢 - 合理范围:5~12秒(与Nginx的
keepalive_timeout对齐即可) - 真正该管的不是它,而是
--timeout-graceful-shutdown和下游服务的读写超时
Nginx + Uvicorn组合里,谁先切断连接?
绝大多数504错误根本不是Uvicorn挂了,而是Nginx在Uvicorn还没返回时就主动断开了。关键要看三个超时值是否形成“递减链条”:
-
proxy_connect_timeout(Nginx):建连阶段,建议≤5s -
proxy_send_timeout(Nginx):发请求体给Uvicorn,建议≤60s(如含大文件上传) -
proxy_read_timeout(Nginx):等Uvicorn响应,必须 ≥ Uvicorn业务最大预期耗时 - Uvicorn本身无内置“请求处理超时”,需靠
asyncio.wait_for()或中间件实现
常见断裂点:proxy_read_timeout 300,但Uvicorn里某个httpx.AsyncClient调用外部API默认超时是10秒——结果Nginx还在等,Uvicorn早因下游超时抛了异常并关闭了连接,Nginx收不到完整HTTP响应,只能回502或504。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
如何在FastAPI里加真正的请求级超时?
Uvicorn不提供全局请求超时开关,必须由应用层兜底。推荐用asyncio.wait_for()包裹耗时操作,而不是依赖框架或服务器配置:
@app.post("/generate")
async def generate_text(request: Request):
try:
result = await asyncio.wait_for(
call_llm_api(request.body),
timeout=45.0 # 明确业务SLA边界
)
return {"result": result}
except asyncio.TimeoutError:
raise HTTPException(status_code=408, detail="Request timeout")
- 避免用
time.sleep()或同步阻塞调用,它们会卡住整个事件循环 - 外部HTTP调用务必显式设
timeout,例如httpx.AsyncClient(timeout=30.0) - 数据库查询需配合驱动的异步超时(如
asyncpg.connect(..., command_timeout=10.0))
容易被忽略的底层限制:Linux TCP重传机制
即使你把所有上层超时都设成60秒,Linux内核对TCP连接建立失败的默认重试上限仍是约63秒(5次指数退避:1+2+4+8+16+32)。这意味着:
- 当目标服务完全不可达(如DNS失败、防火墙丢包),Uvicorn的
connect()调用最多卡63秒才返回ConnectionRefusedError - 无法通过Uvicorn参数绕过,只能靠前置健康检查或DNS预解析缓解
- 若业务要求“10秒内失败”,必须在发起网络调用前加
asyncio.wait_for(connect_task, timeout=10.0)做硬限制
这个63秒是操作系统级硬约束,任何Python层设置都无法突破——它藏在/proc/sys/net/ipv4/tcp_retries2里,改它需要root权限且影响全局网络行为,不推荐。










