如果你从事后端开发或者自己搭过服务器，大概率遇到过这种场景：服务端WebSocket程序明明监听正常，本地用测试工具连得好好的，可一旦部署到线上、请求经过Nginx转发，客户端要么卡在连接中，要么握手成功几秒钟就断开，浏览器控制台还时不时蹦出个 400 Bad Request。
这个问题的根源基本都指向同一件事——Nginx的WebSocket代理配置没有写对。和普通HTTP代理不一样，WebSocket连接建立后需要维持一条双向长连接，而Nginx默认的HTTP代理行为是按短连接设计的，若不做额外配置，握手头会被吞掉，连接自然就建不起来。这篇文章就把我在实际部署中摸索出来的一套配置、排障思路和生产调优经验完整拆开讲，给正在踩坑的人一个可以直接照抄的参考答案。
1. 为什么Nginx代理WebSocket不能照抄普通HTTP配置
1.1 WebSocket握手与普通HTTP请求的关键差异
在动手改配置之前，先搞清楚WebSocket和传统HTTP在主从通信方式上的本质区别，这部分理解了，后面看配置就顺了。
普通HTTP请求是“一问一答”模式：客户端发起请求，服务端返回响应，连接使命完成，可以关闭。整个过程是无状态的、短连接式的，即使HTTP/1.1加入了keep-alive复用机制，本质上还是“请求-响应”的循环模式。
WebSocket则完全不同。它首先通过一次HTTP协议的握手请求建立连接，握手成功之后，这条TCP连接就“升级”为双向通信管道，客户端和服务端可以随时向对方推送数据。关键是——这个连接一旦建立，就长期占用，直到某一方主动关闭。
这就带来一个问题：Nginx作为反向代理，它的天然职责是接收上游请求、转发给后端、等待后端响应、返回给客户端。这是为短连接设计的流转模型。When WebSocket的长期连接经过这个模型时，代理层不能像处理普通请求那样“转发完就撒手”，它必须把这条TCP连接“架空”成一条隧道，让客户端和后端的数据直接双向穿透Nginx。这就是为什么我们需要告诉Nginx“这个连接你不许按普通请求处理，要特殊对待”。
1.2 Connection和Upgrade两个请求头到底在做什么
WebSocket握手之所以能从HTTP协议升级成长连接，靠的是两个关键请求头：Connection: Upgrade和Upgrade: websocket。它们在握手请求中扮演的角色可以用一个不太精确但很好理解的类比：你在一个公司前台的访客系统里登记访客身份，然后前台发你一张临时通行卡，凭卡可以进入内部区域自由活动，不需要每次进出都重新登记。
Upgrade: websocket就是访客需求声明，告诉服务端“我想把当前协议切换为WebSocket协议”；Connection: Upgrade则告诉服务端“这个连接我要继续用，别发完响应就掐断我”。服务端收到这两个头后，如果同意切换，就会返回101 Switching Protocols，从这一刻起，双方在同一个TCP连接上直接跑WebSocket帧数据。
1.3 代理场景下“逐跳头”被吞掉的根本原因
问题恰恰出在Connection这个头上。HTTP协议里有一个重要概念：头字段分为两种类型，一种叫“端到端头”，比如Content-Type、Authorization，它们从客户端出发，穿过所有代理层，最终抵达服务端，语义保持不变；另一种叫“逐跳头”，比如Connection、Keep-Alive、Upgrade，它们只在相邻两个节点之间的单跳链路上有意义，不允许被代理透传。
Nginx作为HTTP代理，默认行为就是“很守规矩”地处理好逐跳头之后继续转发请求。也就是说，它会消费掉Connection头，再向后端发起新请求时，不会自动附带上Connection: Upgrade和Upgrade: websocket。这样一来，后端收到的仅仅是一个普通HTTP请求，根本没有进入WebSocket握手流程。这就是为什么很多人的代理配置看起来“什么都没写错”，但WebSocket就是连不上。
理解到这一层，接下来的配置就好办了。你只需要做两步：把后端请求的HTTP版本提升到1.1，然后显式地把这两个头重新传给后端。
2. 一套能跑起来的最小WebSocket代理配置
2.1 最简配置：一个location块搞定单机服务
如果你的WebSocket后端服务部署在同一台机器上，端口是8080，路径是/ws，那么下面这组配置是最小可用版。我实际生产环境里跑过很久，稳定可靠，适合作为起点。
map $http_upgrade $connection_upgrade { default upgrade; '' close; } server { listen 80; server_name example.com; location /ws { proxy_pass http://127.0.0.1:8080; 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 60s; } }先说最容易忽略的一步：map块。这段代码必须放在http{}上下文中，也就是和server{}同级，不能放进location里，否则Nginx启动直接报错。它的作用稍后解释，先记住这个结构。
2.2 逐行拆解关键指令的用途与原理
这套配置里有几个指令缺一不可，我逐个说一下它们的作用，以及去掉之后会看到什么幺蛾子。
proxy_http_version 1.1：Nginx向后端发起代理请求时，默认使用HTTP/1.0。但HTTP/1.0没有标准的Upgrade机制，即使你把Upgrade头手动传过去了，后端也不认。所以必须显式声明1.1。这一行少了，最常见的报错是后端直接返回404或者干脆不响应。
proxy_set_header Upgrade $http_upgrade：作用是把客户端握手请求里的Upgrade头原样透传给后端。$http_upgrade是Nginx内置变量，代表“客户端请求头中Upgrade字段的值”。普通HTTP请求里这个值是空的，所以不会影响常规的HTTP代理行为。
proxy_set_header Connection $connection_upgrade：这里就是map发挥作用的地方。看这组映射逻辑：当$http_upgrade的值非空（说明是WebSocket握手请求）时，$connection_upgrade就替换成upgrade；当$http_upgrade为空（也就是普通HTTP请求）时，$connection_upgrade就替换成close。这么做的目的是让Nginx既能把Upgrade头传给后端，又不会画蛇添足地给每个普通HTTP请求都加一个Connection: upgrade。
很多人照着网上的配置抄完发现普通网站访问正常，WebSocket却连不上，排查了半天最后发现是map写错了位置，或者变量名拼错。这里我提醒一句：一旦改动map，必须nginx -t通过后再reload，否则旧配置还在内存里运行，改了半天没反应。
proxy_set_header Host $host：保留原始的Host头。后端如果有基于域名的虚拟主机配置，这一行很重要，丢了会导致路由错误。
X-Forwarded-For和X-Real-IP：这是为后端程序获取客户端真实IP服务的。WebSocket应用经常需要记录用户来源IP做统计或安全限制，如果漏了这两个头，后端看到的IP永远是Nginx所在机器的内网地址，业务方排查问题时容易误判。
proxy_read_timeout 60s：这条线的坑最深。Nginx默认的proxy_read_timeout是60秒，意思是如果60秒内代理层没有从后端读到任何数据，它就会主动断开这个连接。WebSocket业务如果设计成“服务器不主动推送，全靠客户端心跳维持”，那客户端发一次心跳可能间隔几十秒甚至一两分钟，一旦超过这个阈值，连接就会被Nginx强行掐断，表现就是“WebSocket莫名其妙断开，报错1006”。后面我会专门讲心跳和超时搭配的经验。
2.3 用wscat和浏览器验证代理是否生效
配置完成后，别急着写业务代码，先用工具验证一下代理链路是否完整。我习惯用wscat做快速连通性测试，没有的话npm install -g wscat装一下就行。
# 直连后端，确认服务本身没问题 wscat -c ws://127.0.0.1:8080/ws # 走Nginx代理，验证转发链路 wscat -c ws://example.com/ws如果直连正常、走代理连接失败，问题基本锁定在Nginx配置层；如果两者都连不上，先去查后端服务进程和监听端口，别在代理配置上浪费时间。
浏览器端验证也很快：F12打开控制台，切到Network面板，刷新页面触发WebSocket连接，找到名字为ws的请求，点开看Response Headers里有没有101 Switching Protocols。看到101，说明握手成功；看到其他状态码，直接对照下一节的内容排查。
我在这个环节还见过一种情况：直连和走代理都能建立连接，但服务端收不到客户端发来的消息。这种一般是代理层只转发了握手请求，后续数据帧没有正确转发。遇到这种问题，优先检查配置里是不是少了第二组proxy_set_header或者proxy_http_version 1.1，因为数据帧阶段依赖HTTP/1.1的Upgrade隧道机制。
3. 多后端节点下的WebSocket会话保持问题
3.1 为什么负载均衡会让WebSocket“串台”
单机部署的WebSocket服务能跑通之后，很多人会自然想到下一个问题：如果后端服务有多台机器，怎么用Nginx做负载均衡？
这里有一个和普通HTTP负载均衡完全不同的陷阱。普通HTTP请求是无状态的，Nginx可以把每次请求轮询到不同后端，业务上完全无感知。但WebSocket连接是有状态的——握手成功后，客户端和后端会在一条TCP连接上持续通信，这个连接绑定了服务端的一段会话上下文，比如登录态、房间信息、临时数据等。如果客户端发来的数据帧被Nginx转发到另一台后端机器上，那台机器根本没有对应的会话上下文，消息就丢了，表现出来就是“连接还在，但不说话了”。
千万不要小看这个问题。我在测试环境验证负载均衡配置时，用两个后端节点，轮流发送消息，结果发现消息经常性丢失，一开始还以为是后端代码有并发Bug，排查了很久才发现是Nginx把同一个WebSocket连接的不同数据帧转发到了不同节点上。
3.2 会话保持的三种常见方案与取舍
WebSocket场景下解决跨节点会话问题的核心思路只有一个：让同一个客户端的连接始终落在同一台后端节点上。业界常见的方案有三种，各有适用场景。
方案一：Nginx的ip_hash负载均衡策略。
upstream ws_backend { ip_hash; server 10.0.0.1:8080; server 10.0.0.2:8080; }ip_hash会基于客户端IP计算哈希值，保证同一个IP的请求稳定分配到同一台后端节点。这个方案配置最简单，不需要后端配合，适合用户量不是特别巨大、客户端IP相对固定的场景。但它有一个先天缺陷：当某个IP下挂了大量客户端（比如公司出口NAT场景，几百个用户共享一个公网IP）时，这个IP的流量会全部压到一台后端节点上，负载严重不均。
方案二：基于Cookie的会话保持（sticky session）。
Nginx商业版有sticky指令，可以直接实现基于Cookie的会话保持；开源版虽然不带这个指令，但可以通过proxy_cookie_flags或后端的会话Cookie来间接实现。这个方案的优点是粒度更细，可以精确到每个客户端会话，不受IP聚合影响；缺点是需要后端配合设置和读取Cookie，增加了架构复杂度。
方案三：应用层重定向。
后端在握手阶段根据业务逻辑把自己节点的标识写入一个特定响应头，Nginx后续根据这个标识决定转发目标。这个方案通常需要开发自定义Nginx模块或者用Lua脚本实现，灵活性最高，但维护成本也最高，一般业务规模没必要上这么重的方案。
我的建议是：中小规模部署，先上ip_hash，实测观察负载分布情况，如果出现明显不均再加Cookie方案。别一上来就用高成本方案，WebSocket的会话保持其实没有想象中那么复杂，很多场景下单机部署都已经够用，多节点更多是为了容灾而非性能。
3.3 结合HTTP服务和WebSocket服务的混合站点配置
实际项目中，绝大多数WebSocket服务不是独立部署的，而是和传统HTTP API服务共用一个域名。比如example.com/api走普通HTTP，example.com/ws走WebSocket。这种情况下，你只需要在同一个server块里配两个location即可，配置逻辑互不干扰。
server { listen 80; server_name example.com; # 普通HTTP API，按常规反向代理配置 location /api/ { proxy_pass http://api_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # WebSocket专用路径，单独配置升级头 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_read_timeout 300s; } }有几个细节值得注意：第一，WebSocket路径建议单独划分，不要和API共用同一路径前缀，否则Nginx的location匹配规则会变得很绕，而且做日志分流时也不好区分。第二，location里用精确匹配=前缀还是用普通前缀匹配，取决于你的接口设计，但/ws这种固定路径直接用前缀匹配就够用了。第三，如果你的WebSocket服务还依赖HTTP接口的登录鉴权，可以让握手请求先经过API层校验，成功后引导客户端连接WebSocket，或者直接在WebSocket握手时携带Token让后端校验。这两种方式我都在生产环境用过，后者更简单直接，但要注意Token的传递安全性，不要把它放进URL参数里。
4. 代理层最常见的故障与完整排查链路
4.1 握手返回400 Bad Request的排查顺序
如果前端WebSocket连接报400错误，不要第一时间冲进后端代码仓库里找Bug。400发生在握手阶段，意味着请求根本没有到达正常的应用逻辑层。我通常按下面这个顺序排查：
第一步，看Nginx错误日志。默认路径一般是/var/log/nginx/error.log，用tail -f实时盯着看。如果日志里出现upstream prematurely closed connection，基本可以确认是后端拒绝了这个请求，原因大概率是握手头没有正确传递。
第二步，确认proxy_http_version 1.1是否配置。这个指令缺失导致的400最隐蔽，因为配置看起来几乎完美，Upgrade头也传了，但后端使用的是HTTP/1.0，无法解析Upgrade请求。
第三步，抓包确认握手请求实际长什么样。这一步可以让你直接看到Nginx转发出去的头是什么状态。用tcpdump在Nginx服务器上抓后端端口的包：
tcpdump -i eth0 -A -s 0 'tcp port 8080' | grep -A 20 'GET /ws'如果抓包结果显示请求头里根本没有Connection: Upgrade，那就回头看配置里的proxy_set_header是不是写错变量名了；如果请求头里有Connection: Upgrade但后端返回400，问题就在后端服务本身，检查它是否真的支持WebSocket协议。
这里再分享一个我踩过的坑：map块定义变量时，如果值里带了多余的空格或者分号，nginx -t可能不会报错，但运行时变量解析会出问题。遇到Connection: upgrade, upgrade这种诡异的重复值，优先检查map块的书写是否规范。
4.2 连接建立后几秒内被断开的问题定位
握手成功（101状态码）但连接很快就断开，这个现象比400更让人头疼，因为问题可能出在很多层面。我把这类问题的排查链路总结成下面这张思维导图式清单，你可以照着自己检查一遍：
- 如果连接断开时后端日志报错，说明是后端主动断开的，检查业务代码有没有对连接时的异常处理不当导致崩溃；
- 如果后端日志无异常，大概率是代理层或网络层断开的，先查Nginx错误日志，重点看
upstream timed out和read timed out； - 如果是
read timed out，那就是proxy_read_timeout的锅，后端在超时时间内没有任何数据输出，Nginx就掐断了连接； - 如果是客户端看到的错误码是1006（异常关闭），这是浏览器端对“非正常关闭帧”的统一错误码，需要看服务端或者代理层的具体断开原因；
- 如果是1001（going away）或1008（policy violation），一般是应用层主动断开，去查业务逻辑。
有一个高频场景值得特别说明：很多WebSocket服务为了省电或省资源，会关闭空闲连接，而客户端默认认为连接依然健在。一旦服务端或代理层的某一个环节先断开了连接，客户端没有及时发现，双方的通信状态就错位了，后续数据全部发送失败。解决这个问题没有捷径，就是靠心跳机制。后面我会细讲心跳怎么配。
4.3 502/504错误的常见原因与确认方法
502 Bad Gateway和504 Gateway Timeout也是WebSocket代理场景里的常客。502表示Nginx作为代理访问后端失败了，504表示Nginx等不到后端的响应。
出现502时，第一反应是检查后端的端口监听状态：
# 查看后端端口是否监听 ss -lntp | grep 8080 # 检查后端进程是否存活 ps aux | grep 你的服务进程名如果后端服务确实活着，但Nginx仍然报502，八成是Nginx与后端的网络不通，比如防火墙拦了内网端口，或者后端服务只监听了127.0.0.1导致跨机器访问不通。还有一种隐蔽的情况：后端服务刚重启，Nginx的upstream配置里写的还是旧IP或旧容器地址，连不上就报502，刷新一下DNS或者同步一下配置就好。
504则主要归咎于超时设置。后端处理握手请求的逻辑比较重（比如要查数据库、调外部接口），耗时超过了proxy_connect_timeout（默认60秒）或者proxy_read_timeout，Nginx等不及就主动放弃。排查方法比较简单：把相关超时时间临时调大，比如proxy_read_timeout 300s，再看是否复现，如果不再报504，说明确实是后端处理耗时长的原因。但要注意，这只是临时排查手段，根本解决之道还是要优化后端的握手响应速度，否则大量连接会堆积在代理层等待资源，拖垮整个服务。
5. 生产环境下Nginx代理WebSocket的调优与监控经验
5.1 超时参数、心跳探测与可靠性配置
走到这一步，说明你的WebSocket代理已经能从“能跑”升级到“稳定跑”。这里我给出的是一组长期实践下来的生产参数，可以直接作为起点使用。
map $http_upgrade $connection_upgrade { default upgrade; '' close; } upstream ws_backend { ip_hash; server 10.0.0.1:8080 max_fails=3 fail_timeout=30s; server 10.0.0.2:8080 max_fails=3 fail_timeout=30s; } 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_connect_timeout 10s; proxy_read_timeout 360s; proxy_send_timeout 360s; proxy_buffer_size 4k; proxy_buffers 8 4k; proxy_busy_buffers_size 8k; } }逐项说一下改动思路：
proxy_connect_timeout 10s：连接后端超时设短一点，快速失败，避免请求堆积。这个值不建议超过10秒，因为同机房内网连接正常情况下都在毫秒级完成，设长了只会让Nginx的worker进程被卡住的连接白白占用。
proxy_read_timeout和proxy_send_timeout：都调到360秒。这个值不是拍脑袋定的，而是根据业务的心跳频率计算出来的。我习惯把超时时间设为心跳间隔的三倍以上。假如客户端每30秒发一次心跳，那么proxy_read_timeout至少90秒；但为了应对网络抖动和客户端异常，我会直接调到300到360秒，宁长勿短。短了会误杀正常连接，长了最多浪费一点系统资源，风险更低。
max_fails=3 fail_timeout=30s：这两项配合能让Nginx在后端节点宕机时快速摘除流量。真的是生产环境的血泪教训——如果不配这个参数，Nginx会不断把请求转发给一个已经挂掉的后端，导致大量连接卡死直到超时，用户侧感知就是“页面转了十几秒然后报错”。配置了这两项之后，后端连续失败3次会被标记为不可用，30秒内不再转发流量，体验明显好转。
关于心跳机制，这里多说几句。WebSocket协议本身没有强制要求客户端保持心跳，但生产环境强烈建议加。原因有三：维持代理层连接存活，防止Nginx的读写超时杀掉空闲连接；及时发现“幽灵连接”（网络断开但两端没感知）；清理后端的无效资源占用。实现方式一般是客户端每隔固定时间（比如30秒）发一个ping帧或者业务自定义的heartbeat消息，服务端收到后回复，代理层保持静默转发即可。Nginx层面完全不需要额外配置，只要超时时间大于心跳间隔，连接就能稳定存活。
5.2 日志格式改造与连接数监控
做WebSocket代理，最怕的就是线上出问题但日志里啥都看不出来。默认的Nginx access log只记录了握手请求的行，连接建立之后的数据帧往来完全没有记录。这就导致排查问题时少了一条最关键的线索。
我建议给WebSocket代理加一个独立的日志格式，重点记录握手阶段的关键信息：
log_format ws_log '$remote_addr [$time_local] "$request" ' '$status $body_bytes_sent "$http_upgrade" ' '$request_time $upstream_response_time ' '$upstream_addr'; server { # ... access_log /var/log/nginx/ws_access.log ws_log; # ... }上面"$http_upgrade"字段会记录客户端传来的Upgrade值，如果这里是空，说明客户端发的是普通HTTP请求，根本没进WebSocket握手流程，问题可能在客户端代码而不是代理配置。$upstream_response_time可以让你判断是哪一跳耗时，如果这个值很大，瓶颈在后端服务；如果很小但客户端依然超时，问题可能在网络链路。
连接数的监控也要安排上。Nginx的stub_status模块提供了基础的连接数据，开启方法是在server块加一个专用location：
location /nginx_status { stub_status on; access_log off; allow 127.0.0.1; deny all; }开启后访问/nginx_status会返回四行关键数据：Active connections是当前活跃连接数，Reading是正在读请求头的连接数，Writing是正在写响应的连接数，Waiting是空闲连接数。WebSocket长连接场景下，Waiting会长期维持在高位，这是正常的，说明大量连接已经建立并处于空闲等待状态。你只要把这几个指标接进监控系统，设定告警阈值，就能对代理层健康状况做到心里有数。
5.3 我长期使用下来的一些建议
最后分享几条我在不同业务背景下总结的经验。这些不属于某个具体配置项，但对稳定性和可维护性的提升很显著。
一条是关于worker进程调优的。Nginx默认的worker进程数是按CPU核数自动设置的，但WebSocket长连接非常消耗内存和文件描述符，如果你的服务端连接数达到几万级别，光靠默认配置是不够的。可以在nginx.conf的events块里调整一下：
events { worker_connections 10240; multi_accept on; }worker_connections表示每个worker进程能同时处理的连接数上限，配合系统的文件描述符限制（ulimit -n调高到65535以上），才能支撑大规模长连接。
另一条是关于线上变更的。WebSocket连接是长期存活的，当你执行nginx -s reload时，老连接不会立刻断开，Nginx会把新配置应用到新连接上，老连接继续由旧配置管理直到自然断开。这个特性有好有坏：好处是reload基本不影响在线用户；坏处是如果你改了和长连接相关的配置（比如proxy_read_timeout），老连接不生效，只有新建立的连接才用新参数。所以我做配置变更后，会刻意观察一段时间，确认新连接的行为符合预期，再考虑是否要让客户端重新连接一次，否则新旧配置混跑容易造成行为不一致。
还有一条是关于定位问题的通用技巧：先绕开代理直连后端。不管报错信息多诡异，先用客户端直连后端服务，如果直连正常，再走代理，两边对比，基本一轮就能锁定问题层级。这个办法帮我处理过不下十个看起来“高深莫测”的WebSocket故障，最后的结论无一例外都是代理配置细节的问题。
WebSocket代理本身并不复杂，核心就是那两行proxy_set_header和一行proxy_http_version。但生产环境的稳定性，靠的是理解握手原理、设置合理的超时和心跳、提前规划好负载均衡的会话保持策略，以及在日志和监控上多下一点功夫。把这些都做到位了，你会发现WebSocket代理其实比普通的HTTP代理还要省心，因为连接一旦建立，Nginx就成了一个近乎透明的通道，真正的压力全在后端业务上。
