keepalive-timeout

长连接空闲一段时间后被固定秒数断开，复用连接时偶发 reset 或 EOF。

现象

HTTP 客户端、数据库连接池或 gRPC 连接在空闲后复用时失败，报 connection reset by peer、EOF、server closed the connection unexpectedly；断开时间往往固定（如 60 秒、350 秒、5 分钟）。新连接通常正常。

快速定位

先确认断开时间是否固定，以及各层 keepalive/idle 配置：

ss -tno | grep -E 'keepalive|timer'
ss -tno state established '( dport = :3306 or dport = :5432 or dport = :6379 )'
sysctl net.ipv4.tcp_keepalive_time net.ipv4.tcp_keepalive_intvl net.ipv4.tcp_keepalive_probes

代理与应用层：

nginx -T | grep -E 'keepalive( |_timeout|_time)|proxy_read_timeout|proxy_send_timeout'
grep -R 'IdleTimeout\|IdleConnTimeout' .

数据库侧对照（idle_session_timeout 需 PostgreSQL 14+）：

mysql -e "SHOW VARIABLES LIKE 'wait_timeout'; SHOW VARIABLES LIKE 'interactive_timeout';"
psql -c "SHOW idle_session_timeout;" -c "SHOW tcp_keepalives_idle;"
redis-cli CONFIG GET timeout

云 LB/NAT 的空闲超时也要核对：

aws elbv2 describe-load-balancer-attributes --load-balancer-arn <arn> --query 'Attributes[?Key==`idle_timeout.timeout_seconds`]'
conntrack -L -p tcp --dport 443 | head

易误判：Nginx 的 keepalive_timeout 不是 TCP keepalive；upstream 块里的 keepalive 是连接池大小，keepalive_time 才是空闲时长。TCP keepalive 也不能替代应用心跳去维持 LB/NAT 的空闲计时 —— 探测包常常不被转发或不被计为活跃流量。固定 60 秒断开更像 ALB/Nginx，固定 350 秒更像 NLB/NAT；数据库报 “server closed the connection” 通常是 DB 或代理先关闭，而不是客户端。

常见根因

1. 中间层 idle timeout 小于应用心跳/keepalive，连接被静默关闭后仍被复用。
2. HTTP 客户端连接池 idle 时间大于服务端 keepAliveTimeout，复用时撞上正在关闭的连接。
3. 数据库池 maxLifetime 大于 DB wait_timeout 或代理超时，拿到失效连接。
4. TCP keepalive 默认 2 小时，远大于 NAT/LB 空闲超时，探测来不及保活。
5. keepalive 探测不被中间设备转发，无法阻止 idle 关闭。
6. 后端发布/重启未优雅排空，连接被直接断开。
7. HTTP/2/gRPC keepalive 频率违反服务端 enforcement，收到 too_many_pings/GOAWAY。
8. keepalive 设置过短，造成额外握手、端口消耗或触发限流。

修复

• 建立超时层级：客户端连接池 idle 短于 LB/NAT idle；服务端 keepalive 长于 LB idle，避免中间层先关而双方仍复用。
• HTTP 客户端把 IdleConnTimeout/maxIdleTime 设为 LB idle 的 80% 左右，并对幂等请求处理 stale connection 重试。
• 数据库池 maxLifetime 比 DB wait_timeout/代理超时短 30–60 秒，开启连接有效性检测。
• 按环境调整 TCP keepalive：tcp_keepalive_time（如 300 秒）、tcp_keepalive_intvl、tcp_keepalive_probes，应用可设 per-socket TCP_KEEPIDLE。
• gRPC/HTTP2 客户端 ping 间隔要大于服务端 EnforcementPolicy.MinTime。
• 发布时先摘流、等待连接排空再退出；LB 开启 deregistration delay。
• 监控连接重置率、EOF 和连接年龄分布，用固定断开秒数反推是哪一层。
• 不要用 tcp_tw_recycle 或缩短 tcp_fin_timeout 来“解决” keepalive 问题。

相关命令

• ss — 查看连接计时器和 keepalive 状态
• sysctl — TCP keepalive 内核参数
• nginx — keepalive 与上游连接池
• connection-timeout — 连接超时的通用排查
• 502-bad-gateway — 复用失效连接导致的网关错误
• network-troubleshooting-cheatsheet — 网络排障速查

读完自测

1. Nginx 的 keepalive_timeout 与 TCP keepalive 是同一件事吗？
2. 数据库连接池的 maxLifetime 应如何与 wait_timeout 配合？
3. 为什么 TCP keepalive 不能阻止云 LB 断开空闲连接？