Toonflow 流式输出 SSE 断连后怎么自动续传?Last-Event-ID、心跳与网关超时分别该怎么设置
Toonflow 的 SSE 断连恢复依赖三件事同时成立:客户端保存 lastEventId 并在重连时带上 Last-Event-ID,服务端按任务保留事件缓冲并从该序号续发,网关关闭响应缓冲并放大空闲读超时。如果服务端不保存事件、只做一次性推送,任何参数调整都只能重跑任务,无法真正续传。
Toonflow 流式输出的 SSE 断连恢复,本质是三件事同时成立:客户端保留 lastEventId 并在重连时带上 Last-Event-ID,服务端为每个生成任务保留可回放的事件缓冲,中间网关关闭缓冲并把空闲读超时放大到分钟级;缺任意一环,重连要么从头发一遍、要么直接拿到空响应。这套设置只对“文本增量、分镜描述”这类可编号的下行事件有效,对一次性返回整段结果、且服务端没有任何事件存储的接口不适用。
先分清断连发生在客户端、网关还是任务侧,再谈设置,否则调参只是碰运气。浏览器 Network 面板里找到 eventstream 那条请求,看它是被主动断开还是长时间无数据后被掐断,同时看记录的 lastEventId 停在哪个序号;服务端侧对照访问日志里的 499、504 与任务状态,如果任务仍在正常生成,说明断的只是传输通道,续传有意义,任务已结束或被取消则只能重跑。
浏览器原生 EventSource 默认就会自动重连,前提是没有在 onerror 里手动 close。服务端可以在事件流开头先下发一行 retry 指定重连间隔,客户端不要吞掉 error 回调,而是记录当前 lastEventId 并让浏览器按间隔重试;如果用的是 fetch 加 ReadableStream 的自定义解析方案,自动重连这层要自己实现,重连请求必须显式带上 Last-Event-ID 请求头,并把已有的文本片段留在内存或本地存储里。
服务端是续传能否成立的关键:每条事件都要带单调递增的 id,缓冲区按 task_id 保存最近一批事件,收到带 Last-Event-ID 的重连请求时,从该序号之后继续发送,而不是重新生成。缓冲区要有明确窗口,超出窗口的旧任务改为返回一次任务快照再追加增量,否则内存会被长任务撑爆;生成内容本身建议落库,缓冲区只是加速层,进程重启后仍能按序号对齐。
心跳是让断连“早被发现”的手段,不是可选项。在事件流里每隔十几秒发送一行冒号开头的注释,既能让客户端确认连接存活,也能避免连接被中间层当成空闲连接回收;心跳不占用事件序号,重连时不会造成重复内容,比发送空 data 更安全。
反向代理和 CDN 是 SSE 最常见的断点。Nginx 侧要显式关闭 proxy_buffering 与 proxy_cache,把 proxy_read_timeout 提到远超单次生成时长的值,并回写 X-Accel-Buffering: no 让上游头生效;使用 HTTP/2 或 CDN 时,要确认该路径没有被整段缓存或强制压缩合并,否则事件会被攒够一批才吐出来,表现为“能连上但半天不出字”。
续传语义要做到至少一次投递、客户端幂等拼接。服务端重连时可能把最后一条事件再发一遍,客户端应按事件 id 或自增序号去重,重复片段直接丢弃,保证拼接后的文本不出现重字;反过来,客户端也不要在重连成功后清空已收到的内容,否则一次闪断就会把前面几百字吞掉。
长连接跨越鉴权有效期会让续传在第一步就失败。生成任务跑得久时,access token 可能在流未结束前过期,重连请求直接返回 401,看起来像“续传不生效”;做法是在重连前先刷新凭证,把刷新失败与网络断连分开处理,并保留 Last-Event-ID 不丢,刷新成功后用同一序号再发起恢复请求。
移动端和后台标签页不要指望浏览器自动重连。页面切到后台后连接常被系统冻结或静默断开,更稳妥的做法是在 visibilitychange 时主动断开、记录 lastEventId 与 task_id,回到前台再调用恢复接口;这样既省流量,也避免半开连接长时间挂着占用并发配额。
恢复链路要有降级方案:SSE 续传连续失败若干次后,改为轮询任务状态接口,按 task_id 与已收到的最大序号拉取增量。轮询的返回结构最好与事件流共用同一套序号语义,客户端拼接逻辑不用改两遍;这是兜底,不是主路径,轮询间隔过密反而会拖慢生成侧。
验证这类设置不能只看“能不能连上”,要人为注入断连。可在生成中途断网数秒、切后台、重启代理进程,观察三项指标:重连后是否能从断点继续、重复事件比例是否为零、首字延迟是否明显变长;把断连点放在任务开始、中途、收尾三个阶段各测一次,才能确认缓冲窗口和超时值选得合理。
最后要明确边界:如果 Toonflow 的流式接口在服务端不保存事件、也没有任务级序号,那么所谓“断连恢复”只能做客户端重试,重试即重新生成,已输出的内容无法复用。要真正实现断点续传,前提是接口侧提供事件 id、可回放缓冲和按 task_id 恢复的入口,具体字段名与开关位置以官方说明为准,配置前先确认这三项是否存在,再决定把精力花在客户端还是网关。