十轮排查定位一个“无声“：用WorkBuddy 接入第五种视频播放平台

十轮排查定位一个"无声"：用WorkBuddy 接入第五种视频播放平台

作者岗位：Java 后端 / 全栈开发（视频监控平台方向）
项目性质：企业级视频监控播放服务（多平台视频接入 + 云台/对讲/告警代理）

摘要

本文记录我用 WorkBuddy 完成的一次完整平台接入：从零新增第5 种视频平台（EasyNVR）到完成实时预览、历史回放、云台、对讲、告警、保活回收全链路，并在后续联调中通过十轮排查定位一个"对讲成功但设备无声"的疑难问题。

最终产出：后端新增 20 个类、43 个测试用例全部通过（其中 41 个单元测试 + 2 个真实连平台的联调测试），前端新增 7 个组件/工具模块，生产构建通过。

本文所述项目为内部系统，文中平台地址、账号、通道号、设备指纹等均已脱敏或以「A平台/ 通道 001」代称。

一、输入材料：接入前我手上有什么

这个播放器服务已经支持 4 种接入方式（大华 NVR 直连、海康 NVR 直连、大华 ICC 平台、萤石云），架构是「一套 API 屏蔽平台差异」：后端按accessType分发，统一返回playerType + url + other，前端按返回的类型自动选择播放内核。

要接入第 5 种平台 EasyNVR，我需要：

1. 平台接口文档——官方是Apifox 分享链接、带密码，WebFetch直接取返回未开放内容
2. 现有代码的约定——PlayerReq已有的字段、ICC/萤石回放怎么分发、@RsaAuth拦截器覆盖范围
3. 设备侧约束——现场是海康球机，通过 GB28181/UDP 接入

关键前置判断（这一步由 WorkBuddy 读代码后给出，直接决定了后面少走多少弯路）：

• PlayerReq里已有sessionId / playType / startTime / endTime，EasyNVR 的回放可以完全复用，零新增字段
• ICC 和萤石的回放实现就是"playback".equals(req.getPlayType())分发，EasyNVR 对齐同一模式即可
• 平台连接信息（IP/端口/账号/secret）全部走 token 载荷，不进配置文件、不下发浏览器，天然支持多平台实例

如果这三个判断错了，新增平台就要动PlayerReq、改签名、动鉴权链路——后面所有联调都要重跑。

二、WorkBuddy 配置与工作方式

我用的是项目级记忆 + 定时任务 + playwright 实测的组合：

补充说明：Apifox 带密码的文档，我是通过分享链接的llms.txt拿到全部接口的.md索引，再逐个抓取 OpenAPI 3.0 原文的——这个技巧被固化进了一个技能，后续接任何 API 文档都能复用。

三、操作步骤（含中途调整与问题处理）

3.1 方案先行，确认 8 个问题再动手

在写代码前，我让 WorkBuddy 先深读现有代码，把 EasyNVR 接入的 8 个待确认问题逐条给出结论并写入docs/EasyNVR播放器接入方案.md。其中三条最有价值：

①ssrc直接用sessionId
GB28181 回放要求ssrc作为会话标识贯穿「查询→ 倍速 → 停止」。方案结论是直接把PlayerReq.sessionId透传，全链路复用，不单独生成。但同时预留了降级路径：如果联调发现平台校验 GB28181 的 10 位数字格式，从 sessionId 哈希映射一个 10 位数字。

这个降级预留后来真的用上了——见3.3。

②disk_id写死但可配
官方文档示例值是 6，没有语义说明。我没有猜它的含义，而是写死成后端常量 + 留easynvr.disk-idyml 配置项，联调时可调。

③ 回放 seek = 重新拉流
官方文档没明说 flv 流能否 seek。我的判断是：不赌平台能力，seek 直接重新调/play（playType=playback、startTime=目标时间、复用同一 sessionId），暂停/恢复/倍速走平台 GB28181 控制接口。这样无论平台支持与否，功能都成立。

3.2 保活机制：解决"用户直接关浏览器"的泄漏

方案定稿后我意识到一个真实问题：用户几乎不会点关闭按钮，都是直接关浏览器/切页面，前端destroy()里的停止回放调用覆盖不到这条路。

而 GB28181 回放会话持续占用设备/NVR 的回放资源，单通道并发通常只有 1 路——泄漏一个会话，同一通道的后续回放会直接失败（提示资源占用/会话达上限），直到平台超时释放或设备重启。

最终方案是应用层 HTTP 心跳：

• 前端每 15sPOST /player-api/easynvr/heartbeat
• 后端EasyNvrSessionRegistry内存表记录lastActive，@Scheduled每 15s 清扫
• 45s（3 个心跳周期）无心跳 → 自动调平台停止预览/停止回放
• pagehide时用navigator.sendBeacon发一条尽力而为的离场通知

一处安全加固：心跳接口不走 RSA（避免每 15s 加解密开销），那裸sessionId就可以被伪造续命。分析下来伪造虽不能创建会话（play 有 RSA）、不能停止他人会话（停止接口有 RSA）、拿不到数据，但能给已知会话无限续命，正好造成我们要防的资源泄漏。所以play()时生成一个随机heartbeatKey（UUID）随PlayRes.other下发，心跳必须携带，不匹配直接拒绝。

宕机恢复分两层：

• 主：会话表落盘easynvr-sessions.json（登记/注销/清扫时写入，用临时文件 + 原子移动）。服务启动时加载，对已过期会话逐个调平台停止——用的是宕机前缓存的完整凭证，不受 token 30 分钟有效期限制
• 辅：后端重启后前端还活着的话，心跳会带原 token，注册表未命中时解密重建会话

残余风险我如实记录了：宕机 + 前端同时关闭 + 落盘文件也损坏的极端情况，残留会话只能等平台超时或后台手动清理。方案里没写"彻底解决"。

3.3 联调：ssrc 校验与CLOUD 回放的两个坑

ssrc 位数：联调报「SSRC需要大于 20 位，且不能重复」，且平台接受的是纯数字。改法是sessionId经 SHA-256 →BigInteger→mod 10^24→%024d补齐。关键是必须是确定性的——同一 sessionId 每次算出同一个值，否则倍速和停止接口引用同一个会话就找不到人了。降级预留刚好用上了。

CLOUD 源回放的 400：这个坑我拆成了三层排查：

1. CLOUD 源不接受disk_id（那是本地磁盘录像参数），传了就 400
2. 去掉disk_id后 200 了，但返回的url（叫.m3u8）实际响应是JSON 分段列表，hls.js 播不了，真正的播放列表在hls_url
3. 改用hls_url后报manifestParsingError——因为平台返回的 url 带查询串（...index.m3u8?...&source=CLOUD），我的.endsWith(".m3u8")判断被查询串干扰没触发。截掉?再判断路径解决
4. 仍失败——那时段平台云存没有录像，hls_url返回的是空播放列表。前端映射为「该时间段无录像数据」

最后我加了一条回归测试，同时断言「CLOUD 不带 disk_id」和「JSON url 换 hls_url」，防止回退。

3.4 浏览器侧疑难问题：为什么必须用 playwright

有两类问题纯靠日志推不出来，必须实际在浏览器里复现：

首开闪屏 + 喇叭失效。用 playwright-core + Edge channel 实测复现（首开报addSourceBuffer 达到上限，F5 后正常），定位到两个根因：

• FLV 元数据分次下发（音频轨晚于视频出现），mpegts.js 中途补建 audio SourceBuffer 报 limit。此前我的降级逻辑把这类瞬态错误切到 jessibuca（canvas 接管，画面重载感）。改成：降级只收窄到编解码层错误，SourceBuffer/MSE 类错误走 800ms 后自动重连（重建<video>），上限 2 次才降级
• jessibuca 3.x 的unmute()是无参调用，带 bool 参数实际不生效，静音切换失效

直播卡死看门狗。对讲时画面偶尔永久停在最后一帧——GB28181 侧音频广播触发重新 INVITE，部分设备会让平台重启推流，ws-flv 连接挂着但不再来数据且无 ERROR 事件。加了看门狗：playing后每 2s 采样currentTime，连续 3 次无推进判定卡死，走同一套重连。

https 对讲不出声（mixed content）。https 页面点对讲立刻变"不安全"。根因是对讲和 ws-flv 的地址都是平台返回的相对路径，后端用http/ws平台 host 补全，Chrome 判定混合内容拦截。同时揪出一个老 bug：talk()用了http://前缀补全talk_url，而new WebSocket("http://...")直接 SyntaxError——这个对讲从来没真正连上过。最终走 nginx wss 反代 +stream-host传参重写解决。

3.5 十轮排查：一次"对讲成功但设备无声"

这是整个项目最难的一环。前端talkSuccess正常触发、设备无声、没有任何报错。我按下面的顺序推进：

第 1-2 轮：地址选错。前端选对讲地址的逻辑是JSON.parse(token)取 streamHost——但 token 是 RSA+AES 加密串，JSON.parse必然失败返回空，导致永远落到公网地址，而主码流走的是内网地址，会话错位。改为按wsURL的 hostname 匹配（与主码流同源），兜底匹配响应innerIp。

第 3-5 轮：缺参数。读官方 SDK 源码（WSPlayer.js / PlaySDKInterface.js）发现两处：官方采集链路getUserMedia失败被.catch(function(e){})静默吞掉，表现就是"对讲中但无声且无报错"；官方通道模式会把StartTalk响应的sampleRate/audioBit传给内部编码器，而 talkByUrl 模式不传，编码器拿到 undefined。补上麦克风预检 + 默认 8000/16。

第 6-8 轮：请求体对齐。用户提供了 ICC 平台官方 StartTalk 载荷，逐字段对比发现我们缺channelSeq、talkmode/target/source/broadcastChannels、enableGBParamAutoAdapt，且audioType应是数字2不是字符串'2'。补上后仍无声，于是开 SDK verbose 日志（localStorage.playSDKLogLevel=6）做客户端逐行对比：

• 我们这边 OPTIONS/DESCRIBE 阶段反复报invalid onvif talk media index:-1, or back stream src is null
• ICC 网页这边一切正常，且DataSourceManager find live data src: talk/pu/237命中

结论是服务端会话状态不同 → 请求体仍不一致。继续对齐官方 WINPC 抓包载荷，发现talkType官方是字符串"1"（我们传数字导致会话异常）、缺optional（携带平台登录 token 做 MTS 会话绑定）、多传了gbDevice、需要 PSDK 顶层信封。

第 8 轮的关键证伪：我保持对讲时，在 ICC 页面对同一设备发起对讲，报「设备正在对讲中」——说明 MTS 真正注册了我们的会话，客户端链路已完全等价。嫌疑收敛到三项：后端代理账号权限、音频内容全静音、MTS→设备转发段。用户复查system是超管全权限，排除第一项。

第 9-10 轮：结案。我在麦克风预检里加了 RMS 电平实测（getUserMedia → AnalyserNode 采样 800ms 算 peak RMS）。第一版测出-inf，但发现是假静音：AudioContext在非用户手势的异步链路里创建会suspended，AnalyserNode 读数全 0。升级预检后（resume()+ 等待running+ 默认静音约束时改用原始约束重测 + 打印轨道 label）才拿到真实结论：

根因是系统选错了麦克风输入设备，浏览器采集到的是静音轨道。设备收到全 0 的 G711 流 → 无声、无报错、talkSuccess照常触发。用户切换正确麦克风后对讲正常。

这里有个容易误判的点值得单独记：talkSuccess在 RTSP PLAY 完成前就会触发，不能作为「会话就绪」的判据——早期音频帧会被丢弃（日志里 seq 从 11 起，说明前 10 帧已被丢）。

沉淀下来的排查顺序是：地址 → 参数对照官方抓包 → 会话注册验证（设备忙测试）→ SDP/RTP 层逐行对比 verbose 日志 → 麦克风 RMS 实测。

四、产出物

顺带沉淀的可复用方法：浏览器疑难问题的 playwright 实测流程（chromium 缺失时用channel: 'msedge'）、SDK verbose 日志开关定位法、RMS 麦克风实测（含 suspended 假静音陷阱）。

五、几点体会

方案先行比写代码值钱。8 个确认问题里，3 个直接影响了架构决策（复用 PlayerReq、ssrc 透传、seek 策略）。如果边写边定，这些改动会连锁影响鉴权、签名和测试。

把"平台文档说的"和"平台实际做的"分开。文档说停止回放必须显式调，但没给路径；说 flv 可能不支持 seek，所以干脆不赌。文档示例的disk_id=6没解释语义，那就写死可配。这些不确定性在联调里都会变成调试成本。

用户不会点关闭按钮。任何依赖前端钩子做资源回收的设计，在真实使用中都会漏。保活机制不是锦上添花，是 GB28181 单通道并发=1 这个约束下的必需品。

「成功回调」不等于「功能可用」。talkSuccess早于 PLAY 完成；addSourceBuffer的瞬态错误被误判为不可恢复错误导致画面重载；unmute(bool)在 3.x 里静默失效。三个 bug 共同指向一件事：不要相信"没报错"和"回调触发了"，要实测。

排查疑难问题时，证伪比枚举更快。「保持对讲时 ICC 页面报设备忙」这一句话，直接洗清了整个浏览器侧链路，把嫌疑从五项收敛到三项。如果没有这个实验，后面可能还在前端继续挖。