简介基于Java实现的GB28181国标平台源码面向安防视频监控领域的Java开发者和需要对接国标设备的工程师可用于学习GB28181协议的信令交互、设备注册、目录查询与实时视频流传输实现。压缩包共49个文件约64KB以43个Java源码文件为主体配合XML、properties、yml等资源文件搭建完整可运行的工程骨架代码规模精简适合按模块逐层阅读。项目当前已实现注册、恢复、目录查询以及实时视频流TCP被动/UDP等基础能力通过修改config.properties配置即可编译运行方便在本地环境快速搭建国标平台进行联调验证。已有4241人学习下载源码目录结构清晰可帮助读者在短时间内理解GB28181平台的核心实现思路并作为二次开发或协议深入研究的有价值参考。对于正在着手国标设备接入或视联网项目开发的团队也是一份难得的实战参考资料。1. JGB28181当业务系统需要直接接入国标设备时Java 平台该怎么选做过安防平台接入的人都有体会设备的 SIP 注册、INVITE 点播、SDP 协商、RTP 收流这套流程看起来协议文档写得明明白白真联调起来却处处是坑。JGB28181 这个名字代表的正是一套完全基于 Java 技术栈实现的 GB28181 国标平台——它把设备接入、信令交互、媒体流转发、录像回放这些能力从 C 的世界搬到 JVM 生态里让做业务系统的团队不需要维护两套技术栈直接用 Spring Boot 那套熟悉的方式把视频能力嵌进自己的平台。适合谁适合手里已有 Java 业务系统、需要快速接入海康大华等厂家设备、又不想被私有 SDK 绑死的团队。本文要解决的问题很直接JGB28181 的核心能力边界在哪怎么从零把它跑起来SIP 和 RTP 的哪些参数最影响对接成败以及生产环境里最常见的五个坑是什么。2. 平台底座SIP 信令与 RTP 媒体流分离的架构逻辑2.1 为什么必须把信令和媒体拆成两个独立模块GB28181 规范本身就把通信拆成了两个平面SIP 负责设备注册、心跳、点播请求、云台指令这些控制信息RTP 负责真正的音视频数据搬运。JGB28181 在架构上延续了这种分离思想信令层和媒体层不共享状态只通过约定的通道交互。这样的好处很实际信令服务可以多实例水平扩展媒体服务则可以独立部署在靠近设备侧的服务器上两者互不拖累。常见做法是媒体节点单独部署信令节点只处理每秒几千次的事务请求。如果哪天 RTP 收流异常导致媒体节点 CPU 打满信令节点依然能正常响应设备注册业务侧顶多看到点播超时而不会出现设备集体掉线的灾难。这是我在生产环境里验证过的选型理由——把故障域切小比任何高可用设计都实在。在 JGB28181 里信令层通常基于 Java 的 SIP 栈实现如 javax.sip 规范的开源实现负责解析 From/To 头域里携带的设备国标编号、Via 的地址信息、SDP 体里的媒体描述媒体层则维护每个通道的 RTP 接收端口、SSRC、时间戳基准。既然是分离设计两者之间就需要一个协调者——这通常由业务层来完成收到 INVITE 后业务层分配媒体端口再把 SDP 组装好交给信令层返回给设备。2.2 平台目录结构里值得先看的三类模块拿到 JGB28181 的工程代码后不用急着读全部源码按三个维度切入最快jgb28181 ├── sip-server # SIP 信令服务负责注册、呼叫、控制指令 ├── media-server # 媒体服务负责 RTP 收流、转推、录像写入 └── web-api # 业务 API设备管理、级联配置、点播接口sip-server 里最核心的是处理 SIP 消息的各类 Handler比如注册请求的鉴权逻辑、INVITE 请求的 SDP 解析、BYE 请求的会话清理。media-server 里的 RTP 接收器决定了平台能同时接入多少路设备以及每路流的编解码缓冲策略。web-api 则是给业务系统调用的 HTTP 接口层点播、录像查询、云台控制都从这里进出。生产部署时一般把三个模块打成三个进程用 Nginx 把 web-api 暴露给内部业务系统。2.3 依赖选型SIP 栈选谁、RTP 处理用什么Java 生态里能用的 SIP 实现并不多主流的就那一两个成熟方案。常见做法是选基于 javax.sip 标准规范的实现因为它在 Servlet 容器、独立 JVM 两种模式下都稳定。RTP 侧也有现成的 Java 媒体框架可用但生产环境里更多是直接用 Netty 做 UDP 收流——GB28181 的 RTP 承载在 UDP 上Netty 的 NIO 模型处理高并发 UDP 收包非常合适内存可控、线程模型清晰。参数上需要关注的不是框架本身而是 JVM 的启动参数。信令节点建议给足堆内存并开启 G1 回收器媒体节点反而要限制堆内存把更多系统内存预留给 Netty 的堆外缓冲。这个反直觉的选择很关键RTP 数据包进出走的是堆外内存堆内存设置过大只会增加 GC 压力对吞吐没有帮助。我一般这样设置# 信令节点 java -Xms2G -Xmx2G -XX:UseG1GC -jar sip-server.jar # 媒体节点堆外缓冲为主 java -Xms512M -Xmx512M -XX:MaxDirectMemorySize2G -jar media-server.jar信令节点堆内存给 2G 是因为 SIP 消息解析会频繁创建字符串对象媒体节点给 512M 堆内存是因为 RTP 数据主要在堆外流转。如果你的业务场景里视频流的 PS 封装解析也在 Java 层完成堆内存要相应上调但不要超过 1G否则 GC 停顿会成为新的瓶颈。3. 从零搭建本地跑通 JGB28181 的最小步骤清单3.1 准备阶段需要哪些基础设施和软件版本在动手之前先明确依赖项。JGB28181 作为 Java 项目JDK 版本、构建工具、数据库是三个绕不开的东西。版本上优先选 LTS 的 JDK构建工具用 Maven 或 Gradle 都行但 Maven 的依赖解析更直观工程里如果带 mvnw 就直接用它省的本地环境不一致。数据库一般选 MySQL用于存设备信息、通道信息、录像索引。还有一个容易忽略的准备工作确认本机的 UDP 端口范围。GB28181 的信令默认走 5060媒体接收端口是一个范围比如 10000 到 20000。如果机器上有防火墙一定要把这些端口的 UDP 入站打开否则设备注册成功了、点播却一直收不到流。涉及容器部署的端口映射也要把 UDP 一并映射很多团队在 Docker 里只映射了 TCP 导致媒体流不通这个坑后面避坑章节会专门提。3.2 配置文件中必调的三个参数组JGB28181 的配置文件一般集中在一个 application.yml 里按信令、媒体、业务三块组织。打开配置文件后第一件事不是改数据库密码而是确认这几个参数sip: id: 34020000002000000001 # 平台自己的国标编号20 位数字 ip: 192.168.1.100 # 平台 SIP 服务对外 IP port: 5060 # 平台 SIP 监听端口 password: admin123 # 平台 SIP 密码设备注册时要填 domain: 3402000000 # 平台域编码 media: ip: 192.168.1.100 # 媒体服务对外 IPSDP 里会带这个地址 port-range: 10000-20000 # RTP 接收端口范围 rtp-packet-size: 1400 # RTP 分包大小单位字节rtp-packet-size这个参数很影响兼容性。GB28181 设备大多支持 MTU 分片但如果把 RTP 包限制在 1400 字节以内可以规避很多路由器对超大 UDP 包的丢包问题。常见做法是设置在 1200 到 1400 之间某些厂商的老设备对大于 1500 字节的 RTP 包会直接丢弃调小这个值立竿见影。sip.id和domain的编号规则要按当地行政区划编码来不能随便填否则会出现设备注册成功、但是上级平台不认你这个编号的情况。3.3 启动服务并模拟一台设备完成注册平台本身启动没什么特别的把三个模块启动后看日志输出。重点要看的是启动完成后控制台是否打印了 SIP 服务的监听地址和端口。接下来用模拟设备验证注册流程这里最常用的工具是 SIPp 配合定制的 XML 脚本或者直接用国标设备模拟器——网上能找到不少开源模拟器能模拟注册、心跳、点播响应整套流程。注册这个动作的本质是设备向平台 SIP 服务发送一条 REGISTER 请求平台回复 401 带上随机挑战码设备用密码做摘要认证后再次发送 REGISTER平台校验通过后回复 200。日志里能看到这个过程就算跑通了注册链路。接着验证点播业务侧调用平台的点播 HTTP 接口平台向设备发送 INVITE设备回 200 OK 并携带 SDP 描述平台解析 SDP 后开始收流。完整链路是# 业务侧发起点播 curl -X POST http://127.0.0.1:8080/api/play \ -H Content-Type: application/json \ -d {channelId: 34020000001310000001, streamType: 1}channelId是设备下某个通道的国标编码streamType填 1 表示主码流填 2 表示子码流。请求返回后会给一个流 ID 和拉流地址用 VLC 播放这个 RTSP 或 HTTP-FLV 地址能看到画面就说明整个链路通了。这个阶段不要急着调清晰度、接告警先把链路跑起来最重要。4. 关键交互细节SIP 消息字段与媒体参数对对接成败的影响4.1 REGISTER 与 INVITE 交互里必须对齐的字段GB28181 的 SIP 消息和标准 SIP 最大的区别在 To/From 头域的取值——不是用户名而是 20 位国标编号。设备注册时From 头里带的是设备自己的国标编号To 头里带的是平台的国标编号。这个字段没对齐最常见的现象是设备日志显示已发送注册请求但平台侧没有任何收到报文的日志。收到 REGISTER 后平台回复 401 时realm字段的值要和配置文件里的domain保持一致nonce是随机生成的挑战码。设备端计算摘要认证用的密码正是配置在设备里的 SIP 密码——这个密码在设备侧和设备侧各有一份任何一边填错了REGISTER 的第 3 步设备带认证信息重发就会失败。INVITE 请求里最需要关注的是 SDP 的y字段它描述了设备媒体流的 SSRC、端口和 IP 地址。平台解析 SDP 时如果对y字段格式兼容得不好会导致点播流程走完但收不到流。还有一条很隐蔽的规则INVITE 的Subject字段在 GB28181 里有特殊的格式要求它携带了发送方和接收方的编号中间用空格分隔。如果这个字段的编码不对有些设备会直接拒绝呼叫。调试这类问题时抓包看 SIP 信令最直观常见的抓包工具都能解析 GB28181 的 SIP 包重点看 REGISTER 的 3 步交互和 INVITE 的 4 步交互是否符合预期。4.2 SDP 协商y 字段、媒体编码与 RTP 收流端口的对应关系设备在响应 INVITE 时返回的 SDP 体里y字段是最关键的一行。它由 10 位十进制数组成前 8 位是 SSRC后 2 位是 RTP 负载类型标识。平台侧需要根据这个字段确定接收 RTP 包时的 SSRC 过滤条件。如果 SSRC 对不上典型的故障现象是端口有数据进来但平台认为流未建立。有些平台的实现会放宽这个校验只按端口收流不做 SSRC 校验但生产环境中还是保留校验更稳妥避免串流。编码协商上GB28181 的媒体描述中视频一般走 H.264 或 H.265音频走 G.711 或 AAC。平台侧要对 SDP 里的rtpmap做兼容处理设备返回 96 号动态负载类型对应的编码是 H.264 还是 H.265必须从rtpmap属性里解出来。很多自研小平台在这里偷懒默认所有 96 都是 H.264结果接到 H.265 设备时花屏或者直接黑屏。JGB28181 的标准实现里这块逻辑要看完整的媒体能力协商而不是简单按负载类型号猜编码。值得注意的是SDP 里的c字段表示媒体流的接收 IP。有些设备的c字段可能写的是内网 IP如果平台和设备的网络模型存在 NAT 转换收流的 RTP 地址要按y字段解析得到的外网映射来处理不能直接拿c字段去连。这方面的经验是把 y 字段解析成一个独立的模块做单元测试用不同厂商设备返回的 SDP 样本验证解析逻辑的鲁棒性比联调时再去抓包定位要高效得多。4.3 心跳机制与超时判定设备在线状态不准时的元凶GB28181 设备会按配置的间隔向平台发送心跳消息通常是 30 秒到 60 秒一次。平台收到心跳后要刷新设备的在线状态同时把心跳时间记录到数据库。生产环境里最容易出现的问题是平台侧为了减轻数据库压力把心跳写入做了异步批处理结果进程崩溃或服务重启后丢失了一批心跳记录设备明明在线却显示离线。常见做法是加一层缓存心跳只写内存状态查询先读缓存再定期把缓存里的状态快照持久化。在线状态判定的超时阈值建议设成心跳间隔的 3 倍而不是 2 倍。比如设备心跳间隔 30 秒平台侧 90 秒没收到心跳才判定离线。2 倍阈值太紧只要网络上偶发一个丢包设备就会在平台侧显示离线随后又自动恢复这种抖动在监控墙上的表现就是设备图标闪烁非常干扰运维判断。另外设备重启后会重新注册平台收到 REGISTER 时如果设备已经处于在线状态要把旧的会话和媒体资源全部释放再做新会话的建立否则端口和会话资源会慢慢泄漏终有一天点播全部失败。5. 生产部署与压力下的行为并发点播、级联和录像回放的取舍5.1 并发点播的资源预算一路流吃多少内存和带宽先算一笔账。一路 1080P 主码流按 4Mbps 码率算一分钟产生 30MB 数据。平台对每一路流的处理涉及三个环节UDP 收包、PS 解封装、转推给播放端。每个环节都有缓冲一路流占用的内存大约在 20MB 到 50MB 之间取决于缓冲时长配置。一个 8G 内存的媒体节点建议并发量控制在 100 路以内留足余量给 GC 和突发峰值。带宽侧的计算更直观100 路 4Mbps 主码流并发转发出口带宽至少在 400Mbps 以上。很多团队在测试环境用千兆内网跑通了 100 路上了生产发现客户处是百兆专线直接卡死。选型时一定要先跟客户确认接入带宽同时把子码流作为默认预览码流主码流只用于录像和回放。JGB28181 的按需拉流策略也很重要业务侧可以对空闲通道做自动断流间隔时间可配置这样能大幅降低空转带宽。5.2 级联对接平台作为下级向上级注册的实现要点级联场景在大规模组网里几乎必现。某市平台作为下级需要把通道推送给省平台本质就是把整个 JGB28181 平台当成一台超级设备向上级平台注册。配置时有几个参数要格外留意一是本级平台的 SIP 服务和上级平台的 SIP 服务要能互通域编码要按行政区划规范填二是向上级注册用的密码要和上级平台配置一致三是通道推送的国标编号必须全局唯一不同平台的通道编号冲突会导致上级平台刷新时掉线。级联的媒体流走向和平级接入不同。上级平台向本级发起点播时INVITE 的 To 头是通道编号本级平台收到后要反向去下级设备发起 INVITE把设备的流拉上来再转推给上级。这个过程中超时控制很重要本级设备响应慢了上级平台的呼叫可能已经超时释放导致转推时找不到会话目标。经验值是本级向下级设备发 INVITE 的超时设 5 秒整个级联呼叫链路的超时要统筹考虑不能各级独立拍脑袋。5.3 录像回放的时间轴拼接与存储策略GB28181 的录像回放涉及两种模式平台侧直接调设备的录像文件或者平台自己存储设备推上来的流。前者依赖设备的录像能力回放时走 SIP 的 INVITE 方法带Recorder参数后者则是平台侧持续收流写存储。生产环境里更稳妥的方案是平台录自己的流因为设备端的存储往往受 SD 卡容量限制而平台侧可以挂大容量存储做长时间留档。时间轴拼接是回放里最琐碎的活。设备在推流过程中可能出现短暂断流录像文件在存储侧会形成多个片段回放接口要把这些片段按时间顺序拼成一个虚拟时间轴。JGB28181 平台里解决这个问题的常见思路是维护一张录像片段表每条记录包含通道编号、开始时间、结束时间、文件路径。回放时按时间范围查出片段按开始时间排序逐个推给播放器。需要注意片段之间的时间间隙超过一定阈值时要在时间轴上留出空隙不能硬拼成一个连续流。6. 避坑指南JGB28181 对接生产中常见的五个故障现象6.1 设备注册成功但 30 秒后掉线重连现象是设备日志显示已收到 200 OK注册成功但每隔 30 秒左右又重新发起注册。原因是平台侧回复 200 OK 后没有正确处理后续的心跳设备的心跳请求被平台忽略设备侧认为平台无响应所以重新注册。解决方法是先确认心跳消息的处理逻辑在信令层加日志看心跳报文是否到达如果到达但没回复检查心跳处理 Handler 是否被异常中断比如解析心跳中的扩展字段时抛了空指针。这类问题抓包时一眼就能看出来REGISTER 三步交互是正常的但中间完全没有心跳消息的往来。6.2 点播请求返回 200 OK但播放端黑屏现象是 SIP 交互全部正常设备也收到了 200 OK但播放器拉流后一直黑屏查看媒体服务日志发现没有 RTP 数据到达。原因是 SDP 里的y字段解析后得到的收流地址和端口与媒体服务实际监听的地址端口不一致。排查顺序是先看设备日志里 SDP 构造时填的本地 IP再看平台收到的 SDP 原文最后确认媒体的 RTP 接收地址是否绑定在正确的网卡上。服务器有多块网卡时media.ip配置不当就会造成这种问题——SDP 里写的是内网地址设备往这地址发流但媒体服务监听的是另一块网卡。6.3 视频画面出现大量马赛克和花屏现象是画面能出来但花屏严重过几秒恢复然后又花屏。原因绝大部分是 RTP 分包大小和 MTU 不匹配导致的丢包或者设备发送的 RTP 包超出了平台接收缓冲。先查网络层面是否有丢包再用 tcpdump 抓 RTP 报文看是否有序列号跳变如果序列号连续但依然花屏问题就在 PS 解封装逻辑上某些设备的 PS 包携带了填充字节解析时没有跳过会导致后续帧数据错位。这类问题需要抓包比对 RTP 里的 PS 包头看解析代码是否正确处理了填充长度字段。6.4 Docker 部署后设备注册成功但点播超时现象是平台部署在 Docker 容器里设备注册没问题但 INVITE 发出去后设备一直不回复或者回复了但流到不了。原因是容器端口映射只做了 TCPUDP 端口没有映射。GB28181 的信令走 UDP 5060媒体收流也是 UDP 随机端口仅映射 TCP 端口远远不够。解决方法是把宿主机端口和容器端口完整映射媒体端口范围在 docker-compose 里逐个映射或者直接用 host 网络模式。生产环境中我一般建议媒体节点用 host 网络信令节点可以走桥接这样能减少端口映射的维护负担。6.5 平台重启后批量设备离线迟迟不恢复现象是平台重启完成但设备列表里大量设备显示离线等很久才慢慢恢复在线。原因有两个一是平台重启后 SIP 服务监听正常但设备端的心跳周期最长可能 60 秒设备还在按旧的时间间隔发心跳平台要等心跳来了才能重新确认在线二是平台侧注册会话缓存丢失设备重发心跳时找不到对应会话被当作未知消息丢弃。解决方法是平台启动后主动查询设备列表向已知设备发送 OPTIONS 探活请求或者调整设备端的心跳间隔到一个较短的周期让注册状态快速收敛。这个场景属于典型的平台重启恢复策略设计不到位提前在代码里做启动补偿就能避免。7. 进阶用法按需拉流策略与信令抓包定位问题的方法到这一步平台已经能稳定收流、正常点播了接下来值得投入的是两个方向一是把按需拉流做好让平台在设备接入量翻倍时不至于把带宽和硬件资源耗尽二是把信令和媒体抓包方法练熟任何对接问题都能在 10 分钟内定位到信令层还是媒体层。按需拉流的实现逻辑不复杂核心是维护每个通道的引用计数。播放器申请拉流时计数加一播放器断开时计数减一计数归零后启动一个延时任务比如 60 秒后发送 BYE 给设备断流这 60 秒的窗口可以避免播放器快速重连时反复向设备发 INVITE。如果在延时期间又有新的播放器申请同一通道取消断流任务即可。这个方案在设备数量大、观看人数少的场景里效果非常显著我见过一个 5000 路的平台在默认全量拉流时把带宽打满改成按需拉流后峰值带宽降了 80%。抓包定位问题的方法值得养成固定套路。先抓信令侧用 tcpdump 过滤端口 5060拿到 SIP 报文后看三个关键节点REGISTER 是否 3 步完成、INVITE 是否 4 步完成、BYE 是否正常结束。信令全通再看媒体侧过滤媒体端口范围看 RTP 包是否到达、序列号是否连续、SSRC 是否和 SDP 中 y 字段一致。这两个层面的数据一比对故障归属基本就定了。# 只抓信令 tcpdump -i eth0 udp port 5060 -w sip.pcap # 抓媒体流按 RTP 端口范围过滤 tcpdump -i eth0 udp portrange 10000-20000 -w rtp.pcap抓包文件用 Wireshark 打开后SIP 流可以直接按呼叫跟踪查看完整的交互时序RTP 流可以看丢包率和抖动。养成这个习惯之后你会发现 GB28181 平台的对接问题 90% 都能用这套方法定位剩下的 10% 是因为设备端的私有实现不标准需要找设备厂商要日志。最后说一个我自己的教训早期做对接时遇到花屏问题总怀疑是平台收流代码有问题反复调解析逻辑调了三天。后来抓包一看是客户网络里的交换机对大于 1500 字节的 UDP 包做了丢包处理设备发的 RTP 包每个都是 1492 字节接近 MTU 上限加上 IP 头刚好超过 1500丢包率虽然只有 1%但因为关键帧数据缺失导致花屏明显。把 RTP 包长限制调到 1200 字节后问题立刻消失。这之后我调任何 GB28181 平台第一件事永远是先确认网络 MTU 和设备的 RTP 包长策略而不是埋头改代码。这套排查思路希望对你有帮助。本文还有配套的精品资源点击获取