Nginx 反代 WebSocket 的配置要点

WebSocket 连接在握手后要保持长活，这给反向代理出了两道题：握手时的协议升级头要原样传给后端；Nginx 默认六十秒的读超时会把空闲连接掐断。配置就围绕这两点展开。 一、标准配置块 ``` 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 "upgrade"; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } ``` 逐行解释：WebSocket 走 HTTP/1.1 的 Upgrade 机制握手，必须显式写 proxy_http_version 1.1——Nginx 反代默认用 1.0，不带 Upgrade 头，握手必失败；Upgrade 和 Connection 两行把升级头透传给后端；读与写超时拉长，避免空闲即断。要理解 read_timeout 的真实含义：它是相邻两次数据到达的最大间隔，不是连接的保活时长。 二、更通用的头写法 同一个 location 既服务普通请求又服务 WebSocket 时，用 map 按条件切换： ``` map $http_upgrade $connection_upgrade { default upgrade; '' close; } # location 内改用 proxy_set_header Connection $connection_upgrade; ``` 普通请求自动带 close，WebSocket 自动 upgrade，一处配置两头兼顾。 三、心跳保活别省 超时调到一小时也未必稳：中间的负载均衡、云防火墙常会静默回收几分钟没流量的连接。所以应用层心跳是必需品——服务端每 30 秒发一个 ping 帧，客户端回 pong，或者前端定时发业务心跳。心跳一来保住连接不被中间设备掐，二来死连接能被及时发现清理。正因为心跳间隔必须小于沿途最小的那个超时，Nginx、后端框架、中间设备三处的空闲超时要逐段核对，缺一处就是"连上后几十秒准点断开"的经典故障。 四、验证与集群注意 握手成功与否看状态码：浏览器开发者工具的网络面板里，WebSocket 连接显示 101 Switching Protocols 才算握手成功，WS 标签页能逐条看消息收发。Socket.IO 这类框架有约定的路径与心跳参数，代理里匹配的路径要和框架对齐，默认 /ws 还是 /socket.io 先确认再排查。上线前先绕开 Nginx 用客户端直连后端测通，再过一遍代理，分两步定位问题。多台后端做集群时还要配 ip_hash 这类会话保持，长连接必须粘在同一台后端上，换台机器连接就断了。