视频流诊断工具使用说明

2026-08-13 · 技术文档 · VVAN

视频平台诊断台 · 使用说明

因工作需要做了一个排查视频流「卡不卡、掉不掉帧、能扛几路」的工具。 单文件 HTML，依赖全部内置，断网也能用。

一、先决定你要不要下载它

这是最容易走弯路的地方，先看清楚：

你要做的事 在线页面够吗 说明
调平台接口、取播放地址 ✅ 够 打开网页就能做
设备体检、看在线状态 ✅ 够 同上
实际把流播出来看 ❌ 不够 必须下载到本地
并发压测、掉帧统计 ❌ 不够 依赖播放，同上

为什么播放必须下载？

拉流要连 ws:// 开头的地址。浏览器有条铁律：HTTPS 页面里不允许出现 非加密的 WebSocket 连接（叫「混合内容」）。这是浏览器强制的， 网站方绕不过去，代理也绕不过去。

页面存到本地之后，地址栏是 file:// 而不是 https://，这条限制就不存在了。

所以正常用法是：在线页面用来调接口，下载到本地用来看流。

二、下载到本地

在线页面右上角有个 「⤓ 下载本页」，点它，存到任意目录。

然后用 Chrome 或 Edge 直接打开这个 .html 文件（双击即可）。

打开后你会发现顶部那条黄色提示没了、下载按钮也没了——这是正常的， 本地模式下它们没有意义，页面自己判断出来了。

Safari 对 MSE（流媒体解封装）的支持有出入，建议用 Chrome 系。

三、连上你的平台

左侧第一栏「平台接入」，先选模式：

模式怎么选

视频平台在公网（有域名或公网 IP）
  └─ 在线代理     ← 什么都不用装
视频平台在内网（10.x / 192.168.x / 专网）
  └─ 本地代理     ← 需要跑一个 Python 脚本，见第五节
视频平台明确放行了 CORS，且你不介意密钥出现在页面里
  └─ 浏览器直连   ← 一般用不上

页面打开时会自动探测，能用哪个就默认选哪个。 标题旁边的小圆点会显示当前状态，比如「本地代理已连接 · 1 个平台」。

填参数

字段 说明
签名方式 平台用哪套签名算法。天翼视联选「天翼视联」，公开接口选「不签名」
平台地址 带端口，如 https://1.2.3.4:9193。结尾不要加斜杠
APPID / APPKEY 平台给你的接入凭证
USER-ID / CUSTOMER-ID 选填，部分平台的接口要求

地址和 APPID 会记住，APPKEY 每次都要重填——这是故意的，密钥不留在浏览器里。

用本地代理并且在配置文件里配好了平台的话，上方会多一个下拉， 选中之后这些字段会隐藏：地址和密钥由本机脚本提供，页面根本不碰。

先自检一次

填完点 「⚙ 自检」。它会拿当前配置真打一次平台接口，把三样东西摊开给你看：

  • 接口返回的 code 和耗时
  • 本次签名的原文（就是拿去算 HMAC 的那个字符串）
  • 平台返回的完整响应

签不过的时候，直接看签名原文对不对，比猜是不是被防火墙拦了有用得多。 常见错法：地址结尾多了斜杠、APPKEY 前后带了空格、时间戳所在机器时间不准。

四、开始诊断

路线 A：从摄像头编号开始（推荐）

  1. 在「摄像头国标编号」里填编号，一行一个
  2. 选取址接口：
    • livestream —— GET 请求，配合 outProtocol=12 出 ws-flv，浏览器最好播
    • getDeviceMediaUrl —— POST 请求，支持静音出流，可以规避 G.711 音频问题
  3. 点 「⤓ 取址并播放」

取到的地址会自动填进下面的「流地址」框并开始播。

只想拿地址不想播，点「仅取址」。 想先确认设备状态，点 「⚕ 设备体检」——它查在线状态、可用状态、网络类型这些， 排除「设备本身就不在线」这种低级原因。

路线 B：已经有流地址

直接把地址粘进「流地址」框，一行一路，点 「▶ 开始」。

路线 C：只想探测不想播

点 「◎ 取址并探测」 或 「◎ 探测流」。 它只建立连接看看流的元信息（编码格式、分辨率、帧率），不真正解码，很快。

五、内网平台：跑本地代理

平台在内网时，在线代理路由不到，需要在你自己的机器上跑一个中转脚本。

cd 文件下载后存放目录
python3 stream-proxy.py

只用 Python 3 标准库，不装任何依赖。macOS 和大多数 Linux 自带 python3， Windows 到 python.org 装一个。

跑起来之后回到页面，模式切到「本地代理」，它会自动探测到。

为什么内网平台需要它

两个原因，缺一不可：

  1. 浏览器不允许网页直接读取第三方平台的响应（平台不返回 CORS 头）。 代理由你本机发请求，绕开了这道限制。
  2. APPKEY 是签名密钥，放进网页任何人都能看到。它留在本机配置文件里，不进浏览器。

至于内网可达——请求从你本机发出，你能访问的平台它就能访问。

六、看懂结果

关键指标

指标 含义 怎么看
掉帧率 解码器丢弃的帧占比 超过阈值（默认 2%）判定异常
卡顿次数 每分钟画面停顿次数 超过阈值（默认 1 次/分）判定异常
缓冲水位 播放器手里囤了几秒数据 持续走高说明网络喂不上或解码跟不上
端到端延迟 从推流到看到画面的时间 追帧开启后会被压低

阈值在左下角「判定阈值」里可以改。它只影响红黄绿的判定，不影响实际测量值。

三个容易误判的坑

缓冲一直涨 ≠ 网络差。 也可能是解码跟不上（CPU 不够、分辨率太高）。 看 CPU 占用能区分：网络问题时 CPU 不高，解码问题时 CPU 打满。

掉帧 0% 不等于没问题。 如果流本身帧率就低（比如推流端只有 5fps）， 解码器无帧可丢，掉帧率当然是 0，但画面照样卡。要结合实际帧率一起看。

单路正常不代表多路正常。 并发压测才是真实场景，见下节。

导出

点 「⤓ 导出报告」 存成文件，方便贴进工单或邮件。 做过主辅码流对比的话，「⤓ 导出对比报告」会把两组数据并排放。

七、并发压测

测「这台机器/这条线路能扛几路」。

左侧「阶梯参数」三个值：

参数 默认 含义
每阶新增路数 1 每一阶加几路
每阶保持秒数 12 每一阶跑多久再加下一阶
最大路数 16 加到几路为止

从 1 路开始，每 12 秒加 1 路，直到 16 路或者出现异常。 异常出现的那一阶，就是这套环境的实际上限。

压测建议开着 「断流后自动取新址重连」——很多平台的播放地址带 token 且有效期短， 不自动续的话测到一半会因为 token 过期断流，被误判成性能问题。

八、解码器选项

一般不用动，遇到具体问题时才调：

选项 什么时候开
Worker 线程解封装 多路并发时开，把解封装挪出主线程，界面不卡
追帧降延迟 延迟持续增大时开。缓冲超过上限就快进，压到下限
stash 缓冲 网络抖动时开，牺牲一点延迟换流畅
静音 音频编码是 G.711 时开，浏览器不支持它，不静音会报错

追帧的两个阈值要一起看：下限不能太小，抽干缓冲反而会更卡。 默认「超过 3 秒开始追、追到剩 1 秒」是个比较稳的组合。

九、排查清单

现象 多半是什么
页面探测不到本地代理 脚本没跑，或端口不是默认的 8788
自检返回非 0 的 code 看签名原文。地址多斜杠 / 密钥带空格 / 本机时间不准
自检提示连接超时 本机到平台网络不通，需要接 VPN 或专网
取到地址但播不出来 检查是不是在线页面——播放必须下载到本地
画面出来但没声音 音频是 G.711，浏览器不支持。勾「静音」即可
播一会儿就断 token 过期。开「断流后自动取新址重连」
证书错误 平台用自签证书，在本地代理配置里把 insecure 设成 true

十、隐私

  • 页面不上传任何数据。所有测量都在你的浏览器里完成。
  • APPKEY 不存浏览器，刷新即失。
  • 走在线代理时，密钥随当次请求传给服务器用于签名，用完即弃，不落库不写日志。
  • 走本地代理时，密钥全程不离开你的机器。
  • 在线页面运行在沙箱环境里，读不到你在本站的任何信息。

十一、工具下载

正在加载文章