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;
    }
}

如果你跑的是 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

判断标准:

常见坑

  1. 只加了 keepalive,没配 1.1 和 Connection ""(老版本)。 最经典的翻车,配置看着对,TIME_WAIT 一个没少。
  2. 池子大小要乘以 worker 数。 keepalive × worker_processes 才是可能压到后端上的空闲连接总量。作者补充:曾经把 keepalive 设成 128、机器 8 个 worker,等于 1024 条可能打到一台连接上限只有 100 的 Java 服务上,直接 connection refused,排查时一度以为是后端挂了。
  3. 后端 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。
  4. keepalive_requests 别随手调大。 默认 1000(1.19.10 之前是 100),定期关连接是为了释放每个连接的内存分配,调到 10000 反而会让内存涨。
  5. 负载均衡指令的顺序。 upstream 里用了 least_conn / ip_hash / hash / random 时,这些指令必须写在 keepalive 上面,顺序反了行为不符合预期。
  6. SSE、WebSocket 会长期占住池子。 这类长连接不要和普通短请求共用同一个 upstream,单独拆一个,并单独配 proxy_read_timeout。

一句话总结

keepalive 32 + HTTP/1.1 + 清空 Connection 头,三行配置换掉每个请求一次 TCP 握手;改完别急着收工,用 ss 确认 TIME_WAIT 真掉下来了,这事才算闭环。