WebSocket连接被服务端关闭？Nginx代理超时与心跳机制全解析

2026年1月26号晚上，我正在工位上收拾东西准备下班，监控群里突然弹出一条告警：实时看板的数据不刷新了。紧接着有同事甩来一张前端控制台的截图，刺眼的红色报错写着“stream disconnected before completion: websocket closed by server before res”。这个项目上线大半年，WebSocket连接一直很稳定，之前从来没出过这种问题。我当时第一反应是服务端挂了或者连接数被打满，可登录服务器一看，进程活着、端口正常监听、日志里也没有任何异常退出，这就有点意思了。

后来我花了好几个小时，从浏览器、客户端工具、Nginx代理、业务代码一路排查过去，最后发现“凶手”确实是WebSocket，但祸根藏在一层平时根本不会留意的代理超时配置里。今天把这次完整的排查过程写出来，希望能帮到正在被WebSocket连接问题折磨的朋友。如果你在实现实时推送、在线状态、消息通知这类功能时，也遇到连接偶尔断开、过一会儿又自己恢复的怪问题，这篇文章基本可以当一份排查手册来用。

1. 问题现场：现象与最初的怀疑

1.1 现象记录：报错信息与业务影响

先说清楚当时的现象。前端的实时看板页原本应该每隔十几秒就收到服务端推送的数据，可报错之后页面上的数字全部冻结了，要手动刷新一次才能恢复一小会儿，过几十秒又断掉。控制台里反复出现那句“stream disconnected before completion: websocket closed by server before res”，这句话拆开看意思很明确：客户端这边有一个流式请求还没有读到完整结果，连接就被对端关闭了。

需要说明的是，这个报错本身并不一定来自浏览器原生的WebSocket API，很多框架在底层封装了长连接或订阅功能（比如GraphQL的subscription、SSE、各种实时消息SDK），它们会在连接异常断开后抛出类似的提示。关键信息其实是后半句“websocket closed by server before res”——连接是被服务端关闭的，而且是在客户端等响应的时候。这直接帮我缩小了排查范围：不是客户端代码主动断的，也不是网络彻底断掉，而是服务端那边“主动”把连接掐了。

业务影响也远比一个看板要广，这个项目里所有依赖WebSocket的功能都受到了牵连：实时告警推送停了、在线用户状态全部显示异常、还有一个内部报表的自动刷新也失效了。虽然核心业务接口还是能通过HTTP正常访问，但只要是走长连接的数据，基本全军覆没。这种“部分功能挂掉、进程还在运行”的状态，最让人头疼。

1.2 我先排除了哪些“正常”问题

出现这种问题，大多数人第一反应是服务端挂了，我也不例外，但很快就把常规项都排除掉了：

• 服务端进程与端口：主进程还在运行，没崩，端口也一直有监听，日志里找不到panic或者fatal的痕迹。
• 数据库与缓存：数据库连接池正常，慢查询没有明显增加，Redis的读写延迟也正常。这说明不是后端资源问题拖垮了连接。
• 网络连通性：从我的电脑直接ping服务端，延迟正常，丢包率为零；用telnet测一下WebSocket对应的端口，也能正常连通。基础网络层面没有明显故障。
• 时间同步：客户端和服务器的系统时间差在1秒以内，排除了因为时间偏差导致TLS或认证失败的可能。
• 最近是否有发版：我特意去问了运维同学，最近一次发版是大概一周前，当天没有发布记录。所以基本可以排除“新代码引入回归bug”这个原因。

这些常规项排完之后，问题更蹊跷了。服务端看着一切正常，但客户端就是连接不稳定，而且不是所有人都受影响，有些人的页面已经恢复正常，有些人的还是一直在断。这种“玄学”现象通常意味着问题出在链路中间层或者某个超时配置上，而不是一个简单粗暴的宕机。

1.3 最初怀疑的几个方向

我在把所有常规项排除掉之后，脑子里大概列了四个怀疑方向，这里也分享给大家，因为后续排查基本都是围绕这四个方向展开的：

1. 服务端连接数打满：如果服务器允许的最大WebSocket连接数已经到了上限，新的连接进不来，旧连接也可能被强制踢掉。但看了监控，当前连接数才占总配额的三成左右，这个方向基本排除。
2. 客户端网络环境差异：有些同事在公司内网访问，有些在外网，防火墙或者代理策略不一样，长连接本来就被很多安全设备盯得很紧，容易误杀。
3. 浏览器版本问题：有同事提到“谷歌浏览器高版本无法启用WebSocket”这个说法，说实话当时我愣了一下，后来仔细想了想，高版本浏览器确实有一些更严格的安全策略会影响WebSocket连接，并不是完全“无法启用”，这个需要重点排查。
4. 中间代理层配置异常：我们服务端前面挂了一层Nginx做反向代理，WebSocket这种长连接对代理层的超时设置非常敏感，如果相关参数不对，就会出现连接自动断开的问题。当时这个方向被我排在了后面，毕竟这套配置上线半年都没动过，谁能想到它才是“幕后黑手”。

现在回头看，这个怀疑顺序基本合理，但唯一的失误就是太相信“配置没动过就不会出问题”这个错觉。很多线上事故恰恰是长期潜伏的配置在某个特定条件的触发下才爆发的。

2. 一步步排查：从浏览器到协议

2.1 先看握手机制：状态码101与响应头

排查WebSocket问题，第一步永远是确认握手是否成功。WebSocket本质上是基于HTTP的协议升级：客户端发一个带 Upgrade: websocket 的HTTP请求，服务器如果同意，就返回状态码 101 Switching Protocols，之后双方在同一个TCP连接上双向收发数据帧。如果握手这一步都失败了，后面所有行为都是白搭。

我用Chrome DevTools打开Network面板，刷新页面，过滤出那个 ws://... 的请求，点开详细内容看了下。状态码是101，响应头里的 Connection: Upgrade 和 Sec-WebSocket-Accept 都在，说明握手本身是成功的。但同时我也注意到响应头里有一个 Via 字段，这证实了连接确实经过了Nginx代理层转发。

这里要提醒大家一个小技巧：如果状态码不是101，而是200或者4xx，那就要警惕了。很多缓存代理和中网防火墙不支持HTTP协议升级，会把 Upgrade: websocket 头直接吞掉，然后当成普通HTTP请求转发给后端，后端返回一个普通的200响应，这时候浏览器端会报 Unexpected response code: 200。我们这次没有这个问题，握手是成功的，所以问题只能出在握手之后的长连接维持阶段。

2.2 用 websocket king 复现连接

确认握手正常之后，我的下一个动作是排除前端业务代码的干扰。浏览器里的WebSocket如果被业务代码里某些异常逻辑提前关闭，表现可能和“连接被服务端断开”非常像，肉眼很难分清楚。所以我想用一个独立的调试工具直连服务端，看看服务端本身到底能不能稳定维持这个连接。

我用的工具叫 websocket king，它是一个很轻量的WebSocket调试客户端，有点像Postman之于HTTP接口的关系，可以填写连接地址、自定义请求头，也能直接发消息、收消息、查看连接状态。我拿它填入生产环境的 ws://服务端地址/推送路径，点连接，很快就返回成功了。然后我让它挂在那里，每隔一段时间手动发一条消息，观察了将近十分钟，连接一直非常稳定，收发消息都正常，没有任何断开迹象。

这个结果非常关键，说明两件事：第一，服务端业务逻辑本身没有主动去关闭WebSocket；第二，从“websocket king客户端”到“服务端”这条链路没有明显问题。那问题就缩小到了“浏览器页面”这个具体场景，或者“浏览器 → Nginx → 服务端”这条链路上的某个环节，和“websocket king → 服务端”这条链路不一样的地方。

2.3 排查谷歌浏览器高版本的限制

既然工具直连没问题，我又回到浏览器环境继续看。用本机Chrome打开那个看板页面，观察连接状态，结果发现一个非常有规律的异常：连接建立后大约60秒左右，WebSocket就会被断开，然后前端代码触发重连，重连成功后又过60秒再次断开，循环往复。

这时候我想起同事提到的“谷歌浏览器高版本无法启用WebSocket”，于是查了一下浏览器版本，确实是比较新的大版本。但经过反复测试和查阅资料，我确认高版本Chrome并不会“禁用”WebSocket，只是对使用环境有严格限制，容易造成“连不上”的假象：

• 混合内容拦截：如果页面是通过 https:// 打开的，而WebSocket地址是 ws:// 而不是 wss://，浏览器会直接拦截，控制台报 Mixed Content。这是最常见的“连不上”原因，但我们这次的页面就是 https:// + wss://，不存在这个问题。
• 单域名连接数限制：一个域名下的WebSocket并发连接数是有限的，通常是6个左右。如果页面里开了多个标签页，或者同一个页面里初始化了多个WebSocket实例，可能互相挤占连接名额，导致新连接一直处于pending状态。
• 标签页后台节流：浏览器为了省电，会把后台标签页的定时器和网络活动降频甚至冻结。如果页面切到后台，WebSocket可能进入挂起状态，消息堆积，等回到前台再一次性推送。这种体验上很像“连接断了”，但实际连接还在。

我逐一排查后，发现页面协议没问题，连接数也没有超，标签页一直保持在前台。浏览器本身的限制基本排除。但那个“60秒准时断开”的规律太扎眼了，任何超时逻辑都逃不开“固定周期”这个特征，我基本上可以把怀疑对象锁定到超时配置上去了。

2.4 服务端日志：断开时机是关键

既然怀疑方向集中到了超时配置，我就去翻了Nginx的日志。这里有个经验：WebSocket被断开时，业务后端日志里往往没有任何记录，因为后端根本不认为自己断了；真正能反映问题的是代理层的access log和error log。

打开Nginx的error log，我看到了类似这样的记录：

txt复制[error] 12345#0: *6789 upstream prematurely closed connection while reading upstream

这种“upstream prematurely closed connection”就是代理层在往上游服务读取数据时，发现上游连接被提前关闭的记录。配合access log里的时间戳，我看到了近乎完美的规律：每个WebSocket连接都在建立后约60秒左右被关闭。

我自己后端用的框架设置了空闲超时吗？我翻遍了代码确认没有这个逻辑。那就只剩一种可能：Nginx在转发WebSocket时默认套用了HTTP请求的超时时间，也就是 proxy_read_timeout，它的默认值恰恰就是60秒。这个时间点一出来，答案基本就在眼前了。

3. 根因定位与修复方案

3.1 真正的根因：代理/网关的空闲超时

确认根因之前，先看我们Nginx里关于WebSocket转发的配置长什么样，给大家一个直观的对比：

nginx复制location /ws/ {
    proxy_pass http://websocket_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 60s;
    proxy_send_timeout 60s;
}

很多人写WebSocket代理配置的时候，都会正确加上 proxy_set_header Upgrade 和 Connection "upgrade"，却忽略了后面两行超时参数。proxy_read_timeout 60s 的意思是：如果Nginx在60秒内没有从上游服务读到任何数据，它就会认为这个连接已经无用了，于是主动把它关闭。

这就有意思了。WebSocket是长连接，但并不意味着每一秒都在传数据。如果客户端和服务端之间没有持续的消息交互，中间也没有心跳，那么在Nginx这个“中间人”眼里，这个连接就是“60秒没有任何动静”的僵尸连接，会被无情清理掉。用大白话讲，这就像小区门卫规定“60秒没看到业主进出，就以为屋里没人，直接把门锁了”，可业主只是安安静静坐在家里看电视，并不是消失了。

那为什么之前一直没有暴露这个问题？因为过去业务数据非常频繁，每隔十几秒就会有一次推送，Nginx每次都能看到上下游之间有数据流动，所以连接永远不会触发超时。而就在出问题的那段时间，上游某个业务模块的推送频率刚好降下来了，连续空闲超过了60秒，连接就被掐断了。这也解释了为什么websocket king直连服务端不会断——它绕过了Nginx这一层，中间没有那个“60秒锁门”的门卫。

这个案例非常有代表性，类似的超时问题在Nginx、HAProxy、云厂商的负载均衡SLB、API网关上都非常普遍，只是默认超时时长不同。有的云负载均衡默认空闲超时是60秒，有的是300秒，总有一个值会来当“定时炸弹”。

3.2 代码层面修复：心跳机制与断线重连

定位到根因之后，修复方案其实有两步，我建议两个动作一起做，而不是只改其中一个。

第一步，把Nginx的 proxy_read_timeout 调大，比如从60秒改成300秒甚至600秒。这一步能缓解“空闲被断开”的问题，但不解决根本隐患，因为只要空闲时间足够长，任何超时时间都会再次被触发。所以我更推荐第二步。

第二步，给客户端和服务端之间增加心跳机制。心跳的本质就是让双方定期互发一个很小的数据包，告诉代理层和链路中的所有中间设备：“我还活着，别关我。”设计心跳时有几个关键参数要注意：

• 心跳间隔：一定要小于代理超时时间的一半。如果代理超时是60秒，心跳至少30秒发一次；如果改成600秒，为了保险我建议心跳还是保持在30到60秒之间，因为链路中间可能还有其他网元，超时时间不可控。
• 消息格式：可以用WebSocket协议自带的Ping/Pong帧，也可以直接在业务层传一个 {"type":"ping"} 的文本消息。考虑到很多Browser客户端和中间代理对协议级Ping/Pong的支持并不完全统一，我习惯用业务消息做心跳，这样排查起来也更直观。
• 服务端配合：服务端收到心跳后必须回一个pong，同时清掉自己的空闲计时器。如果服务端有一层业务级的空闲超时判断，也要记得在心跳到来时重置。

这里放一个我当时写的纯前端心跳加断线重连的示例，比较简洁，可以直接抄：

javascript复制function connectWebSocket(url, { heartbeatInterval = 30000, baseDelay = 2000, maxDelay = 30000 } = {}) {
  let ws = null;
  let heartbeatTimer = null;
  let retryCount = 0;

  function startHeartbeat() {
    if (heartbeatTimer) clearInterval(heartbeatTimer);
    heartbeatTimer = setInterval(() => {
      if (ws && ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({ type: 'ping', ts: Date.now() }));
      }
    }, heartbeatInterval);
  }

  function scheduleReconnect() {
    const delay = Math.min(baseDelay * Math.pow(2, retryCount), maxDelay);
    retryCount += 1;
    setTimeout(() => {
      console.log(`reconnecting in ${delay}ms`);
      connect();
    }, delay);
  }

  function connect() {
    ws = new WebSocket(url);

    ws.onopen = () => {
      console.log('ws connected');
      retryCount = 0;
      startHeartbeat();
    };

    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      if (data.type === 'pong') {
        // 心跳响应，可以在此记录最近存活时间
        return;
      }
      handleBusinessMessage(data);
    };

    ws.onclose = (event) => {
      clearInterval(heartbeatTimer);
      console.warn('ws closed', event.code, event.reason);
      scheduleReconnect();
    };

    ws.onerror = (err) => {
      console.warn('ws error', err);
    };
  }

  connect();
}

有几个细节要注意：baseDelay 和 maxDelay 做指数退避，重连次数越多等待时间越长，防止在服务端异常时造成连接风暴。retryCount 在连接成功时要清零，这样下次抖断后会重新从短延迟开始。另外，心跳pong消息要跟业务消息区分开，别把业务数据当成心跳处理，别把心跳消息丢给业务逻辑。

3.3 针对WPF等客户端场景的补充处理

搜索关键词里出现了“websocket连接 wpf”，这让我想起这个问题的另一面：桌面客户端里的WebSocket连接，踩坑方式和浏览器还不太一样。我们内部有个WPF版的管理工具，也曾经遇到过WebSocket相关的诡异问题，这里顺带整理几个高频坑。

先说一下最常见的问题：如果用C#的 System.Net.WebSockets.ClientWebSocket 写客户端，收到消息的回调通常不是在UI线程上执行的，如果直接在这个回调里更新界面控件，就会抛 InvalidOperationException。解决办法是借助 Dispatcher 切回UI线程：

csharp复制private async Task ReceiveLoopAsync(ClientWebSocket ws, CancellationToken ct)
{
    var buffer = new byte[4096];
    while (ws.State == WebSocketState.Open && !ct.IsCancellationRequested)
    {
        var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), ct);
        if (result.MessageType == WebSocketMessageType.Close)
        {
            await ws.CloseAsync(WebSocketCloseStatus.NormalClosure, "bye", ct);
            break;
        }

        var message = Encoding.UTF8.GetString(buffer, 0, result.Count);
        Application.Current.Dispatcher.Invoke(() =>
        {
            // 在这里安全更新UI控件
        });
    }
}

第二个高频坑是TLS版本。老版本.NET Framework默认可能走TLS1.0或者TLS1.1，而现在的主流服务端往往会禁用这两个旧版本，导致 wss:// 连接握手失败或者意外关闭。排查时可以先用下面的代码强制指定TLS协议版本再测：

csharp复制ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 | SecurityProtocolType.Tls13;

第三个和浏览器场景类似，WPF客户端在锁屏、休眠、切换网络之后，底层TCP连接可能已经“假死”，但 ClientWebSocket.State 还是 Open，如果不去主动检测，你会一直等一个永远不会来的消息。解决办法还是心跳：定期发送心跳，连续几次没有收到pong，就主动把旧连接关掉重建。只有把“心跳 + 自动重连”这套组合拳用在所有类型的客户端上，才算真正把这个问题关进笼子里。

3.4 影响范围与服务端多实例注意事项

这次问题的影响范围刚开始看只是“看板数据不刷新”，但实际上所有依赖WebSocket的长连接功能都受了影响。这给团队提了个醒：实时推送类的故障不能只看表面接口是否通，还要把“连接维持情况”纳入监控。比如统计每分钟的连接断开次数、平均连接时长、心跳响应耗时等指标，一旦出现“连接平均存活时间接近60秒”这种特征，立刻把代理层超时配置调出来查。

另外想单独提醒一个服务端多实例部署的坑：WebSocket长连接不是无状态的，如果服务端背后挂了多个实例，又没有配置粘性会话（sticky session），客户端每次重连可能被负载均衡转发到不同的后端实例上，旧实例缓存的数据和连接状态全部对不上。即使单个实例本身没问题，多个实例之间一旦出现会话不同步，就会产生“连接总是被莫名其妙断开”的错觉。所以排查WebSocket问题时，也要把负载均衡策略、实例数量、会话保持时间这些因素一起考虑进去。

顺带一提，如果团队里有人用obs-websocket或者类似的现成WebSocket服务，配置导出和备份这件事也值得重视。obs-websocket默认监听4444端口，里面存着认证密码和一堆参数，很多人升级完或者换机器后连不上，多半就是配置丢了。我们这次修完之后，也顺手把所有WebSocket相关配置（心跳间隔、超时时间、认证token、服务地址）统一收进了配置中心，并加了注释和导出脚本，算是把这次踩坑的经验固化了下来。

4. 常见问题与排查技巧实录

4.1 WebSocket连接问题速查表

这次排查过程中，我把项目群里反馈过的各种WebSocket怪问题整理成了一张速查表，这里分享出来。它不一定覆盖所有情况，但能覆盖掉大多数日常遇到的“连接不稳定”类问题，配合前面的排障思路使用效果更好。

这个表格里的每一行，我都见过不止一次。尤其是“空闲固定时间断开”和“页面切后台恢复后消息堆积”，这两条在实际项目中几乎必踩其一。

4.2 排障工具选型：从DevTools到Wireshark

排查WebSocket问题，工具链并不复杂，但选对工具能省一半时间。我的习惯是“先浏览器、再客户端、最后抓包”，从上层到底层逐级确认。

• Chrome DevTools：这是第一站。Network面板里过滤 ws，可以看到握手请求、每一帧收发消息、close code。特别要关注close code：1000表示正常关闭，1006表示异常断开（多数是底层网络断掉或者连接被中间层重置），1008表示安全策略违反。看到1006的时候，十有八九不是应用层主动关闭的行为。
• websocket king或同类调试工具：第二站。它能帮你快速验证“服务端是否真的能稳定维持连接”，排除前端业务代码和浏览器环境的干扰。我这次就是靠它把问题锁定到了Nginx层。
• Wireshark：第三站，也是最底层的手段。如果需要确认TCP层面的RST包是谁发的、TLS握手是否正常，就必须抓包了。抓本机到服务端的流量时，过滤语法可以用 tcp.port == 443 && (websocket || http.upgrade)。如果流量是TLS加密的，还需要先设置SSLKEYLOGFILE环境变量，才能看到解密后的WebSocket帧。
• 服务端和中间件日志：这一点经常被忽略，但恰恰最容易定位。Nginx的error log里那句“upstream prematurely closed connection”直接给我指明了方向；如果没有业务日志和中间件日志光靠客户端猜，排查效率会低很多。

工具要用，但不要迷信工具。排障的本质是“确认每一层是否健康”，而不是某一种工具能一步到位解决问题。

4.3 排查长连接问题的几条经验

这次问题修完之后，我在项目周会上分享过排查WebSocket问题的几条经验，这里也一并写出来，每条都是真金白银换来的：

1. 先分清是“连不上”还是“被断开”。这两种问题的排查路径完全不同：连不上优先看端口、防火墙、代理、证书；被断开优先看超时、心跳、服务端主动关闭逻辑。别混着查，会把简单问题复杂化。
2. 客户端报错信息只是线索，不是证据。同一个“websocket closed by server before res”背后可能是Nginx超时、服务端panic、负载均衡踢连接、客户端自己触发重连，只盯着客户端日志很容易被带偏。
3. 断开时间有没有“固定规律”，是判断超时问题的最强信号。只要是接近固定周期后被断开，基本就是某个超时参数在作祟。这时候别慌着改代码，先把链路里所有中间件的超时配置逐个翻一遍。
4. 任何WebSocket连接都应该默认内置“心跳 + 自动重连”机制，别等出了问题再加。这是生产环境的基本素养，不是可选项。
5. 排查完别急着撤，把监控补上。至少要统计连接断开次数、平均连接时长、心跳成功率这三个指标，后续再有类似问题能直接看到趋势，而不是等用户投诉。

说实话，排查到根因的那一刻，我心里既松了一口气又有点惭愧。服务端进程明明健康得很，代理配置也半年没动过，但它就是会在业务频率下降的那一刻精准地咬你一口。WebSocket看起来就是一个“建立连接、发消息、收消息”的简单协议，可真到了生产环境，链路里每一层都可能成为断连的元凶。希望这篇记录能帮你在下一次遇到“可能是WebSocket引起的问题”时，少走几步弯路。