uvicorn的--timeout-keep-alive控制http/1.1空闲连接复用时长，默认5秒，生产推荐设为15–60秒以匹配nginx等网关配置，禁用（设0）将退化为http/1.0致吞吐腰斩。
timeout-keep-alive 参数控制连接复用时长
Uvicorn 的 timeout-keep-alive 控制的是 HTTP/1.1 keep-alive 连接在空闲状态下最多保持多久不关闭。它不是请求处理超时，也不是 SSL 握手超时，而是纯 TCP 层连接复用的“静默等待窗口”。默认值是 5 秒，对开发环境够用，但生产中常被压测或客户端长轮询打穿——连接频繁重建，服务端 TIME_WAIT 暴增，CPU 花在握手而非业务上。
三种设置方式优先级与实操差异
Uvicorn 配置遵循「命令行 > 编程式 > 环境变量」优先级，timeout-keep-alive 同样适用：
Uvicorn 0.52.1
下载
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
- 命令行最直接：
uvicorn main:app --timeout-keep-alive 60，适合临时调试或 CI 启动 - 编程式需注意进程模型：
uvicorn.run(..., timeout_keep_alive=60)，但若同时设workers>1，该参数只作用于主进程（worker 进程继承此值），且必须放在if __name__ == "__main__"块内，否则多进程启动时会重复初始化事件循环 - 环境变量不可用：
UVICORN_TIMEOUT_KEEP_ALIVE并不存在 —— Uvicorn 官方未支持该环境变量映射，强行设置无效
和 timeout、keepalive 参数容易混淆的点
别把 timeout-keep-alive 和另外两个名字相近的参数搞混：
-
timeout（或--timeout）是整个请求生命周期上限，包括读请求头、读 body、执行 handler、写响应全过程；它对应 Gunicorn 的timeout，Uvicorn 文档里已标记为 deprecated，建议改用--limit-timeout或中间件控制 -
keepalive是 Gunicorn 配置项（如gunicorn_config.py中的keepalive = 5），它影响的是 Gunicorn master 进程向 worker 发心跳的间隔，和 Uvicorn 的timeout-keep-alive完全无关 - 真正和
timeout-keep-alive协同工作的是--backlog：前者决定单个空闲连接活多久，后者决定系统 socket 队列能暂存多少待 accept 的连接；两者要配合调优，比如设--timeout-keep-alive 30时，--backlog至少配到2048以上，否则高并发下新连接可能被内核丢弃
生产环境典型值与反模式
线上服务不是越大越好，关键看客户端行为和反向代理配置：
- Nginx 默认
keepalive_timeout是 60s，若 Uvicorn 设成 5s，Nginx 每次都会遇到连接被提前关闭，触发重连，增加延迟 - 移动端 App 常用短连接 + 长轮询，
timeout-keep-alive设太高（如 300s）反而导致连接堆积，尤其当客户端网络不稳定却没发 FIN 包时 - 推荐值：与前端或网关的 keep-alive 设置对齐，常见取值
15～30秒；若明确走 Nginx，且 Nginx 配了proxy_http_version 1.1和proxy_set_header Connection ''，可设为60 - 反模式：在 Docker 容器里设
--timeout-keep-alive 0（即禁用 keep-alive），这会让所有请求退化为 HTTP/1.0，吞吐直接腰斩，别这么干
Keep-Alive: timeout=30 这样的响应头，以及用 ss -tan | grep :8000 | wc -l 观察 ESTABLISHED 连接数是否稳定——太低说明连接太快断，太高说明积压了。
