Skip to content

从 NowFind 看 rrweb 会话录屏链路设计

约 8100 字大约 27 分钟

rrweb录屏Electron前端监控

2026-10-12

rrweb 常被当作一个「录屏库」来用:装上 record,配一个 replayer,页面上就能放回放。但在真实的桌面端业务里,录制只是开头——录下来的数据怎么在几百条事件每秒的频率下不拖垮主进程、怎么在窗口被复用时不错档、出问题后怎么和日志对上时间轴,才是真正花时间的地方。

NowFind(牛客招人)桌面端把 rrweb 用在了一个很具体的位置:HR 跑自动化任务或人工接管时录下页面画面,任务结束后上传到私有 OSS,出问题时把当时的屏幕还原出来看,并与 SLS 日志按 logIndex 精确对齐、互为佐证。

本文根据《NowFind rrweb 录屏与回放实现分析》整理,分析基准日期为 2026 年 10 月 12 日,分析对象为桌面端仓库 fe-nowfind-3(master 分支,release-20261010)。文中实现细节、默认参数与代码片段均已对照仓库源码逐条核对;但未执行回放实验,也未复现 wasm 泄漏与断网场景。

一、先明确边界:只用录制,不用回放

如果把它当成一个「录屏功能」来看,很容易第一反应是同时引入 @rrweb/record 和 rrweb(replayer)。NowFind 的做法相反:

  • 客户端产物里只有 @rrweb/record,replayer 完全不进客户端。
  • 回放发生在排查机侧,由外部 rrweb-player 加载 OSS 上下载下来的事件流。

这样切分的原因很实际:录制是业务行为,必须在用户的机器上跑;而回放只是「人想看」时的动作,属于排查工具链,没必要背着几百 KB 的 replayer 和相关依赖进客户端包。

整条链路的组成与归属可以一次性列清楚:

项值
录制库@rrweb/record@2.0.0-alpha.18,源码内置为 src/common/util/lib/rrweb-record/index.js(373KB,ESM 单文件,自包含、无外部依赖,MIT)
唯一使用方src/preload/util/rrweb/index.ts 的 startRecord()
录制侧preload,分 page(脚本任务页)与 browser(人工接管页)两种
落盘 / 上传侧主进程 src/main/util/rrweb/index.ts
存储私有 OSS 桶 rrweb/<fileName>.zip + 后端登记接口
回放排查机侧 skill rrweb-replay,生成本地 replay.html

一个容易忽略的细节:录制侧在 preload,落盘与上传侧在 main。这意味着每一条 rrweb 事件都要跨进程走一趟 IPC,后面所有的性能设计基本都在处理这个跨进程边界。

二、为什么不用 npm 包:自维护 fork 与两处补丁

仓库里 src/common/util/lib/rrweb-record/README.md 记录得很直白:上游存在内存泄漏,截至 2.1.6 仍未修复,所以把 npm 包里的 dist/record.js 直接拷贝进仓库自行维护。

问题出在 serializeNodeWithId 的 iframe 分支。rrweb 每录入一个同源 iframe,就往模块级的 mutationBuffers 里 push 一个 MutationBuffer,而且永远不删。iframe 被移出 DOM 之后,它的 document、JS 上下文和 wasm 实例都回收不掉。

在本项目里,这个泄漏会落到一个非常具体的地方:BOSS 在线简历 iframe(web/frame/c-resume)每打开一次就新建一个 wasm 实例,同一个页面打开约 120 份后 wasm 地址空间耗尽,直接报 WebAssembly.instantiate(): Out of memory。

补丁共两处,但只有第一处带 [nowcoder patch] 注释——第二处是一行纯删除,注释无处可挂。所以 grep -n "nowcoder patch" index.js 实际只会命中一条,别以为漏打了:

位置改动原因
serializeNodeWithId 中 onceIframeLoaded 的调用条件加 && !_isBlockedElement(n2, blockClass, blockSelector)让 blockSelector 在 iframe 分支也真正跳过内容录入,而不是只换成占位
文件末尾删除 //# sourceMappingURL=record.js.map仓库未带 map 文件

补丁插在 serializedNode.type === Element && tagName === 'iframe' && !_isBlockedElement(...) 这个判断上。也就是说,被 block 掉的 iframe 连内部文档都不再序列化,onceIframeLoaded 根本不会注册——这才是真正切断 mutationBuffers 增长的开关。

这里有个容易踩的坑:判断不能用 recordChild。增量变更路径(MutationBuffer)调用时传的是 skipChild: true,用它会把所有动态插入的 iframe 的录制一起关掉,范围远大于预期。

代价也要说清楚:被屏蔽的简历 iframe 在回放里不显示任何内容。占位尺寸取的是 iframe 插入那一刻的大小,而那时弹窗还没展开,通常是 0,所以回放里连占位框都看不到。

验证手段是 dist/cdp/script/probe-boss-resume-wasm-leak.cjs:录屏开启时反复打开、关闭简历,GC 之后 documents 数量不应增长。升级流程也很明确:从新版 npm 包取 dist/record.js 覆盖 index.js → 按上表重新打补丁 → 用验证脚本复测。

这段经历值得单独记一笔:依赖里被放弃维护的那一类 bug,往往需要用「把源码拷进自己仓库」这种最笨的方式解决。代价是升级要手工走一遍,收益是不再被上游的发版节奏卡住。

三、录制配置:每一项背后的权衡

录制入口是 startRecord()(src/preload/util/rrweb/index.ts:56)。开关来自 --use-record=1 命令行参数,由主进程按 funConfigCommonStore 注入;preload 侧只做一次 getArgv('use-record') === '1'。

总开关在 src/common/pinia/module/funConfig.ts:20-23:

const canUseRecord = computed(() => !!(isLocal || isDev || funConfig.value?.canUseRecord?.enable));
const canRecordBrowser = computed(() => canUseRecord.value && !funConfig.value?.closeRecordBrowser?.enable);
const canRecordPage = computed(() => canUseRecord.value && !funConfig.value?.closeRecordPage?.enable);

也就是说录像拆成了两条独立开关:接口模式(browser,人工接管 + 接口抓简历)和自动化任务(page,脚本任务页)。出问题时可以只关掉其中一条,不用全量停录。

真正有意思的是配置项本身,每一项都对应一个具体的成本:

配置值为什么
checkoutEveryNms1 小时全量快照太大,基本等于关掉;整页导航本身就会产生新快照
slimDOMOptions'all'源头剥离 <script> / 注释 / head meta / favicon / title,直接压缩 FullSnapshot,收益贯穿 IPC + 磁盘 + zip + 上传整条链路
inlineStylesheetfalse默认 true 时每次全量快照会同步读同源外链的 cssRules,强制样式重算,是重 DOM 页最贵的单帧主线程操作;实测 BOSS 首页 2.7MB 快照中外链内联占了 1MB
blockSelectoriframe[src*="/web/frame/c-resume"], .resume-detail iframe, .resume-detail-wrap iframe挡掉简历 iframe,配合前面的 fork 补丁防 wasm OOM
sampling.mousemove0必须为 0,否则鼠标移动会被节流采样、数量对不上
sampling.mousemoveCallback0减少保存频率
sampling.scroll / media100节流窗口 100ms
sampling.mouseInteraction只留 MouseUp / MouseDown / Click其余关闭减量
sampling.input'all'输入全量记录

inlineStylesheet: false 是其中权衡最明显的一项。关掉它换来了主线程不用做样式重算,代价是回放时外链样式依赖 CDN 上该 CSS 仍可访问——BOSS 的静态资源带版本号,一般长期有效,所以这个代价是可以接受的。如果换成不带版本号的资源,这个决定可能就要反过来做。

这里有个容易误读的点:这个开关只管 <link> 外链分支。<style> 标签和 CSSOM 注入的样式不受它门控,仍然会内联,所以运行时动态注入的样式不会在回放里丢。代价只落在「原页面靠外链 CSS 文件的那部分样式」上。

另外,启动前有一组跳过条件:URL 以 file://、about:blank、chrome 开头,或命中 static.nowcoder.com/test/tool/blank.html,直接不录。

插件一:reorder-adds(仅 zhaopin.com)

这个插件只处理 type=3, source=0(IncrementalSnapshot / Mutation)事件的 adds 数组,对其做拓扑排序(Kahn 算法 + BFS),确保 parent 节点排在 child 之前。

原因是智联在使用 Vue Teleport 等场景时会产生 adds 顺序倒置——parent 排在 child 之后,replay 端因为找不到 parent 而丢弃子节点,回放里就缺一块 DOM。排序后仍不能归入拓扑序的节点(如循环依赖)追加到末尾,保证不丢节点。非 zhaopin.com 域名直接返回 {}(空插件,不生效)。

实现上做了两级快速跳过,让绝大多数 mutation 事件零开销:adds.length <= 1 直接返回;否则先扫一遍「有没有哪个 parent 落在本批 adds 内」,没有内部依赖(这是常态)也直接原样返回。只有真的存在倒置才走 Kahn + BFS。

插件二:nc-input-poll(仅隔离环境)

这个插件处理的是 Electron 的一个世界隔离问题。打包版 contextIsolation=true,preload 运行在隔离世界,而 rrweb 的 setter hook 打在隔离世界的 HTMLInputElement.prototype 上,抓不到页面世界里的 el.value = x(例如 el-input 下拉回填)。结果是回放时输入框是空的。真实键盘输入不受影响,因为那走的是 rrweb 自带的 input/change 监听,跨世界有效。

解决方案是每 500ms 轮询读 DOM——读 property 跨世界有效,且不改页面、不派发事件——发现值变化就补发一条标准 rrweb Input 事件(type: 3, data.source: 5)。

几个实现上的细节,每个都是一次踩坑:

  • 做成 record plugin 是为了蹭 rrweb 的 observer 生命周期:主文档和每个同源 iframe 各装一份,停录时统一拆掉。但 plugin 自带的 callback 只能发 Plugin 事件(type 6),回放端不会当输入应用,所以事件仍要走外部传入的 emit 发标准事件。
  • 密码 / file / submit / button / reset / image 类型跳过——密码不落盘,file 的 value 无意义,按钮类的 value 是文案不是用户输入。
  • 基线取空态而非首见值。取值可能在首轮轮询前就被写入,按首见值建基线会导致这条永远发不出来。
  • 补齐前先查 mirror.getId(el):rrweb 还没收录该节点(对应 mutation 未到)时不更新基线、等下一轮。否则会发出一条指向未知 node id 的 Input 事件,回放端无效,而且基线已推进、下一轮也不会再补。
  • 原生 input/change 事件把基线推到当前值,避免重复补发;radio 还要把同 name 的所有兄弟项基线一起更新——rrweb 对 radio 是连同同组其它项一并记录的。
  • 监听用 {capture: true, passive: true},与 rrweb 自己的 input/change 监听保持一致,避免被页面的 stopPropagation 挡掉。
  • observer 里全程包 try/catch:rrweb 不给 observer 兜 try/catch,这里抛出去会让整段录制起不来。
  • 仅在 process.contextIsolated 为 true 时挂载;否则 rrweb 自己的 hook 是好的,补录只会产生重复事件。

四、数据流:三处刻意的性能设计

整条链路是这样的:

flowchart TD
    A["rrweb emit(e)"] --> B["enqueueRecord(uuid, from, e)<br/>preload/buffer.ts"]
    B --> C["按 uuid 分组缓冲<br/>renderer 侧即时 JSON.stringify"]
    C -->|"300ms 或 512KB"| D["ipcRenderer.send<br/>'page:rrwebRecord' {uuid, from, batch}"]
    D --> E["_saveRrwebData()<br/>main/util/rrweb/index.ts:169"]
    E --> F["补齐/固化归属信息<br/>dbRrweb.set(uuid, info)"]
    F --> G["写 root/{from}/{taskId}/{uuid}_{ts}.txt<br/>注入 extInfo"]
    G --> H["bufferWrite()<br/>main/util/rrweb/buffer.ts"]
    H -->|"3s 定时 / flushRrwebBuffer"| I["fs.promises.appendFile 批量落盘"]

三处设计都在做同一件事:保护主进程。

第一,preload 批量下发。 旧逻辑是每个 rrweb 事件一次 ipcRenderer.send,而 mousemove 不节流时可达几百条每秒,高频挤占跨进程主通道。现在按 uuid 聚合,BATCH_FLUSH_MS = 300ms 或 BATCH_MAX_BYTES = 512KB 触发,把「每事件一条 IPC」聚合成「每 ~300ms 一条」。

按 uuid 分组还有一个语义作用:停录后仍会 emit 的节流尾事件属于旧 uuid,与新录制段的新 uuid 分属不同批次,天然互不串档。

第二,renderer 侧即时序列化。 JSON.stringify 在 preload 完成,batch 是 \n 拼接的已序列化事件串(JSON 会把事件内的换行转义为 \n,所以分隔符无歧义)。主进程只需要字符串拼接,把 extInfo 注入每行:

function injectExtInfo(line: string, extInfoJson: string): string {
    if (line.length < 2 || line[0] !== '{' || line[1] === '}') return line;
    return `{"extInfo":${extInfoJson},${line.slice(1)}`;
}

它利用了「rrweb 事件经 JSON.stringify 恒为以 { 开头的对象串」这一前提,在首个 { 后插入字段。主进程无需逐条 parse/stringify——主进程是关键共享进程,能省一点是一点。

第三,main 侧缓冲落盘。 bufferWrite 在内存攒 3s,一次性 fs.promises.appendFile,避免每个事件同步阻塞主进程。配套还有两个细节:用 fileBytes 内存计数替代每批 fs.statSync 做 50MB 分片判断;用 createdDirs 这个 Set 免掉每批 existsSync + mkdir 的主进程同步 IO。

这里的落盘缓冲本身还有两层保护,都属于「不做就会偶发丢数据」的那类:

  • flushAllBuffers 带重入保护(flushingPromise)。已有 flush 在执行时等它完成,而不是并发再刷一遍——两次 flush 同时 writeBuffer.clear() 会把数据清掉却没人读走。
  • flushRrwebBuffer() 等完在途 flush 之后还会再刷一次,因为等待期间可能有新数据写进来。它也正是停录上传前、以及退出时调用的那个函数。

fileBytes 的计数是双向维护的:正常写入时「写入即计」(含还没落盘的缓冲),所以它比磁盘实际大小更早反映进度,分片判断更准;而重启后续写旧文件时计数缺失,saveRrwebData 会用 fs.statSync 播种一次磁盘实际大小,之后交回内存维护。顺带一提,分片判断用的是写入前的累计值,所以单段实际会略超过 50MB(多出一批的量)才换新段。

第四,renderer 侧的容错也不能少。 单条事件的 JSON.stringify 失败时直接丢弃这一条,不污染整批——批量下发的收益是「一条 IPC 顶几百条」,代价就是一条坏数据可能带走整批。

五、归属信息:为什么这么麻烦

每条录像都要能回答「这是哪个任务的」。IRrwebCacheInfo(src/main/util/rrweb/index.ts:26)固化了 taskId / conversationId / platform / sessionId / uuidAppExec / contentId / from / uid,取值优先级是:cacheInfo 固化值 > 粘滞绑定 uuidOwnerTask > 反查运行中任务。

两类来源的差异在于:

  • from='page':脚本任务页,归属从 taskCommonStore 反查,平台由 groupToPlatform(group) 反查 TASK_PLATFORM_CONFIG。反查时有个额外约束:已知归属 taskId 时只认同 taskId 的那个任务,只有未知归属(首条事件)才退回「优先取运行中任务」——复用窗口下同一 contentId 可能并存多个任务,按 contentId 取运行中任务会把 A 的尾部事件算到 B 头上。
  • from='browser':人工接管,拿不到 group,用当前页 URL 的 hostname 反查平台,并且按 hostname 长度降序匹配——让 ehire.51job.com 先于 51job.com 命中,避免 51Job 企业版被误判成普通版。browser 的 taskId 首次就固定为 '0'。

browser 分支还有个顺序上的讲究:sessionId 和 platform 是每次 save 都尝试补一次的,不能写进 if (!taskId) 里。因为首条事件时 dbTakeOver.set('sessionId') 可能还没完成、或者页面 URL 还没跳到目标平台域名——一旦和 taskId 绑在同一个条件里,taskId 会被立刻设成 '0',后面就再也补不上了。

两个辅助缓存各解决一个具体的错档场景:

uuidOwnerTask(粘滞绑定),即 uuid → {taskId, conversationId, platform}。文件上传清除后(cacheInfo 已不存在)到达的尾部事件,仍按原任务归属,避免复用同一 contentId 时把 A 的尾包串到 B。

这里有个不显眼但很致命的约束:必须存全三个字段。如果只存 taskId,尾包的 conversationId 会为空,于是落到按 contentId 反查、命中正在运行的 B,写出 taskId=A 但 conversationId=B 的串档记录。上限 5000 条,超量丢最早一条。

taskRecordLocator,即 taskId → 当前录屏段 {uuid, fileName},供日志指向回放文件(如 bossDialogGuard 的 recordFileName)。它只给文件名不给完整对象键,因为完整键 <credential.path>/rrweb/<fileName>.zip 里的路径前缀和 zipUrl 都要等任务结束上传时才确定。

这两个缓存都只在 from === 'page' 时写(browser 的 taskId 恒为 '0',没有归属可言),且都设了 5000 条上限、超量丢最早一条——早期 uuid 早已结束,不会再有尾部事件。

另外,_saveRrwebData 每次算完这套归属信息后写库前会做一次全字段比较,与 dbRrweb 里已有的完全相同就跳过写入。这条录像事件是每秒几百条的热路径,绝大多数事件的归属信息是不变的,省下的就是这些高频小写。

整个 _saveRrwebData 外面包了一层 try/catch,异常上报还做了 60s 限频。源码注释写得很直白:「这里不建议打 log,否则太多了」——同样是热路径的缘故。

六、生命周期:起录、停录与复用

起录

page / browser 的 preload 初始化时 canUseRecord && startRecord(from)。同一文档内已在录时直接 no-op——重开一段会换新 uuid,把一次任务的录像切成多段、各自单独上传成一条录屏记录。整页导航后是全新 JS 上下文,拦截条件自然失效。

同时 ensureUnloadFlush() 注册一次卸载兜底 flush(pagehide / beforeunload),覆盖导航 / reload / 直接销毁 wc 这些没有停录回执的路径。

停录:为什么要延迟 ack

主进程通过 controlPageRecord(wc, 'stop', requestId) 单向发 page:rrwebControl。preload 收到后停录,然后延迟 STOP_ACK_DELAY_MS = 250ms 再回执 page:rrwebStopped。

这个延迟不是随手加的:rrweb 的 throttle cleanup 只移除监听,不取消已排队的 trailing setTimeout(scroll / media 的 100ms 节流窗口),所以 stopRecord() 之后仍可能有节流尾事件 emit 出来。

围绕这个窗口,preload 侧有三个配套动作:

  1. stopRecord() 内部立即 flushRecordBuffer()。否则已缓冲的事件还压在 300ms 定时器里,会晚于 ack 到 main,直接破坏 FIFO 顺序。
  2. 延迟期满后再 flushRecordBuffer() 一次,然后才发 page:rrwebStopped——把「~100ms 内仍可能 emit 的尾事件已入缓冲」这件事落成事实,再让 ack 排在它们后面。
  3. 未在录时不延迟。canUseRecord 关、空白页、已停过这几种情况下 currentStop 为空,也就不会有尾事件,此时立即 ack,不必白等 250ms。

延迟 ack 的作用是让这些尾事件经同一 renderer 的 IPC FIFO 排在 ack 之前到达主进程。主进程侧维护 requestId → resolve 的映射(stop_1、stop_2…),收到 ack 就说明尾部事件均已送达,接下来 drain 在途 save(waitInflightSaves)→ flush → 上传,保证尾包不丢。超时兜底 2s,避免 wc 卡死时永久挂起。

waitInflightSaves 这一步的必要性来自 IPC 的实现方式:page:rrwebRecord 的 ipcMain 处理是 fire-and-forget(不 await 落盘),所以「事件已送达」不等于「事件已写入缓冲」。saveRrwebData 会把每个落盘 promise 登记进 inflightSaves,停录上传前 drain 一遍,避免出现「上传并清库之后,尾包才落盘」从而被迫等下次释放或启动补传的情况。

任务结束:录像必须早于入池

src/main/script/util/reuse.ts 里的顺序是关键:

stopAndFlushTaskRecord(wc)         ← 停录(带回执) + flush + 快照本任务 uuid 列表,只做轻活
releaseToPool(contentId, group)    ← 窗口尽快回互动页 / 入池
clearTaskContentId(...)
void uploadRrwebDataByUuids(uuids) ← 后台上传(不 await,内部吞异常)

录像必须在 releaseToPool 之前封存,因为 resetBossChat 会把页面导航去互动页;否则录像会混进导航、抓错页面。

而把上传后置是这轮优化的核心目标:网络上传实测可达数十秒,不能阻塞复用(窗口入池)。快照得到的 uuid 在停录时已经定死,即便 wc 被下个任务复用、在同一 contentId 起新录像,后台上传也只命中本任务这批 uuid。

配套的保护集合是 uploadingUuids:它在 uploadRrwebDataByUuids 的任何 await 之前同步登记,让下个复用同一 contentId 的任务在快照时跳过这批 uuid,避免与 clear(file, uuid) 竞态导致重复上传 / 重复保存。

销毁分支(forceDestroy 或 drain 超时)走 stopAndUploadTaskRecord → delPageWebView,后者内部的 uploadRrwebData 是 fire-and-forget;此时上面那步不再重复触发,避免同一批 uuid 被两个上传器并发处理。

再往外看一层,releaseTaskPage 这个入口本身还有三道闸,都是为了「同一个 wc 不能被处置两次」:

  • in-flight 锁(releasing: contentId → promise)。停止流程与 run 结束路径几乎同时进入时,后来的调用直接 await 前一次,不重复执行 stop/upload/releaseToPool——下面的 idle/owner 守卫只能挡顺序重入,挡不住并发同时进入。
  • 所有权守卫。wc 已在池中(reuse.idle)或已被同组任务 B 接管(reuse.ownerTaskId !== task.taskId)时直接跳过,否则会误删 B 的监听、把 B 在用的 wc 标成 idle。
  • drain 超时则销毁不入池。drainInflight 超时说明 A 仍有在途 CDP/导航,无法保证 B 安全接管,此时走 stopAndUploadTaskRecord + delPageWebView。

最后清 contentId 用的是 CAS(同时校验 runId 和 contentId):经过这一串异步窗口后,同一个 taskId 可能已被新 run 重新 addTask 并复用本 wc,不校验就会误清新 run 的页面归属。

这段顺序编排集中体现了「异步后台任务 + 资源复用」的典型难点:所有跨复用的状态,都必须在复用发生之前就固化下来,而不是依赖「复用之后再去反查」。

免刷新复用页的「补起录」

入池时已经 stopAndFlushTaskRecord 停录了。如果复用页不整页导航,preload 不会重跑、页面侧的 startRecord 也不会自己恢复——这张页此后永远不再录,快照恒为空、静默不上传。

所以业务侧需要在确认页面已就绪、本次不会再整页导航的地方调用 startReusedPageRecord()(例如 BOSS 的 checkIframeLoadSuccess 成功之后),主进程再 controlPageRecord(wc, 'start')。

落点要尽量晚:如果早于导航调用,会先对上个任务的残留页拍一张 FullSnapshot,随后的整页导航又会另起一段,一次任务就变成两条录屏。好在重复调用无害(非复用 run 在 startReusedPageRecord 是 no-op 并返回 false,页面侧已在录时 preload 也 no-op),所以落点可以多设几处,保证不漏。

实际落点也确实是「多设几处」的:BOSS(boss.ts、microChat、catchUpRecord)、51Job(search、recommend)、51job 企业版、百度等共约 9 个业务入口都调了它。主进程侧还顺手记了一个 runId → 起录请求次数 的计数器,纯用于埋点对账——看一个 run 调了几次、有没有再出现「早起录 + 后导航」的回归,不做门禁(是否真的换新段由 preload 按「当前是否在录」判定,比主进程猜更准)。

其他触发点

  • appendResumeData:browser 接管时把 geekInfo 以 type: 5(Custom)/ tag: 'boss-resume-data' 的 rrweb 事件写进录像。它走的是另一条落盘路径——saveRrwebData 的单条 data 分支,由主进程自己 JSON.stringify 并合并进已有的 data.extInfo;只有 preload 上来的批量才走 batch 那条字符串注入的快路径。同一份落盘逻辑要同时伺候这两种输入,也是 _saveRrwebData 里 batch !== undefined 分支的由来。
  • uploadAllRrwebData:登录用户 id 变化后 5 秒触发,补传上次运行的残留;退出时只 flushRrwebBuffer() 保证落盘。
  • 生命周期埋点:stopAndUploadTaskRecord / stopAndFlushTaskRecord / uploadRrwebDataByUuid / uploadRrwebDataByUuids / saveRrwebData 全部走 SLS.execFunc。

七、上传与存储

flowchart TD
    A["uploadRrwebDataByUuid({uuid})"] --> B["zipFile(file)<br/>archiver level 6"]
    B --> C["useOss('private').uploadFile<br/>rawName: rrweb/fileName.zip"]
    C --> D["saveRrwebFile<br/>POST /api/now/find/feign/agent/mouse-track/upload"]
    D --> E["clear(file, uuid)<br/>删本地 txt + 回收空目录 + dbRrweb.remove"]

几个要点:

  • 分片:单文件超过 maxFileSize = 50MB 就换新段,IRrwebCacheInfo.items[] 记录每段的 {fileName, zipUrl}。上传是「每段一个 zip」,先传成功的段先记 zipUrl,避免重复上传。旧版单文件路径(无 items)保留兼容分支。
  • 压缩:archiver('zip', {zlib: {level: 6}})。选 level 6 是因为压缩比已接近 level 9(约 95%)但快数倍,能减少主进程 zip 时的 CPU 阻塞。
  • 私有桶硬编码 useOss('private');登记接口 saveRrwebFile,body 带 ext:{createdAt, from, uuidAppExec, conversationId, platform, sessionId, os, osVersion}。
  • 只上传本执行 / 同 contentId 的:uploadRrwebData 按 uuidAppExec + contentId 双重匹配;noSameUuidAppExec 用于 uploadAllRrwebData 只补传历史数据。
  • 清理:clear() 先 writeFileSync(file, '') 清空再 unlinkSync 删除;接着 dropFileBytes 丢掉内存字节计数(避免 fileName 复用时留下脏计数)、目录空则 rmdir 并从 createdDirs 移除、最后 dbRrweb.remove(uuid)。
  • 空目录回收:uploadAllRrwebData 会先 clearPageDir() 扫一遍 root/page/ 下纯数字命名的空子目录(即 taskId 目录)并删掉,避免长期运行后堆积。
  • 补传:上传失败留库不删,下次 uploadAllRrwebData 或复用释放时再传。落到代码上是「失败即中断」——某一段拿不到 zipUrl 就直接 return,既不继续处理后续段、也不清库,把整条记录原样留给下次;而先传成功的段已经把 zipUrl 写回 items,重试时不会重复上传。
  • 空文件(size <= 10 字节)直接判失败清掉;uid 与当前登录用户不符的数据不 save(这个判断放在上传完成之后、登记之前)。

本地文件布局:

{root}/{from=browser|page}/{taskId}/{uuid}_{timestamp}.txt    每行一条 rrweb 事件(含 extInfo)

root 取 app.getPath('sessionData')/nowcoder/record/;本地开发改为 __dirname/../nowcoder/record/。

数据库方面,dbRrweb 是独立命名空间(ownFile: true),避免共享 config.json 被大命名空间越撑越大、拖慢高频小写。

八、与 SLS 日志对齐:整套设计里最关键的一环

前面所有工程细节都是为了「录下来」,而这一节才是让它真正有用的部分——把画面和代码执行钉死在一起。

每条 rrweb 事件都会被注入 extInfo:

{"extInfo": {"url": "...", "logIndex": 42, "conversationId": "..."}, "type": 3, "timestamp": 1775..., ...}

extInfo.logIndex 取自 SLS.getLogIndex(),与 SLS 每条日志的 logIndex 是同一个自增计数器,按 uuidAppExec 从 0 递增(logIndex++ 发生在 send 之后)。

于是在同一次 uuidAppExec 内成立一条等价关系:

回放画面某一帧的 extInfo.logIndex = N ⟺ SLS 里该 uuidAppExec 的第 N 条日志

反过来也成立,而且 uuidAppExec 同时是 rrweb 录屏的索引键之一。conversationId 也逐条写进 extInfo,是「按会话找录屏」的根因字段(后端需要把它落成索引列)。

实际用起来是这样的:BOSS 的 bossDialogGuard 日志直接带一组「录屏句柄」字段:

字段含义
recordEnabled取自 canRecordPage。为 false 表示这次没有录屏可查,排查时不必再找
recordFileName录屏文件名(来自 getTaskRecordLocator),完整对象键要上传后才能拼出
recordUuid即 dbRrweb 主键,可用来查整条录屏记录
detectedAt检测时刻,与 rrweb 同机同钟,可据此 seek 回放
observationId每次上报表一个随机串,用来区分「同一个弹窗报了两次」

有意思的是 scene 字段的类型设计:它被定义成字符串字面量的联合类型而非常量对象,理由写在注释里——联合类型能让调用点保留字面量,于是「SLS 里搜到的就是源码里那个词」,可以直接反查代码。这是一个很小但很实用的可观测性约定:日志字段的值应当是可 grep 的。

要注意跨启动的 logIndex 不可比(各自从 0 起),对齐只在同一个 uuidAppExec 内成立。

这套对齐之所以可信,还得益于日志侧本身的不丢保障:SLS 会把未上报的日志按周期备份到本地数据库(用「条数 + 首尾 logIndex」作指纹去重,内容没变就跳过写盘),下次启动再分片补传(每片 200 条)。中途崩溃时备份完整保留,已发送的分片会重复,但重复优于丢失——重复的按 logIndex 去重即可,而一旦丢一条,后面所有序号就全错位了。换句话说,logIndex 能被当成对齐键,前提是日志链路本身愿意为它牺牲去重。

九、回放工具链

排查机侧由 skill rrweb-replay 提供完整链路,与 frontend-debug、sls-log 相互独立又相互验证:

flowchart LR
    A["URL / objectKey<br/>或 SLS 定位键"] --> B["fetch_rrweb.js<br/>鉴权 + 下载 + ZIP 校验 + 解压"]
    B --> C["to_replay.js<br/>replay.html + replay-data.js + timeline.json"]
    C --> D["与 SLS 按 logIndex 交叉验证"]
  • 下载:私有 OSS 直连 403 属正常表现(App 的凭证是 upload-only),fetch_rrweb.js 会用本机身份自动签发临时 GET URL 并立即重试——优先 ali-oss SDK + 环境变量凭证,失败回退 aliyun oss sign。签名 URL 只在进程内存流转,不回显、不落盘。
  • 生成回放页:产出 replay.html + 同目录的 replay-data.js(两者必须放一起)+ timeline.json。事件数据外置是为了避免大事件量时浏览器解析卡死。回放页右侧是 logIndex 时间线,点击即可跳转。
  • 样式内联:replay.html 左上角的「下载当前时刻 HTML」会导出独立自包含页面。serializeDocument 把外链 CSS(Node 侧预取打包成 bundled-css.js,绕过 CORS)、CSS-in-JS(从原始事件树收 _cssText)全部内联,并做 normalizeInvalidNesting(把内层 <button> 换成 <span>),避免非法嵌套导致 HTML 重解析时结构漂移。
  • 交叉验证:先用 conversationId 在 SLS 找到该次 uuidAppExec,再按 logIndex 双向对齐——日志报错的 logIndex → 回放页跳到该时刻看画面;回放里异常的一帧 → 回该 uuidAppExec 第 N 条附近日志定位是哪个 method。

这里最有价值的其实是最后一句:两者一致时结论可信度拉满;而画面异常但日志无对应错误(或反之),本身就说明存在日志盲区或静默失败——这是单看任何一侧都发现不了的问题。

十、已知坑清单

坑处理
同源 iframe 的 mutationBuffers 只增不删 → BOSS 简历 wasm OOM自维护 fork + blockSelector 补丁
隔离世界抓不到页面 JS 写入的表单值nc-input-poll 轮询补录插件
补录事件指向 rrweb 尚未收录的节点 idmirror.getId 未命中则不发、等下一轮
页面 stopPropagation 挡掉 input 监听与 rrweb 一致用 {capture: true, passive: true}
radio 同组兄弟被误判为「值变了」而重复补发原生事件后把同 name 的兄弟项基线一起更新
observer 里抛异常导致整段录制起不来(rrweb 不兜 try/catch)observer 全程包 try/catch
智联 Teleport 导致 adds 顺序倒置、replayer 丢子节点reorder-adds 拓扑排序插件
停录后 100ms 内仍有节流尾事件延迟 250ms ack + IPC FIFO 顺序 + waitInflightSaves drain
已缓冲事件压在定时器里、晚于 ack 到 main停录时与延迟期满各 flush 一次
未在录时白等 250mswasRecording 为假则立即 ack
「事件已送达」不等于「已落盘」(ipcMain 是 fire-and-forget)inflightSaves 登记 + 停录上传前 drain
并发 flush 把 writeBuffer 清两次、数据丢失flushingPromise 重入保护 + 等完在途 flush 再刷一次
单条 JSON.stringify 失败污染整批下发丢弃该条,不中断整批
重启后续写旧文件时分片判断失准fileBytes 缺失时用磁盘实际大小播种一次
入池导航污染录像停录必须早于 releaseToPool
复用同 contentId 导致上传串档 / 重复上传停录时快照 uuid + uploadingUuids 排除 + uuidOwnerTask 粘滞绑定
同一 wc 被并发 release、重复 stop/uploadreleasing in-flight 锁 + idle/owner 所有权守卫
异步窗口后误清新 run 的 contentIdCAS:同时校验 runId + contentId
上传失败被当成已清理失败即 return 中断,留库待补传
每个事件一条 IPC 挤爆主通道preload 300ms / 512KB 批量
每个事件同步落盘阻塞主进程main 侧 3s 缓冲 appendFile + 内存字节计数 + 写库前全字段比较短路
内联外链样式导致快照巨大inlineStylesheet: false

十一、小结

把这条链路拆开看,它的复杂度几乎全部来自四件事:

  1. 保护主进程不被高频 IO 拖垮——批量 IPC、renderer 侧序列化、main 侧缓冲落盘,三道缓冲一脉相承;
  2. 复用窗口下不串档——粘滞绑定、uuid 快照、uploadingUuids、CAS 清理,每个都在处理「状态该在什么时候固化」;
  3. 批量化之后的容错——一旦把「每个事件一条」改成「一批一条」,每一步都得回答「丢一条会怎样」:单条序列化失败就丢该条、并发 flush 要防清两次、上传失败要留库而不是当已清理、ipcMain 是 fire-and-forget 所以送达不等于落盘;
  4. 自维护 fork 修上游的内存泄漏——把 npm 包拷进仓库,用两行补丁换掉一个 wasm OOM。

而让它从「能录」变成「有用」的,是那行 extInfo.logIndex。录屏本身只是数据,能和时间轴上的日志对上,它才是证据。