GBHub 国标视频平台

1. 登录与认证

平台使用 JWT Bearer Token 认证，所有 API 请求均需携带 Authorization 头。默认用户名 root，密码在首次部署时由管理员设置（默认 admin123）。

• 访问地址：http://<服务器IP>:3002（端口可在配置文件修改）。
• 登录：输入密码，点击“登录”或按回车键。
• 会话保持：登录后 Token 保存在浏览器 localStorage，刷新页面无需重新输入密码。若要登出，点击右上角“退出”。
• 修改密码：点击右上角“修改密码”，需提供当前密码和新密码（两次确认）。修改后原 Token 失效，需重新登录。
• 平台信息：点击“平台信息”可查看 SIP 服务器配置（设备 ID、域、监听地址、密码等），用于设备注册和级联配置。

2. 设备管理

2.1 查看设备列表

该页面展示所有已成功向平台注册的 GB/T 28181 设备。设备信息包含：

• 设备 ID：国标 ID（20 位数字）。
• IP：设备网络地址。
• 名称：设备自定义名称（可编辑）。
• 通道数：该设备下的视频通道数量。
• SSRC：是否启用 SSRC 校验。
• 传输：SIP 传输协议（UDP/TCP）。
• 状态：在线/离线（基于 SIP 心跳），点击状态标签可查看状态变化历史。
• 操作：刷新通道、查看通道、编辑设备、删除设备。

2.2 添加设备（预录入）

平台支持手动预录入设备信息，设备上线后通过 SIP 注册自动填充 IP/端口。

• 设备 ID：20 位国标设备编码（必填）。
• 名称：便于识别的设备名称（可选）。
• 独立密码：为该设备单独设置注册密码（不填则使用全局密码）。

2.3 设备状态历史 新增

点击设备列表中的“在线”或“离线”状态标签，弹出模态框显示该设备的状态变化记录。

• 数据来源：由定时任务 sync_device_status 同步产生，仅当设备状态发生变化时写入。
• 显示内容：状态（在线/离线）和变化发生的本地时间（自动转换为浏览器时区）。
• 分页：支持每页 10/20/50 条记录切换。
• 适用场景：排查设备频繁离线问题、了解设备在线率。

2.4 设备注册配置

平台本身不主动扫描设备，所有设备必须通过 SIP 协议主动注册。请按以下步骤在摄像头端配置：

1. 获取平台 SIP 参数：点击右上角“平台信息”，记录：
   • SIP 服务器 ID（如 34020000002000000001）
   • 域（Realm）（如 3402000000）
   • SIP 监听端口（默认 UDP 6060）
   • 密码（默认 QSAe6780）
2. 进入摄像头 Web 管理：通常通过浏览器访问摄像头 IP，登录后找到“网络设置”或“高级配置”中的“SIP”或“28181”选项。
3. 填写注册参数（参考下表）：

   参数	说明	示例值
   SIP 服务器 IP	平台服务器的 IP 地址	192.168.1.100
   SIP 服务器端口	平台监听端口（UDP/TCP）	6060
   SIP 服务器 ID	平台设备 ID	34020000002000000001
   域	平台域	3402000000
   设备 ID	摄像头唯一 ID（建议按规则编制）	34020000001320000001
   密码	平台注册密码	QSAe6780
   传输协议	UDP 或 TCP（建议 UDP）	UDP

4. 保存配置，摄像头将发送 SIP REGISTER 请求。注册成功后，平台设备列表出现该设备，状态变为“在线”。

2.5 通道操作

点击设备行的“📂 通道”按钮，列出该设备的所有通道（如摄像头各视频流）。每个通道支持以下功能：

• 实时直播：点击 “WS‑TS” 或 “WebRTC” 按钮，打开播放器观看实时视频。
• 停止播放：点击“⏹ 停止”按钮，关闭当前播放并释放资源。
• 截图：点击“📸 截图”，平台请求设备抓拍一张图片，成功后自动打开新窗口显示。
• 设备录像：点击“📼 设备录像”，弹出时间选择器，查询该通道在设备本地存储的历史录像文件（需设备支持）。
• 截图历史：点击“🖼️ 截图历史”，查看该通道所有已保存的截图列表，可预览或删除。
• 批量设置：勾选多个通道，可批量开启/关闭子码流，或批量指定节点。

2.6 设备录像查询

在通道列表中点击“设备录像”，选择起始时间和结束时间，系统会向设备发送历史录像检索请求。返回结果包括：

• 文件名、开始时间、结束时间、文件大小。
• 支持三种播放方式：WS‑TS（转码播放）、WebRTC（低延迟）、MP4播放（直接下载或浏览器预览）。
• 关闭回放窗口时，系统会自动停止拉流，避免资源浪费。

2.7 编辑设备配置

点击设备行的“✏️ 编辑”，可修改设备名称、SSRC 校验开关、传输协议和密码（密码留空则不修改）。保存后设备将重新注册生效。

3. 级联管理

3.1 上级平台配置

若本平台需级联到上级 SIP 域（例如公安视频联网平台），需添加上级平台信息：

• 设备 ID：上级平台分配给本域的设备 ID（通常为 20 位数字）。
• 服务器 ID新增：上级平台的 SIP 服务器 ID（当上级要求区分设备 ID 和服务器 ID 时使用）。若未提供，默认使用 device_id。
• 域：上级平台域（Realm）。
• 密码：上级平台注册密码。
• 上级地址：上级 SIP 服务器的 IP 和端口（如 10.0.0.1:5060）。
• 本地地址：本平台用于级联的本地 SIP 监听地址（默认 0.0.0.0:5070）。
• 传输协议：UDP 或 TCP。
• 协议版本新增：可选 2016 或 2022（默认 2022）。

3.2 通道绑定

将国标通道（由“设备ID_通道ID”组成）或非国标流（App+Stream）映射到指定的节点，实现流的分发管理。

• 添加绑定：填写通道 ID、流标识（推荐格式 设备ID_通道ID）、应用名（通常 rtp）。
• 一键绑定设备通道：从设备列表中选择设备，自动为该设备的所有通道创建绑定（流标识按 设备ID_通道ID 生成）。
• 选择通道：从已绑定列表中选择通道，自动填入表单。
• 通道名称管理新增：在绑定列表中可直接点击“✏️”按钮为通道设置自定义名称，该名称会显示在 Catalog 目录中（若未设置则显示通道 ID）。
• 批量操作：支持多选、全选、批量删除、清空全部绑定。
• 节点映射：列表中的“节点”列显示每个绑定当前分配的节点（可从节点下拉框修改）。

3.3 目录管理 独立导航

管理国标级联的行政区域名称、业务分组名称、通道自定义名称和通道归属，并主动推送目录给上级平台。

🏛️ 行政区域名称

为行政区划代码（2/4/6 位）设置友好显示名称，上级平台看到的目录树更直观。

• 设置：输入区划代码（如 340200）和名称（如 镜湖区），点击“设置”。
• 编辑：在列表中点击“编辑”回填到输入框，修改后重新设置。
• 删除：恢复为默认显示（如“区县级-340200”）。

📂 业务分组/虚拟组织名称

为国标编码（215 业务分组 / 216 虚拟组织）设置自定义名称，用于构建业务目录树。

• 编码规则：20 位编码的第 13~15 位必须为 215（业务分组）或 216（虚拟组织）。
• 层级关系：215 下只能包含 216 节点；216 下可挂载设备或拉流代理。
• 父子关系：通过编码前缀自动推断，前 12 位相同的 216 归属于对应 215。

🏷️ 通道名称管理 新增

为通道设置自定义显示名称，该名称将优先显示在 Catalog 目录中（若未设置则显示通道 ID）。

• 设置：输入通道 ID（20 位编码）和自定义名称，点击“设置”。
• 删除：移除自定义名称，恢复为通道 ID 显示。
• 快速操作：在级联管理 → 通道绑定列表中，可直接点击“✏️”按钮为通道设置名称。

🔗 通道业务分组配置

将通道挂载到指定的虚拟组织（216）下。

• 选择通道：点击“🔍”按钮，从已绑定的级联通道列表中选择。
• 选择虚拟组织：点击“🔍”按钮，从已创建的 216 类型编码中选择。
• 设置：保存配置，通道出现在对应虚拟组织下。
• 移除：取消分组，通道归入“未分组设备”。

📤 目录推送

主动向所有已注册的上级平台推送目录。

• 扁平列表：仅推送通道列表，无目录层级。
• 行政目录：按行政区划（省/市/区）组织通道。
• 业务目录：按业务分组（215/216）组织通道。
• 推送结果显示成功或失败的上级平台地址。

4. 系统管理 新增

位于右上角“平台信息”旁边，点击 “⚙️ 系统管理” 按钮进入。

• 备份配置：一键导出平台全部配置（包括拉流代理、推流代理、行政区域名称、业务分组名称、通道业务分组、通道绑定关系等）为 JSON 文件，用于系统迁移或灾备。
• 恢复配置：选择备份文件上传，支持“恢复前清空现有数据”选项，可完整恢复平台配置。
• 数据范围：覆盖代理配置、目录数据、通道绑定（正向与反向）、通道名称等所有核心配置。

5. 流管理

查看当前节点上正在发布的实时流（包括国标推流和拉流代理产生的流）。

• 刷新流列表：从当前选中的节点获取最新的流信息。
• 节点选择：可选择“自动（第一个在线节点）”或具体节点，切换后自动刷新列表。
• 流操作：
  • “WS‑TS” 和 “WebRTC” 按钮可直接在本平台播放器播放。
  • “地址” 按钮弹出所有协议的播放地址（RTSP、RTMP、HTTP-FLV、WS-FLV、HLS、HTTP-TS、WS-TS、fMP4 等），支持一键复制。

6. 云端录像

查询节点录制生成的 MP4 文件。这些文件通常由拉流代理（开启录制）产生，存储在节点的 /record/ 目录下。

• 查询条件：按通道 ID、App、开始/结束时间过滤。
• 结果列表：显示文件名、起止时间、文件大小，提供播放和下载按钮。
• 批量删除：勾选多个文件，确认后删除（不可恢复，请谨慎）。
• 分页：每页 10 条，支持翻页。

7. 拉流代理

拉流代理用于将外部 RTSP/RTMP/HLS 等流拉取到平台，转换为标准协议（FLV/TS/fMP4），并可选进行 MP4 录制。

7.1 添加拉流代理

点击“添加拉流代理”，弹出表单填写以下字段：

• Vhost：虚拟主机，默认 __defaultVhost__，一般无需修改。
• App：应用名（如 live、rtp），用于区分业务。
• Stream：流名称，唯一标识该流。
• 源流地址 (URL)：要拉取的流地址，支持 RTSP、RTMP、HTTP 等。
• 模式：常驻 表示持续拉流；按需 表示只在有播放请求时拉流（节省带宽）。
• 节点：选择执行拉流任务的节点，自动（轮询） 会随机分配在线节点。
• RTP 类型：RTSP 拉流时的传输方式（0-TCP，1-UDP，2-组播），默认为 TCP。
• 超时 (秒)：拉流连接超时时间，默认 15 秒。
• 开启 MP4 录制：勾选后，拉流代理会将视频流切片为 MP4 文件并保存。

7.2 参数详解

参数	类型	必填	说明
vhost	string	否	虚拟主机，用于多租户隔离
app	string	是	应用名，建议字母数字
stream	string	是	流标识，唯一性
url	string	是	源流地址，必须可访问
on_demand	bool	否	true=按需，false=常驻
节点	string	否	指定节点 ID，不填则自动轮询
rtp_type	int	否	0-TCP, 1-UDP, 2-组播
timeout_sec	float	否	连接超时（秒）
enable_mp4	bool	否	是否开启 MP4 录制
mp4_save_path	string	否	录制保存根目录（默认为节点配置）
mp4_max_second	int	否	切片时长（秒），默认由节点决定

7.3 FFmpeg 代理 新增

通过 FFmpeg 拉流代理，支持任意协议（HTTP、RTSP、RTMP、HLS 等），并由 ZLMediaKit 的 FFmpeg 进程完成拉流和转推。

• 源地址：支持任意协议的拉流地址（如 http://live.hkstv.hk.lxdns.com/live/hks2/playlist.m3u8）。
• 目标地址：推流地址，一般是推给自己（如 rtmp://127.0.0.1/live/hks2）。
• 超时 (ms)：推流成功超时时间，默认 10000ms。
• 开启 HLS/MP4：是否开启 HLS 或 MP4 录制。
• FFmpeg 命令模板 key：配置文件中 FFmpeg 命令模板的 key（非内容），默认使用 ffmpeg.cmd。
• 节点：指定 ZLM 节点 ID，不填则自动轮询在线节点。

7.4 录制配置

勾选“开启 MP4 录制”后，节点会将流以 MP4 格式切片保存。存储路径规则：/record/{app}/{stream}/{日期}/{文件名}.mp4。可通过 mp4_save_path 和 mp4_max_second 自定义。

7.5 备份与恢复

备份功能可导出所有拉流/推流代理的配置（含录制参数），恢复时可选清空现有代理再导入，适用于迁移或灾难恢复。

• 备份：点击“备份”按钮，浏览器自动下载 JSON 文件。
• 恢复：点击“恢复”按钮，选择备份文件，系统会解析并重新创建代理。恢复时若勾选“清空现有代理”，会先删除 Redis 中的原有代理再写入。

8. 推流管理

推流管理可将平台内的流（如国标设备流或拉流代理流）推送到外部 RTMP/RTSP 服务器，实现直播分发或云端收录。

• 必填参数：协议（RTMP/RTSP）、Vhost、App、Stream、目标地址（dst_url）、节点。
• 状态：显示“推流中”或“已断开”。
• 删除：停止推流并移除配置。

9. ONVIF 设备发现

通过节点扫描局域网内支持 ONVIF 协议的摄像头，快速获取 RTSP 地址并一键添加拉流代理。

• 搜索：选择节点（必须在线），设置超时时间（默认 9000ms），点击搜索，结果列出设备型号、ONVIF URL。
• 获取 RTSP：点击“📡 RTSP”，输入用户名密码，返回该设备的 RTSP 流地址（含认证参数）。
• 添加代理：点击“➕ 代理”，输入用户名密码，App 和 Stream 名称，系统自动创建拉流代理（默认不开启录制）。

10. 鉴权管理

为特定流（App/Stream）设置播放或推流 Token，实现访问控制。

• 设置：填写 App、Stream、类型（play/publish）、有效期（秒，0=永久）。
• 查询：查看现有 Token 及其剩余有效期。
• 删除：移除 Token。
• 带有 Token 的流，在访问 URL 时必须附加 ?token=xxx 参数，否则被拒绝。

11. 告警管理

查看设备通过 SIP 上报的告警事件（如移动侦测、视频遮挡、IO 报警等）。

• 查询：可按设备 ID、通道 ID、时间范围过滤。
• 列表：包含设备 ID、通道 ID、告警时间、描述信息。
• 删除：支持多选删除告警记录。

12. 用户管理

管理平台普通用户的访问权限。

• 添加用户：设置用户名和密码，新用户可登录查看分配的通道。
• 分配通道：为指定用户分配可访问的国标设备通道或拉流代理流（支持多选和分页）。
• 清理通道新增：一键移除用户权限中已不存在的设备通道或拉流代理，避免权限残留。
• 修改密码：管理员可为普通用户重置密码。
• 删除用户：移除用户及其所有权限。

13. 定时任务 更新

管理平台定时触发的任务，支持截图、录制、会话清理和设备状态同步。

📋 支持的任务类型

类型	说明	所需参数
国标设备	对指定国标设备的通道进行截图或录制	设备 ID、通道 ID、Cron 表达式
拉流代理	对拉流代理的流进行截图或录制	App、Stream、Cron 表达式
会话清理	扫描 Redis 会话，关闭无人观看的转发流并删除记录	仅 Cron 表达式
设备状态同步 新增	定时扫描设备在线/离线状态，写入 GreptimeDB	仅 Cron 表达式
清理录像 新增	定时清理指定保留天数前的录像文件和数据库记录	Cron 表达式、保留天数（默认7）
清理截图 新增	定时清理指定保留天数前的截图文件	Cron 表达式、保留天数（默认7）

⚙️ 设备状态同步说明 新增

• 用途：定时扫描所有设备，检测在线/离线状态变化，并将变化记录写入 device_status_log 表。
• 环境变量：
  • SYNC_BATCH_SIZE：每次扫描设备数，默认 2000
  • SYNC_MAX_ITERATIONS：单次最大循环次数，默认 10
  • DEVICE_OFFLINE_TIMEOUT_SECS：离线判定超时秒数，默认 180
• 执行响应：返回在线/离线计数和游标。
• 设置示例：Cron 表达式 */3 * * * * 表示每 3 分钟同步一次。

📝 Cron 表达式

使用 UTC 时间。例如北京时间 (UTC+8) 凌晨 3:00 对应 UTC 前一天 19:00，应写为 0 19 * * *。

14. 播放器使用

14.1 播放控制

平台播放器支持三种播放方式，可根据场景选择：

• WS‑TS：通过 WebSocket 传输 MPEG-TS 流，延迟约 < 1秒，兼容性好（几乎所有现代浏览器）。
• WebRTC：基于 UDP 的实时传输，延迟约 < 500毫秒，需浏览器支持（Chrome/Edge 推荐）。
• MP4 直接播放：用于录像回放，浏览器原生支持，若跨域受限可点击“新窗口打开”。

播放器界面提供暂停/恢复、音量、全屏等标准控制，并支持云台控制（仅对国标设备直播有效）。

14.2 云台控制

在播放器下方，若当前播放的是国标实时流，会出现云台控制面板：

• 方向控制：上下左右（长按连续移动）。
• 变焦：放大/缩小。
• 停止：停止所有云台动作。
• 预置位：显示已保存的预置位列表，点击可调用。
• 地址：查看当前流的所有协议地址。

14.3 自动重试 新增

播放器支持网络中断后自动恢复播放：

• WS‑TS：断线后自动重试最多 5 次，每次间隔递增（1s→2s→3s→4s→5s）。播放成功后计数器归零。
• WebRTC：连接中断时不显示错误提示，仅输出控制台日志，由浏览器 ICE 机制自动尝试重连。
• 多路播放器：每个通道独立维护重试状态，互不影响。

15. 常见问题与排查

Q1: 设备注册失败，状态离线？

• 检查平台 SIP 端口（6060）是否被防火墙阻止。
• 确认摄像头配置的 SIP 服务器 ID、域、密码与平台信息一致。
• 查看平台日志（logs/sip.log）中的错误信息，常见错误有 “401 Unauthorized”（密码错误）或 “404 Not Found”（ID 不匹配）。

Q2: 播放直播流时黑屏或卡顿？

• 检查网络带宽，尝试降低视频码率（在设备端设置）。
• 切换到 WebRTC 播放（低延迟）或尝试更换节点。
• 查看节点日志，确认是否有解码错误或丢包。

Q3: 拉流代理添加后状态为“未运行”？

• 确认源流地址是否可访问（用 VLC 测试）。
• 检查节点是否在线且能访问外网（若拉取外网流）。
• 查看节点日志，排查连接超时或认证失败问题。

Q4: 录制开启但云端录像查不到文件？

• 确认节点有写入权限（如 /record 目录）。
• 检查拉流代理是否持续运行（按需模式可能未激活）。
• 查看节点的 on_record_mp4 回调是否正常（需后端支持入库）。

Q5: ONVIF 搜索超时或找不到设备？

• 确保摄像头与服务器在同一子网，且 ONVIF 服务已开启（默认 80 端口）。
• 增大超时时间（如 15000ms）。
• 检查节点上是否已安装 onvif 相关依赖（后端实现）。

Q6: 备份/恢复代理时提示数据过大？

• 后端限制单次恢复最大 100 MB，若代理数量过多，请分批处理或联系管理员调整配置。

Q7: FFmpeg 代理添加失败？

• 确认 ZLM 节点已配置 [ffmpeg] 段，且 FFmpeg 命令可用。
• 检查源地址是否可访问，目标地址是否被占用。
• 查看节点日志中的 addFFmpegSource 相关错误信息。

Q8: 如何修改前端显示端口或节点地址？

• 前端端口在 common.js 的 window.PORTS 中修改。
• 节点地址在“节点管理”中添加或修改（该功能由管理员操作，不在本手册详述）。

Q9: 目录推送后上级平台未更新？

• 确认上级平台是否在线，且 SIP 注册正常。
• 检查推送类型是否正确（行政目录选 “admin”，业务目录选 “biz”）。
• 查看 sip-server 日志，确认 Catalog 消息是否成功发送。

Q10: 设备状态历史无记录？

• 确认定时任务“设备状态同步”已创建并启用。
• 检查同步任务是否正常执行（查看任务日志）。
• 若设备从未发生变化或同步任务尚未运行，列表为空。

Q11: 通道自定义名称未显示在 Catalog 中？

• 确认已在级联管理的通道绑定列表中设置了名称。
• 在级联管理中点击“刷新缓存”使缓存失效。
• 重新推送目录（行政或业务）使上级平台获取最新名称。