Nginx反代WebSocket避坑指南：从Upgrade握手到超时配置与负载均衡

做后端开发、尤其是前端有实时通信需求的同学，十有八九会在 Nginx 反代 WebSocket 这件事上栽过跟头。明明本地直连后端一切正常，一旦套上 Nginx 反代，要么握手失败、要么连上几秒就被切断、要么多节点部署时消息串到别的实例上。这些问题我在做实时消息推送和在线协作功能时都遇到过，而且每类坑背后都有非常明确的原因和排查路径。这篇文章就把这些坑整理成一份可以直接对照的清单，从 Upgrade 原理到超时配置、从负载均衡到 WSS 证书，配合排查命令和速查表，一次讲清楚。

1. 先把原理吃透：Nginx 反代 WebSocket 的底层机制

1.1 从 HTTP Upgrade 到 101 Switching Protocols

WebSocket 并不是凭空建立连接的，它基于 HTTP/1.1 的 Upgrade 机制。客户端会先发一个普通 HTTP GET 请求，在请求头里带上：

http复制Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: xxxx
Sec-WebSocket-Version: 13

后端如果同意升级，就返回 101 Switching Protocols。这个响应之后，这条 TCP 连接就不再按 HTTP 的请求—响应模式工作，而是直接变成一条双向的 WebSocket 数据通道。

这里就引出了 Nginx 反代 WebSocket 的核心矛盾。Nginx 默认是个 HTTP 代理，它在转发请求时会自己处理请求头，不会主动把 Connection: Upgrade 这类头原封不动传给后端。一旦这个头丢了，后端收到的是一个普通 GET 请求，自然不会返回 101，WebSocket 握手就直接失败。

我见过不少人在 Nginx 配置里只加了 proxy_pass，没加任何请求头处理，然后就上浏览器调试，看到 WebSocket connection failed 或 Error during WebSocket handshake，第一反应是后端代码写错了，查了半天发现 Nginx 这里就挡掉了。

1.2 最小可用配置模板与 map 处理

一个能正常工作的 Nginx 反代 WebSocket 配置，核心就是以下这几行：

nginx复制map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream ws_backend {
    server 127.0.0.1:8080;
}

server {
    listen 80;
    server_name example.com;

    location /ws/ {
        proxy_pass http://ws_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        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_set_header Upgrade $http_upgrade; 这行的意思是：如果客户端请求里带了 Upgrade: websocket，Nginx 就把这个头原样转发给后端；如果客户端没带，这个头就不存在。Connection 头直接用 $connection_upgrade 这个 map 变量来控制——有 Upgrade 头时设置为 upgrade，没有时设置为 close。

这样做的好处是，同一个 location 里如果既有 WebSocket 请求又有普通 HTTP 请求，普通请求不会因为强制设置了 Connection: upgrade 而出现异常。

我一直建议团队把 map 这种写法作为默认模板，不要图省事直接写死 Connection "upgrade"。因为一旦 WebSocket 连接握手完成，后续这条连接上跑的就已经不是普通 HTTP 了，你要是还按普通代理的思维去处理，后面各种奇怪问题都会冒出来。

2. 连接建立阶段的常见坑：请求头丢失、路径错配、版本太老

2.1 最常见的坑：Upgrade 与 Connection 请求头没传

这个问题在前面原理部分已经点到了，但实际场景里还有一些更隐蔽的变种。

第一个变种是：配置里加了 proxy_set_header Upgrade $http_upgrade;，但 $http_upgrade 为空。这种情况常见于浏览器或客户端没有正确发起 WebSocket 握手，比如前端代码写错了 URL，用的是 http:// 而不是 ws://，或者拼接 URL 的时候把路径搞错了。这时候 Nginx 转发出去的是一个普通 GET 请求，后端自然不会走 WebSocket 逻辑。

第二个变种是：有多个 location 或 server 块，WebSocket 请求实际命中的不是你以为的那个 location。比如你配置了 location /ws/，但前端代码请求的是 /socket.io/，那就完全不会走这个规则。

排查这种问题时，我习惯先在后端日志里看请求头。如果后端收到的请求头里没有 Upgrade: websocket，那就说明问题出在 Nginx 转发这一层；如果后端收到了但没返回 101，那就要查后端逻辑。

2.2 location 路径错配导致的握手失败

location 的匹配规则在 Nginx 里非常容易踩坑，尤其是 location /、location = /、location ^~、location ~ 这些不同前缀的优先级先后，我见过不少人把 /ws 和 /ws/ 搞混。

Nginx 的 location 匹配优先级是：精确匹配 = 最高，然后是 ^~ 前缀匹配，再是正则匹配 ~ 或 ~*，最后才是普通前缀匹配。这意味着如果你同时存在 location = /ws 和 location /，请求 /ws 会走精确匹配，而 /ws/abc 会走普通前缀匹配。

WebSocket 的 URL 一般都会带路径，比如 ws://example.com/ws/chat。如果配置里写的是 location = /ws，那 ws/chat 根本不会命中它，而是可能命中其他规则。

我的建议是，WebSocket 的 location 路径尽量用带前缀的独立路径，比如 /ws/，并且在 location 里加一个简单的健康检查接口。这样既方便前端拼接 URL，也方便后端做鉴权前置处理。

2.3 Nginx 版本过低导致的兼容性坑

Nginx 对 WebSocket 反代的支持是从 1.3.13 版本才引入的，之后在 1.4.0 做了进一步完善。如果服务器上装的是 1.2.x 或更早版本，配置里写 proxy_set_header Upgrade $http_upgrade; 是无效的，$http_upgrade 变量根本没有意义。

我遇到过一台老机器，跑了几年没动过，Nginx 版本停留在 1.2.9，新项目要接入 WebSocket，我配置写好了、nginx -t 也通过了，但握手就是失败。后来一查版本，心里直呼好家伙。

现在用 apt install nginx 或 yum install nginx 装的基本都是 1.18 以上版本，不会有这个问题。但如果你是用编译方式装的、或者从网上下的乱七八糟的包，一定要先确认版本。

另外要注意，Nginx 官方主线版本（Mainline）和稳定版本（Stable）之间的差异不大，至少 WebSocket 反代这块差异可以忽略。不过如果一定要在 Linux 上通过包管理器安装，建议从 Nginx 官网的软件源安装，而不是用系统自带的源，因为系统源里的版本可能比较旧。

3. 连接保持阶段的坑：超时配置、心跳与异常断连

3.1 默认超时导致 WebSocket 每分钟被切断一次

WebSocket 握手成功之后，连接就变成了一条长期存活的双向通道。但 Nginx 在处理代理连接时，默认有一套超时控制：proxy_read_timeout 默认 60 秒，proxy_send_timeout 默认 60 秒。

这意味着什么？如果 WebSocket 连接在 60 秒内没有任何数据交互（无论是客户端发还是后端发），Nginx 就会认为这条连接已经空闲到可以释放，直接把连接断开。

前端表现就是：页面刚打开时连接好好的，过一会儿就断，而且断的时间点非常规律，基本就是 60 秒左右。如果你在页面上加了重连逻辑，就会看到连接每 60 秒断开一次、立刻重连、再 60 秒断开，循环往复。

解决方式很简单，把超调大或者设为 0（不超时）：

nginx复制location /ws/ {
    proxy_pass http://ws_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

这里还有一个细节：proxy_read_timeout 和 proxy_send_timeout 是指两次数据交互之间的间隔超时，不是连接总时长。只要在 3600 秒内有任意一次数据交互，计时器就会重置。所以设置成 3600s 并不意味着连接只能活一小时，而是只要连接保持活跃，它可以一直存活。

3.2 心跳机制只是兜底，超时配置才是根本

很多人为了保活，会在前端或者后端加心跳机制，每隔一段时间发一次 ping/pong。这个思路是对的，但如果 Nginx 的超时配置没调大，心跳间隔又大于超时时间，那连接照样会被切断。

比如前端每 30 秒发一次心跳，Nginx 超时默认 60 秒，看起来没问题。但如果某次心跳因为网络抖动延迟了几秒，加上前端页面切到后台时心跳间隔可能被浏览器拉长，就很容易超过 60 秒。

我的建议是双管齐下：Nginx 超时配置调到至少 300 秒以上，前端心跳间隔保持在 30~60 秒。这样即使丢一两次心跳，连接也不会被 Nginx 断掉。

后端协议层面，WebSocket 本身的 ping/pong 帧（opcode 0x9 和 0xA）可以用于心跳，但很多业务框架用的是自定义消息。不管用哪种，只要保证在超时时间内有数据包经过 Nginx 就行。因为 Nginx 看到的只是 TCP 层的数据流动，它不关心你发的是 ping 还是业务消息。

3.3 "upstream prematurely closed" 这类报错如何定位

Nginx 错误日志里经常能看到这样一行：

code复制upstream prematurely closed connection while reading response header from upstream

这个报错的意思是：Nginx 在等待后端返回响应头时，后端的连接就提前关闭了。在 WebSocket 场景下，这个报错通常出现在两个阶段：

一个阶段是握手阶段。后端返回 101 之前，连接就断了。可能原因是后端服务崩溃、后端代码里主动拒绝了升级请求、或者后端监听的端口根本不对。

另一个阶段是连接保持阶段。握手已经完成，Nginx 正在做数据中继，这时后端主动关闭了连接，Nginx 就会在日志里记录类似信息。

碰到这种报错，第一步不是翻 Nginx 配置，而是直接看后端日志和连接状态。用 netstat -anp | grep 8080 看端口有没有在监听，用 curl -v 直接请求后端看握手是否正常。如果直连后端没问题，再回来查 Nginx 的日志和配置。

我还遇到过一种特殊情况：后端代码里有超时机制，超过了约定的 idle 时间后主动关连接，这时 Nginx 的 proxy_read_timeout 就算设得再大也没用，因为断连是后端自己发起的。

所以排查思路一定要从两端入手，别一上来就甩锅给 Nginx。

4. 多节点场景的坑：负载均衡、会话保持与连接数管理

4.1 轮询模式下消息串节点的原因

如果后端 WebSocket 服务不止一个实例，Nginx 的 upstream 默认是轮询（round-robin）方式分发请求。第一个连接打到节点 A，第二个连接打到节点 B，第三个打到节点 C。

问题来了：WebSocket 是有状态的长连接。客户端 A 连接到了节点 1，它发的消息由节点 1 处理；客户端 B 连接到了节点 2，它发的消息由节点 2 处理。如果客户端 A 想给客户端 B 发消息，而节点 1 和节点 2 之间没有做消息同步，节点 1 根本不知道客户端 B 的存在，消息就发不出去。

更常见的表现是：客户端每次重连，Nginx 都可能把它路由到不同的节点，导致客户端拿到的新连接不是之前那个会话所在的节点，之前会话里的上下文全丢了。

很多人把这类问题笼统地叫做“消息串节点”，但本质上不是消息串了，而是会话没有绑定到固定节点。

4.2 ip_hash 的适用范围与局限

解决会话保持最简单的方式是 ip_hash：

nginx复制upstream ws_backend {
    ip_hash;
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
}

ip_hash 的原理是取客户端 IP 的哈希值，然后把相同 IP 的请求固定分发到同一个后端节点。这样同一个客户端的所有请求都会落在同一台机器上，会话就能保持住了。

但这个方案有几个明显的局限。第一个是：如果大量用户从同一个出口 IP 访问（比如公司内网、学校 NAT），哈希就会集中在少数几个节点上，造成负载不均。第二个是：如果后端节点数量发生变化（扩缩容），哈希结果会大变，所有连接都会重新分配，导致大规模重连。第三个是：如果客户端本身用的是 IPv6，ip_hash 的行为跟 IPv4 不一样，容易踩坑。

在 WebSocket 场景下，用户跨地区分布、出口 IP 固定的情况很常见，ip_hash 往往不是最佳方案。

4.3 多节点下的连接数与内存规划

除了会话保持，多节点场景下还要考虑连接数和内存的规划。

Nginx 作为反向代理，每个 WebSocket 连接会占用两个文件描述符（fd），一端连着客户端，一端连着后端。默认的 worker_connections 是 1024，对于高并发 WebSocket 场景肯定不够。我在配置高并发反代时一般会这么调：

nginx复制worker_processes auto;

events {
    worker_connections 10240;
    use epoll;
}

要注意的是，worker_connections 不只是一个数字，它还受系统文件描述符上限（ulimit -n）的限制。如果系统默认值是 1024，你就算在配置里写 10240，实际也起不来那么多连接。需要把系统级和进程级的 ulimit 配置一起改。

另外，每个 WebSocket 连接在没有数据流动时，连接是阻塞挂起的，占用的内存主要是内核 socket 缓冲区和 Nginx 的 connection 结构体。连接数到万级别时，Nginx 占用的内存也就几百 MB，还好。但后端进程往往不止一个实例，每个实例都要维护自己的客户端连接表，这个开销才是大头。

部署在 Kubernetes 里时，还有一层 Service 做负载均衡，Nginx 或者 Ingress Controller 反代 WebSocket 时同样要处理会话保持问题。原理没有本质区别，只是多了网络转发层，排查时要把每一层的超时和头转发都检查一遍。

5. HTTPS/WSS 场景的坑：证书、私钥与双向验证

5.1 WSS 反代的完整配置要点

WebSocket 跑在 HTTPS 下就是 WSS，Nginx 侧需要配置 SSL 证书，然后把客户端请求转发给后端的 WebSocket 服务。

基本的 WSS 反代配置：

nginx复制server {
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate     /etc/nginx/ssl/example.com.pem;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;

    location /ws/ {
        proxy_pass http://ws_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

这里有个容易忽略的点：ssl_certificate 配置的文件应该包含完整的证书链。如果你的证书是从证书厂商签发的，一般需要把服务端证书和中间证书合并成一个 .pem 文件。如果只放了服务端证书，没有中间证书，某些客户端会报证书链不完整。

另外，http2 这个参数和 WebSocket 的关系要留意。HTTP/2 早期对 WebSocket 的支持有兼容性问题，不过现在的浏览器和 Nginx 都能处理好。如果你用的是比较老的 Nginx 版本，遇到 WSS 连接建立失败，可以试试去掉 http2 再看。

5.2 私钥类型与格式差异：RSA、ECC

Nginx 配置证书时，ssl_certificate 和 ssl_certificate_key 这两个文件必须配对。私钥的格式和类型有时也会坑人。

私钥常见的两种类型是 RSA 和 ECC（椭圆曲线）。RSA 兼容性最好，但性能相对低；ECC 性能高、密钥短，但要求客户端也支持。现在主流浏览器都支持 ECC，所以很多新证书都直接用 ECDSA 签发了。

Nginx 支持的私钥格式主要是 PEM，也就是以 -----BEGIN PRIVATE KEY----- 或 -----BEGIN EC PRIVATE KEY----- 开头的那种文本格式。如果证书厂商给你的是 .key 文件，但里面是 PKCS#8 格式，Nginx 也是支持的。但如果里面是 PKCS#1，Nginx 可能就不认，需要转换。

我自己遇到过的情况是：从某个证书平台下载证书时，默认下载的是 .pfx 格式，里面包含证书和私钥，不能直接给 Nginx 用。需要先转换成 PEM 格式，再用 OpenSSL 拆分出证书和私钥：

bash复制openssl pkcs12 -in cert.pfx -nocerts -out key.pem -nodes
openssl pkcs12 -in cert.pfx -clcerts -nokeys -out cert.pem

然后 nginx -t 验证通过再重载。这类格式转换的坑在 Nginx 部署时非常常见。

5.3 双向 TLS：需要客户端证书时的配置

有些内部系统会要求客户端也提供证书，做双向 TLS。Nginx 配置：

nginx复制server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;
    ssl_client_certificate /etc/nginx/ssl/ca.crt;
    ssl_verify_client on;
    ssl_verify_depth 2;

    location /ws/ {
        proxy_pass http://ws_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header X-SSL-Client-Cert $ssl_client_cert;
    }
}

这里有几个要点：

ssl_client_certificate 指向的是签发客户端证书的 CA 证书，Nginx 用这个 CA 去验证客户端证书的签名。ssl_verify_client on 表示强制验证客户端证书，如果客户端没带有效证书，握手直接失败。

这里有个坑：WebSocket 的 JavaScript API 在浏览器里是无法自定义客户端证书的。浏览器会从系统证书库里自动选择证书，或者在连接时弹出选择框。如果你的前端页面是重定向到 WebSocket 连接，很可能因为证书选择弹窗被浏览器拦截，导致连接失败。

所以在 Web 场景下，双向 TLS 的 WebSocket 并不常见，更多是在原生客户端或服务端到服务端的连接里使用。如果你的项目是原生客户端，也要注意有些 WebSocket 库对客户端证书的支持并不好，可能需要底层网络库去注入证书链。

6. 排查清单：现象、报错与指令对照

6.1 三次快速定位的命令

遇到 Nginx 反代 WebSocket 出问题时，我一般按下面这三个命令快速定位方向。

第一步，确认 Nginx 配置语法没有问题：

bash复制nginx -t

这个命令会检查配置文件的语法，同时按照 Nginx 的方式加载配置。如果有错，它会直接告诉你出错的文件和行号。很多人改完配置不跑这一步就直接 nginx -s reload，语法错误会导致 reload 失败，甚至可能让旧的配置继续跑。

第二步，用 curl 模拟 WebSocket 握手，直接测试后端：

bash复制curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==" -H "Sec-WebSocket-Version: 13" http://127.0.0.1:8080/ws/chat

这条命令的目的是绕过 Nginx，直连后端。如果后端返回了 HTTP/1.1 101 Switching Protocols，说明后端没问题。如果返回 200 或者 4xx，说明后端没走 WebSocket 逻辑。

第三步，同样的命令打给 Nginx 的对外地址：

bash复制curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==" -H "Sec-WebSocket-Version: 13" http://localhost/ws/chat

如果直连后端是 101，但通过 Nginx 就变成其他响应，那问题基本可以锁定在 Nginx 转发层。接下来重点检查 proxy_set_header、proxy_pass 和 location 规则。

6.2 错误信息速查表

我在排查过程中经常遇到的错误信息和对应原因，整理成一张速查表：

这里说一个容易被忽略的：浏览器端报 1006 并不代表服务端有问题，很多是网络中间层（比如云厂商的负载均衡、防火墙）主动掐断了空闲连接。在这种场景下，就算 Nginx 的 proxy_read_timeout 设得很大，中间层设备也会在你长时间无流量时把连接清掉。这时除了调大 Nginx 超时，还要配合心跳机制来保持连接活跃。

6.3 一套验证过的完整示例配置

最后，给出一份我实际部署时验证过、可以直接改改就用的完整配置：

nginx复制# 放在 /etc/nginx/conf.d/websocket.conf 或主配置的 http 块里
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream ws_realtime {
    ip_hash;
    server 10.0.0.11:8080 max_fails=3 fail_timeout=10s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=10s;
    keepalive 32;
}

server {
    listen 80;
    listen 443 ssl http2;
    server_name ws.example.com;

    ssl_certificate     /etc/nginx/ssl/ws.example.com.pem;
    ssl_certificate_key /etc/nginx/ssl/ws.example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    access_log /var/log/nginx/ws_access.log;
    error_log  /var/log/nginx/ws_error.log;

    location /ws/ {
        proxy_pass http://ws_realtime;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        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_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
        proxy_connect_timeout 10s;
    }
}

注意这份配置里 upstream 我加了 ip_hash，如果后端点超过三个或者有扩缩容计划，ip_hash 会导致连接重排，这种场景可以考虑用基于哈希 key 的 hash $remote_addr consistent;，或者引入 Redis/其他方案做节点会话路由。还有一个细节是 keepalive 32;，这个参数能让 Nginx 与后端之间维持 32 个空闲的 HTTP 长连接，减少重复握手开销。聊天室、消息推送这类高并发场景，效果很明显。

配置完成后执行 nginx -t，通过后 nginx -s reload，然后用上面的 curl 命令验证握手是否正常。

最后再分享一个经验：Nginx 反代 WebSocket 的问题，九成以上都出在我前面列的这几类坑里。每次接到相关排查需求，我都是先看版本、再看请求头、再看超时、最后看后端日志，一圈走下来基本能定位。尤其是刚接手一个老项目时，别急着改配置，先拿 curl 把后端-代理-客户端三层链路都打一遍，数据会告诉你问题在哪。这套方法我用了很多年，实测效率最高，也最不容易被现象带偏。