SSE 断线后如何补齐状态:Node.js 与浏览器实战

用可运行的 Node.js 服务与浏览器看板实现 SSE 重放和快照恢复,拆解游标过期、异步回调、慢连接与多实例边界,并给出自动化测试和部署验收方法。

批量导入已经处理到第八千条,网页上的数字却停在第六千条。用户切换过网络,浏览器也重新连上了服务器,看板看起来一切正常,只是断线期间的更新没有回来。这类问题很容易逃过开发环境验收:只要一直保持连接,几行 EventSource 代码就能表现得很好。

要把进度看板做完整,需要同时回答三个问题:页面第一次打开时从哪里开始,连接中断后从哪里继续,服务器已经丢掉旧事件时又该怎么办。本文实现一个可运行的 Node.js 服务与浏览器页面,把这三个分支放进同一套协议,并用测试验证边界。示例展示的是“恢复当前状态”,不承担支付、发货等业务事件必须逐笔执行的责任。

本文使用 Node.js 24 的内置模块,没有 npm 依赖;本次实际运行版本是 24.22.1。协议与 API 资料于 2026 年 11 月 7 日核对。这个选题关注长期存在的连接恢复问题,不把成熟协议包装成当天新发布的功能。

先确定快照和事件之间的关系

我们的任务看板只有一个字段 completed,表示当前进程累计处理的条数。服务每秒增加一次,网页通过 SSE 接收更新。为了让示例容易复现,数据和最近十条事件都放在内存里,服务只监听本机地址。

每份快照返回 epoch、seq、completed。epoch 是服务实例启动时生成的随机标识,seq 是这一实例内递增的事件序号。每条事件的 ID 则写成“epoch:seq”。序号便于判断顺序,epoch 避免重启后的第一个事件被误认为旧进程的第一个事件。随机标识只能识别代际变化,不能让内存数据在重启后继续存在。

先读取快照再订阅,天然存在一个时间窗口。假设快照停在序号十二,浏览器建立事件流之前,服务器已经产生十三和十四。若服务只把新连接放进广播集合,页面从十五开始接收,前面的两个变化就消失了。我们的接口要求浏览器带上快照位置,服务器先重放十三、十四,再接入实时广播。

另一种窗口出现在重放和订阅之间:先读历史,等待一次异步操作,再登记连接,同样可能漏掉中间事件。因此“支持重放”还不够,历史读取与实时订阅必须有明确的交接点。本文把这段操作限制在一次同步的事件循环执行中,后文会说明它为什么不能直接照搬到数据库和多实例场景。

历史有边界,过期必须让客户端知道

保留十条事件不代表客户端最多只能断线十秒。十秒只是本例每秒一条时的近似值;真实系统的保留时间取决于事件速率。如果十条记录是四十九到五十八,那么游标四十八仍可续传,因为需要的四十九还在;游标四十七则缺少四十八,必须重新取快照。

这就是判断式“cursor < oldest - 1”的来源。直接写成“cursor < oldest”会错误拒绝刚好可恢复的边界。未来游标也不能接受:当前只有五十八,客户端却要求从一百开始等待,服务应明确要求重建状态,而不是让页面永久停留在一个永远对不上的前提上。

本文用名为 reset 的 SSE 事件表达这些情况,原因包括无效游标、历史过期、进程代际变化和未来位置。reset 是本文定义的应用事件,不是浏览器内置的 SSE 控制命令。页面收到后主动关闭旧连接,再读快照。

服务端同时提供快照、重放和实时流

先创建一个目录,保存下面的 server.mjs。稍后还需要同目录的 index.html,两个文件准备好后再启动。makeApp 的 keep 参数控制保留条数,默认十条,限制在一到一千之间;heartbeatMs 默认十五秒,仅用于控制注释心跳。

import http from 'node:http';
import { randomUUID } from 'node:crypto';
import { readFileSync } from 'node:fs';
import { pathToFileURL } from 'node:url';

export function writeFrame(res, frame) {
  if (res.destroyed || res.writableEnded) return false;
  if (res.write(frame)) return true;
  // This demo disconnects a slow reader instead of growing a private queue.
  res.destroy();
  return false;
}

export function makeApp({ keep = 10, heartbeatMs = 15000 } = {}) {
  if (!Number.isInteger(keep) || keep < 1 || keep > 1000)
    throw new Error('keep must be an integer in 1..1000');
  const html = readFileSync(new URL('./index.html', import.meta.url));
  const epoch = randomUUID(), history = [], clients = new Set();
  let seq = 0, completed = 0;
  const snapshot = () => ({ epoch, seq, completed });
  const encode = e => `id: ${epoch}:${e.seq}\nevent: progress\ndata: ${JSON.stringify(e)}\n\n`;
  function tick() {
    if (seq === Number.MAX_SAFE_INTEGER) throw new Error('sequence exhausted');
    const event = { seq: ++seq, completed: ++completed };
    history.push(event);
    if (history.length > keep) history.shift();
    const frame = encode(event);
    for (const res of clients) if (!writeFrame(res, frame)) clients.delete(res);
    return event;
  }
  function readCursor(raw) {
    if (typeof raw !== 'string' || raw.length > 80) return null;
    const parts = raw.split(':');
    if (parts.length !== 2 || !/^(0|[1-9][0-9]*)$/.test(parts[1])) return null;
    const n = Number(parts[1]);
    return Number.isSafeInteger(n) ? { epoch: parts[0], seq: n } : null;
  }
  const server = http.createServer({ requestTimeout: 5000 }, (req, res) => {
    let url;
    try { url = new URL(req.url, 'http://localhost'); }
    catch { res.writeHead(400); return res.end(); }
    res.setHeader('Cache-Control', 'no-store');
    if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); return res.end(); }
    if (url.pathname === '/') {
      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
      return res.end(html);
    }
    if (url.pathname === '/api/state') {
      res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
      return res.end(JSON.stringify(snapshot()));
    }
    if (url.pathname !== '/api/events') { res.writeHead(404); return res.end(); }
    const cursor = readCursor(req.headers['last-event-id'] ?? url.searchParams.get('after'));
    const oldest = history[0]?.seq ?? seq + 1;
    const reason = !cursor ? 'invalid_cursor' : cursor.epoch !== epoch ? 'epoch_changed'
      : cursor.seq > seq ? 'future_cursor' : cursor.seq < oldest - 1 ? 'expired_cursor' : null;
    res.writeHead(200, {
      'Content-Type': 'text/event-stream; charset=utf-8',
      'Cache-Control': 'no-store, no-transform',
      'X-Accel-Buffering': 'no'
    });
    res.on('error', () => { clients.delete(res); res.destroy(); });
    res.on('close', () => clients.delete(res));
    res.flushHeaders();
    if (reason) return res.end(`event: reset\ndata: ${JSON.stringify({ reason })}\n\n`);
    if (!writeFrame(res, `retry: 1500\nid: ${epoch}:${cursor.seq}\n\n`)) return;
    // No await: validation, replay and subscription share this event-loop turn.
    for (const event of history) {
      if (event.seq > cursor.seq && !writeFrame(res, encode(event))) return;
    }
    clients.add(res);
  });
  const heartbeat = setInterval(() => {
    for (const res of clients) if (!writeFrame(res, ': heartbeat\n\n')) clients.delete(res);
  }, heartbeatMs).unref();
  server.once('close', () => clearInterval(heartbeat));
  return { server, tick, snapshot, clients };
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const app = makeApp();
  const ticker = setInterval(app.tick, 1000).unref();
  app.server.once('close', () => clearInterval(ticker));
  app.server.listen(3000, '127.0.0.1', () => console.log('http://127.0.0.1:3000'));
}

/api/state 返回当前快照,/api/events 返回事件流。每个进度事件包含完整的 completed 数值,浏览器把它赋给页面,而不是盲目加一。对于这种展示状态,完整值能简化重复事件处理;如果改成金额增量或列表操作,客户端就必须具备相应的去重和应用规则,不能直接沿用赋值逻辑。

输出帧使用固定的事件名、受控的事件 ID,以及 JSON.stringify 编码后的单行数据,最后以空行结束。这样不会把字符串中的换行误解释成新的协议字段。SSE 使用 UTF-8 文本,id、event、data 和 retry 各有自己的解析含义,空行承担帧分隔作用。WHATWG 的 SSE 规范是判断这些格式细节的依据。

服务端优先读取 Last-Event-ID 请求头,然后才读取 after 查询参数。这一点很关键:after 是页面最初打开连接时的基准,后续自动重连仍然访问同一个 URL;如果一直优先使用 after,浏览器明明已经收到了新事件,服务器却会反复从最早位置重播。

连接开始时发送的第一块只有 retry 和 id,没有 data。这里的 ID 等于已经验证的客户端基准,不会偷偷跳过事件。这样即使暂时没有新进度,连接再次断开时也可以带回基准位置。真正的业务事件都另有自己的 ID。reset 不提供一个假的最新 ID,避免把尚未恢复的状态伪装成已经追上。

这段同步代码的保证范围很窄

游标检查、历史遍历和 clients.add 之间没有 await,tick 更新状态、记录事件和广播也都是同步执行。在这个单进程实现中,两段逻辑不会在中间交错。快照的三个字段也从同一份内存状态一次性取得,因此 seq 所指的版本与 completed 相互对应。

如果把 history 查询改成数据库请求,这个推理立刻失效。数据库查询尚未返回时,订阅端可能已经错过后续通知。可靠的扩展方式是让快照带上同一数据版本的日志位置,客户端从该位置读取可持久重放的日志,实时通知只负责唤醒读取。另一个方案是先订阅并暂存新事件,再按高水位重放历史、去重后交接,但暂存区也需要容量上限和明确的失败恢复。

不要把“同一个时间戳”当成跨系统一致性的证明。若快照来自一个数据库、事件序号来自另一个缓存,两边必须有能解释的提交关系。否则页面拿到的数据可能已经包含事件二十,却只携带位置十九;也可能位置已经到二十,数据仍停在十九。前者导致重复,后者可能永久跳过必要变化。

浏览器需要区分自动重连和重新同步

保存以下 index.html。它不使用前端框架,目的是把连接的生命周期完整暴露出来。页面保留旧数字时会给出状态提示,只有拿到快照或成功应用事件才推进显示。

<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>SSE 进度恢复</title>
<h1>批量任务看板</h1>
<p>已处理:<strong id="count">尚未读取</strong></p>
<p id="status" role="status"></p>
<button id="refresh">重新读取</button>
<script type="module">
const count = document.querySelector('#count');
const status = document.querySelector('#status');
let source = null, generation = 0, timer = null, failures = 0;
const valid = x => x && typeof x.epoch === 'string' &&
  /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(x.epoch) &&
  Number.isSafeInteger(x.seq) && x.seq >= 0 &&
  Number.isSafeInteger(x.completed) && x.completed >= 0;

async function synchronize() {
  const mine = ++generation;
  clearTimeout(timer);
  source?.close(); source = null;
  status.textContent = '正在读取最新状态,旧数字暂时保留';
  const recover = message => {
    if (mine !== generation) return;
    ++generation;
    source?.close(); source = null;
    const delay = Math.min(30000, 500 * 2 ** Math.min(failures++, 6)) + Math.random() * 300;
    status.textContent = message + ',稍后重新读取';
    timer = setTimeout(synchronize, delay);
  };
  try {
    const r = await fetch('/api/state', { cache: 'no-store', signal: AbortSignal.timeout(5000) });
    if (!r.ok) throw new Error('snapshot HTTP ' + r.status);
    let view = await r.json();
    if (mine !== generation) return;
    if (!valid(view)) throw new Error('invalid snapshot');
    count.textContent = String(view.completed);
    const es = new EventSource('/api/events?after=' + encodeURIComponent(view.epoch + ':' + view.seq));
    source = es;
    es.onopen = () => { if (mine === generation) status.textContent = '已连接'; };
    es.addEventListener('progress', event => {
      if (mine !== generation) return;
      try {
        const data = JSON.parse(event.data);
        if (!Number.isSafeInteger(data.seq) || data.seq < 0 || !Number.isSafeInteger(data.completed) ||
            data.completed < 0 || event.lastEventId !== view.epoch + ':' + data.seq)
          throw new Error('invalid event');
        if (data.seq <= view.seq) return;
        if (data.seq !== view.seq + 1) throw new Error('sequence gap');
        count.textContent = String(data.completed);
        view = { epoch: view.epoch, seq: data.seq, completed: data.completed };
        failures = 0;
        status.textContent = '已同步到事件 ' + view.seq;
      } catch { recover('事件无法应用'); }
    });
    es.addEventListener('reset', () => recover('历史已不可续传'));
    es.onerror = () => {
      if (mine !== generation) return;
      status.textContent = es.readyState === EventSource.CLOSED
        ? '连接已终止,请检查服务后点击重新读取'
        : '连接中断,浏览器正在重连';
    };
  } catch { recover('读取失败'); }
}
document.querySelector('#refresh').onclick = () => { failures = 0; synchronize(); };
synchronize();
</script>
</html>

正常网络中断时,页面保留同一个 EventSource,让浏览器执行自己的重连流程。应用不会在每次 error 回调里再创建一个连接,否则原连接的自动重试和手写定时器可能同时工作,页面越断线连接越多。EventSource 的 CONNECTING 与 CLOSED 需要分开处理,进入终止状态后,本例提示用户检查服务并手动重新读取。MDN 的 EventSource 说明提供了接口与状态背景。

reset 则走另一条路径:关闭旧连接,读取快照,重新建立带新基准的连接。快照请求失败或连续收到无法恢复的历史时,代码采用带随机抖动的递增等待,最高约三十秒。它不会在服务器异常期间紧密循环请求。恢复成功应用了新进度后,失败计数归零。

generation 用来隔离不同轮次的连接。用户可能在快照请求尚未返回时点击“重新读取”,旧请求晚到后不能覆盖新请求的结果;旧连接排队中的回调也不能继续修改页面。只关闭连接并不足以表达所有异步工作的归属,用轮次号检查能让这个条件变得清楚。

浏览器记住 ID,不等于业务处理已经成功

Last-Event-ID 表示浏览器的事件流解析进度,并不是应用事务提交凭据。浏览器更新自己的事件 ID 与 JavaScript 回调成功修改业务状态是不同的步骤。因此代码在 JSON 解析、字段校验或顺序检查失败时,立即转入重新同步,而不是任由异常抛出后继续相信自动重连会补回来。规范中的事件分发步骤说明了这一顺序。

当前页面只做同步的 DOM 文本赋值,随后更新本地 view。小于等于当前序号的重复事件直接忽略,跳过了预期下一序号则重新取快照。完整值赋值可以承受重复展示,但顺序检查仍有价值,它能暴露服务重放或客户端处理链上的缺口。

若回调里还要写 IndexedDB、发送确认或者等待另一个接口,就需要串行处理与明确的失败状态。不能把 async 回调当成天然串行的队列,也不能只把最新 ID 存到 localStorage,却不保存与它对应的状态。页面重载后若拿着很新的位置和空白数据继续订阅,很可能永远补不回已经跳过的内容。

本文页面每次重新载入都先读取快照,没有把连接进度当作持久化状态。这里选择的是看板最终跟上当前值,而不是保证所有中间动画都播放一遍。审计记录、计费流水和需要逐条执行的命令,应该有独立的持久消费协议,不能从“页面能重连”推导出业务恰好执行一次。

用真实 HTTP 测试恢复分支

保存下面的 smoke.test.mjs。这份测试使用 Node 内置测试器和 fetch,不需要安装测试框架。first 只解析本服务输出的单行 JSON 帧,用于读到第一条应用消息后结束连接;它不是可复用到任意网站的通用 SSE 解析器。

import test from 'node:test';
import assert from 'node:assert/strict';
import { once } from 'node:events';
import { makeApp, writeFrame } from './server.mjs';

async function setup(t) {
  const app = makeApp({ keep: 2 });
  app.server.listen(0, '127.0.0.1');
  await once(app.server, 'listening');
  t.after(async () => {
    app.server.closeAllConnections();
    await new Promise(resolve => app.server.close(resolve));
  });
  const base = `http://127.0.0.1:${app.server.address().port}`;
  return { ...app, base, url: n => base + '/api/events?after=' + app.snapshot().epoch + ':' + n };
}
// Test helper for this server's one-line JSON frames, not a general SSE parser.
async function first(url, headers = {}) {
  const r = await fetch(url, { headers, signal: AbortSignal.timeout(2000) });
  const reader = r.body.getReader(), decoder = new TextDecoder();
  let text = '';
  try {
    for (;;) {
      const { value, done } = await reader.read();
      if (done) throw new Error('stream ended without data');
      text += decoder.decode(value, { stream: true });
      let i;
      while ((i = text.indexOf('\n\n')) >= 0) {
        const block = text.slice(0, i); text = text.slice(i + 2);
        const line = block.split('\n').find(x => x.startsWith('data: '));
        if (line) return JSON.parse(line.slice(6));
      }
    }
  } finally { await reader.cancel(); }
}
test('snapshot gap and reconnect header', async t => {
  const app = await setup(t);
  const s = await (await fetch(app.base + '/api/state')).json();
  app.tick(); app.tick();
  assert.equal((await first(app.url(s.seq))).seq, 1);
  assert.equal((await first(app.url(0), { 'Last-Event-ID': s.epoch + ':1' })).seq, 2);
});
test('retention boundary', async t => {
  const app = await setup(t);
  app.tick(); app.tick(); app.tick();
  assert.equal((await first(app.url(1))).seq, 2);
  assert.equal((await first(app.url(0))).reason, 'expired_cursor');
});
test('invalid cursor, future position and process replacement', async t => {
  const app = await setup(t), other = await setup(t);
  assert.equal((await first(app.base + '/api/events?after=bad')).reason, 'invalid_cursor');
  assert.equal((await first(app.url(1))).reason, 'future_cursor');
  assert.equal((await first(app.base + '/api/events?after=' + other.snapshot().epoch + ':0')).reason,
    'epoch_changed');
});
test('backpressure policy with a response double', () => {
  const res = { destroyed: false, write: () => false, destroy() { this.destroyed = true; } };
  assert.equal(writeFrame(res, 'frame'), false);
  assert.equal(res.destroyed, true);
});

在这三个文件所在目录执行:

node --version
node --test smoke.test.mjs
node server.mjs

测试会使用系统分配的空闲端口,正常结果是四项通过、零失败。单独启动服务则固定监听 127.0.0.1:3000;若端口被占用,应先释放端口或修改最后的 listen 参数。浏览器访问 http://127.0.0.1:3000 后,应先显示当前计数,再逐步更新,不需要手动刷新。

本次在 Node.js 24.22.1 中实际运行了上述四项测试,全部通过。还运行了包含实时事件、心跳、连接清理、请求方法限制等分支的八项服务端回归测试,全部通过,并检查了浏览器脚本语法。背压分支使用响应替身触发 write 返回 false,不是对真实弱网的压测。没有把这些结果称为浏览器端到端测试,也没有执行 Nginx、CDN 或生产环境验收。

手工验证短断线与历史过期

服务保持运行时,在另一个终端执行下面的命令。它先读取一个真实游标,再用 curl 观察流。命令需要常见的 POSIX shell、curl 和同一 Node 运行时。

CURSOR=$(node --input-type=module -e "const s=await (await fetch('http://127.0.0.1:3000/api/state')).json(); console.log(s.epoch+':'+s.seq)")
curl -N --max-time 4 "http://127.0.0.1:3000/api/events?after=$CURSOR"
sleep 12
curl -N --max-time 4 "http://127.0.0.1:3000/api/events?after=$CURSOR"

第一次应连续看到 progress 事件。因为我们主动设置了四秒上限,curl 最后报告超时退出属于预期结果,不代表服务异常。等待十二秒后,继续使用同一个旧游标,第二次应收到 expired_cursor 的 reset,因为最初位置之后需要的历史已经被挤出十条窗口。这个实验故意重用旧游标,不能把它误称为 curl 自动携带 Last-Event-ID。

要检查请求头优先级,可以记下第一次输出中的某个完整 ID,把它作为 Last-Event-ID 请求头重新连接,同时保留较旧的 after 参数。服务器应从请求头指定的位置之后开始。自动化测试已经覆盖了这个冲突组合。

浏览器层面的验收还应覆盖断网恢复、服务重启、反复点击重新读取,以及页面进入后台后再返回。短断线应通过历史重放追上;长断线应显示重新读取并以快照恢复;服务重启后计数回到零是本例内存模型的结果,页面不能把旧进程的游标当作新进程的有效位置。这里列出的是应执行的浏览器验收步骤,不声称已在具体浏览器版本上完成。

慢连接、代理和权限决定能否上线

示例处理背压的方式很保守:当 response.write 返回 false,就销毁这个慢连接,停止继续堆积数据,让客户端稍后重连或取快照。false 表示有数据排在用户态缓冲区,并不等于该事件已经发送失败;同样,true 也不是浏览器应用成功的确认。Node.js 24.22.1 的 response.write 文档明确区分了写入与缓冲状态。

这个策略牺牲了慢客户端的连续性,换取示例不维护无限队列。真实项目通常会等待 drain,同时设置每个连接的待发字节上限、等待时长和事件滞后上限。若一个客户端持续跟不上生产速度,反复重连只会制造更多重放工作,应降低推送频率、合并可替代的状态更新,或明确要求走低频快照模式。

历史保留条数也不是完整的内存预算。本例每帧只有两个安全整数,大小可控;实际事件可能携带大量文本或数组,应同时限制单帧字节数和历史总字节数。广播成本随连接数增加,遍历历史重放也会占用事件循环。每次新连接都重放一万条并不是免费的可靠性,应结合在线人数、断线频率和恢复时间决定窗口。

心跳使用注释帧,不分配新的业务序号,也不改变看板值。它的作用是让空闲流持续有字节经过,并帮助连接层暴露问题;收到心跳仍不等于数据源健康。若后台任务停止生产而连接还活着,产品最好同时展示最近一次业务更新时间,避免“已连接”掩盖“长时间没有新数据”。

反向代理可能缓冲上游响应,使服务器每秒写入的数据在浏览器端成批出现。代码设置了 X-Accel-Buffering: no,但是否被采用取决于代理配置。Nginx 的 proxy_buffering 可以显式关闭,读取超时应结合心跳间隔设置;中间 CDN 的缓冲与最大连接时长仍需另外核验。Nginx 官方代理模块文档描述了这些缓冲控制。不要因为直连 curl 正常,就认为整个公网链路具备相同效果。

公开部署前还缺少哪些约束

这个示例没有用户身份、租户隔离、连接限额或外部持久化,不能把监听地址改成公网地址就作为生产看板。真正的进度接口必须先判断当前用户能看哪一项任务,再查询对应快照和事件。事件 ID 是位置标记,不是访问凭证;客户端能够猜到一个 ID,绝不意味着有权读取那段日志。

同源页面通常可以沿用受保护的会话机制。跨源使用时要处理凭证与精确的来源许可,不应把长期访问令牌塞进查询字符串,暴露给访问日志或其他记录。原生 EventSource 的构造方式没有任意自定义请求头参数;若系统必须使用特定 Authorization 头,应选择支持该需求的传输实现,并承担相应的流解析与重连工作。

一个页面也不应为每个小部件都打开独立流。优先在页面内复用连接,再把事件分发给组件;多标签页共享则需要额外的所有权和生命周期设计。HTTP/2 能改善连接复用,但不会消除服务器端订阅数量、流量和慢消费者成本,部署时还应核验浏览器到代理以及代理到后端各段实际使用的协议。

最后,多实例不能各自生成互不相通的内存日志,再期待负载均衡让续传自然成立。客户端可能在重连时进入另一实例,结果频繁 reset。为状态看板接受偶尔重新取快照可以是一种明确的产品选择;若要求跨实例连续续传,就需要共享、可重放、有访问控制的日志以及一致的快照位置。

把这些条件写进接口契约后,SSE 的工程边界就很清楚:连接负责传送帧,事件位置负责描述进度,快照负责在历史不足时恢复当前状态。测试应证明这三者能交接,而不只是证明页面打开时出现过一条消息。

相关文章

评论

登录后即可参与讨论

暂无评论。