Nginx upstream keepalive配置详解：原理、场景与性能优化实战-平芜编程栈

1. 项目概述：为什么我们需要关注upstream的keepalive？

如果你用过nginx做反向代理，大概率配置过proxy_pass指向一个后端服务器地址。当流量变大，后端是多个服务实例组成的集群时，你就会用到upstream模块来定义这个服务器组。这时候，一个看似不起眼但至关重要的配置参数——keepalive，就浮出水面了。很多人的配置里，这个值要么是默认的没动过，要么是随便填了个数，直到线上出现连接数飙升、响应时间变长甚至偶发性超时，才回头来琢磨它。

简单说，upstream块里的keepalive指令，控制的是nginx与后端服务器之间TCP长连接池的大小。它和HTTP协议里的Keep-Alive头是两回事，那个是客户端到nginx的。我们这里说的是nginx作为客户端，去连接后端服务时，是否以及如何复用TCP连接。在高并发场景下，不配或者配错这个参数，性能表现天差地别。想象一下，每个用户请求过来，nginx都要和后端服务“握手”三次建立新连接，请求完再“挥手”四次断开，这其中的网络延迟和系统资源消耗，在每秒数千次请求下会被放大成严重的性能瓶颈。

我经历过一个典型的案例：一个ToC的API服务，日均请求过亿。初期upstream里没配keepalive，压测时发现nginx服务器本地端口很快被用尽，出现大量TIME_WAIT状态的连接，后端服务的负载反而很低。加上适当的keepalive配置后，不仅平均响应时间下降了近60%，nginx本身的CPU和内存消耗也显著降低。这个参数，就是那种“配置五分钟，性能提升一倍”的典型。

所以，这篇内容不是简单的配置说明，而是结合原理、场景和踩坑经验，把upstream keepalive这件事掰开揉碎了讲清楚。无论你是正在优化线上网关的架构师，还是刚接手nginx配置的开发者，都能从中找到直接可用的参数和避坑指南。

2. 核心原理：从短连接到连接池的演进

要理解keepalive为什么重要，得先看看没有它的时候，nginx是怎么和后端“打交道”的。

2.1 默认模式：短连接的代价

在默认情况下，或者显式设置keepalive 0;时，nginx对upstream采用的是短连接模式。其生命周期是这样的：

接收请求：nginx收到客户端的一个请求。
创建连接：nginx从操作系统申请一个本地端口，向后端服务器发起TCP三次握手，建立一条全新的连接。
发送与接收：通过这个新连接，将客户端的请求转发给后端，并等待后端响应。
关闭连接：收到后端响应并返回给客户端后，nginx会主动发起TCP四次挥手，关闭这条连接。这个连接随即进入TIME_WAIT状态，等待2MSL（Maximum Segment Lifetime，通常60秒）后，端口资源才被真正释放。

这个过程的问题显而易见：高频度的连接建立与销毁。建立连接有“三次握手”的延迟（1个RTT），关闭连接有“四次挥手”的延迟和TIME_WAIT等待。对于高并发服务，这会导致：

高延迟：每个请求都额外增加了至少1个RTT的连接建立时间。
高资源消耗：频繁调用系统socket接口，消耗CPU；大量TIME_WAIT连接占用本地端口和内存，可能导致端口耗尽错误（Cannot assign requested address）。
后端压力：后端服务器也需要频繁处理连接建立和销毁，消耗其资源。

2.2 Keepalive模式：连接复用的艺术

启用keepalive后，模式转变为长连接连接池。其核心思想是：连接用完不断开，而是放回一个池子里，供后续请求复用。

配置指令很简单，在upstream块中：

upstream backend_servers { server 192.168.1.10:8080; server 192.168.1.11:8080; keepalive 32; # 关键配置：为每个worker进程维护的连接池大小 }

同时，在location的代理配置中，必须显式清除可能导致连接关闭的头部，并设置正确的协议版本：

location /api/ { proxy_pass http://backend_servers; proxy_http_version 1.1; # 必须使用HTTP/1.1，它支持长连接 proxy_set_header Connection ""; # 清空Connection头，防止传递错误信息 # ... 其他proxy配置 }

此时，连接的生命周期变为：

初始化：nginx worker进程启动后，连接池是空的。
请求处理：
- 当请求到来，需要转发到某个后端服务器（如192.168.1.10:8080）时，worker进程首先尝试从对应的连接池中获取一个空闲的、存活的（keepalive）连接。
- 如果池中有，则直接使用，省去握手。
- 如果池为空或没有存活连接，则新建一个连接。
请求完成：请求响应结束后，如果连接状态良好，nginx不会关闭它，而是将其放回连接池，标记为空闲状态，等待下一个请求。
连接维护：nginx会定期检查池中的连接是否还健康（通过检测socket是否可读等）。如果连接被服务器关闭或出现错误，则会从池中丢弃。

这里的keepalive 32是什么意思？这个数字不是nginx与单个后端服务器之间允许的最大并发连接数。那个是由worker_connections和负载均衡算法决定的。这里的32是指：每个nginx的worker进程，为这个upstream块中的每个后端服务器，最多缓存32个空闲的长连接。

它是一个缓存池的上限。假设你有2个后端服务器，配置了keepalive 32，那么在最理想的情况下，一个worker进程可能会缓存2 * 32 = 64个空闲连接。实际并发连接数可能远高于此，因为正在处理请求的连接是不在“空闲池”里的。

2.3 核心参数与关联配置解析

理解了基础模式，我们来看看几个关键参数和它们之间的联动。

keepalive指令

语法：keepalive connections;
上下文：upstream
作用：启用并设置每个worker进程与每个后端服务器之间保持的空闲长连接最大数量。
默认值：未启用（相当于短连接模式）。

proxy_http_version 1.1;这是启用upstream keepalive的必要条件。HTTP/1.0协议设计之初没有考虑长连接，默认是“请求-响应-关闭”模式。虽然可以通过Connection: keep-alive头来模拟，但不够标准。HTTP/1.1则默认是长连接，协议支持更好。nginx在作为客户端向后端发送请求时，使用HTTP/1.1能更可靠地维持TCP通道。

proxy_set_header Connection "";这个配置非常关键。如果不设置，当客户端请求的Connection头是close时，nginx可能会将这个头原样转发给后端，导致后端在处理完请求后主动关闭连接，使得nginx无法将连接回收到池中。将其设置为空字符串，nginx会移除这个头，或者根据proxy_http_version自动处理为适合长连接的模式。

keepalive_timeout(在 upstream 中)这是一个更精细的控制参数，但请注意，在标准的http_upstream模块中，并没有一个叫keepalive_timeout的指令。控制空闲连接存活时间的是系统层面的keepalive参数和nginx内部的健康检查机制。人们常混淆的是upstream块中的keepalive_timeout，它实际上存在于stream模块（用于TCP/UDP代理）中。对于HTTPupstream，空闲连接的保活主要依赖于TCP的keepalive机制（通过so_keepalive参数配置，不常用）和nginx自身的清理逻辑。一个连接在池中空闲时间过长，在下次被取出使用时，nginx会先进行检查，如果不可用则丢弃并新建。

与worker_connections的关系worker_connections在events块中设置，定义了一个worker进程可以同时打开的最大连接数（包括客户端连接和到后端的连接）。这是一个全局资源上限。你设置的upstream keepalive池大小，实际占用的连接数不能超过worker_connections为每个worker分配的资源。例如，worker_connections = 4096，你有4个worker，那么每个worker平均能有1024个连接资源。你需要为客户端连接、到其他上游的连接预留空间，然后才能决定每个upstream的keepalive值。

实操心得一：参数不是越大越好我曾见过有人把keepalive设置为worker_connections的值，这是错误的。连接池缓存的是空闲连接。如果设置过大，会导致大量空闲连接长时间占用系统资源（文件描述符、内存），而这些资源本可以用于处理更多活跃请求。合理的keepalive值应该略高于每个后端服务器在单位时间内（如1秒）平均从单个worker收到的请求数，这样既能保证连接复用，又不浪费资源。一个从经验出发的初始值可以是(平均QPS per worker / 平均每秒请求吞吐 per connection)的1.5到2倍。

3. 配置场景与参数计算实战

知道了原理，我们来面对灵魂拷问：这个keepalive值到底该设多少？这里没有银弹，但有清晰的决策路径和计算方法。

3.1 场景一：高并发、低延迟的API网关

这是最典型的场景。你的nginx作为入口网关，后面是大量的应用服务器，要求快速响应。

特征：

请求/响应模型简单，单个请求处理时间短（通常<100ms）。
每秒请求量（QPS）高。
后端服务器数量多，且负载均衡。

配置思路：目标是让连接复用率尽可能高，减少握手开销。连接池大小应能覆盖单个worker进程在一个请求平均处理周期内可能发往单个后端服务器的请求数。

简化计算公式：

单个worker对单个后端的估算峰值并发请求数 ≈ (总QPS / worker进程数) * (请求平均处理时间 / 1000) / 后端服务器数量

然后，keepalive值可以设为这个估算值的1.2到2倍。

举例：

服务总QPS = 10000
nginxworker_processes= 8
平均请求处理时间（后端耗时） = 50ms = 0.05s
后端服务器数量 = 10

计算：

每个worker平均QPS = 10000 / 8 = 1250
每个worker对单个后端的平均QPS = 1250 / 10 = 125
单个worker对单个后端的估算并发连接数（根据利特尔法则）≈ 125 QPS * 0.05s = 6.25
考虑峰值波动，取2倍缓冲：6.25 * 2 ≈ 12.5

因此，一个合理的起始配置可以是：

upstream api_backend { least_conn; # 使用最少连接负载均衡，配合keepalive更公平 server 10.0.1.1:8080; server 10.0.1.2:8080; ... # 共10台 keepalive 16; # 取整，并略高于计算值 }

同时，在server或location中：

proxy_http_version 1.1; proxy_set_header Connection ""; # 建议加上超时控制，防止异常连接占用池资源 proxy_connect_timeout 3s; proxy_read_timeout 10s;

3.2 场景二：低频、长连接的数据推送服务

例如WebSocket代理或Server-Sent Events (SSE)。

特征：

连接建立后，会保持很长时间（分钟甚至小时级别）。
在这个长连接上，可能有间歇性的数据推送。
总并发连接数可能不高，但每个连接生命周期长。

配置思路：这种情况下，keepalive的连接池意义不大，因为连接本身已经是长连接，并且会被一直占用。配置的重点是确保nginx与后端之间的连接稳定，以及正确传递升级头（如WebSocket的Upgrade头）。keepalive值可以设置得较小，甚至对于纯WebSocket代理，有时短连接模式更简单（因为WS连接建立后通常不会重建）。

配置示例：

upstream ws_backend { server 10.0.2.1:9000; keepalive 4; # 保持少量连接用于初始握手和健康检查即可 } location /ws/ { proxy_pass http://ws_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # 注意这里不是空，是"upgrade" proxy_set_header Host $host; # 长连接超时设置需要很长 proxy_read_timeout 3600s; proxy_send_timeout 3600s; }

注意：对于WebSocket，proxy_set_header Connection "upgrade";是必须的，这与普通HTTP长连接的proxy_set_header Connection "";冲突。这意味着，对于需要同时代理普通HTTP和WebSocket的upstream，需要仔细设计路由规则，或者接受WebSocket连接无法从keepalive池中获益（通常可以接受，因为WS连接数相对少）。

3.3 场景三：混合流量与保守配置

很多业务是混合型的，既有短平快的API，也有上传下载等耗时操作。

特征：

请求处理时间分布差异大（从几毫秒到几十秒）。
流量模式难以预测。

配置思路：采取保守策略。设置一个中等大小的keepalive值，并密切监控连接池的使用情况。监控是关键。

配置与监控：

upstream mixed_backend { server 10.0.3.1:8080; server 10.0.3.2:8080; keepalive 32; # 一个折中的起始值 }

如何监控？nginx的stub_status模块或商业版的状态模块可以提供基础信息，但对于upstream keepalive的细节，我们需要依赖日志或第三方模块。最有效的方法是在编译nginx时加入--with-http_stub_status_module，然后配置：

location /nginx_status { stub_status on; access_log off; allow 127.0.0.1; # 仅允许本机访问 deny all; }

访问http://your-nginx-server/nginx_status会得到类似：

Active connections: 291 server accepts handled requests 16630948 16630948 31070465 Reading: 6 Writing: 179 Waiting: 106

这里的Waiting通常常被理解为空闲的客户端连接（keepalive连接）。但对于上游连接，不直接可见。

更细粒度的监控，需要通过分析error_log（设置info级别）或使用如ngx_http_status_module（第三方）等模块。一个实用的土方法是：通过后端服务器的连接数来间接观察。在后端服务器上使用netstat或ss命令，查看来自nginx服务器的连接状态。如果看到大量ESTABLISHED连接且数量相对稳定，说明keepalive生效了。如果看到大量TIME_WAIT状态，则说明连接在频繁开闭。

实操心得二：动态调整与观察期永远不要一次性把keepalive调到一个很大的值然后放任不管。我的建议是：
先计算：用上述公式算出一个理论值。
后观察：在预发布或低峰期，配置一个略低于理论值的参数（例如理论值12，先设8）。
监控：通过后端服务器连接数、nginx的waiting连接数（虽不精确但有趋势参考）、系统监控（如ss -s看到的TCP连接统计）观察1-2个完整流量周期（一天）。
调整：如果发现后端ESTABLISHED连接数经常等于或接近keepalive值，且新建连接数（SYN_SENT）很少，说明池大小可能够用。如果频繁创建新连接，可以适当调大。如果ESTABLISHED连接数远低于keepalive值且很稳定，可以考虑调小以释放资源。
压测验证：在调整后，进行压力测试，观察平均响应时间、错误率、nginx及后端服务器的资源使用率（CPU、内存、文件描述符）的变化。

4. 常见问题排查与深度优化

配置上了，不代表就万事大吉。下面是一些我踩过的坑和对应的解决方案。

4.1 问题一：配置了keepalive，但后端服务器依然看到大量TIME_WAIT连接

现象：在nginx上配置了keepalive，但后端服务器的netstat -n | grep :8080 | grep TIME_WAIT | wc -l结果依然很高。

排查步骤：

检查nginx配置：确认proxy_http_version 1.1;和proxy_set_header Connection "";已正确设置在使用了proxy_pass http://upstream_name;的location中。一个常见的错误是只在http或server块设置了，但某个特定的location块覆盖了它们。
检查后端应用：有些后端应用服务器（如某些旧版本或配置不当的Tomcat、Jetty）可能会在HTTP响应头中强制返回Connection: close。即使nginx希望保持连接，后端主动关闭了，nginx也只能遵循。你需要检查后端应用的配置，确保其支持并允许HTTP/1.1长连接。
检查负载均衡与失败重试：如果nginx开启了proxy_next_upstream（默认在错误时重试），且重试到了另一个后端服务器，那么与第一个服务器的连接可能会被关闭。这属于正常行为。
检查keepalive值是否过小：如果并发请求瞬间超过keepalive池大小，多余的请求就会创建新连接。请求处理完后，如果池已满，这些新连接就会被关闭，从而产生TIME_WAIT。需要根据流量评估并调大keepalive值。
使用调试日志：将nginx的error_log级别调整为info，可以在日志中看到更详细的连接建立和关闭信息，有助于定位问题。

4.2 问题二：连接池“泄露”或僵尸连接

现象：监控发现，nginx与某个后端服务器的ESTABLISHED连接数持续增长，直到达到很高水平，甚至超过keepalive配置，但实际流量并不大。

原因与解决：

后端响应异常未正常结束：如果后端服务器响应缓慢，或者响应体没有正确结束（例如，没有发送正确的Content-Length或chunked结束标记），nginx可能会一直等待，认为这个连接上的请求还没处理完，因此不会将其释放回连接池。这个连接就“泄露”了。
- 解决：设置合理的proxy_read_timeout和proxy_send_timeout。例如，对于API服务，设置proxy_read_timeout 30s;，超过这个时间就断开连接并返回错误给客户端。
TCP Keepalive未生效：网络中间设备（如防火墙、负载均衡器）可能会断开空闲连接。如果TCP层的keepalive探测包没有发送或未收到回应，nginx可能无法感知连接已死，仍将其留在池中。
- 解决：在listen指令中为上游socket启用TCP keepalive（需要nginx支持相应参数，通常在内核层面配置更通用）。更可靠的方法是，在后端应用层实现健康检查或心跳。
nginx版本Bug：极少数情况下，旧版本nginx的upstream模块可能存在连接管理bug。
- 解决：升级到稳定版或最新主线版。

4.3 问题三：负载不均衡

现象：启用了keepalive后，配合某些负载均衡算法（如默认的round-robin），发现流量向后端服务器分配得不均匀。

原因分析：keepalive连接池是每个worker进程独立维护的。假设你有2个后端服务器（A, B）和4个nginx worker进程（W1, W2, W3, W4）。

初始时，所有池都是空的。
请求到来，被分配到不同worker。W1的第一个请求可能给了A，W2的第一个请求可能给了B，W3的第一个请求又给了A…… 这样，每个worker进程都会为自己建立到A和B的连接并放入池中。
后续请求，worker会优先复用自己池中的连接。如果W1处理的请求远多于W2，那么即使A和B服务器性能相同，A服务器接收到的连接和请求也会远多于B，因为W1总是用连向A的连接。

解决方案：

使用least_conn（最少连接）负载均衡算法：这是与keepalive搭配最友好的算法。它会把新请求分配给当前活跃连接数最少的后端服务器。这在一定程度上可以抵消每个worker独立连接池带来的倾斜。注意，它计算的是“活跃连接”，而非池中的空闲连接。
```
upstream backend { least_conn; server backend1.example.com; server backend2.example.com; keepalive 32; }
```
调整keepalive值：适当减小keepalive值，可以促使连接更快地被回收和重建，从而增加负载均衡算法的调度机会。但这与性能优化目标相悖，需要权衡。
使用zone指令（商业版Nginx Plus）：Nginx Plus提供了一个zone指令，可以在worker进程之间共享上游服务器的状态信息，从而实现更精确的负载均衡。开源版不支持此功能。
接受一定的不均衡：在大多数场景下，只要worker进程间的请求分配是均衡的（这通常由操作系统调度或外部负载均衡器保证），并且后端服务器数量不是特别少，这种由keepalive带来的不均衡是可以接受的。监控后端服务器的负载（CPU、内存、QPS），只要差异在可接受范围内（如10%以内），就不必过度优化。

4.4 高级优化：与多阶段请求和缓冲的配合

在一些复杂场景，如文件上传/下载、流式响应，还需要考虑proxy_buffering等设置与keepalive的协同。

场景：大文件上传。客户端通过nginx上传一个1GB的文件到后端。

如果proxy_buffering on（默认）：nginx会先接收并缓冲整个客户端请求体（1GB），然后再向后端发起连接并传输。此时，keepalive连接在nginx开始向后端发送数据时才会被占用。连接占用时间短，但nginx内存压力大。
如果proxy_buffering off：nginx会像管道一样，边接收客户端数据，边转发给后端。此时，从请求一开始，keepalive连接就被占用，并且会占用很长时间（取决于上传速度）。这可能导致连接池中的连接被长时间占用，影响其他请求的复用。

建议：

对于API等小请求，保持proxy_buffering on（默认），keepalive效果最佳。

对于明确的大文件上传场景，可以针对特定location关闭缓冲，并考虑为该location使用独立的、keepalive值较小的upstream配置，或者直接使用短连接（不配keepalive），避免影响核心API的连接池。

# 专门处理大文件上传的 upstream，使用短连接或极小的keepalive upstream upload_backend { server 10.0.4.1:8080; # keepalive 2; # 或者直接不设置，默认为0 } location /upload { proxy_pass http://upload_backend; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_buffering off; # 关闭缓冲，启用流式传输 client_max_body_size 10G; proxy_read_timeout 300s; proxy_send_timeout 300s; }

5. 性能测试与效果验证

任何配置优化，都需要用数据说话。下面是如何验证keepalive配置是否带来收益的方法。

测试工具：常用wrk、ab(ApacheBench)、jmeter。测试目标：对比开启优化keepalive前后，相同压力下的性能指标。关键指标：

吞吐量（Requests/sec）：是否提升。
平均延迟（Latency Avg）及延迟分布（P99, P95）：是否下降，特别是尾部延迟。
错误率：连接错误、超时错误是否减少。
系统资源：
- nginx服务器：TIME_WAIT连接数（ss -tan state time-wait | wc -l）、新建连接速率（sar -n TCP 1观察active/s和passive/s）。
- 后端服务器：ESTABLISHED连接数（ss -tan state established | wc -l）、CPU使用率。

测试脚本示例（使用wrk）：

# 测试开启keepalive前（配置中keepalive 0或注释掉） wrk -t12 -c400 -d30s --latency http://your-nginx-server/api/test # 调整nginx配置，启用keepalive 32，并重载配置 `nginx -s reload` wrk -t12 -c400 -d30s --latency http://your-nginx-server/api/test

预期结果：

开启合理的keepalive后，在相同并发下，吞吐量应有明显提升（例如10%-50%，取决于请求处理时间和网络延迟）。
平均延迟和P99延迟应下降，因为省去了大量的TCP握手时间。
nginx服务器的**TIME_WAIT连接数应大幅减少**。
后端服务器的**ESTABLISHED连接数应稳定在一个较低的水平**，而不是随着并发数线性增长。

我的实测数据记录：在一次内部服务优化中，针对一个平均响应时间25ms的API：

keepalive 0(短连接)：压测QPS约 3200，平均延迟 38ms，nginx服务器产生约 28000个/秒的TIME_WAIT。
keepalive 64：压测QPS提升至约 5100，平均延迟降至 28ms，TIME_WAIT连接数降至几乎为0，后端服务器稳定连接数在120左右（对应8个worker * 64/每个 ≈ 512的池大小，实际使用约1/4）。

这个数据清晰地展示了连接复用的威力。最后，记住一个核心原则：upstream keepalive的优化，本质是在用内存（维护连接池）换取CPU和网络延迟。你需要根据实际的硬件资源、网络条件和业务流量模式，找到那个最佳的平衡点。没有一劳永逸的配置，只有持续观察和调整的过程。