中转类服务对外提供 SSE 流式输出时,最容易让排查人员头疼的问题不是连接直接断开,而是断开之后重试成功,客户端却收到一串拼不回去的残缺事件流。下面这个场景在模型 API 中转站里尤其常见:客户端用事件流方式接收大模型回复,中途某个网络抖动导致中转站到上游的请求断掉,中转站自动重连,可客户端那边看到的连接却始终没断过。结果就是解析器忽然报错,或者一小段文本被莫名其妙拼到下一条消息里。
先复现一下问题现场
在流式输出场景中,客户端常通过SSE或类似机制接收连续事件。当中转站与上游服务之间的连接发生中断并自动重试后,客户端可能会收到一段不完整的事件流——例如一个事件的data字段被截断,或者两个事件的边界丢失。这种残缺流会导致客户端解析错误,甚至出现事件错位,而由于重试本身是透明的,从客户端视角看,连接并未断开,因此难以快速定位。
我一般会让现场的人先抓一下客户端收到的原始字节流。如果看到类似下面这种,基本就能确定是重试边界没有处理:
data: {"choices":[{"delta":{"content":"你好"}}]}
data: {"choices":[{"delta":{"content":",今天天"}}]}
data: {"choices":[{"delta":{"content":"气不错"}}]}
# 上游中断,重试后残留了半行
data: {"choices":[{"delta":{"content":"的!"}}]} {"choices":[{"delta":{"content":"我们出发"}}]}注意看第三行和第四行之间,最后一条事件把重试前的残余数据和重试后的新数据拼在了一起,事件边界完全丢失。这种问题靠客户端抛出的报错信息很难直接定位到根因,因为报错往往只提示 JSON 解析失败,不会告诉你这是重试导致的。
问题出在重试后的第一个事件上
导致该问题的根源在于,中转站重试上游连接之后,并未向客户端声明流的重新开始,而是直接继续转发新收到的数据。客户端仍按原有的事件边界解析,自然会将残留的半截数据与新数据拼接,形成损坏的事件。SSE规范的注释行提供了一种轻量的带外信息机制:以冒号开头的行不会被当作事件处理,却可以被客户端识别。这为标记流状态提供了可能。
排查时不要先怀疑客户端解析器写得不对,除非你能确认上游断开后中转站完全没有向客户端发送任何标识。大多数情况是中转站只做了重连,没做流状态重置。客户端拿到的数据在字节层面是连续的,但语义层面已经断了。
重试成功之后,先发一行特殊注释
解决思路是在中转站重试成功后,先发送一条特殊格式的Heartbeat注释,例如“: retry-start”,再开始转发真实事件。客户端在解析时若遇到该注释,便知当前流已重新开始,应清空缓冲区内所有未完成的数据。这样既不需要改动现有的事件格式,也不会对正常事件造成干扰,只需在客户端解析器中增加几行分支判断。
实际实现时需要注意两处:在中转站侧,当检测到上游连接中断并完成重连,必须立即输出一条Heartbeat注释,且该注释应置于任何数据之前;在客户端侧,解析器需要识别该注释并触发重置逻辑。为了避免与正常心跳混淆,建议使用带有特定标记的注释文本,并在代码中加以注释说明。测试时,可以人为断开上游连接,观察客户端收到的数据流是否符合预期。
中转站侧的逻辑参考如下,重点是注释必须写在重连成功后的第一个字节位置:
# 上游连接断开,重连成功后
retry_count += 1
if reconnect_success:
# 关键:先向客户端输出一行SSE注释,再转发数据
await client_send(": retry-start\n\n")
# 清空中转站内部缓冲中的半截数据
upstream_buffer.clear()
# 继续正常转发
async for chunk in upstream_stream():
await client_send(chunk)客户端识别这块注释时,要做两件事:清空当前未完成事件的缓冲区,以及重置事件解析状态。很多 SSE 解析库会把注释行直接忽略,所以需要确认你的解析器有没有提供“遇到注释行时执行回调”的钩子,如果没有,可能要自己包一层原始流解析。
// 客户端SSE解析,伪代码
expect: data: {json}
expect: : retry-start
client.on('line', (line) => {
if (line.startsWith(': retry-start')) {
parser.reset(); // 清空缓冲区,重新开始组装当前事件
return;
}
// 其他正常SSE解析逻辑
});验证方式很简单:在上游服务与中转站之间人为制造断连,比如重启上游服务、拔掉网线几秒再恢复,观察客户端是否还能解析出连续完整的 events。注意要看完整事件,不要只看 echo 出来的一部分文本。
三种边界情况,别指望一条注释解决所有问题
用这种方案时要留几个心眼。第一种,如果中转站不是主动重试而是由客户端重连,那么客户端本就会重新建立连接,不需要额外的标记,硬加注释反而会让客户端误判。第二种,如果中转站与上游之间是半开连接,中间无异常感知,则可能需要额外依赖上层心跳检测才能触发重连,这时需结合连接超时参数进行调整。第三种,如果客户端自身也有重连逻辑,那就要确认两端重试的判定标准是否一致,否则可能出现中转站已重置、客户端却还在按旧事件边界等数据。
我这边的做法是,在中转站日志里额外记录一条 stream_reset_at 字段,记录每次发送 retry-start 注释的时间点,与上游日志的 reconnect 时间做对齐检查。这样即使客户端没有上报,也能从日志里判断出流式会话期间发生过几次重试。
使用Heartbeat注释并非万能。如果中转站不是主动重试而是由客户端重连,那么客户端本就会重新建立连接,不需要额外的标记。此外,若中转站与上游之间是半开连接,中间无异常感知,则可能需要额外依赖上层心跳检测才能触发重连,这时需结合连接超时参数进行调整。该方案适用于中转站代理流式输出的场景,对于其他协议则未必有效。
容易忽略的两个细节
一个常见误区是认为只要在流中定期发送任意注释作为心跳就能避免残缺事件流。实际上,普通心跳注释只能维持连接活跃,无法告知客户端流的重新开始。必须在重试边界显式插入状态标记,且客户端要主动检查该标记,否则残缺问题依旧存在。另一个误区是忽略注释行的格式,比如误用“#”或“//”开头,这不会被SSE解析为注释,反而成为非法数据。
最后建议:如果你维护的是对外开放的中转 API,最好在文档里写下这条行为约定——重试后流内会出现 : retry-start 注释。这样接你服务的下游团队不用猜,你后续排查时也有个明确的语义锚点。没有这个约定之前,两端各查各的日志,可能要浪费一整天。