# PyGBSentry
**Repository Path**: zhshhao/PyGBSentry
## Basic Information
- **Project Name**: PyGBSentry
- **Description**: 开箱即用的国标（GB/T 28181-2022）视频管理平台 · 纯 Python 自研 SIP 栈 · FastAPI + Vue 3 + ZLMediaKit
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 7
- **Created**: 2026-10-13
- **Last Updated**: 2026-10-13
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
---
> **🚀 想要一个秒级启动、纯 Python 原生、对 AI 生态友好的国标视频平台？**
> 就是它了。**生产环境需要 Go 单二进制部署、插件商城与企业级授权？请了解同一团队的商业版 [GBWatch](#-商业版-gbwatchgo)。**
**PyGBSentry** 基于**最新 GB/T 28181-2022 标准**构建（向下兼容 2016 版设备）。与依赖第三方 C 库或商业 SIP 中间件的方案不同，我们从零实现了**纯 Python 的 SIP/GB28181 协议栈**，让你真正掌控从信令到流媒体的全链路。
---
## ✨ 为什么选择 PyGBSentry？
| 维度 | PyGBSentry | 传统方案 |
|------|-----------|---------|
| ⚡ 启动速度 | **秒级** | 分钟级 |
| 🛠️ 开发效率 | **Python 生态** | 复杂配置 |
| 🤖 AI 集成 | **原生友好** | 需要额外适配 |
| 🔄 并发模型 | **异步架构** | 线程模型 |
Python + FastAPI 意味着**秒级启动**、**原生异步并发**和**开箱即用的 AI 生态**。不用和 XML 缠斗，没有不透明的二进制——只有干净、可读的 Python。
---
## 🎯 核心特性
### ⚡ 首帧 < 500ms
RTP 端口池预分配 + 四路并行 INVITE + RTT 自适应定时器，交付你在 GB28181 平台上见过的最快实况连接。
### 🩺 六维健康评分 + 播放自愈
六大维度实时健康评分，智能播放恢复：
- **RTCP NACK** —— 丢包瞬时重传
- **UDP → TCP 自动降级** —— 网络劣化时无缝切换传输协议
- **双缓冲无缝切换** —— 零花屏的流切换
### 🔍 纯 Python SIP 栈 —— 没有黑盒
每一条 SIP 消息都用纯 Python 解析、构造与分发。完全透明、完全可调试、完全属于你。在信令流程的任意位置打下断点，看清正在发生的一切。
### 📡 GB/T 28181-2022 原生支持
全面符合最新国标：
- `a=track` SDP 协商
- 绝对云台定位
- 3D 拉框放大（DragZoom）
- 设备文件目录检索
### 🧩 插件生态
无需 Fork 即可扩展：
- **飞书** —— 告警通知
- **企业微信** —— 企业消息
- **MQTT** —— 物联网桥接
- **S3** —— 云端归档
- **AI** —— 推理管线集成
### 🏎️ 高并发优化
| 优化项 | 效果 |
|-------|------|
| 分片 DialogManager | 会话分片，锁竞争降低 16 倍 |
| 对象池 | 2K+ 对象预分配，热路径零 GC 压力 |
| 线程池 | SIP 消息多核并行解析 |
| 预过滤 Handler | 分发前减少 70% 无效消息扫描 |
### 🏗️ 生产级高可用
- **RFC 3261 状态机** —— 标准兼容的 SIP 会话生命周期
- **Redis 持久化** —— 会话状态重启不丢
- **节点故障转移** —— 多节点部署自动恢复
- **TLS 热重载** —— 证书轮换不停机
---
## 📸 界面预览
| 监控中心（多分屏实时预览） |
工作台（资源概览与告警趋势） |
 |
 |
| 通道工作区（设备通道管理 / 云台 / 预览） |
设备列表（国标设备台账） |
 |
 |
| 国标级联（上下级平台对接） |
多协议接入（RTSP / ONVIF / SDK） |
 |
 |
> 更多界面截图见 [docs/images/](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 │
│ （持久化数据、审计日志、级联关系） │ （会话、状态、限流） │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 🚀 快速开始
### Docker 一键部署（Linux 推荐，含流媒体服务）
```bash
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 服务状态。
### 本地开发模式（Windows / Linux / macOS）
```bash
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](docs/INSTALL.md)。
---
## 🗂️ 功能全景
```
国标接入 视频业务 智能运维 数据集成 可视化
───────────── ───────────── ───────────── ───────────── ─────────────
设备注册 实时预览 网络看门狗 MQTT 对接 GIS 地图
平台级联 多分屏播放 流健康监测 Webhook 回调 电视墙
目录推送 录像检索回放 SLA 质量看板 级联上报 轨迹回放
GPS 订阅 云台 PTZ 容量基线预警 飞书/企微告警 可视化指挥
语音对讲 预置位轮巡 SIP 信令审计 S3 云存储 告警联动
```
---
## 💎 商业版：GBWatch（Go 语言）
同一团队打造的**商业版视频平台**，与 PyGBSentry 定位互补、代码库独立：
| | PyGBSentry（本项目） | GBWatch（商业版） |
|---|---|---|
| 语言 | Python 3.12+ / FastAPI | Go 1.25+（单二进制） |
| 许可 | AGPL v3（开源） | 商业许可（闭源二进制交付） |
| 定位 | 开发者 / AI 生态 / 二次开发 | 生产环境交付 / 商业运营 |
| 插件生态 | Python 插件 | 插件商城（官方 + 第三方，付费订阅） |
| 平台授权 | — | 按通道数授权（64 / 256 / 不限），Ed25519 实例绑定证书，超限拒绝新增设备 |
| 插件商城支付 | — | 支付宝 / 微信扫码购买插件，管理后台一键配置 |
GBWatch **覆盖开源版的全部核心能力**（设备注册/目录/实时预览/录像回放/云台/级联/告警等），并在此基础上额外提供：
| 增量能力 | 说明 |
|---------|------|
| 🚀 部署形态 | Go 单二进制 + 一键脚本，**3 分钟上线**；前端内嵌、内置 SQLite，无需 Nginx / MySQL / 编译环境（开源版为 Python + Docker/源码部署） |
| 📹 全协议矩阵 | GB/T 28181-2016/2022 双向级联（含目录订阅与 TCP 主动收流）· ONVIF Profile S 自动发现 · JT/T 808+1078 车载视频×轨迹同步 · GA/T 1400 视图库上报 · 海康 ISAPI / 大华 HTTP 事件网关 · RTSP/RTMP 拉流代理 |
| 🤖 AI 闭环 | 定时抓拍 → 推理服务 → 结构化事件 → 告警联动 → **以图搜图**（切片归并），内置周界防护 / 工地安全 / 移动侦测算法包 |
| 🔔 告警体系 | 30+ 报警类型**中文解析**；飞书 / 钉钉 / 企微 / 邮件 / 短信 / MQTT 推送；未处理自动升级链 L1→L2→L3 · 值班路由 · 声光/门禁/广播联动 · 报警切片 HMAC 签名免登分享 |
| 🏢 企业级 | 多租户行级隔离 + 配额 · License 功能矩阵 + 机器码绑定 · 取证证据链（SHA-256 链式哈希）· 审计中心 · 设备远程配置回显+下发（OSD/录像计划/升级等）· MinIO / NAS 归档 |
| 📦 插件商城 | **36 个官方插件**开箱即用（AI 分析 10 / 告警推送联动 9 / 运维巡检 11 / 存储证据 3 / 安全网络 3），子进程 Hook 模型任何语言可写，第三方实名入驻、支付宝/微信扫码购买 |
| ✅ 质量保障 | 六套端到端验收套件（70+ 断言）一键复跑，覆盖级联、通道授权、取证、推送等核心链路 |
**交付形态**：闭源二进制交付，License 与部署实例 Ed25519 绑定、防篡改，禁止逆向与二次分发；同一团队提供部署、定制与技术支持服务。
### 授权版本与定价
| 版本 | 通道数 | 定价 | 目标客户 |
| --- | --- | --- | --- |
| 标准版 | 64 路 | ¥5,800 永久授权（含首年更新与工单） | 小型项目、单体企业（几十路摄像头） |
| 专业版 | 256 路 | ¥19,800 永久授权（含首年更新与插件商城） | 中型项目、需要 AI 插件与商城生态 |
| 旗舰版 / OEM | 不限 | ¥59,800 / 年（含年度续约与优先支持） | 集成商批量交付、OEM 白标贴牌 |
> 所有版本均为**闭源二进制交付**，授权证书与部署实例绑定（Ed25519 防篡改），超出通道数自动拒绝新增设备；更新服务续费为授权费的 20%/年。价格可随项目规模与 OEM 数量另议。
PyGBSentry 与 GBWatch 服务于不同场景：**学习、二次开发、AI 集成选 PyGBSentry；生产部署、商业运营、需要插件生态与支付能力选 GBWatch。**
---
## 📡 GB/T 28181-2022 增强特性
| 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](docs/INSTALL.md)。
---
## 📖 文档导航
| 文档 | 适合谁 | 内容 |
|:---|:---|:---|
| [INSTALL.md](docs/INSTALL.md) | 运维/实施 | 完整部署手册，含 Docker、手工、高可用方案 |
| [INSTALL_DEPLOY.md](docs/INSTALL_DEPLOY.md) | 运维/实施 | 生产环境 checklist、NAT、端口、SSL 配置 |
| [DEVELOPER.md](docs/DEVELOPER.md) | 开发者 | 架构详解、目录说明、添加 API、扩展 SIP 逻辑 |
| [PLUGIN_SPEC.md](docs/PLUGIN_SPEC.md) | 开发者 | 插件开发规范、生命周期、API、上架流程 |
| [MEDIA_SERVER.md](docs/MEDIA_SERVER.md) | 运维/开发者 | ZLMediaKit 配置、Hook 说明、排错指南 |
| [COMPATIBILITY.md](docs/COMPATIBILITY.md) | 实施/用户 | 浏览器与设备兼容性矩阵 |
| [QA_TROUBLESHOOT.md](docs/QA_TROUBLESHOOT.md) | 所有人 | 常见问题与排查步骤 |
---
## 🤝 参与贡献
欢迎任何形式的贡献：Issue 反馈、文档改进、功能开发、Bug 修复。
```bash
# 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](https://gitee.com/suoten/GBDoctor)
- **GitHub**：[github.com/suoten/GBDoctor](https://github.com/suoten/GBDoctor)
平台接入不顺畅？用 GBDoctor 体检一下就知道卡在哪一环。
**🧰 更多相关项目**
| 项目 | 简介 | 仓库 |
|------|------|------|
| **ProtoForge** | 开源 PLC 协议模拟器：零硬件模拟 Modbus/S7/OPC-UA/BACnet/GB28181 等 28 种协议，测试上位机与网关通信 | [Gitee](https://gitee.com/suoten/ProtoForge) · [GitHub](https://github.com/suoten/ProtoForge) |
| **EdgeLiteGateway** | 开源边缘 AI 网关（Python 版）：13 种工业协议 + ONNX 推理引擎，10 分钟 Docker 部署 | [Gitee](https://gitee.com/suoten/EdgeLiteGateway) · [GitHub](https://github.com/suoten/EdgeLiteGateway) |
| **EdgeLiteGateway-Go** | 工业边缘 AI 网关 Go 版：单二进制部署，附 Linux amd64/arm64/armv7 预编译包 | [Gitee](https://gitee.com/suoten/EdgeLiteGateway-Go) · [GitHub](https://github.com/suoten/EdgeLiteGateway-Go) |
| **EdgeAgent-Hub** | 边缘智能体管理平台（Go）：ONNX + LLM + RAG + 多智能体编排，Modbus/OPC UA/MQTT 全协议接入，断网自治 + A/B 分区 OTA | [Gitee](https://gitee.com/suoten/edgeagent-hub) · [GitHub](https://github.com/suoten/EdgeAgent-Hub) |
| **IoT-ZTNA** | IoT 零信任网络访问网关（Rust）：eBPF/XDP 线速过滤 + SPIFFE 设备身份 + AI 行为检测 | [Gitee](https://gitee.com/suoten/iot-ztna) · [GitHub](https://github.com/suoten/IoT-ZTNA) |
---
## 📄 开源协议
本项目采用 [GNU Affero General Public License v3.0](LICENSE) 开源协议。
> 对于网络交互软件，AGPL v3 确保任何在公网提供服务的修改版本，也必须向用户公开源代码。这保护了开源社区的利益，也保证了项目的长期健康发展。
---
## ⭐ 社区与支持
- 问题反馈：[GitHub Issues](https://github.com/suoten/PyGBSentry/issues) ｜ [Gitee Issues](https://gitee.com/suoten/PyGBSentry/issues)
- 作者邮箱：[suoten@163.com](mailto:suoten@163.com)
如果你觉得项目有帮助，欢迎点亮 **Star**，这是对开源作者最好的鼓励。
---
# English
**Turn any server into a GB/T 28181-compliant intelligent video hub — pure Python SIP stack, built from scratch.**
📖 **[English Documentation → README_EN.md](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.
# PyGBSentry
_开箱即用的国标（GB/T 28181-2022）视频管理平台 —— 纯 Python 自研 SIP 栈_
