常见问题与排错
本文汇总 GT-Streaming 应用集成 阶段的常见问题与排查思路。错误码完整定义见 错误码定义。
打开媒体请求失败
返回 -27（终端不在线）
含义： 网关侧无该终端在线连接。
排查：
- 在演示站或自有监控系统确认终端识别号是否在线
- 检查终端主服务器地址、端口是否指向正确网关
- 若终端要求
ACC ON，确认信号线或模拟状态 - 确认 simNo 与网关登记一致（含前导零、长度）
返回 -5（超时）
含义： 规定时间内终端未成功推流。
排查：
- 终端是否在线但 1078 媒体通道 未建立（防火墙、NAT）
- 终端到 媒体服务 的推流 IP/端口是否可达
- 通道号是否有效（部分终端仅支持 1–4）
- 异步模式下是否在等待
ready通知而终端实际已失败（检查failed通知）
返回 -21（资源已被占用）
含义： 同通道已有冲突的媒体请求。
常见场景：
- 远程回放同通道只能有一路（不支持共享）
- 对讲占用后，不能再打开同通道实时/对讲
- 上次请求未正确关闭
处理： 关闭已有 reqId，或换通道/终端再试。参见 生命周期 · 共享打开。
返回 -3 / -2（执行失败 / 内部错误）
排查：
- 查看媒体服务与网关日志
- 终端是否连上后立即断开
- 打开参数是否合法（
dataType、channel、proto） - 偶发
-207（操作失败，请重试）可重试打开
返回 -10 / -18（token 问题）
处理：
播放器无画面 / 黑屏
| 检查项 | 说明 |
|---|---|
ready 是否为 true | 异步 + HLS 须等 ready 再创建播放器 |
playUrl 是否可访问 | 浏览器能否跨域/HTTPS 访问播放地址 |
| 协议是否匹配 | FLV 用 mpegts.js；HLS 用 hls.js |
| iPhone Safari | 不支持 FLV，须改用 HLS，见 flv-vs-hls |
| 保活是否中断 | 超时后流被关，播放器仍连接旧地址 |
HTTP-FLV 异步： 可提前创建播放器等待码流，或收到 ready 后再创建。见 生命周期 · 播放。
播放中途自动停止
最常见原因： 未调用 keep_alive。
- 实时与回放均建议 每 15 秒 保活一次
- 关闭播放器时同步停止保活定时器
- WebSocket API /
strm-js可自动处理
收不到 WebSocket / STOMP 通知
- token 不一致 — HTTP API 登录后 token 变更，但 STOMP 仍用旧 token 订阅
- 未订阅正确队列 — 流媒体通知：
/user/{token}/queue/strm - 异步打开但未订阅 — 无法感知
ready/failed/closed - 会话过期 — 重新登录并重建连接
建议新应用改用 WebSocket API 避免双连接问题。
多路播放问题
| 现象 | 原因 | 建议 |
|---|---|---|
| 同步模式只能开少量路 | 同步阻塞至终端响应 | 改用 异步模式 |
| 需多域名 | 同步模式浏览器连接数限制 | 异步模式或多域名方案 |
| 无法控制码流 | 非控制方 reqId | 仅 ctrl=true 的请求可切流 |
见 异步与同步模式。
对讲问题
| 现象 | 处理 |
|---|---|
-21 | 先关闭同通道其它播放/对讲 |
| 单向下行有声 | 检查 taUrl 连接与麦克风权限（须 HTTPS） |
| 2019 终端失败 | 调整长短号选项，见 对讲集成指南 |
远程回放问题
| 现象 | 处理 |
|---|---|
| 查询无文件 | 确认终端录像时间范围、通道 |
| 回放卡顿 | 网络或终端存储读取；可试子码流 |
| 拖动/快进无效 | 确认终端支持对应 9202 控制；模拟终端有限制见 monitor-tools |
录像上传问题
| 现象 | 处理 |
|---|---|
| 上传一直进行中 | 订阅 av_upload 通知 或轮询状态接口 |
| v4 上传失败 | 确认 fileSz 参数已传，见 迁移到 v4.0 |
| 上传参数错误 | 使用查询远程录像返回的完整文件信息 |
详见 终端录像上传和下载。
主动安全附件问题
| 现象 | 处理 |
|---|---|
| 无附件记录 | 确认已发 MQ 或启用自动提取 |
| 类型对不上 | 使用 v4 统一 ADAS 编码 |
| 任务 hanging | 查终端在线与 9208 响应 |
详见 主动安全附件集成指南。
推荐排查顺序
1. 终端是否在网关在线？
2. API 登录与 token 是否有效？
3. 打开接口 errCode 与 message？
4. 异步模式是否收到 StrmNotif（sent / failed / ready / closed）？
5. playUrl 能否在浏览器/播放器单独访问？
6. keep_alive 是否持续调用？
7. 查服务端与网关日志