简介这是一套面向FreeSWITCH开发者与视频监控集成工程师的GB28181国标视频接入模块源码包用于对接符合《GB/T 28181-2016》标准的网络摄像机、NVR及视频平台可作为国标视频统一接入网关的核心组件无需额外中间件即可编译集成。压缩包共9个文件约17KB包含核心实现文件mod_gb28181.c、跨平台构建脚本Makefile.am、Makefile.in、Windows工程配置.vcxproj、基础配置模板conf目录与自动加载配置说明autoload_configs另附Python演示脚本与README.md。模块支持SIP信令注册、心跳保活、RTP over UDP实时音视频流拉取、设备目录查询、云台控制及录像回放等关键功能适配FreeSWITCH主流版本。README.md详细说明了编译步骤、配置方法与典型部署场景便于读者快速理解目录结构与集成流程。目前已有65人学习下载适合需要快速验证国标接入方案或二次开发的中高级开发者参考。1. FreeSWITCH 接 GB28181为什么很多团队最后都绕回这套源码包做视频接入的团队大多经历过这个阶段设备侧是海康、大华、宇视这类标准 GB28181 摄像机平台侧却想用 FreeSWITCH 做信令和媒体调度。直接拿 SIP 硬怼注册能通、INVITE 能发但一到 PS 流解复用、RTP 时间戳对齐、录像回放就集体翻车。原因不复杂——GB28181 不是纯 SIP它是 SIP 信令 MANSCDP 控制 PS 封装 RTP 承载三件套缺一层都跑不起来。这套「FreeSWITCH 下 GB28181 国标视频接入模块源码包」解决的正是这个断层把国标设备的注册、心跳、目录查询、实时点播、历史回放、云台控制翻译成 FreeSWITCH 能识别的 channel 和 media bug让上层继续用 mod_conference、mod_record 这些现成能力。适合谁做安防平台对接、视频会议融合、执法记录仪汇聚的团队尤其是已经有一堆 FreeSWITCH 存量业务、不想再引一套独立流媒体服务的场景。下面按「先立住原理、再动手复现、最后讲坑」的顺序拆开。2. 国标信令与媒体面模块到底替你翻译了哪几层2.1 GB28181 的三层结构以及 FreeSWITCH 卡在哪一层GB28181 的交互可以粗暴切成三层。第一层是 SIP 信令层负责 REGISTER 注册、MESSAGE 传控制体、INVITE 建会话第二层是 MANSCDP 控制层用 XML 承载 Catalog 目录查询、DeviceInfo 设备信息、RecordInfo 录像检索、PTZCmd 云台指令第三层是媒体层设备把 H.264/H.265 裸流打成 PS 包再塞进 RTP 发送。FreeSWITCH 原生只认第一层和「标准 RTP 载荷」。它收到 INVITE 里的mvideo和artpmap:96 PS/90000时SDP 协商能过但媒体 bug 拿到的是 PS 流直接丢给解码器就是黑屏。模块的核心价值就在第二、三层把 MANSCDP 的 XML 收发封装成 API把 PS 流在 media bug 里解复用成裸 H.264再重新打包成 FreeSWITCH 内部能处理的帧。提示PS 是 MPEG-2 Program Stream不是「PS 图片」。它的 PES 包里带 PTS/DTS解复用时要按 PES 头长度逐段切不能按固定字节读。2.2 模块的目录结构与关键源文件职责拿到源码包后先别急着编译花十分钟把目录摸清楚后面排错能省一半时间。典型结构如下不同实现命名略有差异但职责划分基本一致目录/文件职责排错时先看它mod_gb28181/模块入口定义 module interface、API 注册模块加载失败sip_stack/SIP 事务、注册状态机、MESSAGE 分发设备注册不上manscdp/XML 编解码Catalog/DeviceInfo/RecordInfo目录查不到ps_demux/PS 头解析、PES 拆分、H.264 提取点播黑屏media_bridge/RTP 收发、jitter buffer、与 core media bug 对接花屏、卡顿ptz/PTZCmd 组包与透传云台不动sip_stack和manscdp是信令面ps_demux和media_bridge是媒体面。新手最容易犯的错是信令通了就以为成了结果媒体面 PS 解复用没写对INVITE 200 OK 之后一路黑屏。2.3 一次实时点播的完整信令与媒体时序把一次RealPlay点播拆成可观测的步骤方便你对着日志定位设备 REGISTER模块回 401 挑战设备带 Authorization 重注册模块记录Contact和DeviceID。平台侧调模块 API 发Catalog查询设备回 MESSAGE 带 XML 目录。平台选一路通道调 API 发 INVITESDP 里s填Playy填 SSRC。设备回 200 OK随后向模块 SDP 里给的 IP/端口发 PS over RTP。模块 media bug 收 RTPps_demux解出 H.264交给 core 的 jitter buffer。平台侧通过uuid_record或 conference 取流。第 4 步之后如果ps_demux没工作你会看到 RTP 包在收、rtp_rx计数在涨但解码器没帧。这时候抓包看 PES 起始码00 00 01 BA有没有被正确识别。3. 从零编译到设备注册成功可抄作业的落地步骤3.1 编译环境与依赖准备FreeSWITCH 模块编译对版本敏感建议先确认 core 版本再动手。常见做法是源码包和 FreeSWITCH 源码树同级放置用./configure时指定模块路径。# 依赖FreeSWITCH 源码树、libxml2、openssl、pcre # 假设 FreeSWITCH 源码在 /opt/freeswitch-src cd /opt/freeswitch-src # 把模块软链到 src/mod/applications 下 ln -s /opt/gb28181-mod/mod_gb28181 src/mod/applications/mod_gb28181 # 重新生成 makefile ./configure --enable-core-pgsql-supportno # 只编这个模块省时间 make mod_gb28181-installln -s这一步是关键FreeSWITCH 的模块发现机制靠src/mod/applications下的目录扫描。make mod_gb28181-install只编目标模块比全量make install快得多。编完检查modules.conf里有没有mod_gb28181没有就手动加一行否则启动不加载。参数说明--enable-core-pgsql-supportno只是示例按你实际 core 配置来如果模块依赖libxml2确认pkg-config --cflags libxml-2.0能输出路径否则 configure 阶段会静默跳过 XML 支持运行时报manscdp init failed。3.2 模块配置SIP 端口、域、媒体 IP 三个必调项模块加载后第一件事是配gb28181.conf或等价 XML 配置。三个参数决定能不能通configuration namegb28181.conf descriptionGB28181 module settings !-- SIP 监听端口别和 core 的 5060 撞 -- param namesip-port value5062/ !-- SIP 域设备注册时填的域必须一致 -- param namesip-domain value3402000000/ !-- 媒体面对外 IP多网卡时最容易配错 -- param namemedia-ip value192.168.1.100/ !-- RTP 端口范围 -- param namertp-port-min value30000/ param namertp-port-max value30100/ /settings /configurationsip-port和 core 的 5060 分开避免 SIP 消息互相干扰。sip-domain是国标 20 位域编码的前 10 位设备侧配置的 SIP 服务器 ID 必须和它匹配否则 REGISTER 直接被拒。media-ip是血泪经验重灾区服务器有内网和外网两块网卡时SDP 里c行填错 IP设备把流发到不可达地址现象是信令全通、媒体零收包。注意rtp-port-min/max范围别开太大100 个端口够几十路并发开几千个端口会让防火墙规则和端口回收变复杂。3.3 用 API 命令验证注册与目录查询模块一般会注册几个fs_cli命令用来手动触发国标交互。注册成功后先别写业务代码用命令把链路走通# 进 fs_cli fs_cli # 查看已注册设备 gb28181_status # 主动查某设备目录 gb28181_catalog 34020000001320000001 # 对某通道发起实时点播 gb28181_invite 34020000001320000001 34020000001320000001gb28181_status输出里重点看DeviceID、RegisterTime、Expires。如果设备列表为空回到 3.2 检查sip-domain和端口。gb28181_catalog返回的是设备回的 XML 解析结果能看到通道数量和名称。gb28181_invite成功后用show channels应该能看到一个gb28181/开头的 channel。参数说明gb28181_invite两个参数分别是设备 ID 和通道 ID很多设备这两者相同但球机通常设备 ID 和通道 ID 不同传错会收到 404。点播后如果 channel 建了但没媒体看gb28181_status里的SSRC和抓包是否一致。3.4 媒体面打通PS 解复用与录制验证信令通了、channel 建了最后一步是验证媒体真的解出来了。最直接的办法是录一段文件看能不能播# 对已建立的 channel 录制 10 秒 fs_cli -x uuid_record channel-uuid start /tmp/gb_test.mp4 10 # 录完用 ffprobe 看有没有视频流 ffprobe -v error -show_streams /tmp/gb_test.mp4如果ffprobe报moov atom not found或只有音频说明ps_demux没解出有效 H.264。常见原因是 PES 包里 H.264 的 NAL 起始码是00 00 00 01而 PS 系统头里也有类似字节解复用状态机没区分开。另一个原因是设备发的是 H.265模块只支持 H.264SDP 协商时没拒绝导致解出来是乱码。参数说明uuid_record的时长参数单位是秒写 10 就是录 10 秒路径要写模块进程有写权限的目录。ffprobe的-show_streams会列出所有流重点看codec_name是不是h264、width/height是否正常。4. 避坑与排查五条真实踩过的坑4.1 设备注册成功但目录查询超时现象gb28181_status能看到设备gb28181_catalog发出去后一直没返回日志里 MESSAGE 发出去了但没收到响应。原因MANSCDP 的 XML 里SN序列号没递增或重复设备侧把重复 SN 的请求丢弃另一种是DeviceID填了设备 ID 而不是通道 ID设备不认。解决检查manscdp组包代码里 SN 是不是全局自增每次请求 1Catalog 查询的DeviceID用设备 ID但返回的目录里通道 ID 要单独记录后续 INVITE 用通道 ID。4.2 INVITE 200 OK 后媒体零收包现象信令全通show channels有 channel但rtp_rx计数为 0抓包看不到设备发流。原因SDP 里c行填的媒体 IP 设备不可达或者mvideo端口和设备实际发送端口不一致。多网卡服务器上模块取了默认路由网卡 IP而设备在另一个网段。解决显式配media-ip为设备能访问的地址抓包确认设备有没有往该 IP 发包没有就是网络或 SDP 问题有包但模块没收到就是防火墙拦了 RTP 端口段。4.3 点播有画面但花屏、卡顿现象能解出 H.264但画面周期性花屏或几秒卡一下。原因jitter buffer 太小RTP 乱序或丢包时直接丢帧或者 PS 解复用按固定长度读遇到跨 RTP 包的 PES 包就截断。解决调大media_bridge的 jitter buffer 深度ps_demux要维护跨包缓冲PES 包长度字段说多少就攒够多少再解不能假设一个 PES 在一个 RTP 包里。4.4 历史回放拉流失败现象实时点播正常RecordInfo查询能返回录像列表但回放 INVITE 后无流。原因回放 SDP 里s要填Playbackt填录像起止时间很多实现漏了t行或时间格式不对国标要求 ISO8601 带时区。解决对照设备文档确认回放 SDP 格式t行时间用2024-01-01T00:00:00这种格式且要和RecordInfo返回的时间段对得上。4.5 模块加载后 core 启动变慢或崩溃现象加了模块后 FreeSWITCH 启动卡住或运行中 core dump。原因模块在SWITCH_MODULE_LOAD里做了阻塞操作比如同步等设备响应或者 media bug 回调里做了耗时解析阻塞了 core 的媒体线程。解决加载阶段只做初始化和线程创建所有网络等待放独立线程media bug 回调里只做轻量解复用重活丢队列异步处理。5. 进阶把国标接入做成可运维的稳定服务5.1 用 SSRC 和通道映射做多路并发管理单路跑通后多路并发的核心是 SSRC 管理。国标 INVITE 的y行是 SSRC模块要保证每路会话 SSRC 唯一并在收到 RTP 时按 SSRC 找到对应 channel。常见做法是维护一张SSRC - channel_uuid哈希表INVITE 时分配BYE 时回收。// 伪代码SSRC 分配与查找 uint32_t alloc_ssrc(void) { static uint32_t seed 0x10000000; return __sync_add_and_fetch(seed, 1); // 原子自增避免并发重复 } // 收到 RTP 时按 SSRC 查 channel switch_channel_t *ch find_channel_by_ssrc(ntohl(rtp-ssrc)); if (!ch) { /* 未知 SSRC丢弃并计数告警 */ }__sync_add_and_fetch保证多线程下 SSRC 不重复。find_channel_by_ssrc用哈希表 O(1) 查找别用线性遍历几十路以上会拖垮媒体线程。未知 SSRC 要计数告警这通常意味着设备侧 SSRC 和协商不一致是排查媒体问题的关键线索。5.2 心跳超时与设备离线检测国标设备靠 Keepalive 心跳维持在线状态模块要维护每个设备的最后心跳时间超时标记离线并清理相关 channel。超时阈值一般设心跳间隔的 3 倍设备通常 60 秒一次心跳阈值设 180 秒。参数建议值说明心跳间隔60s设备侧配置模块按此预期离线阈值180s3 倍心跳间隔容忍抖动检查周期30s定时器扫描别太频繁channel 清理延迟5s离线后延迟清理防抖检查周期别设太短30 秒扫一次足够channel 清理加 5 秒延迟避免设备网络抖动导致误清理又立刻重注册。5.3 用抓包和日志定位媒体问题的固定套路媒体问题排查有一套固定动作养成习惯能省大量时间。第一步tcpdump抓 RTP 端口段确认包到没到第二步看模块日志里ps_demux的 PES 解析计数第三步ffprobe录制的文件确认解码结果。三步定位到具体层没包是网络/SDP有包没 PES 是解复用有 PES 没帧是 NAL 提取。我自己的习惯是每次改ps_demux后先跑一段 30 秒录制用ffprobe看nb_frames和duration是否匹配不匹配就说明丢帧再回去看 jitter buffer 和跨包缓冲。这套源码包的价值不在于「能跑」而在于它把国标三层结构拆成了可单独调试的模块你哪层出问题就盯哪层不用在黑盒子里猜。希望帮到你。本文还有配套的精品资源点击获取