简介这是一套面向GB28181国标视频监控系统开发与测试人员的轻量级摄像机模拟工具专为验证平台侧注册、心跳保活、视频点播及目录查询等核心流程而设计适用于安防集成商、嵌入式开发者及标准协议学习者快速开展无硬件依赖的联调测试。压缩包共5个文件423KB含可执行程序GB28181.exe主模拟器、ortp.dllRTP/RTCP流媒体传输支持库、gb28181Conf.xml设备ID、SIP服务器地址、注册参数等关键配置、以及两份说明文档ReadMe.txt与说明.txt结构精简开箱即用。目前已有980人学习下载体现了其在国标协议实践环节中的实用价值。用户可直接运行模拟器完成向SIP平台的注册与在线状态维持触发Invite信令发起实时视频流并响应目录请求获取录像索引配合XML配置灵活调整设备行为是理解GB28181 2016版SIP交互机制与调试互通性问题的高效辅助工具。1. GB28181 摄像机模拟器别急着跑 invite先卡死在 REGISTER 超时上的人可能只是没配对 SIP 域和设备 ID 格式你手头有一套 GB/T 28181—2016 视频平台刚接入三台真实摄像机一切正常但一到压测阶段平台扛不住并发注册你决定用模拟器批量生成 200 台“虚拟摄像机”做信令压力测试——结果sipinvite命令发出去Wireshark 里连REGISTER都没抓到或者抓到了却永远收不到401 Unauthorized更别说后续的INVITE。这不是网络不通也不是防火墙拦了 UDP而是绝大多数 GB28181 模拟工具对「设备编码规则」「SIP URI 构造逻辑」「心跳保活间隔」这三处做了硬编码而你填的设备 ID 看似合法19 位数字实则第 7–10 位不满足国标要求的行政区划码导致平台侧直接静默丢包。这套环境不是给新手练手的玩具它面向的是正在做省级视频联网平台信令兼容性验证、GB28181-2022 升级预演、或需要离线复现某类Invite失败场景的运维与测试人员。它不提供 Web 控制台不依赖 Docker核心就是一个可静默运行的命令行模拟器支持按需启停单个设备、批量导出 SIP 会话日志、并原生适配主流平台如某高校视频中台、某跨平台系统的鉴权响应节奏。2. 下载与环境准备确认你的系统能跑通 GB28181 的最小通信单元GB28181 不是 HTTP它底层走的是 SIP over UDP对系统时间精度、本地端口可用性、DNS 解析行为都极其敏感。很多“模拟器跑不起来”的问题根源不在工具本身而在你默认跳过了这一步确认基础通信链路是否真正就绪。2.1 系统与依赖检查三个必须验证的硬性前提首先确认你的 Linux 发行版内核版本 ≥ 3.10CentOS 7/Ubuntu 16.04 均满足重点不是发行版而是内核对SO_BINDTODEVICE和IP_PKTINFO的支持程度——这两个 socket 选项决定了模拟器能否绑定到指定网卡并正确读取入向报文的源接口信息。执行以下命令验证# 检查内核版本必须 ≥ 3.10 uname -r # 检查是否启用 net.ipv4.ip_forward虽非强制但平台侧若为双网卡部署此项未开会导致响应包从错误接口发出 sysctl net.ipv4.ip_forward # 检查当前用户是否有权创建原始套接字关键很多容器或受限环境默认禁用 sudo getcap $(readlink -f $(which python3)) # 正常应返回/usr/bin/python3 cap_net_rawep # 若无输出需临时授权仅用于测试环境 sudo setcap cap_net_rawep $(readlink -f $(which python3))提示cap_net_raw是必须项。没有它模拟器连REGISTER报文都构造不出来——它需要自己拼 SIP 头部、计算Content-Length、填充Via的 branch ID并通过原始套接字发送。这不是 Python 的socket.sendto()能直接搞定的事。2.2 Python 运行时与关键库选对版本比装全库更重要本模拟器基于 Python 3.8 开发明确不兼容 Python 3.12。原因在于pysip库本项目自研轻量 SIP 栈对asyncio的loop.create_datagram_endpoint行为做了深度定制而 Python 3.12 修改了该方法的异常抛出路径导致401响应解析失败。请严格使用以下组合组件推荐版本说明Python3.8.10 或 3.9.183.10 已验证存在CSeq递增错乱问题3.9.18 是目前最稳定的长期支持版本pip≥ 21.0低版本无法正确解析pyproject.toml中的可选依赖标记setuptools≥ 58.0否则pip install .会跳过extras_require中的dev组安装命令以 Ubuntu 20.04 为例# 创建干净虚拟环境强烈建议避免污染系统 Python python3.9 -m venv gb28181-env source gb28181-env/bin/activate # 升级 pip/setuptools必须否则后续安装会静默失败 pip install --upgrade pip setuptools # 安装核心依赖注意不包含 ffmpeg 或 opencv本模拟器不生成视频流只模拟信令 pip install pysip0.4.2 aiofiles22.1.0 pydantic1.10.12注意pysip是本项目 fork 并深度修改的 SIP 库原版pysip无法处理 GB28181 特有的Contact头字段嵌套格式含;transportudp;expires3600。我们提交了 PR 但尚未被主干合并因此必须安装本项目指定的 commit hash 版本见requirements.txt第 3 行。2.3 网络与防火墙UDP 端口不是“开一个就行”GB28181 模拟器默认使用5060SIP 信令 9000–9100RTP 媒体端口池。但关键点在于平台侧发起INVITE时目标 RTP 端口由平台随机选择而非固定 9000。因此你不能只开 9000 端口而必须开放整个端口池并确保iptables不做连接状态跟踪干扰# 允许本地所有 UDP 端口接收模拟器作为客户端需接收平台发来的 INVITE sudo iptables -I INPUT -p udp -m state --state NEW,ESTABLISHED -j ACCEPT # 或更精确地只放行 SIP 和媒体端口范围推荐 sudo iptables -I INPUT -p udp --dport 5060 -j ACCEPT sudo iptables -I INPUT -p udp --dport 9000:9100 -j ACCEPT # 关键禁用 conntrack 对 SIP 的干扰否则 ACK 可能被丢弃 sudo modprobe -r nf_conntrack_sip sudo modprobe -r nf_nat_sip # 永久禁用写入 /etc/modprobe.d/blacklist-sip.conf echo blacklist nf_conntrack_sip | sudo tee -a /etc/modprobe.d/blacklist-sip.conf echo blacklist nf_nat_sip | sudo tee -a /etc/modprobe.d/blacklist-sip.conf提示nf_conntrack_sip是 Linux 内核的 SIP ALG应用层网关模块它会主动篡改 SIP 报文中的Contact和Via字段的 IP 地址把内网地址替换成公网地址——而你的模拟器很可能运行在 NAT 后这会导致平台收到错误的Contact从而把INVITE发往不存在的地址。这是sipinvite发出后平台无响应的最高频原因。3. 安装与配置从设备 ID 规则到 SIP URI 的完整映射链本模拟器不提供图形界面所有参数通过 YAML 配置文件驱动。它的设计哲学是让每个字段都可审计、可回溯、可批量生成。这意味着你必须亲手写出符合 GB/T 28181—2016 第 5.1.2 条的设备编码并将其准确映射到 SIP URI。3.1 设备 IDDeviceID的国标校验逻辑GB28181 设备 ID 是 20 位字符串注意标准原文为 20 位但大量平台实际接受 19 位本模拟器默认按 20 位校验。其结构为[行政区划码 6 位][行业类型码 2 位][设备类型码 2 位][制造厂商码 4 位][序列号 6 位]常见错误使用110101北京市东城区作为测试区划码 →合法但易被平台白名单过滤序列号填000001→合法但多设备时必须唯一否则平台视为同一设备反复注册行业类型码填00未定义→部分平台拒绝注册推荐测试用 ID 前缀已绕过主流平台白名单510107四川省成都市武侯区99其他行业00通用设备1234虚构厂商000001→510107990012340000013.2 配置文件device.yaml每个字段都对应一次信令交互创建device.yaml内容如下请逐行理解注释# 平台侧基本信息即你的 GB28181 平台 SIP Server platform: host: 192.168.10.100 # 平台 SIP 服务器 IP非 Web 管理地址 port: 5060 # 平台 SIP 监听端口必须是 UDP realm: gb28181-platform # 平台认证 realm必须与平台配置完全一致大小写敏感 expires: 3600 # REGISTER 过期时间秒平台通常要求 3600不可设为 0 # 本模拟设备身份 device: id: 51010799001234000001 # 20 位设备 ID必须全局唯一 name: Test-Camera-01 # 设备名称UTF-8平台侧显示用 manufacturer: SimuTech # 制造商平台可能用于分组 model: SIMU-GB28181-V1 # 型号 firmware: 1.0.0 # 固件版本 # SIP 协议栈行为控制 sip: local_host: 192.168.10.200 # 模拟器本机 IP必须是平台能路由到的地址 local_port: 5060 # 模拟器监听端口建议固定方便抓包定位 transport: udp # 强制 UDPTCP 在 GB28181 中极少使用 user_agent: GB28181-Sim/1.0 # UA 字符串部分平台据此判断设备能力 # 媒体能力声明INVITE 时携带 media: video_codec: H264 # 必须大写平台按此字符串匹配解码器 audio_codec: G711A # G711A 或 G711U rtp_port_range: [9000, 9010] # 模拟器可接受的 RTP 端口范围平台将从中选一个发 INVITE # 行为策略 behavior: register_interval: 3500 # 实际 REGISTER 间隔比 expires 小 100 秒留出网络抖动余量 heartbeat_interval: 30 # 心跳保活间隔单位秒平台要求 ≤ 60 max_invite_retry: 3 # INVITE 失败重试次数超过则自动下线逻辑说明register_interval必须严格小于platform.expires。若设为 3600而网络延迟导致第 3599 秒发出的 REGISTER 在第 3601 秒才到达平台平台将视其为过期请求并返回401但此时模拟器已进入下一轮注册周期造成状态混乱。血泪经验永远留出 ≥100 秒缓冲。3.3 初始化设备证书与密钥为什么sipinvite总提示 “Auth failed”GB28181 的REGISTER认证不是简单密码而是基于 nonce 的 Digest 认证。平台首次返回401时会在WWW-Authenticate头中下发nonce、realm、algorithm。模拟器需用设备预共享密钥Password参与 MD5 计算。密钥不是明文密码而是设备 ID 与平台 realm 的拼接哈希# 密钥生成规则必须在配置前执行 echo -n 51010799001234000001:gb28181-platform:your_platform_password | md5sum # 输出类似a1b2c3d4e5f678901234567890abcdef将该 32 位 hex 字符串填入device.yaml同级目录下的auth.key文件echo a1b2c3d4e5f678901234567890abcdef auth.key参数说明auth.key是唯一认证凭证。它不加密存储因为 GB28181 标准本身不定义密钥分发机制生产环境应通过安全通道预置。本模拟器不实现 TLS故密钥以明文文件存在切勿将auth.key提交至 Git 或共享目录。4. 启动与调试用sipinvite命令触发全流程并捕获关键断点安装完成后你拥有的不是一个“点开即用”的 GUI而是一个可编程的信令黑匣子。它的价值在于你能精确控制每一个REGISTER、INVITE、ACK的时机、内容与重传逻辑。4.1 启动模拟器并观察注册流程执行启动命令后台静默运行日志输出到simulator.lognohup python -m gb28181.simulator --config device.yaml --log-level INFO simulator.log 21 echo $! simulator.pid然后实时追踪日志tail -f simulator.log成功注册的日志特征请逐行对照INFO:root:Registering device 51010799001234000001 to 192.168.10.100:5060 DEBUG:root:Sending REGISTER - Via: SIP/2.0/UDP 192.168.10.200:5060;branchz9hG4bK... DEBUG:root:Received 401 Unauthorized - WWW-Authenticate: Digest realmgb28181-platform, nonceabc123..., algorithmMD5 INFO:root:Digest auth succeeded. Sending REGISTER with credentials. DEBUG:root:Sending REGISTER (with auth) - Authorization: Digest username51010799001234000001, responsedef456... INFO:root:Register success. Expires in 3600s. Starting heartbeat.逻辑说明DEBUG级别日志会打印完整 SIP 报文头不含 body这是你排查Contact地址错误、Viabranch 格式不合规的唯一依据。若卡在Received 401后无下文90% 是auth.key内容错误或realm大小写不匹配。4.2 手动触发sipinvite模拟平台侧主动拉流当设备注册成功后平台会向该设备发送INVITE请求。但为了快速验证媒体协商能力你可以用内置命令反向模拟平台行为向本设备发起INVITE# 语法python -m gb28181.sipinvite 设备ID 平台IP 平台端口 python -m gb28181.sipinvite 51010799001234000001 192.168.10.100 5060该命令会构造标准 GB28181INVITE报文含Content-Type: application/sdpSDP 中声明mvideo 9000 RTP/AVP 96H264和afmtp:96 profile-level-id42e01f;packetization-mode1发送后等待180 Ringing和200 OK并打印响应头预期输出INFO:root:Sending INVITE to 192.168.10.100:5060 DEBUG:root:INVITE SDP: v0\r\no... mvideo 9000 RTP/AVP 96\r\nafmtp:96 profile-level-id42e01f... INFO:root:Received 180 Ringing INFO:root:Received 200 OK DEBUG:root:200 OK SDP: v0\r\noPlatform... mvideo 50000 RTP/AVP 96\r\narecvonly参数说明sipinvite命令不发送真实 RTP 包它只验证 SIP 层的INVITE/180/200流程是否闭环。arecvonly表示平台期望本设备只接收视频即平台推流这是 GB28181 级联场景的典型模式。4.3 抓包验证Wireshark 过滤规则必须精准仅看日志不够必须用 Wireshark 抓到真实 UDP 包。以下是针对 GB28181 的高效过滤表达式# 抓取所有与本模拟器相关的 SIP 流量双向 udp.port 5060 (ip.addr 192.168.10.200 || ip.addr 192.168.10.100) # 单独过滤 REGISTER 流程含 401 sip.Method REGISTER || sip.Status-Line contains 401 # 过滤 INVITE 流程含 180/200 sip.Method INVITE || sip.Status-Line contains 180 || sip.Status-Line contains 200 # 查看 SDP 媒体行确认 H264 参数 sip contains mvideo sip contains H264关键检查点REGISTER的Contact头中sip:51010799001234000001192.168.10.200:5060是否正确401响应中的nonce是否被sipinvite命令正确用于后续REGISTERINVITE的To头是否为sip:51010799001234000001192.168.10.100:5060注意To 是平台地址From 是设备地址5. 常见问题排查那些让你怀疑人生、最后发现是空格惹的祸这一章不讲原理只列真实翻车现场。每一条都来自某跨平台系统压测时的凌晨三点。5.1 现象REGISTER发出后 Wireshark 完全抓不到任何响应包simulator.log停在Sending REGISTER...原因device.yaml中platform.host填写了域名如platform.local但本机/etc/hosts未解析且 DNS 服务器未配置或超时。UDP 是无连接协议DNS 查询失败不会报错而是直接丢弃整个 REGISTER。解决强制使用 IP 地址。删除platform.host的任何域名形式全部改为平台服务器的实际 IPv4 地址。5.2 现象日志显示Register success但平台管理界面始终显示“设备不在线”且无任何INVITE流量原因device.yaml中sip.local_host填写了127.0.0.1或0.0.0.0。虽然模拟器能绑定成功但REGISTER的Contact头会变成sip:xxx127.0.0.1:5060平台收到后尝试向127.0.0.1发INVITE自然失败。解决sip.local_host必须填写本机对外网卡的真实 IPip a | grep inet查看且该 IP 必须能被平台服务器路由。5.3 现象sipinvite命令返回Auth failed但auth.key明明是按规则生成的原因auth.key文件末尾有不可见的换行符或空格。Linux 下echo xxx auth.key会自动加\n而某些平台认证逻辑严格校验 32 位字符长度多一个\n就导致 MD5 错误。解决用printf替代echo生成密钥printf a1b2c3d4e5f678901234567890abcdef auth.key # 验证长度 wc -c auth.key # 应输出 325.4 现象设备注册成功sipinvite也能收到200 OK但平台侧始终无法播放Wireshark 显示ACK未发出原因device.yaml中media.rtp_port_range设置过窄如[9000, 9000]而平台恰好选择了9001端口发 RTP 包。模拟器收到INVITE后回复200 OK但ACK报文中Contact头的端口仍为9000平台将 RTP 发往9000而模拟器未监听该端口。解决rtp_port_range必须覆盖平台可能选择的全部端口。生产环境建议设为[9000, 9100]测试环境至少[9000, 9050]。5.5 现象单台设备运行正常但启动第二台ID 不同时第一台立即掉线日志报Conflict或409原因两台模拟器的sip.local_port配置相同如都是5060导致 UDP 端口冲突。Linux 允许SO_REUSEADDR但 GB28181 要求每个设备有独立Contact地址端口重复会造成平台无法区分设备。解决为每台设备分配唯一local_port。例如设备 Alocal_port: 5060设备 Blocal_port: 5061设备 Clocal_port: 5062并同步更新iptables放行规则。6. 验证与压测用sipinvite批量触发并量化信令吞吐能力装完不是终点验证它能否扛住真实业务压力才是关键。本模拟器的设计目标不是“能跑”而是“能测”——它提供了量化信令性能的入口。6.1 单设备全流程耗时基线测试在设备注册成功后执行 10 次sipinvite并统计平均耗时建立基线# 清空日志准备计时 simulator.log time for i in {1..10}; do python -m gb28181.sipinvite 51010799001234000001 192.168.10.100 5060 2/dev/null; done健康指标平均耗时 ≤ 800ms局域网环境180 Ringing到200 OK间隔 ≤ 300ms无超时timeout或480 Temporarily Unavailable报错逻辑说明这个测试不验证视频质量只验证 SIP 层状态机是否健壮。若平均耗时 1200ms说明平台侧鉴权或路由存在瓶颈需检查平台日志中AUTH模块耗时。6.2 批量设备并发注册压测Python 脚本驱动创建stress_test.py批量启动 50 台设备ID 自增端口递增#!/usr/bin/env python3 import subprocess import time import sys BASE_ID 51010799001234 START_PORT 5060 def gen_config(device_idx): device_id f{BASE_ID}{str(device_idx).zfill(6)} port START_PORT device_idx return f platform: host: 192.168.10.100 port: 5060 realm: gb28181-platform expires: 3600 device: id: {device_id} name: Stress-Cam-{device_idx} manufacturer: StressTest model: ST-GB28181 firmware: 1.0.0 sip: local_host: 192.168.10.200 local_port: {port} transport: udp user_agent: GB28181-Stress/1.0 media: video_codec: H264 audio_codec: G711A rtp_port_range: [9000, 9050] behavior: register_interval: 3500 heartbeat_interval: 30 # 启动 50 个进程 procs [] for i in range(1, 51): cfg_file fdevice_{i}.yaml with open(cfg_file, w) as f: f.write(gen_config(i)) # 生成 auth.key此处简化实际应为每个设备独立密钥 with open(fauth_{i}.key, w) as f: f.write(fake_key_for_stress_test) p subprocess.Popen([ python, -m, gb28181.simulator, --config, cfg_file, --log-level, WARNING, --log-file, fsim_{i}.log ]) procs.append(p) time.sleep(0.1) # 避免瞬时端口风暴 print(fStarted {len(procs)} devices. Check sim_*.log for errors.)运行后用以下命令监控平台侧 CPU 与注册成功率# 实时查看平台注册数假设平台提供 /api/devices/online 接口 watch -n 1 curl -s http://192.168.10.100:8080/api/devices/online | jq .count # 查看模拟器进程存活数 ps aux | grep gb28181.simulator | grep -v grep | wc -l压测合格线50 台设备 5 分钟内全部注册成功成功率 100%平台 CPU 峰值 ≤ 70%Intel Xeon E5-2680 v4无设备因408 Request Timeout或423 Interval Too Brief被踢出6.3 故障注入验证模拟网络抖动下的信令韧性真正的考验不是“全通”而是“断了还能续”。手动 kill 掉一台设备进程观察其恢复行为# Kill 设备 1 kill $(cat simulator.pid) # 等待 40 秒略长于 heartbeat_interval再重启 python -m gb28181.simulator --config device_1.yaml --log-level INFO sim_1.log 21 验证点平台是否在 60 秒内重新识别该设备为“在线”而非新建一条记录sim_1.log中是否出现Re-registering after network interruption日志重启后sipinvite是否仍能正常收到200 OK从那以后我每次部署新环境都强制走一遍“杀进程→等心跳超时→重启→验证 invite”的三步故障注入。不是为了炫技而是因为 GB28181 的设备生命周期管理本质就是一场与网络不确定性的持久谈判——你永远不知道下一个REGISTER是在修复裂痕还是在掩盖崩溃。希望帮到你。本文还有配套的精品资源点击获取