从 NowFind 看 rrweb 会话录屏链路设计
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,脚本任务页)。出问题时可以只关掉其中一条,不用全量停录。
真正有意思的是配置项本身,每一项都对应一个具体的成本:
| 配置 | 值 | 为什么 |
|---|---|---|
checkoutEveryNms | 1 小时 | 全量快照太大,基本等于关掉;整页导航本身就会产生新快照 |
slimDOMOptions | 'all' | 源头剥离 <script> / 注释 / head meta / favicon / title,直接压缩 FullSnapshot,收益贯穿 IPC + 磁盘 + zip + 上传整条链路 |
inlineStylesheet | false | 默认 true 时每次全量快照会同步读同源外链的 cssRules,强制样式重算,是重 DOM 页最贵的单帧主线程操作;实测 BOSS 首页 2.7MB 快照中外链内联占了 1MB |
blockSelector | iframe[src*="/web/frame/c-resume"], .resume-detail iframe, .resume-detail-wrap iframe | 挡掉简历 iframe,配合前面的 fork 补丁防 wasm OOM |
sampling.mousemove | 0 | 必须为 0,否则鼠标移动会被节流采样、数量对不上 |
sampling.mousemoveCallback | 0 | 减少保存频率 |
sampling.scroll / media | 100 | 节流窗口 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 侧有三个配套动作:
stopRecord()内部立即flushRecordBuffer()。否则已缓冲的事件还压在 300ms 定时器里,会晚于 ack 到 main,直接破坏 FIFO 顺序。- 延迟期满后再
flushRecordBuffer()一次,然后才发page:rrwebStopped——把「~100ms 内仍可能 emit 的尾事件已入缓冲」这件事落成事实,再让 ack 排在它们后面。 - 未在录时不延迟。
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 尚未收录的节点 id | mirror.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 一次 |
| 未在录时白等 250ms | wasRecording 为假则立即 ack |
| 「事件已送达」不等于「已落盘」(ipcMain 是 fire-and-forget) | inflightSaves 登记 + 停录上传前 drain |
并发 flush 把 writeBuffer 清两次、数据丢失 | flushingPromise 重入保护 + 等完在途 flush 再刷一次 |
单条 JSON.stringify 失败污染整批下发 | 丢弃该条,不中断整批 |
| 重启后续写旧文件时分片判断失准 | fileBytes 缺失时用磁盘实际大小播种一次 |
| 入池导航污染录像 | 停录必须早于 releaseToPool |
| 复用同 contentId 导致上传串档 / 重复上传 | 停录时快照 uuid + uploadingUuids 排除 + uuidOwnerTask 粘滞绑定 |
| 同一 wc 被并发 release、重复 stop/upload | releasing in-flight 锁 + idle/owner 所有权守卫 |
| 异步窗口后误清新 run 的 contentId | CAS:同时校验 runId + contentId |
| 上传失败被当成已清理 | 失败即 return 中断,留库待补传 |
| 每个事件一条 IPC 挤爆主通道 | preload 300ms / 512KB 批量 |
| 每个事件同步落盘阻塞主进程 | main 侧 3s 缓冲 appendFile + 内存字节计数 + 写库前全字段比较短路 |
| 内联外链样式导致快照巨大 | inlineStylesheet: false |
十一、小结
把这条链路拆开看,它的复杂度几乎全部来自四件事:
- 保护主进程不被高频 IO 拖垮——批量 IPC、renderer 侧序列化、main 侧缓冲落盘,三道缓冲一脉相承;
- 复用窗口下不串档——粘滞绑定、uuid 快照、
uploadingUuids、CAS 清理,每个都在处理「状态该在什么时候固化」; - 批量化之后的容错——一旦把「每个事件一条」改成「一批一条」,每一步都得回答「丢一条会怎样」:单条序列化失败就丢该条、并发 flush 要防清两次、上传失败要留库而不是当已清理、ipcMain 是 fire-and-forget 所以送达不等于落盘;
- 自维护 fork 修上游的内存泄漏——把 npm 包拷进仓库,用两行补丁换掉一个 wasm OOM。
而让它从「能录」变成「有用」的,是那行 extInfo.logIndex。录屏本身只是数据,能和时间轴上的日志对上,它才是证据。
