# WebSocket 连接稳定性：从 Codex 协同编辑的断连震荡到端到端可验证的保活体系

在某个周一清晨，一位远程办公的产品经理正通过 Codex 编辑一份关键融资材料。文档刚写到“市场壁垒”段落，光标突然冻结——页面右下角弹出微弱提示：“连接已中断，正在重试…” 三秒后恢复，但紧接着又消失。他没在意。十分钟后，另一位协作者提交了一段技术架构描述，却在产品经理本地版本中完全丢失。回滚、对比、冲突解决…宝贵的四十分钟被吞噬在无声的连接震荡里。

这不是偶发故障，而是我们反复目睹的现实切片：WebSocket 并非一条“永远在线”的管道，而是一组精密咬合、毫秒级协同、跨七层协议栈的状态契约。当 1006 Abnormal Closure 日志在控制台高频刷屏时，它不是网络抖动的叹息，而是协议语义、中间件策略与应用逻辑在亚秒级时间窗口内发生系统性失配的警报。Codex 的案例之所以典型，正因为它把这种失配推到了极限——高一致性要求、多端实时同步、长生命周期编辑会话，任何一环的松动都会被指数级放大为用户体验的崩塌。

我们不再满足于“重启 Nginx”或“调大超时值”这类经验主义响应。真正的稳定性，必须建立在可推演、可量化、可证伪的工程认知之上。本文将带你穿透日志表象，直抵协议内核：从 RFC 6455 定义的状态机如何被浏览器、代理和内核共同改写；到心跳机制为何在应用层与传输层上演着一场危险的双人舞；再到 Nginx 如何在你毫无察觉时，用缓冲区和超时参数悄悄劫持了你的 Pong 帧。这不是一份配置清单，而是一套端到端的连接健康度诊断协议——它能告诉你，为什么 3600 秒不是随意选的数字，为什么 proxy_buffering off 是尊严底线，以及当 onclose 事件携带 1001 码时，那串 "heartbeat failed" 字符背后，究竟藏着 SDK 架构里怎样一个不可配置的硬伤。

协议状态机：被遗忘的确定性基石

当你在浏览器中执行 new WebSocket('wss://...')，你启动的远不止一次 TCP 握手。你激活的是一个由 RFC 6455 严格定义的有限状态机（FSM），它的每一个跃迁都承载着明确的语义承诺。理解这个状态机，是所有稳定性的起点——因为任何“断连”，本质上都是对某个状态跃迁规则的违反。

三个阶段，两种心跳，一场关于“活性”的精密博弈

RFC 将 WebSocket 生命周期划分为三个逻辑阶段：Upgrade 握手、数据传输、关闭握手。但关键在于，这三个阶段并非线性流水线，而是存在状态回退与并行响应能力的动态系统。

• 握手阶段的核心是 HTTP Upgrade 机制。客户端发送 GET /ws HTTP/1.1，携带 Connection: Upgrade 和 Upgrade: websocket 头，并附上一次性挑战值 Sec-WebSocket-Key。服务端验证后返回 HTTP/1.1 101 Switching Protocols 及 Sec-WebSocket-Accept。这里有一个常被忽视的事实：TCP 连接在三次握手完成时就已经建立，Upgrade 仅是对已有 TCP 流的语义重解释。这意味着，如果 Upgrade 成功但后续长时间无数据交互，连接仍处于“已协商但未激活”状态。此时，防火墙或负载均衡器可能因空闲超时直接切断底层 TCP 连接，而双方均浑然不觉——它们的 WebSocket 状态机还稳稳停在 OPEN，仿佛一切如常。
• 数据传输阶段以二进制/文本帧为主，但协议强制要求支持三种控制帧：Ping（0x09）、Pong（0x0A）和 Close（0x08）。Ping 帧用于探测对端活性，而 Pong 帧是唯一必须立即响应的帧类型（RFC 6455 §5.5.3），且必须原样回传 Ping 的应用数据。这构成了第一道心跳防线——应用层心跳。它的价值在于语义明确、可控性强、可编程。Ping 由客户端主动发起，Pong 由服务端严格按 RFC 回应，整个过程完全运行在应用层，不受 TCP 拥塞控制影响。
• 关闭握手阶段的严谨性常被低估。Close 帧必须包含状态码（2 字节）和可选原因短语。常见状态码如 1000（正常关闭）、1001（端点因离开而关闭）、1006（异常关闭）具有明确业务含义。当一方发送 Close 后未收到响应即关闭 TCP，另一方将收到 1006 错误。这并非协议错误，而是状态机因 TCP 层异常中断而无法完成约定跃迁。

stateDiagram-v2 [*] --> CONNECTING CONNECTING --> OPEN: HTTP 101 received CONNECTING --> FAILED: HTTP non-101 or timeout OPEN --> CLOSING: Close frame sent OPEN --> CLOSED: TCP FIN received before Close frame CLOSING --> CLOSE_WAIT: Close frame received CLOSE_WAIT --> CLOSED: Close frame sent & ACKed CLOSED --> [*] FAILED --> [*] note right of CONNECTING Client sends Upgrade request. Timeout = 30s (browser default) end note note right of OPEN Data frames and Ping/Pong allowed. No timeout defined by RFC — relies on application layer. end note note right of CLOSING Must respond to Ping with Pong. Must not send data frames. Max 30s for Close handshake. end note 

这张状态图揭示了一个残酷真相：OPEN 状态本身不提供保活保证。它像一个静止的舞台，等待着 Ping、Pong 或 Close 来驱动故事发展。一旦在 OPEN 状态下发生 TCP 层静默丢包（如中间路由器缓存溢出），状态机就会卡死在那里，直到应用层心跳超时或 TCP keepalive 触发 RST。如果你的重连逻辑只监听 onclose 事件，而没有结合 onerror 和 onmessage 消息间隔进行监控，那么这种“假活”连接将永远游离在你的可观测范围之外。

跨层超时：一场不容妥协的数学对齐

RFC 6455 对状态跃迁施加了严格的时序约束，这些约束是互操作性的强制要求，而非建议。其中最关键的是关闭握手超时（30 秒）与心跳响应窗口（由 ping_interval 和 pong_timeout 共同决定）。

以 Codex SDK 默认配置为例：

// @codex-team/codex-websocket v2.3.7 src/client.ts const DEFAULT_CONFIG = { pingInterval: 25000, // 每25秒发送一次Ping pongTimeout: 10000, // 等待Pong响应的超时时间为10秒 maxReconnectAttempts: 10, reconnectDelay: 1000 }; 

此处 ping_interval=25000ms 与 pong_timeout=10000ms 构成一个 35 秒的活性探测周期：若连续两个 Ping 均未收到 Pong（即 25s + 10s + 25s = 60s 内无有效响应），则判定连接死亡。这个周期必须与所有中间层超时参数形成数学对齐，否则必然出现“假死”或“假活”。

这张表格揭示了跨层参数协同的本质：上层超时必须严格大于下层超时。例如，pong_timeout (10s) < proxy_read_timeout (3600s) 是安全的，但 ping_interval (25s) > upstream-keepalive-timeout (60s) 则构成风险——因为 Ingress 可能在两次 Ping 之间关闭了与后端的连接，导致第 2 个 Ping 直接失败。Codex 生产环境经压测验证，upstream-keepalive-timeout 至少需设为 ping_interval * 3 = 75s，才能覆盖 99.9% 的网络抖动场景。

这种对齐不是工程优化，而是协议合规的数学必然。当你在配置文件里写下 proxy_read_timeout 3600，你签署的是一份与 RFC 6455 的契约：我承诺，在 3600 秒内，绝不因上游沉默而单方面撕毁连接。任何小于这个值的配置，都是对协议精神的背叛，其代价就是用户眼中那一次次“莫名其妙”的重连。

心跳的双重面孔：应用层与传输层的脆弱共生

WebSocket 的心跳绝非单一机制，而是应用层与传输层两套独立但目标一致的保活体系。将二者混为一谈，是绝大多数连接不稳定问题的根源。它们在设计哲学、作用范围、失效模式上存在根本差异，而它们的协同失效，则构成了现代 Web 实时通信中最隐蔽、最顽固的故障模式。

应用层心跳：语义精确，却不堪一击

应用层心跳是 WebSocket 协议内生的保活机制，其核心价值在于