Nginx upstream keepalive 怎么配:3 步消掉后端 TIME_WAIT
技术教程 · SRE · 可靠性 · 2026-11-17
Nginx upstream keepalive 怎么配:3 步消掉后端 TIME_WAIT
一句话开头
如果你在 Nginx 和后端之间看到几千个 TIME_WAIT、接口 p99 时不时抖一下,后端日志里全是新建连接,那基本可以确定:每个请求都在重新做一次 TCP 握手,upstream keepalive 没生效。
前置准备
先确认三件事,后面都要用到:
# 1. 版本(1.29.7 前后写法不一样)
nginx -v
# 2. worker 进程数(算池子大小要用)
nginx -V 2>&1 | tr ' ' '\n' | grep -i worker_processes
ps aux | grep "nginx: worker" | grep -v grep | wc -l
# 3. 确认后端支持 HTTP/1.1 长连接(Java / Go / Node 默认都可以)
curl -sv http://10.0.0.1:8080/health 2>&1 | grep -i "connection"
步骤 1:在 upstream 里开连接池
upstream api_backend {
server 10.0.0.1:8080 weight=5;
server 10.0.0.2:8080 weight=3;
keepalive 32;
}
keepalive 32 指的是每个 worker 进程缓存的最大空闲连接数,不是总连接上限,也不限制一个 worker 能开多少条连接——这点官方文档写得很明确,但很多人理解反了。池子满了按最近最少使用(LRU)淘汰最老的空闲连接。
取值经验:后端节点数 × 2 起步;流量大的场景按 (峰值 QPS / worker 数) / 每连接平均处理请求数 × 2 估。绝大多数场景 32~64 就够。
步骤 2:配上 HTTP/1.1 并清空 Connection 头
如果你跑的是 1.29.7 之前的版本,这一步必须写,否则池子永远是空的:
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://api_backend;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
-
proxy_http_version 1.1:Nginx 对上游默认用 HTTP/1.0,而 HTTP/1.0 不支持持久连接。
-
proxy_set_header Connection "":把客户端带来的 Connection: keep-alive / close 清掉,否则它会干扰上游连接复用逻辑。
如果你跑的是 1.29.7 及以上:proxy_http_version 默认已经是 1.1,keepalive 默认开启(默认 32),而且默认行为相当于带 local 参数——连接不再在不同 location 之间共享。这两行可以不写,但写上不会有副作用,跨版本迁移时更省事。
改完先验语法再 reload:
nginx -t && nginx -s reload
步骤 3:压一把,确认连接真的被复用
配置不报错不等于生效,必须看连接状态:
# 打一点流量
for i in $(seq 1 200); do curl -s -o /dev/null http://127.0.0.1/api/health; done
# 到后端那条连接上的 ESTABLISHED 数
ss -tan state established dst 10.0.0.1:8080 | wc -l
# 全机 TIME_WAIT 总量 / 总览
ss -tan state time-wait | wc -l
ss -s
判断标准:
-
生效:ESTABLISHED 稳定在一个小数字(几十条),TIME_WAIT 不随请求量线性增长。
-
没生效:ESTABLISHED 剧烈上下跳,TIME_WAIT 一路堆到几千上万。
常见坑
- 只加了
keepalive,没配 1.1 和Connection ""(老版本)。 最经典的翻车,配置看着对,TIME_WAIT 一个没少。 - 池子大小要乘以 worker 数。 keepalive × worker_processes 才是可能压到后端上的空闲连接总量。作者补充:曾经把 keepalive 设成 128、机器 8 个 worker,等于 1024 条可能打到一台连接上限只有 100 的 Java 服务上,直接 connection refused,排查时一度以为是后端挂了。
- 后端 keep-alive 超时比 Nginx 短,会偶发 502。 error log 里是 upstream prematurely closed connection while reading response header。作者补充:Node 默认 keepAliveTimeout 是 5s,Nginx 默认 keepalive_timeout 是 60s,这个组合几乎必现。要么把后端调到 65s 以上,要么把 Nginx 的 keepalive_timeout 压到 30s。
keepalive_requests别随手调大。 默认 1000(1.19.10 之前是 100),定期关连接是为了释放每个连接的内存分配,调到 10000 反而会让内存涨。- 负载均衡指令的顺序。 upstream 里用了 least_conn / ip_hash / hash / random 时,这些指令必须写在 keepalive 上面,顺序反了行为不符合预期。
- SSE、WebSocket 会长期占住池子。 这类长连接不要和普通短请求共用同一个 upstream,单独拆一个,并单独配 proxy_read_timeout。
一句话总结
keepalive 32 + HTTP/1.1 + 清空 Connection 头,三行配置换掉每个请求一次 TCP 握手;改完别急着收工,用 ss 确认 TIME_WAIT 真掉下来了,这事才算闭环。