简介这份PDF资料聚焦WebSocket应用部署到服务器后出现连接失败的问题面向Java后端开发者与运维人员尤其是使用Tomcat 8、从本地环境迁移到服务器时遇到连接异常的读者。内容围绕环境差异、包冲突、连接地址配置与长连接特性展开梳理了从Tomcat 7升级到Tomcat 8时容易踩坑的典型场景并给出可操作的排查与解决思路。资源包共1个PDF文件约46KB篇幅精炼适合快速查阅与对照排错。目前已有10558人学习下载说明该问题在实际部署中较为普遍。读者可从中获得包冲突规避、WebSocket连接URL正确写法、远程调试注意事项等具体经验并附有示例Demo下载地址便于结合代码理解连接失败的原因与修复方式提升部署调试效率。1. WebSocket 上线即断连为什么本地跑通的服务一部署就翻车本地ws://localhost:8080/ws跑得好好的一放到服务器上换成wss://your-domain.com/ws浏览器控制台立刻甩出WebSocket connection to ... failed或者更气人的——握手成功连上三秒后无声无息断开。这不是玄学是 WebSocket 部署到服务器时最典型的一类问题连接失败。它牵扯的环节比普通 HTTP 接口多得多因为 WebSocket 要先经过一次 HTTP Upgrade 握手再切换到长连接中间任何一层——Nginx、Tomcat、防火墙、TLS 证书、心跳配置——出问题都会让连接建不起来或者建起来又断掉。这篇文章面向的是已经把 WebSocket 功能写出来、准备或刚刚部署到服务器上的后端和全栈工程师。我会按“先定位失败发生在哪一层再逐层解决”的思路把 Tomcat 部署、Nginx 反向代理、TLS 证书、心跳机制、超时参数这几块讲透每一步都给可复现的命令和配置。看完你应该能自己判断我这次连接失败到底是握手没过去还是过去了又被谁掐断了。2. 先定位失败发生在哪一层握手、升级还是心跳WebSocket 连接失败不是一个单一错误它至少分三个阶段TCP 连接建立、HTTP Upgrade 握手、连接建立后的保活。不同阶段失败现象和排查手段完全不同。很多人一上来就改代码其实问题在 Nginx 配置或者云服务器安全组改一天代码也没用。所以第一步永远是分层定位。2.1 用浏览器和命令行把失败阶段钉死打开浏览器开发者工具切到 Network 面板筛选WS。刷新页面触发连接看这条 WebSocket 请求的状态状态一直是pending最后超时TCP 层就没通或者握手请求被某层吞了。状态101 Switching Protocols但马上变红断开握手成功了是连接建立后被断开重点查心跳和超时。状态400、403、404、502握手阶段被拒看响应头和服务器日志。命令行侧用curl模拟握手能拿到比浏览器更原始的信息# 模拟 WebSocket 握手-i 打印响应头-N 禁用缓冲 curl -i -N \ -H Connection: Upgrade \ -H Upgrade: websocket \ -H Sec-WebSocket-Version: 13 \ -H Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ \ https://your-domain.com/ws正常应该返回HTTP/1.1 101 Switching Protocols并带上Upgrade: websocket和Connection: Upgrade两个响应头。如果返回的是200、400或502说明请求根本没走到 WebSocket 处理逻辑问题在反向代理或应用服务器配置上。这一步的价值在于它把“连接失败”这个大帽子缩小到具体某一层。2.2 三个阶段的典型现象对照把常见现象和对应层整理成一张表排查时直接对号入座比盲目试错快得多。现象失败阶段优先排查对象请求 pending 后超时TCP / 握手安全组、防火墙、Nginx 监听端口返回 400 / 403HTTP 握手Nginx Upgrade 头、后端路径映射返回 502 / 504反向代理转发后端服务是否存活、代理超时101 后秒断连接保活心跳、proxy_read_timeout、空闲超时部分客户端能连部分不能环境差异TLS 版本、证书链、客户端代理这张表不是让你背而是让你在遇到问题时先问一句我现在卡在哪一行。定位准了后面的配置才有意义。我见过太多人把 101 后秒断当成握手失败去改 Nginx 的 Upgrade 头方向完全错了。2.3 打开后端和代理的日志开关定位阶段一定要让日志说话。Tomcat 侧确认访问日志和 WebSocket 相关日志打开Nginx 侧把error_log级别临时调到info能看到 Upgrade 请求有没有被转发、转发到哪个 upstream。# Nginx 临时提高日志级别排查完记得调回 # 在 http 或 server 块中 error_log /var/log/nginx/error.log info; # 实时观察握手请求 tail -f /var/log/nginx/error.log | grep -i upgrade日志里如果看到upstream prematurely closed connection说明后端在握手阶段就关了连接问题在应用服务器如果看到client intended to send too large body之类是请求被限制。日志级别调高会带来性能开销排查完务必调回warn或error这是血泪经验。3. Tomcat 侧部署 WebSocket从依赖到路径映射如果后端是 Java 技术栈Tomcat 是最常见的容器。WebSocket 在 Tomcat 上的部署有几个固定动作漏一个就连不上。这一章按“依赖 → 端点 → 路径 → 容器配置”的顺序讲每一步都能直接抄。3.1 依赖和端点类的正确写法用 Jakarta WebSocketTomcat 10 及以上或 javax WebSocketTomcat 9 及以下坐标不同混用会直接导致端点注册失败。先确认 Tomcat 大版本再选依赖。!-- Tomcat 10 使用 jakarta 命名空间 -- dependency groupIdjakarta.websocket/groupId artifactIdjakarta.websocket-api/artifactId version2.1.0/version scopeprovided/scope /dependency// 服务端端点路径 /ws注意 ServerEndpoint 的值要和前端一致 import jakarta.websocket.OnMessage; import jakarta.websocket.OnOpen; import jakarta.websocket.Session; import jakarta.websocket.server.ServerEndpoint; ServerEndpoint(/ws) public class WsEndpoint { OnOpen public void onOpen(Session session) { // 连接建立时记录 session便于后续推送 System.out.println(open: session.getId()); } OnMessage public void onMessage(String msg, Session session) { // 回显验证双向通信是否正常 session.getAsyncRemote().sendText(echo: msg); } }ServerEndpoint(/ws)里的路径是相对于应用上下文根的。如果应用部署为/app前端要连的是/app/ws不是/ws。这个上下文路径是新手最容易踩的坑之一连不上先检查这里。scope设为provided是因为 Tomcat 自带 WebSocket 实现打包进 war 反而可能冲突。3.2 路径映射和容器参数怎么配端点注册有两种方式注解扫描和ServerEndpointExporter。Spring Boot 内嵌 Tomcat 时必须手动注册ServerEndpointExporter否则注解端点不会被扫描到表现为握手 404。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.socket.server.standard.ServerEndpointExporter; Configuration public class WsConfig { Bean public ServerEndpointExporter serverEndpointExporter() { // 内嵌容器下必须注册否则 ServerEndpoint 不生效 return new ServerEndpointExporter(); } }如果部署到独立 Tomcat外置 war 包则不需要这个 BeanTomcat 自己会扫描。判断标准很简单用java -jar跑 Spring Boot 就是内嵌需要丢 war 到 Tomcat 的webapps就是外置不需要。搞反了要么端点不注册要么重复注册报错。Tomcat 侧还有几个连接相关参数值得关注在server.xml的Connector上Connector port8080 protocolHTTP/1.1 connectionTimeout20000 maxThreads200 redirectPort8443 /connectionTimeout对普通 HTTP 请求生效WebSocket 升级后走的是另一套超时逻辑但握手阶段仍受它影响。如果握手请求本身很慢先看这个值是不是太小。3.3 验证 Tomcat 端点是否真的注册成功部署完别急着连前端先用命令行确认端点活着。启动应用后用前面那条curl命令打本地端口curl -i -N \ -H Connection: Upgrade \ -H Upgrade: websocket \ -H Sec-WebSocket-Version: 13 \ -H Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ \ http://127.0.0.1:8080/ws返回101说明 Tomcat 侧端点正常问题在更外层Nginx、TLS、安全组。返回404说明路径不对或端点没注册回到 3.1 和 3.2 检查。返回400通常是 Upgrade 头缺失或Sec-WebSocket-Key格式不对。这一步把 Tomcat 从嫌疑名单里排除或坐实非常关键。4. Nginx 反向代理 WebSocketUpgrade 头和超时是重灾区生产环境很少让 Tomcat 直接对外前面通常挂 Nginx。Nginx 默认按普通 HTTP 处理请求不会转发 Upgrade 头结果就是握手请求到了 Nginx 就变成普通 GET后端返回 200 或 400前端报连接失败。这一章把 Nginx 配置讲全包括 Upgrade 头、超时、以及和 TLS 的配合。4.1 让 Nginx 正确转发 Upgrade 请求核心是proxy_set_header把Upgrade和Connection透传给后端并用map指令处理Connection的值避免硬编码。# 在 http 块中定义 map根据 Upgrade 头动态设置 Connection map $http_upgrade $connection_upgrade { default upgrade; close; } server { listen 443 ssl; server_name your-domain.com; location /ws { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; # WebSocket 必须用 1.1 proxy_set_header Upgrade $http_upgrade; # 透传 Upgrade proxy_set_header Connection $connection_upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 3600s; # 长连接读超时见 4.2 proxy_send_timeout 3600s; } }proxy_http_version 1.1是硬性要求HTTP/1.0 不支持 Upgrade。Connection用map动态设置是因为普通请求和 Upgrade 请求需要不同的值写死upgrade会让普通请求也带上可能引发其他问题。proxy_read_timeout默认 60 秒意味着连接空闲 60 秒就被 Nginx 掐断这是“连上后一分钟就断”的元凶。4.2 超时参数和心跳机制必须配套Nginx 的proxy_read_timeout和前端/后端的心跳机制要一起设计。如果心跳间隔 30 秒而proxy_read_timeout是 60 秒理论上安全但如果网络抖动导致一次心跳丢失就可能被掐。稳妥做法是心跳间隔明显小于超时时间比如心跳 25 秒、超时 300 秒以上。前端心跳实现// 每 25 秒发一次 ping服务端回 pong let ws new WebSocket(wss://your-domain.com/ws); let heartbeatTimer null; ws.onopen () { heartbeatTimer setInterval(() { if (ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify({ type: ping })); } }, 25000); }; ws.onclose () { clearInterval(heartbeatTimer); // 断线重连逻辑注意加退避别疯狂重连 };服务端收到ping回pong同时可以借心跳更新“最后活跃时间”用于服务端主动清理死连接。心跳不只是防代理超时也是检测半开连接的手段——TCP 连接看起来还在实际对端已经没了只有靠心跳才能发现。4.3 TLS 证书和 wss 的常见坑用wss://时证书链不完整是最隐蔽的坑。浏览器能打开 HTTPS 页面不代表 WebSocket 握手能过——某些客户端对证书链校验更严格。用openssl检查证书链是否完整# 检查服务器返回的证书链-showcerts 打印全部 openssl s_client -connect your-domain.com:443 -servername your-domain.com -showcerts输出里如果只有一张证书没有中间 CA就是链不完整。解决办法是在 Nginx 配置里把中间证书和服务器证书按顺序拼进同一个文件ssl_certificate /etc/nginx/ssl/fullchain.pem; # 服务器证书 中间证书 ssl_certificate_key /etc/nginx/ssl/privkey.pem;fullchain.pem的顺序是服务器证书在前、中间证书在后顺序错了同样会失败。另外确认listen 443 ssl而不是listen 443少了ssl参数 TLS 根本不启用。5. 避坑与排查连接失败最常见的五类翻车前面讲的是“怎么配”这一章讲“配了还不行怎么办”。下面五条都是我在实际部署里反复遇到的按“现象 → 原因 → 解决”写遇到问题直接对照。5.1 现象本地 101线上 400原因Nginx 没有透传Upgrade和Connection头后端收到的是普通 HTTP 请求WebSocket 握手条件不满足返回 400。解决按 4.1 的配置补上proxy_http_version 1.1、proxy_set_header Upgrade、proxy_set_header Connection。改完nginx -t校验再nginx -s reload别直接重启避免配置错误导致服务全挂。5.2 现象连上后固定 60 秒断开原因Nginxproxy_read_timeout默认 60 秒连接空闲超过这个时间被代理层关闭。解决把proxy_read_timeout和proxy_send_timeout调到大于心跳间隔的值同时确认心跳真的在发。只调超时不加心跳遇到网络中断还是发现不了死连接只加心跳不调超时心跳间隔必须小于 60 秒否则照样断。5.3 现象部分用户连不上报证书错误原因证书链不完整或者服务器只配了服务器证书没配中间证书。不同客户端对链校验严格程度不同导致“有的人能连有的人不能”。解决用 4.3 的openssl命令确认链完整把中间证书拼进fullchain.pem。另外检查 TLS 版本禁用过老的 TLS 1.0/1.1但也要确认客户端支持你启用的最低版本。5.4 现象握手成功但收不到消息原因连接建立了但消息被缓冲或路由错了。常见于多实例部署时没有做会话共享消息推到了另一个实例。解决单实例先确认OnMessage和sendText逻辑正常多实例场景需要引入 Redis 发布订阅或专门的消息中间件做会话路由把 session 和实例的映射关系维护起来。这是架构层面的问题不是配置能解决的。5.5 现象日志里大量upstream prematurely closed connection原因后端在握手阶段就关闭了连接通常是端点路径不匹配、应用启动失败、或者 Tomcat 线程池被打满。解决先确认后端进程活着、端口在监听ss -lntp | grep 8080再确认路径映射一致。线程池打满的话看maxThreads和实际并发WebSocket 长连接会长期占用线程NIO 模式下虽然不占线程但连接数仍有上限需要评估容量。6. 上线前的自检清单与一个压测技巧配置改完别急着宣布搞定上线前跑一遍自检能省掉大量“上线后才发现”的尴尬。下面这份清单我每次部署都会过一遍按顺序执行任何一项不过就别往下走。检查项命令 / 方法期望结果后端端点存活curl模拟握手打本地端口返回 101Nginx 配置语法nginx -tsyntax is ok代理层握手curl打域名 443返回 101证书链完整openssl s_client -showcerts至少两张证书心跳生效观察连接存活超过超时时间不断开断线重连手动 kill 后端再启动前端自动恢复自检里最容易被忽略的是“断线重连”。很多人只测正常连接不测异常恢复结果线上后端重启一次所有客户端就永久失联了。前端重连一定要加退避别用固定 1 秒疯狂重试会把后端打垮// 指数退避重连最大 30 秒 let retry 1000; function reconnect() { setTimeout(() { ws new WebSocket(wss://your-domain.com/ws); retry Math.min(retry * 2, 30000); // 翻倍封顶 30 秒 }, retry); }最后分享一个压测技巧用websocat或自己写脚本并发建连观察在多少并发下开始出现握手失败或秒断。这个数字就是你的容量边界比任何理论估算都准。我一般会从 100 并发开始逐步加到出现失败记录下当时的连接数和服务器指标作为扩容依据。部署 WebSocket 这件事坑基本都在“连接建立”和“连接保活”这两段把 Nginx 的 Upgrade 头、超时参数、心跳机制这三样配对了八成问题就没了。剩下的两成靠日志和分层定位也能快速收敛。希望帮到你。本文还有配套的精品资源点击获取
WebSocket 部署上线即断连？Nginx 代理与心跳超时排查指南
简介这份PDF资料聚焦WebSocket应用部署到服务器后出现连接失败的问题面向Java后端开发者与运维人员尤其是使用Tomcat 8、从本地环境迁移到服务器时遇到连接异常的读者。内容围绕环境差异、包冲突、连接地址配置与长连接特性展开梳理了从Tomcat 7升级到Tomcat 8时容易踩坑的典型场景并给出可操作的排查与解决思路。资源包共1个PDF文件约46KB篇幅精炼适合快速查阅与对照排错。目前已有10558人学习下载说明该问题在实际部署中较为普遍。读者可从中获得包冲突规避、WebSocket连接URL正确写法、远程调试注意事项等具体经验并附有示例Demo下载地址便于结合代码理解连接失败的原因与修复方式提升部署调试效率。1. WebSocket 上线即断连为什么本地跑通的服务一部署就翻车本地ws://localhost:8080/ws跑得好好的一放到服务器上换成wss://your-domain.com/ws浏览器控制台立刻甩出WebSocket connection to ... failed或者更气人的——握手成功连上三秒后无声无息断开。这不是玄学是 WebSocket 部署到服务器时最典型的一类问题连接失败。它牵扯的环节比普通 HTTP 接口多得多因为 WebSocket 要先经过一次 HTTP Upgrade 握手再切换到长连接中间任何一层——Nginx、Tomcat、防火墙、TLS 证书、心跳配置——出问题都会让连接建不起来或者建起来又断掉。这篇文章面向的是已经把 WebSocket 功能写出来、准备或刚刚部署到服务器上的后端和全栈工程师。我会按“先定位失败发生在哪一层再逐层解决”的思路把 Tomcat 部署、Nginx 反向代理、TLS 证书、心跳机制、超时参数这几块讲透每一步都给可复现的命令和配置。看完你应该能自己判断我这次连接失败到底是握手没过去还是过去了又被谁掐断了。2. 先定位失败发生在哪一层握手、升级还是心跳WebSocket 连接失败不是一个单一错误它至少分三个阶段TCP 连接建立、HTTP Upgrade 握手、连接建立后的保活。不同阶段失败现象和排查手段完全不同。很多人一上来就改代码其实问题在 Nginx 配置或者云服务器安全组改一天代码也没用。所以第一步永远是分层定位。2.1 用浏览器和命令行把失败阶段钉死打开浏览器开发者工具切到 Network 面板筛选WS。刷新页面触发连接看这条 WebSocket 请求的状态状态一直是pending最后超时TCP 层就没通或者握手请求被某层吞了。状态101 Switching Protocols但马上变红断开握手成功了是连接建立后被断开重点查心跳和超时。状态400、403、404、502握手阶段被拒看响应头和服务器日志。命令行侧用curl模拟握手能拿到比浏览器更原始的信息# 模拟 WebSocket 握手-i 打印响应头-N 禁用缓冲 curl -i -N \ -H Connection: Upgrade \ -H Upgrade: websocket \ -H Sec-WebSocket-Version: 13 \ -H Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ \ https://your-domain.com/ws正常应该返回HTTP/1.1 101 Switching Protocols并带上Upgrade: websocket和Connection: Upgrade两个响应头。如果返回的是200、400或502说明请求根本没走到 WebSocket 处理逻辑问题在反向代理或应用服务器配置上。这一步的价值在于它把“连接失败”这个大帽子缩小到具体某一层。2.2 三个阶段的典型现象对照把常见现象和对应层整理成一张表排查时直接对号入座比盲目试错快得多。现象失败阶段优先排查对象请求 pending 后超时TCP / 握手安全组、防火墙、Nginx 监听端口返回 400 / 403HTTP 握手Nginx Upgrade 头、后端路径映射返回 502 / 504反向代理转发后端服务是否存活、代理超时101 后秒断连接保活心跳、proxy_read_timeout、空闲超时部分客户端能连部分不能环境差异TLS 版本、证书链、客户端代理这张表不是让你背而是让你在遇到问题时先问一句我现在卡在哪一行。定位准了后面的配置才有意义。我见过太多人把 101 后秒断当成握手失败去改 Nginx 的 Upgrade 头方向完全错了。2.3 打开后端和代理的日志开关定位阶段一定要让日志说话。Tomcat 侧确认访问日志和 WebSocket 相关日志打开Nginx 侧把error_log级别临时调到info能看到 Upgrade 请求有没有被转发、转发到哪个 upstream。# Nginx 临时提高日志级别排查完记得调回 # 在 http 或 server 块中 error_log /var/log/nginx/error.log info; # 实时观察握手请求 tail -f /var/log/nginx/error.log | grep -i upgrade日志里如果看到upstream prematurely closed connection说明后端在握手阶段就关了连接问题在应用服务器如果看到client intended to send too large body之类是请求被限制。日志级别调高会带来性能开销排查完务必调回warn或error这是血泪经验。3. Tomcat 侧部署 WebSocket从依赖到路径映射如果后端是 Java 技术栈Tomcat 是最常见的容器。WebSocket 在 Tomcat 上的部署有几个固定动作漏一个就连不上。这一章按“依赖 → 端点 → 路径 → 容器配置”的顺序讲每一步都能直接抄。3.1 依赖和端点类的正确写法用 Jakarta WebSocketTomcat 10 及以上或 javax WebSocketTomcat 9 及以下坐标不同混用会直接导致端点注册失败。先确认 Tomcat 大版本再选依赖。!-- Tomcat 10 使用 jakarta 命名空间 -- dependency groupIdjakarta.websocket/groupId artifactIdjakarta.websocket-api/artifactId version2.1.0/version scopeprovided/scope /dependency// 服务端端点路径 /ws注意 ServerEndpoint 的值要和前端一致 import jakarta.websocket.OnMessage; import jakarta.websocket.OnOpen; import jakarta.websocket.Session; import jakarta.websocket.server.ServerEndpoint; ServerEndpoint(/ws) public class WsEndpoint { OnOpen public void onOpen(Session session) { // 连接建立时记录 session便于后续推送 System.out.println(open: session.getId()); } OnMessage public void onMessage(String msg, Session session) { // 回显验证双向通信是否正常 session.getAsyncRemote().sendText(echo: msg); } }ServerEndpoint(/ws)里的路径是相对于应用上下文根的。如果应用部署为/app前端要连的是/app/ws不是/ws。这个上下文路径是新手最容易踩的坑之一连不上先检查这里。scope设为provided是因为 Tomcat 自带 WebSocket 实现打包进 war 反而可能冲突。3.2 路径映射和容器参数怎么配端点注册有两种方式注解扫描和ServerEndpointExporter。Spring Boot 内嵌 Tomcat 时必须手动注册ServerEndpointExporter否则注解端点不会被扫描到表现为握手 404。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.socket.server.standard.ServerEndpointExporter; Configuration public class WsConfig { Bean public ServerEndpointExporter serverEndpointExporter() { // 内嵌容器下必须注册否则 ServerEndpoint 不生效 return new ServerEndpointExporter(); } }如果部署到独立 Tomcat外置 war 包则不需要这个 BeanTomcat 自己会扫描。判断标准很简单用java -jar跑 Spring Boot 就是内嵌需要丢 war 到 Tomcat 的webapps就是外置不需要。搞反了要么端点不注册要么重复注册报错。Tomcat 侧还有几个连接相关参数值得关注在server.xml的Connector上Connector port8080 protocolHTTP/1.1 connectionTimeout20000 maxThreads200 redirectPort8443 /connectionTimeout对普通 HTTP 请求生效WebSocket 升级后走的是另一套超时逻辑但握手阶段仍受它影响。如果握手请求本身很慢先看这个值是不是太小。3.3 验证 Tomcat 端点是否真的注册成功部署完别急着连前端先用命令行确认端点活着。启动应用后用前面那条curl命令打本地端口curl -i -N \ -H Connection: Upgrade \ -H Upgrade: websocket \ -H Sec-WebSocket-Version: 13 \ -H Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ \ http://127.0.0.1:8080/ws返回101说明 Tomcat 侧端点正常问题在更外层Nginx、TLS、安全组。返回404说明路径不对或端点没注册回到 3.1 和 3.2 检查。返回400通常是 Upgrade 头缺失或Sec-WebSocket-Key格式不对。这一步把 Tomcat 从嫌疑名单里排除或坐实非常关键。4. Nginx 反向代理 WebSocketUpgrade 头和超时是重灾区生产环境很少让 Tomcat 直接对外前面通常挂 Nginx。Nginx 默认按普通 HTTP 处理请求不会转发 Upgrade 头结果就是握手请求到了 Nginx 就变成普通 GET后端返回 200 或 400前端报连接失败。这一章把 Nginx 配置讲全包括 Upgrade 头、超时、以及和 TLS 的配合。4.1 让 Nginx 正确转发 Upgrade 请求核心是proxy_set_header把Upgrade和Connection透传给后端并用map指令处理Connection的值避免硬编码。# 在 http 块中定义 map根据 Upgrade 头动态设置 Connection map $http_upgrade $connection_upgrade { default upgrade; close; } server { listen 443 ssl; server_name your-domain.com; location /ws { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; # WebSocket 必须用 1.1 proxy_set_header Upgrade $http_upgrade; # 透传 Upgrade proxy_set_header Connection $connection_upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 3600s; # 长连接读超时见 4.2 proxy_send_timeout 3600s; } }proxy_http_version 1.1是硬性要求HTTP/1.0 不支持 Upgrade。Connection用map动态设置是因为普通请求和 Upgrade 请求需要不同的值写死upgrade会让普通请求也带上可能引发其他问题。proxy_read_timeout默认 60 秒意味着连接空闲 60 秒就被 Nginx 掐断这是“连上后一分钟就断”的元凶。4.2 超时参数和心跳机制必须配套Nginx 的proxy_read_timeout和前端/后端的心跳机制要一起设计。如果心跳间隔 30 秒而proxy_read_timeout是 60 秒理论上安全但如果网络抖动导致一次心跳丢失就可能被掐。稳妥做法是心跳间隔明显小于超时时间比如心跳 25 秒、超时 300 秒以上。前端心跳实现// 每 25 秒发一次 ping服务端回 pong let ws new WebSocket(wss://your-domain.com/ws); let heartbeatTimer null; ws.onopen () { heartbeatTimer setInterval(() { if (ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify({ type: ping })); } }, 25000); }; ws.onclose () { clearInterval(heartbeatTimer); // 断线重连逻辑注意加退避别疯狂重连 };服务端收到ping回pong同时可以借心跳更新“最后活跃时间”用于服务端主动清理死连接。心跳不只是防代理超时也是检测半开连接的手段——TCP 连接看起来还在实际对端已经没了只有靠心跳才能发现。4.3 TLS 证书和 wss 的常见坑用wss://时证书链不完整是最隐蔽的坑。浏览器能打开 HTTPS 页面不代表 WebSocket 握手能过——某些客户端对证书链校验更严格。用openssl检查证书链是否完整# 检查服务器返回的证书链-showcerts 打印全部 openssl s_client -connect your-domain.com:443 -servername your-domain.com -showcerts输出里如果只有一张证书没有中间 CA就是链不完整。解决办法是在 Nginx 配置里把中间证书和服务器证书按顺序拼进同一个文件ssl_certificate /etc/nginx/ssl/fullchain.pem; # 服务器证书 中间证书 ssl_certificate_key /etc/nginx/ssl/privkey.pem;fullchain.pem的顺序是服务器证书在前、中间证书在后顺序错了同样会失败。另外确认listen 443 ssl而不是listen 443少了ssl参数 TLS 根本不启用。5. 避坑与排查连接失败最常见的五类翻车前面讲的是“怎么配”这一章讲“配了还不行怎么办”。下面五条都是我在实际部署里反复遇到的按“现象 → 原因 → 解决”写遇到问题直接对照。5.1 现象本地 101线上 400原因Nginx 没有透传Upgrade和Connection头后端收到的是普通 HTTP 请求WebSocket 握手条件不满足返回 400。解决按 4.1 的配置补上proxy_http_version 1.1、proxy_set_header Upgrade、proxy_set_header Connection。改完nginx -t校验再nginx -s reload别直接重启避免配置错误导致服务全挂。5.2 现象连上后固定 60 秒断开原因Nginxproxy_read_timeout默认 60 秒连接空闲超过这个时间被代理层关闭。解决把proxy_read_timeout和proxy_send_timeout调到大于心跳间隔的值同时确认心跳真的在发。只调超时不加心跳遇到网络中断还是发现不了死连接只加心跳不调超时心跳间隔必须小于 60 秒否则照样断。5.3 现象部分用户连不上报证书错误原因证书链不完整或者服务器只配了服务器证书没配中间证书。不同客户端对链校验严格程度不同导致“有的人能连有的人不能”。解决用 4.3 的openssl命令确认链完整把中间证书拼进fullchain.pem。另外检查 TLS 版本禁用过老的 TLS 1.0/1.1但也要确认客户端支持你启用的最低版本。5.4 现象握手成功但收不到消息原因连接建立了但消息被缓冲或路由错了。常见于多实例部署时没有做会话共享消息推到了另一个实例。解决单实例先确认OnMessage和sendText逻辑正常多实例场景需要引入 Redis 发布订阅或专门的消息中间件做会话路由把 session 和实例的映射关系维护起来。这是架构层面的问题不是配置能解决的。5.5 现象日志里大量upstream prematurely closed connection原因后端在握手阶段就关闭了连接通常是端点路径不匹配、应用启动失败、或者 Tomcat 线程池被打满。解决先确认后端进程活着、端口在监听ss -lntp | grep 8080再确认路径映射一致。线程池打满的话看maxThreads和实际并发WebSocket 长连接会长期占用线程NIO 模式下虽然不占线程但连接数仍有上限需要评估容量。6. 上线前的自检清单与一个压测技巧配置改完别急着宣布搞定上线前跑一遍自检能省掉大量“上线后才发现”的尴尬。下面这份清单我每次部署都会过一遍按顺序执行任何一项不过就别往下走。检查项命令 / 方法期望结果后端端点存活curl模拟握手打本地端口返回 101Nginx 配置语法nginx -tsyntax is ok代理层握手curl打域名 443返回 101证书链完整openssl s_client -showcerts至少两张证书心跳生效观察连接存活超过超时时间不断开断线重连手动 kill 后端再启动前端自动恢复自检里最容易被忽略的是“断线重连”。很多人只测正常连接不测异常恢复结果线上后端重启一次所有客户端就永久失联了。前端重连一定要加退避别用固定 1 秒疯狂重试会把后端打垮// 指数退避重连最大 30 秒 let retry 1000; function reconnect() { setTimeout(() { ws new WebSocket(wss://your-domain.com/ws); retry Math.min(retry * 2, 30000); // 翻倍封顶 30 秒 }, retry); }最后分享一个压测技巧用websocat或自己写脚本并发建连观察在多少并发下开始出现握手失败或秒断。这个数字就是你的容量边界比任何理论估算都准。我一般会从 100 并发开始逐步加到出现失败记录下当时的连接数和服务器指标作为扩容依据。部署 WebSocket 这件事坑基本都在“连接建立”和“连接保活”这两段把 Nginx 的 Upgrade 头、超时参数、心跳机制这三样配对了八成问题就没了。剩下的两成靠日志和分层定位也能快速收敛。希望帮到你。本文还有配套的精品资源点击获取
