🚀 想要一个秒级启动、纯 Python 原生、对 AI 生态友好的国标视频平台？ 就是它了。生产环境需要 Go 单二进制部署、插件商城与企业级授权？请了解同一团队的商业版 GBWatch。
PyGBSentry 基于最新 GB/T 28181-2022 标准构建（向下兼容 2016 版设备）。与依赖第三方 C 库或商业 SIP 中间件的方案不同，我们从零实现了纯 Python 的 SIP/GB28181 协议栈，让你真正掌控从信令到流媒体的全链路。
| 维度 | PyGBSentry | 传统方案 |
|---|---|---|
| ⚡ 启动速度 | 秒级 | 分钟级 |
| 🛠️ 开发效率 | Python 生态 | 复杂配置 |
| 🤖 AI 集成 | 原生友好 | 需要额外适配 |
| 🔄 并发模型 | 异步架构 | 线程模型 |
Python + FastAPI 意味着秒级启动、原生异步并发和开箱即用的 AI 生态。不用和 XML 缠斗，没有不透明的二进制——只有干净、可读的 Python。
RTP 端口池预分配 + 四路并行 INVITE + RTT 自适应定时器，交付你在 GB28181 平台上见过的最快实况连接。
六大维度实时健康评分，智能播放恢复：
- RTCP NACK —— 丢包瞬时重传
- UDP → TCP 自动降级 —— 网络劣化时无缝切换传输协议
- 双缓冲无缝切换 —— 零花屏的流切换
每一条 SIP 消息都用纯 Python 解析、构造与分发。完全透明、完全可调试、完全属于你。在信令流程的任意位置打下断点，看清正在发生的一切。
全面符合最新国标：
a=trackSDP 协商- 绝对云台定位
- 3D 拉框放大（DragZoom）
- 设备文件目录检索
无需 Fork 即可扩展：
- 飞书 —— 告警通知
- 企业微信 —— 企业消息
- MQTT —— 物联网桥接
- S3 —— 云端归档
- AI —— 推理管线集成
| 优化项 | 效果 |
|---|---|
| 分片 DialogManager | 会话分片，锁竞争降低 16 倍 |
| 对象池 | 2K+ 对象预分配，热路径零 GC 压力 |
| 线程池 | SIP 消息多核并行解析 |
| 预过滤 Handler | 分发前减少 70% 无效消息扫描 |
- RFC 3261 状态机 —— 标准兼容的 SIP 会话生命周期
- Redis 持久化 —— 会话状态重启不丢
- 节点故障转移 —— 多节点部署自动恢复
- TLS 热重载 —— 证书轮换不停机
| 监控中心（多分屏实时预览） | 工作台（资源概览与告警趋势） |
 |
 |
| 通道工作区（设备通道管理 / 云台 / 预览） | 设备列表（国标设备台账） |
 |
 |
| 国标级联（上下级平台对接） | 多协议接入（RTSP / ONVIF / SDK） |
 |
 |
更多界面截图见 docs/images/。
┌─────────────────────────────────────────────────────────────────────┐
│ 终端层（多端覆盖） │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ Web 后台 │ │ Mobile App │ │ 第三方平台 / 设备 │ │
│ │ Vue 3 + TS │ │ uni-app │ │ GB28181 级联对接 │ │
│ └──────┬───────┘ └──────┬───────┘ └────────────┬─────────────┘ │
└──────────┼─────────────────┼───────────────────────┼────────────────┘
│ │ │
┌──────────▼─────────────────▼───────────────────────▼────────────────┐
│ 接入网关层 │
│ Nginx 负载均衡 / HTTPS 终结 / 静态资源分发 │
└──────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────────────┐
│ 业务服务层（FastAPI） │
│ REST API · WebSocket 推送 · 插件运行时 · 审计日志 · 配置治理 │
├──────────────────────────┬──────────────────────────────────────────┤
│ SIP 信令引擎 │ 流媒体网关 │
│ 自研 Python SIP 栈 │ ZLMediaKit Hook 对接 │
│ GB28181 注册/点播/回放 │ WebRTC / FLV / HLS / RTSP / RTMP │
│ 级联/PTZ/报警/语音 │ RTP 接收 / 录像回调 / 云端录制 │
├──────────────────────────┴──────────────────────────────────────────┤
│ 数据与缓存层 │
│ PostgreSQL / MySQL / SQLite │ Redis │
│ （持久化数据、审计日志、级联关系） │ （会话、状态、限流） │
└─────────────────────────────────────────────────────────────────────┘
git clone https://github.com/suoten/PyGBSentry.git
cd PyGBSentry/editions/open-source
# 方式一：自动生成密钥并启动（推荐）
python tools/generate_env.py --docker
docker compose up -d
# 方式二：一行命令全自动部署
make docker-init内置 ZLMediaKit 仅提供 Linux 二进制。Windows / macOS 开发者请使用下方「本地开发模式」。
访问 http://<服务器IP> 进入安装向导，首次使用创建管理员账号即可。
🔍 部署诊断：
./deploy/setup.sh doctor一键检查端口、数据库、ZLM、SIP 服务状态。
cd backend
cp .env.example .env
python -m venv venv
# Windows: venv\Scripts\activate Linux/macOS: source venv/bin/activate
pip install -r requirements.txt
python app/initial_data.py
python -m app.main # → http://localhost:8000
cd ../frontend
npm install
npm run dev # → http://localhost:5173本地模式使用 SQLite，无需 PostgreSQL/Redis，适合二次开发与轻量体验。
📖 完整部署手册（含生产环境 checklist、NAT、SSL、高可用）见 docs/INSTALL.md。
国标接入 视频业务 智能运维 数据集成 可视化
───────────── ───────────── ───────────── ───────────── ─────────────
设备注册 实时预览 网络看门狗 MQTT 对接 GIS 地图
平台级联 多分屏播放 流健康监测 Webhook 回调 电视墙
目录推送 录像检索回放 SLA 质量看板 级联上报 轨迹回放
GPS 订阅 云台 PTZ 容量基线预警 飞书/企微告警 可视化指挥
语音对讲 预置位轮巡 SIP 信令审计 S3 云存储 告警联动
同一团队打造的商业版视频平台，与 PyGBSentry 定位互补、代码库独立：
| PyGBSentry（本项目） | GBWatch（商业版） | |
|---|---|---|
| 语言 | Python 3.12+ / FastAPI | Go 1.25+（单二进制） |
| 许可 | AGPL v3（开源） | 商业许可（闭源二进制交付） |
| 定位 | 开发者 / AI 生态 / 二次开发 | 生产环境交付 / 商业运营 |
| 插件生态 | Python 插件 | 插件商城（官方 + 第三方，付费订阅） |
| 平台授权 | — | 按通道数授权（64 / 256 / 不限），Ed25519 实例绑定证书，超限拒绝新增设备 |
| 插件商城支付 | — | 支付宝 / 微信扫码购买插件，管理后台一键配置 |
GBWatch 商业版亮点：
- Go 单二进制部署 —— 编译即用，无运行时依赖，资源占用显著更低
- 插件商城 —— 16 个官方插件开箱即用（通知推送、MQTT 桥接、AI 告警降噪、行为关联分析、移动侦测、镜头健康体检等），第三方开发者实名入驻、自主定价
- 企业级授权管理 —— 订阅到期自动停用、多实例绑定、防篡改证书校验
- 二进制交付 + 授权绑定 —— 仅交付编译产物，授权与实例硬件绑定、禁止逆向与二次分发，从源头防泄露
- 插件商城在线支付 —— 管理员开启支付宝 / 微信支付，用户扫码购买插件
- 商业支持 —— 同团队提供部署、定制与技术支持服务
| 版本 | 通道数 | 定价 | 目标客户 |
|---|---|---|---|
| 标准版 | 64 路 | ¥5,800 永久授权（含首年更新与工单） | 小型项目、单体企业（几十路摄像头） |
| 专业版 | 256 路 | ¥19,800 永久授权（含首年更新与插件商城） | 中型项目、需要 AI 插件与商城生态 |
| 旗舰版 / OEM | 不限 | ¥59,800 / 年（含年度续约与优先支持） | 集成商批量交付、OEM 白标贴牌 |
所有版本均为闭源二进制交付，授权证书与部署实例绑定（Ed25519 防篡改），超出通道数自动拒绝新增设备；更新服务续费为授权费的 20%/年。价格可随项目规模与 OEM 数量另议。
PyGBSentry 与 GBWatch 服务于不同场景：学习、二次开发、AI 集成选 PyGBSentry；生产部署、商业运营、需要插件生态与支付能力选 GBWatch。
| 2022 新特性 | 说明 | 配置方式 |
|---|---|---|
| SDP a=track 轨道标识 | 精准区分主/子码流与多路轨道，解决 2016 版码流切换模糊问题 | GB28181_STREAM_SWITCH_USE_TRACK_SUBJECT=true |
| 绝对云台控制 | 支持地理坐标级精准定位，满足高空瞭望、应急指挥场景 | API 自动识别 2022 指令 |
| 3D 放大/定位 (DragZoom) | 框选即放大，操作体验对标主流 GIS 平台 | PTZ 面板直接调用 |
| 文件目录检索 | 按时间、类型、通道精准检索设备端录像文件 | /api/v1/devices/{id}/file-catalog |
| 报警细化分类 | 支持入侵、徘徊、聚集等 20+ 细分报警类型订阅与联动 | 报警中心自动解析 |
| 远程配置下载/设置 | 批量下发编码、网络、OSD 参数，千级设备集中运维 | ConfigDownload / ConfigSet API |
如何切换版本：修改
backend/.env中的GB28181_VERSION=2022，重启后端即可。系统会自动适配 SDP、信令 XML 与交互流程。
| 部署形态 | 操作系统 | 内存 | 说明 |
|---|---|---|---|
| Docker 完整部署 | Linux（Ubuntu 20.04+ / Debian 11+ / CentOS 8+） | 4GB+ | 含 ZLMediaKit 流媒体服务，推荐生产环境 |
| 本地开发模式 | Linux / Windows 10+ / macOS 12+ | 2GB+ | SQLite 开箱即用，需外置 ZLM 才能播放 |
| 高可用集群 | Kubernetes 1.25+ | 8GB+ | 使用 deploy/helm/ 部署 |
详细环境要求与端口说明请参考 docs/INSTALL.md。
| 文档 | 适合谁 | 内容 |
|---|---|---|
| INSTALL.md | 运维/实施 | 完整部署手册，含 Docker、手工、高可用方案 |
| INSTALL_DEPLOY.md | 运维/实施 | 生产环境 checklist、NAT、端口、SSL 配置 |
| DEVELOPER.md | 开发者 | 架构详解、目录说明、添加 API、扩展 SIP 逻辑 |
| PLUGIN_SPEC.md | 开发者 | 插件开发规范、生命周期、API、上架流程 |
| MEDIA_SERVER.md | 运维/开发者 | ZLMediaKit 配置、Hook 说明、排错指南 |
| COMPATIBILITY.md | 实施/用户 | 浏览器与设备兼容性矩阵 |
| QA_TROUBLESHOOT.md | 所有人 | 常见问题与排查步骤 |
欢迎任何形式的贡献：Issue 反馈、文档改进、功能开发、Bug 修复。
# 1. Fork 本仓库
# 2. 创建特性分支
git checkout -b feature/your-feature
# 3. 提交变更
git commit -m "feat: add your feature"
# 4. 推送并发起 Pull Request
git push origin feature/your-feature🩺 GBDoctor — GB/T 28181 接入诊断医生
与 PyGBSentry 互为补充：PyGBSentry 负责把设备"接上来、管得好"，GBDoctor 负责在接不上、画面有问题时快速定位"为什么"——同时扮演模拟上级平台和模拟摄像头两个角色，3 分钟输出全链路（注册/保活/目录/点播/云台等 12 项）体检报告，无需抓包。
- Gitee：gitee.com/suoten/GBDoctor
- GitHub：github.com/suoten/GBDoctor
平台接入不顺畅？用 GBDoctor 体检一下就知道卡在哪一环。
🧰 更多相关项目
| 项目 | 简介 | 仓库 |
|---|---|---|
| ProtoForge | 开源 PLC 协议模拟器：零硬件模拟 Modbus/S7/OPC-UA/BACnet/GB28181 等 28 种协议，测试上位机与网关通信 | Gitee · GitHub |
| EdgeLiteGateway | 开源边缘 AI 网关（Python 版）：13 种工业协议 + ONNX 推理引擎，10 分钟 Docker 部署 | Gitee · GitHub |
| EdgeLiteGateway-Go | 工业边缘 AI 网关 Go 版：单二进制部署，附 Linux amd64/arm64/armv7 预编译包 | Gitee · GitHub |
| EdgeAgent-Hub | 边缘智能体管理平台（Go）：ONNX + LLM + RAG + 多智能体编排，Modbus/OPC UA/MQTT 全协议接入，断网自治 + A/B 分区 OTA | Gitee · GitHub |
| IoT-ZTNA | IoT 零信任网络访问网关（Rust）：eBPF/XDP 线速过滤 + SPIFFE 设备身份 + AI 行为检测 | Gitee · GitHub |
本项目采用 GNU Affero General Public License v3.0 开源协议。
对于网络交互软件，AGPL v3 确保任何在公网提供服务的修改版本，也必须向用户公开源代码。这保护了开源社区的利益，也保证了项目的长期健康发展。
- 问题反馈：GitHub Issues ｜ Gitee Issues
- 作者邮箱：suoten@163.com
如果你觉得项目有帮助，欢迎点亮 Star，这是对开源作者最好的鼓励。
Turn any server into a GB/T 28181-compliant intelligent video hub — pure Python SIP stack, built from scratch.
📖 English Documentation → README_EN.md
PyGBSentry is an open-source video management platform built on GB/T 28181-2022 (backward compatible with 2016 devices), featuring a self-implemented pure Python SIP stack, FastAPI backend, Vue 3 admin UI, and integrated ZLMediaKit streaming — covering device access, platform cascading, live preview, playback, PTZ control, two-way audio, alarm linkage, and a plugin ecosystem.