SSE Last-Event-ID Reconnection Protocol: Implementation Details

在构建实时流式应用时，Server-Sent Events（SSE）提供了一种轻量级的服务端推送方案。然而，网络中断、页面刷新或服务端重启都会导致连接中断，进而丢失未接收的响应数据。SSE 规范中定义的 Last-Event-ID 机制正是为了解决这一问题，通过在重连时携带上次接收事件的标识符，使服务端能够从断点处恢复流式传输，避免重复推送或数据遗漏。本文将从协议层面的 HTTP Header 交互入手，详细阐述服务端恢复点查询的实现逻辑与客户端状态同步的最佳实践。

Last-Event-ID 协议机制解析

SSE 规范明确定义了 Last-Event-ID 请求头的行为：当客户端与服务器的连接中断后，浏览器会在下次重连时自动在请求头中携带 Last-Event-ID，其值为上次成功接收的最后一个事件的 id 字段。服务端接收到此请求后，应从该事件标识符之后开始发送后续事件，而非从头开始推送整个流。这一机制的核心前提是每个事件都必须拥有唯一的标识符，且服务端具备根据标识符查询并恢复事件流的能力。

从协议交互的角度来看，完整的断线续传流程涉及以下几个关键步骤。首先，服务端在发送每个事件时需要在事件数据中包含 id 字段，例如使用 id: 12345 的格式标注事件序号。其次，客户端的 EventSource API 会自动维护最近接收事件的标识符，当检测到连接断开并触发重连时，会在请求头中附加 Last-Event-ID: 12345。最后，服务端解析该请求头，根据其值从数据库或内存缓存中查询对应的恢复点，然后从下一条记录开始继续推送事件。

值得注意的是，Last-Event-ID 的值在某些边缘情况下可能为空或不可用。例如，当服务器重启导致内存中的事件序列丢失时，客户端虽然会发送 Last-Event-ID，但服务端可能无法找到对应的恢复点，此时通常会返回错误或重新从头开始推送。另一种情况是如果上一个事件的 id 字段为空，浏览器可能不会在重连请求中携带 Last-Event-ID 头。因此，设计可靠的事件流系统时，需要确保每个事件都包含连续的、递增的标识符，并建立持久化存储机制以支持跨服务端实例的恢复查询。

HTTP Header 字段设计

在实现 Last-Event-ID 协议时，HTTP Header 的设计需要关注两个核心字段：响应端的事件标识符字段与请求端的恢复标识符字段。

服务端推送的事件格式遵循 SSE 规范，每个事件行由字段名、冒号和值组成，其中 id 字段用于标注事件序号。典型的服务端响应格式如下所示：

id: 1001
data: {"type": "text-delta", "value": "Hello"}

id: 1002
data: {"type": "text-delta", "value": " World"}

id: 1003
data: {"type": "finish-message", "value": {"finishReason": "stop"}}

客户端在重连时，浏览器会自动在 HTTP 请求头中添加 Last-Event-ID 字段，其值即为最近接收事件的 id。在服务端代码中，可以通过解析请求头获取该值，例如在 Python Flask 中使用 request.headers.get('Last-Event-ID')，在 Node.js Express 中使用 req.headers['last-event-id']。需要注意的是 HTTP Header 字段名通常不区分大小写，但 SSE 规范使用的是 kebab-case 格式的 Last-Event-ID。

此外，为了支持更复杂的恢复场景，可以在响应头中额外携带自定义元数据。例如，X-Event-Sequence 可用于标注当前事件的序列号，X-Stream-Complete 可用于标识整个流是否已结束。这些自定义头字段能够帮助客户端在重连时快速判断是否需要继续接收，还是已经存在完整的本地副本。

服务端恢复点查询实现

服务端实现恢复点查询的关键在于设计高效的事件存储与检索机制。由于 SSE 通常运行在无状态的 HTTP 服务器上，而连接可能中断于任意时刻，因此必须将每个事件持久化存储，以确保即使服务端重启或请求被路由到不同服务器实例，也能正确恢复流。

一种常见的实现方案是使用数据库或分布式缓存作为事件存储。对于每个响应会话，分配一个唯一的会话标识符，并按顺序存储每个事件及其序号。服务端在接收重连请求时，首先从请求头或查询参数中提取会话标识符与 Last-Event-ID，然后在数据库中执行类似 SELECT * FROM events WHERE session_id = ? AND event_id > ? ORDER BY event_id ASC 的查询，获取从断点之后的所有事件并依次推送。

这种方案的优势在于能够支持水平扩展的多服务器架构，任一服务器实例都能根据 Last-Event-ID 恢复流，而不必依赖初始连接的服务器实例。然而，其代价是每个事件都需要实时写入数据库，这会引入显著的写放大问题。以大语言模型的流式响应为例，一个包含数百个 token 的响应可能产生数百条事件记录，如果每次都同步写入数据库，将大幅增加延迟并消耗数据库 I/O 资源。

针对这一问题，可以考虑以下几种优化策略。第一，使用内存缓存（如 Redis）存储最近的事件序列，数据库仅用于持久化备份，查询时优先从缓存获取，缓存未命中时再查询数据库。第二，采用批量写入机制，将多个事件合并为单次数据库写入操作，但需要权衡恢复可靠性 —— 如果批量写入尚未完成时发生中断，部分事件可能无法被正确恢复。第三，在流结束时不存储逐条事件，而是仅存储完整的响应内容，这样成功完成的流不需要额外交互，仅失败的流才需要从数据库恢复部分事件。

客户端重连状态同步

客户端在实现重连状态同步时，需要维护两个核心状态：最近接收事件的标识符，以及当前会话的连接状态。当 EventSource 检测到连接断开并触发自动重连时，它会自动将 Last-Event-ID 附加到新的请求中。开发者可以通过监听 message 事件获取每个事件的数据，并在回调中更新本地存储的最近事件 ID。

对于更复杂的多设备同步场景，客户端需要处理额外的状态协调问题。例如，用户在手机上的会话中断后，希望在平板电脑上继续接收相同的流式响应。这种情况下，客户端不仅需要在重连时传递 Last-Event-ID，还需要从服务器获取当前会话的完整历史记录，包括已经完成的事件与正在传输中的事件。

一种推荐的实现模式是客户端在建立 SSE 连接时，首先检查本地是否存在未完成的会话。如果存在，则在请求头中携带 Last-Event-ID 并同时在请求体或查询参数中指定会话 ID。服务端在处理这类请求时，会同时返回两个部分：首先是从 Last-Event-ID 之后的事件流，其次是会话的当前状态信息（如是否已取消、是否已完成等）。客户端在接收到这些数据后，优先渲染本地已有的内容，然后逐步追加从服务器获取的新事件。

此外，客户端还需要处理超时与重试策略。SSE 的默认重连间隔由服务端的 retry 字段指定，但如果服务端未设置，浏览器通常会使用默认的重试逻辑。在实际应用中，建议将重试间隔设置为 2 至 5 秒之间，既能保证快速恢复，又不会对服务器造成过大的瞬时压力。对于需要更快恢复的场景，可以在客户端实现指数退避重连策略，初始间隔设为 1 秒，随后每次失败翻倍，直至达到上限。

工程实践参数与监控要点

在实际生产环境中部署 Last-Event-ID 断线续传机制时，以下参数与监控指标值得重点关注。

事件标识符的设计应采用单调递增的整数或时间戳组合，以确保全局唯一性与顺序性。推荐使用 64 位整数作为事件 ID，避免使用字符串或随机 ID 造成排序困难。同时，事件 ID 的分配应在服务端完成，而非依赖客户端生成，以防止多客户端场景下的 ID 冲突。

事件存储的清理策略也需要谨慎设计。对于已完成或已取消的会话，其存储的事件记录应被及时清理，以释放存储空间并避免数据无限膨胀。可以考虑在会话状态变更为已完成或已取消后的 1 小时或 24 小时后执行异步清理任务。

监控方面，应重点关注以下指标：重连请求占比（重连请求数占总请求数的比例）、恢复失败率（服务端无法根据 Last-Event-ID 找到恢复点的比例）、事件推送延迟（从事件生成到客户端接收的平均时间）以及数据库写入延迟（每个事件的存储操作耗时）。这些指标能够帮助及时发现系统瓶颈并优化性能。

最后，需要为恢复失败的情况设计降级策略。当服务端无法根据 Last-Event-ID 恢复事件流时，应向客户端返回明确的错误信息或状态码，客户端可以据此决定是重新从头接收还是提示用户会话已失效。

资料来源：本文核心技术与实践细节参考了 zknill.io 上关于 SSE Token 流可恢复性的深度分析（https://zknill.io/posts/everyone-said-sse-token-streaming-was-easy/），以及 htmx 文档中 Last-Event-ID Header 的规范说明（https://four.htmx.org/reference/headers/Last-Event-ID）。

web