Nginx 中 keepalive_timeout 对性能提升的实践

keepalive_timeout本身不直接提升性能，而是长连接机制的开关和节拍器；真正起效需协同upstream keepalive、HTTP/1.1协议及后端keep-alive支持，共同减少TCP握手与TLS协商开销，设过大易致502或连接堆积，过小则增握手损耗。

keepalive_timeout 本身不直接“提升性能”，它只是长连接机制的开关和节拍器。真正起作用的是它配合 upstream keepalive、HTTP/1.1 协议和后端支持，共同减少 TCP 握手与 TLS 协商开销。调得过大或过小，都可能引发 502 错误、连接堆积或资源耗尽。

明确区分两个 keepalive_timeout 场景

Nginx 中存在两套独立的 keepalive 控制逻辑，不能混用：

1. 面向客户端的 keepalive_timeout：控制浏览器等客户端连接空闲多久后关闭。默认 75 秒，常见设为 30–65 秒。对静态资源站可设 10–30 秒；对内网 API 或 SSE 流式服务，可设到 60–300 秒。
2. 面向上游的 keepalive_timeout（需配合 upstream keepalive）：这不是一个独立指令，而是 upstream 块中 keepalive N; 所隐含的空闲超时逻辑。它的实际生效依赖于 Nginx 连接池行为——空闲连接在池中最多保留多久。这个值必须 严格小于 后端服务自身的 keep-alive timeout（如 Tomcat 的 keep-alive-timeout），否则 Nginx 主动关连接，后端还在等复用，就会触发 “upstream prematurely closed connection” 报错。

关键协同配置缺一不可

只改 keepalive_timeout 数值，几乎没用。必须配套以下三项：

1. 在 upstream 块中启用连接池：keepalive 32;（数值建议为后端单实例并发承载能力的 60%–80%，例如后端 maxConnections=200，则设 120–160）
2. 在 proxy location 中启用 HTTP/1.1 并清理 Connection 头：proxy_http_version 1.1; + proxy_set_header Connection '';
3. 确认后端真实支持长连接：用 curl -I http://backend/ 检查响应头是否含 Connection: keep-alive，且无 close；Spring Boot 需配 server.tomcat.keep-alive-timeout=75，Node.js 需设 server.keepAliveTimeout = 75000

验证是否真正生效，而不是看配置

别只盯着 conf 文件里的数字。有效优化要看运行态指标：

1. 用 ss -tnpo | grep :8080 | wc -l 查 Nginx 到后端的真实 ESTABLISHED 连接数，应稳定在 keepalive 设置值附近（如设 32，实测在 28–32 波动），而非随请求量线性增长
2. 观察 nginx_stub_status 中 Waiting 连接数是否明显下降；若 Writing 很低但 Waiting 很高，说明连接空闲多、复用率差
3. 压测时对比开启前后：TIME_WAIT 连接数应显著减少，P95 延迟更平稳，错误率（尤其是 502）下降

典型误配与后果

常见踩坑点直接影响稳定性：

1. 后端未开 keep-alive，Nginx 却设了大 timeout → 连接被后端主动断开，Nginx 日志报 “upstream prematurely closed connection”，返回 502
2. upstream keepalive 设太大（如 1024），但后端 maxConnections 只有 200 → 后端拒绝新连接，出现大量 connect timeout 或 503
3. keepalive_timeout 设为 0（禁用）或过短（如 2 秒）→ 客户端频繁重连，CPU 花费在握手，QPS 上不去
4. 忘记 proxy_set_header Connection '' → 客户端传来的 Connection: close 被透传，Nginx 不复用连接