简介JGB28181是一套基于Java实现的GB28181国标信令平台源码面向安防视频监控开发者、系统集成商及需要对接国标设备的学生工程师。项目核心涵盖设备注册、目录查询、实时视频流TCP被动/UDP等基本功能修改config.properties配置文件即可完成本地部署适合用作国标协议学习与实际项目二次开发的基础框架。资源包共49个文件以43个Java源文件为主辅以2个XML配置、1个properties属性文件、1个yml配置及README文档压缩包仅64KB结构精简便于快速阅读核心信令逻辑与配置项。简介还保留了功能更新日志与国标QQ交流群信息方便使用者跟进版本变化。目前已有4241人浏览学习说明其在国标接入场景中具备参考价值。下载后可直接获取完整工程源码通过研读注册、目录查询、实时流会话建立等代码实现能加深对GB28181协议交互过程的理解并为自研业务系统嵌入国标能力提供可运行的最小示例。1. 国标接入的 Java 解法JGB28181 平台到底解决了什么干过视频监控对接的人都知道最折磨人的不是镜头装歪了而是不同厂家的设备 SDK 各有一套今天调海康的 SDK明天调大华的 SDK后天又来一个不知名厂家的私有协议时间全耗在适配上了。某次做一个跨区域联网项目现场接了三种不同品牌的 NVR 和 IPC光联调就折腾了两周后来换了思路让所有设备走 GB28181 国标协议接入一个统一的 Java 平台两天搞定。JGB28181 就是这一类基于 Java 实现的国标平台核心是把 SIP 信令、RTP 媒体流、设备目录管理这些本来要逐个对接的脏活统一收口让上层业务只关注一件事拿到标准化的设备树和实时视频流。适合被私有 SDK 折磨过的后端开发也适合要快速搭建国标监控平台的团队。2. 先弄清国标接入的基本盘SIP 信令与 RTP 媒体流的职责边界2.1 国标 28181 不是协议是一套会话规矩第一次接触 GB28181 的人容易误以为它是一个像 HTTP 那样的“协议”上手后才发现它是一整套“会话规矩”。国标的核心思路是把视频监控的联网通信拆成两条独立通道一个是信令通道负责设备注册、目录查询、实时点播的请求与响应走的叫 SIPSession Initiation Protocol另一个是媒体通道负责实际传输音视频码流通常走 RTP。信令通道像是打电话时“先拨号、等待接通”的过程媒体通道是接通后“说话”的过程两者分离但状态关联。平台侧的角色也由此划分需要有一个 SIP 服务端来接收设备上报的注册消息维护设备在线状态同时要有一个媒体接收模块监听 RTP 端口把设备推上来的码流解析出来再转交给上层的流媒体服务或播放器。JGB28181 在 Java 生态里做这件事核心依赖的是 SIP 协议的 Java 实现库和 RTP 的底层 Socket 收发能力。选 Java 而不是 C 或 Go优势在于后端团队能直接用熟悉的 Spring 体系去做业务扩展设备管理、权限控制、录像检索这些功能能快速长出来。设备接入的过程可以分成三步理解设备上线时先向平台的 SIP 端口发送注册请求平台回 200 OK设备进入在线状态业务系统要看到某路视频时平台向设备发 INVITE 请求设备回 200 OK 后开始往指定 IP 和端口推 RTP 流平台收到 RTP 流后解析封装转成可播放的格式。这套流程在所有国标设备上一致这也是平台能替代私有 SDK 的根本原因。2.2 平台模块怎么划分信令服务、媒体收流、业务接口三块各管各的看一个国标平台实现得好不好先看它的模块边界是否清晰。标准的 JGB28181 平台在代码层面会分成三大模块。第一个模块是信令服务负责启动一个基于 Java 的 SIP 监听端点通常监听在 5060 端口UDP。这个模块处理设备注册、注销、心跳保活、目录查询请求、云台控制指令核心工作是把 SIP 消息解析成内部事件对象再交给业务层处理。第二个模块是媒体收流负责监听一组 RTP 端口当设备推流时接收数据包解析 PS 封装Program Stream提取 H.264 或 H.265 的视频帧然后通过转封装或直接转发的方式输出。这里的关键是端口管理和码流平滑处理端口分配策略决定了并发路数的上限。第三个模块是业务接口层是给上层系统用的。基于 Spring Boot 暴露 HTTP API比如查询设备列表、发起实时点播、停止点播、查询录像文件列表。这三个模块在 JGB28181 里是分开实现的信令模块不直接碰媒体数据媒体模块也不关心业务逻辑。理解这个概念后再回头看“平台”这两个字的含义——它不是简单的视频播放器而是一个信令与媒体分离的中间层。设备厂商不再需要暴露私有 SDK 给集成商只需要支持国标协议上层业务系统也不关心设备品牌只需要调用平台接口。技术栈上Java 的并发模型天然适合同时处理大量设备的信令交互一个设备一个注册会话SIP 事务的状态管理用 ConcurrentHashMap 就能很好地处理。2.3 代码里看信令接入基于 Java 的 SIP 注册处理核心逻辑直接看代码最能说明问题。JGB28181 的注册处理可以抽象成一个监听器关键代码结构如下Component public class SIPRegisterHandler { private final DeviceRegistry deviceRegistry; public SIPRegisterHandler(DeviceRegistry deviceRegistry) { this.deviceRegistry deviceRegistry; } public void handleRegister(SipRequest request) { // 从 SIP 消息的 From 头解析设备 ID国标设备的编码是 20 位数字 String deviceId extractDeviceIdFromHeaders(request); // 从 Contact 头解析设备上报的 IP 和端口后续回复和发流都用这个地址 InetSocketAddress deviceAddress extractContactAddress(request); // 校验设备 ID 格式20 位数字中心编码 类型 序号 if (!isValidDeviceId(deviceId)) { // 日志记录非法设备 ID不回复 200 OK设备会因超时自动重试 log.warn(收到非法设备ID {}, deviceId); return; } // 构造 SIP 200 OK 响应带上 Via、From、To 等头字段 SipResponse okResponse buildOkResponse(request); // 向设备地址发送响应 sipSender.sendResponse(okResponse, deviceAddress); // 更新平台内的设备在线状态表记录最近注册时间 deviceRegistry.updateOnlineStatus(deviceId, deviceAddress); // 国标要求注册成功后必须立刻发一条目录查询请求拿到设备下的通道列表 sendCatalogQuery(deviceId); } }这段逻辑里两个细节比较关键设备 ID 的 20 位编码是国标的基础约定比如中心编码 8 位加上设备类型码 2 位加上行业编码 2 位再加序号校验这一步不能省否则垃圾消息会污染设备表注册成功后立刻发目录查询这是国标的标准交互顺序。另一个细节是用ConcurrentHashMap维护设备地址与 ID 的映射因为 SIP 是无连接的每次请求都要靠设备 ID 来定位回复地址。实际项目中设备地址要保存最后上报的地址而不是注册表里首次记录的地址因为很多设备在心跳里会更新自己的 IP 和端口。2.4 媒体接收通道的端口规划与线程模型设备推流是另一个独立的体系。在 JGB28181 的实现里RTP 收流端口需要提前规划不能每路流都随便占用一个端口。常见做法是配置一个端口范围比如从 30000 到 40000每路点播会话从范围里分配一个未被占用的端口。这个范围决定了平台能同时处理多少路实时流如果范围太小会出现点播报错“无法分配端口”的情况。媒体模块的线程模型也需要注意。每收一路流就创建一个线程的写法在并发高时会崩溃正确做法是使用 Netty 的 EventLoop 线程组来处理 RTP 数据包数据解析用独立的工作线程池。数据结构上每路流用一个会话对象维护当前收到的 RTP 序列号和 PS 包的组装状态同一个设备的多次点播也要分配不同的会话避免串流。另外RTP 包中 PS 封装的解析要注意时间戳的处理不处理时间戳直接转发的方案会造成播放器无法倍速拖动处理时间戳的方案则需要维护一个映射缓存。3. 把 JGB28181 平台跑起来从环境准备到一路现场视频点播3.1 部署环境的硬性要求JDK 版本、数据库选型与端口清单从零部署 JGB28181 平台需要准备的环境比想象中要简单但也有些版本上的硬性要求。JDK 建议使用 8 或 11 版本国标项目里大量依赖的 SIP 库和 Netty 组件在这些版本上表现最稳定某些开箱即用的实现里打包的依赖还停留在 javax 命名空间直接跑在 17 上会报模块访问错误。数据库用 MySQL 5.7 或 8.0 即可平台的主要存储内容是设备表、通道表、录像索引量级不大不需要分库分表。Redis 是可选项如果追求设备状态能在多实例间共享就用它存状态单机部署可以省掉。端口规划上最低需要三个端口范围信令模块的 SIP 端口默认 5060UDP媒体收流端口范围建议至少 100 个连续 UDP 端口以及业务接口的 HTTP 端口常用 8080。生产环境部署时还有一个容易忽略的点SIP 信令走 UDP意味着防火墙要放行 UDP 协议而不仅是 TCP如果只放了 TCP设备能注册但不能收流因为 RTP 也是 UDP 承载。遇到过最典型的问题是云服务器安全组默认全开 TCPGB28181 设备的注册报文发进来就被丢弃表现就是设备一直在“注册中”。3.2 初始化配置application.yml 里的参数逐项说明平台启动前需要改的核心配置在application.yml里。以下是我在模拟项目X里使用的配置模板逐条说明参数含义server: port: 8080 # 业务 API 的 HTTP 端口给上层系统调用 sip: server: ip: 192.168.1.10 # 平台的 SIP 服务对外地址必须填实际网卡 IP不能填 0.0.0.0 port: 5060 # SIP UDP 监听端口国标固定为 5060一般不改 domain: 34020000002000000001 # SIP 域20 位国标编码标识本平台身份 password: 12345678 # 设备注册时校验的密码设备端要配置一致 media: rtp: port-range-start: 30000 # 媒体收流起始端口 port-range-end: 40000 # 媒体收流结束端口动态分配给每路点播会话 packet-session-timeout: 30 # 收流会话超时时间超过 30 秒没收到包则释放会话 catalog: auto-query-on-register: true # 设备注册后自动发起目录查询拉取通道列表 mysql: url: jdbc:mysql://127.0.0.1:3306/gb28181?useUnicodetruecharacterEncodingutf8 username: root password: your_password logging: level: com.jgb28181: debug # 建议启动排查时开 debug 级日志domain这一项是很多人配错的。它标识的是平台自身在国标网络里的编码设备注册时会把From头里的域字段和平台配置比对不一致会拒绝注册。另外media.packet-session-timeout直接影响资源回收速度。参数设太短会导致偶尔网络抖动时点播中断设太长会占用无用端口。30 秒是折中值。除此之外还有设备密码的配置项这个是国标注册过程的密码校验一般设备端默认填平台的 ID 或者统一密码要和这里的password保持一致。3.3 启动平台与检查设备注册状态的三个命令配置改完之后启动平台用 Spring Boot 的标准方式即可# 前端启动方式适合本机调试日志直接打在终端 java -jar jgb28181-platform.jar --spring.profiles.activedev # 生产环境中推荐后端启动方式日志重定向到文件 nohup java -jar jgb28181-platform.jar --spring.profiles.activeprod logs/platform.log 21 # 启动后确认 SIP 端口处于监听状态 netstat -unlp | grep 5060启动后第一个要确认的是 UDP 5060 端口是否真的在监听。用netstat检查时注意加-u参数只看 TCP 看不到 UDP 监听。接下来在设备管理平台里添加一台设备填入平台 IP 和 SIP 域然后观察日志。如果设备注册成功日志中会出现一条类似“设备注册成功34020000001320000001”的记录同时平台会自动发起目录查询拉动设备下的通道列表。如果没看到注册日志先用 tcpdump 在服务器上抓 UDP 5060 端口确认报文是否到达tcpdump -i any udp port 5060 -n -vv这段抓包能快速区分问题方向。有包到了服务器但平台没反应是平台解析问题包根本没到是网络或设备配置问题。实际调试中用 tcpdump 二十秒就能定位八成以上信令问题比来回改设备配置高效得多。3.4 走通第一路实时点播从 API 到 RTP 收流的全链路验证设备在线后第一路实时点播的验证流程值得完整走一遍。平台暴露的接口一般长这样# 查询设备下的通道列表从返回结果里拿到 channelId curl http://192.168.1.10:8080/api/devices/34020000001320000001/channels # 发起实时点播请求 curl -X POST http://192.168.1.10:8080/api/play/start \ -H Content-Type: application/json \ -d { deviceId: 34020000001320000001, channelId: 34020000001320000001, streamType: live, ssrc: 123456, mediaHost: 192.168.1.10, mediaPort: 30000 }发起点播后平台的内部处理链路大致是收到 HTTP 请求后创建一个会话从端口范围里分配一个 RTP 收流端口把媒体地址放在 INVITE 请求的 SDP 描述里下发给设备设备解析 SDP 后用 RTP 协议把码流推到对应端口。所以验证时要盯两个层面——信令层看 INVITE 是否发送、设备是否回了 200 OK媒体层看 RTP 端口是否收到 UDP 包。用下面的命令看收流情况# 观察指定 RTP 端口收到多少包 tcpdump -i any udp port 30000 -n | head -50 # 如果 RTP 端口收到连续包说明信令链路和媒体发流链路都通了 # 此时在平台里停止点播确认平台向设备发 BYE 请求释放会话这个流程如果一路走通整套平台的核心链路就没有问题了。第一路通了之后再挂多路设备基本就只是端口分配和数据库写入的性能问题。值得提醒的是点播成功后要在终端拉一段流到 VLC 里验证可播放性有的平台能做到“收到 RTP 包但 PS 封装解析有问题”表现是平台显示流在线但画面出不来这个需要结合信令和 SDP 协商来排查。4. JGB28181 平台的避坑指南注册不上、点播黑屏、掉线的真相都在这里4.1 设备注册一直失败平台日志里连 SIP 报文都看不到现象设备配置了平台 IP 和端口状态一直显示离线平台日志没有任何收到注册消息的记录。原因UDP 端口被防火墙拦截是最常见的原因其次是设备配置的 SIP 服务器地址不可达。云服务器上安全组规则只放行了 TCP 端口而国标 SIP 注册走的是 UDP 5060报文直接被丢弃。解决先在服务器上执行抓包确认报文是否到达再用firewall-cmd --add-port5060/udp --permanent添加 UDP 端口放行云服务器则需要在安全组同时添加入方向的 UDP 5060 和 RTP 端口范围规则。我一般会把 RTP 端口范围和业务端口一并放行避免后续联调再次踩坑。4.2 注册成功了但点播画面一直黑屏平台能看到建流客户端播放无输出现象平台日志显示注册成功、点播正常、RTP 收到大量包但用 VLC 拉流没有画面。原因两个方向最常见。第一平台发给设备 INVITE 请求里的 SDP 携带的媒体地址填了监听地址或内网地址设备的 RTP 流发到了错误的地址第二收到的 RTP 流是 PS 封装的 H.264但播放器不支持或者流里没有关键帧播放器拿到的是不完整的码流无法起播。解决第一类问题在平台配置里把 SIP 服务 IP 和媒体收流 IP 明确填为服务器实际网卡地址第二类问题需要先抓包看 RTP 包内容确认是 PS 封装然后检查是否有关键帧。如果视频编码是 H.265要确认播放端是否支持。平台如果能配置转码可以先把 H.265 转成 H.264 验证链路再排查播放端解码能力。另外还有一个点是 SDP 里的y字段有些设备要求这个字段的 SSRC 和实际发送的 SSRC 一致不一致设备也会推流但平台侧会话匹配会出问题。4.3 设备稳定运行一段时间后频繁掉线心跳超时和网络扰动分不清现象设备上线后运行几个小时随后在平台里频繁上下线每次间隔几十分钟。原因国标设备依靠 SIP 心跳保活默认心跳周期一般为 60 秒平台需要在设备连续三次心跳超时后才判定离线。如果平台里心跳超时时间配置过短比如设成了 30 秒网络只要有一次延迟就会误判离线。另一个原因是平台侧的设备表更新有并发问题多条设备的注册和心跳消息同时到达时丢失了部分更新。解决把心跳超时时间设成心跳周期的 3 倍以上比如设备 60 秒心跳平台配置 180 秒超时。把设备状态更新操作加上同步锁或改为原子更新避免并发写入覆盖。还可以在设备管理页面加一个“最后心跳时间”字段结合 NTP 校时观察能更准确判断是平台判离线还是设备真离线。4.4 级联对接上级平台时上级平台看不到下级设备现象平台同时开启了作为“下级平台”向上级级联的配置级联显示成功但上级平台列表中看不到注册上来的通道。原因国标级联的流程是两个层面平台向“上级平台”注册注册成功后平台要主动发送目录查询请求推送本域内所有设备的信息。很多实现只做了注册忽略了注册成功后主动推送目录的步骤。解决在平台的 SIP 模块里检查是否有注册成功后自动发送目录信息的实现。如果没有需要手动在管理页面触发“目录推送”或者改造代码在收到上级平台的 MESSAGE 目录查询消息后把本域所有设备信息封装成 XML 回复。这个逻辑并不复杂但漏掉一步就会导致上级平台侧一片空白定位时需要同时在上级平台看信令日志区分是“注册失败”还是“目录查询没有响应”。4.5 平台重启后设备全部离线注册鉴权密码错乱现象平台重启几分钟内所有设备疯狂重连但大部分设备注册失败。原因国标注册有密码校验机制。设备端配置的注册密码是固定的平台配置正确的情况下重启只需要重新注册一次就能成功。但如果平台的数据表被重置过设备 ID 和密码的映射表丢失或者设备端配置的平台 SIP 域不对就会反复重试失败。解决重启前先备份数据库的device表确认设备的密码字段没有被重新初始化为默认值。批量接入时建议用统一密码并固定在两端配置中减少单点配置错误。遇到重启后大批量重连失败先抓包确认设备是否收到 401 未授权的响应收到就是密码校验问题直接看两端的密码配置。5. 把 JGB28181 平台用得更顺手的三个技巧5.1 用级联模式把平台当作上级平台接入未知名设备很多场景下 JGB28181 平台不只是接入设备还要作为下级平台对接第三方的国标平台。级联调试三步法可以帮你快速跑通先在参考配置里开放“平台接入域”步骤为# 添加一个上级平台账户配置上级平台的 SIP 域和 IP curl -X POST http://localhost:8080/api/platforms/add \ -H Content-Type: application/json \ -d { platformDomain: 34020000002000000002, platformIp: 192.168.2.20, platformPort: 5060, deviceId: 34020000002000000001 }平台会向目标 IP 发起注册请求并默认推送全部设备信息。如果上级平台迟迟看不到通道用 tcpdump 抓 5060 端口看两边是否完成 REGISTER 事务再重点看上级平台是否发送CATALOG查询以及回复的 XML 里设备编码是否正确。级联模式下最重要的是“域”和“设备 ID”必须全国标规范否则上级平台校验不过注册就失败。5.2 用抓包工具区分信令问题和媒体问题排查国标问题时80% 的“疑难杂症”可以通过抓包一次性定性。信令层面重点看 REGISTER 消息是否被回复INVITE 消息的 SDP 内容是否包含正确的 IP 和端口媒体层面看 RTP 包的 payload type 和 SSRC 是否跟 INVITE 中协商一致。SSRC 不对是常见的不显示画面的原因因为平台侧不知道收到的包属于哪个会话。抓包时建议同时抓 SIP 端口和分配的 RTP 端口把信令和媒体放在一个 pcap 文件里回放时能对应起来。5.3 平台稳定运行的日常维护日志轮转与端口回收检查平台长时间运行后有两个容易被忽视的点。一是日志文件没有配置轮转策略时debug 级别日志会轻松撑爆磁盘Spring Boot 中可配置logback-spring.xml按天轮转并保留 7 天。二是端口回收异常点播断开后如果代码里有Socket.close()被异常跳过或超时线程未清理端口会逐步耗尽。日常巡检可以写一行脚本检查已使用端口数量# 统计当前媒体端口的占用数如果持续增长不下降说明有会话泄漏 netstat -unlp | grep -E 30000|30001|30002 | wc -l正常情况端口数是和活跃点播数对应的如果断开后端口数不降就要去会话表里看是否有残留记录。自从有一次因为端口泄漏导致扩容前一天晚上 4 路流直接推不出去之后我养成了每次上线前都跑一遍端口检查脚本的习惯。这套平台只要把注册、点播、级联这三条链路摸透后面维护起来基本没有大坑。希望帮到你。本文还有配套的精品资源点击获取