# java-28181框架

**Repository Path**: hui_hui_zhou/java-28181-framework

## Basic Information

- **Project Name**: java-28181框架
- **Description**: 这是28181框架，有点类似mvc，利用注解开发，目前功能没完善
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 6
- **Created**: 2024-09-20
- **Last Updated**: 2026-06-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# java-28181-framework

基于 Spring Boot 3 + JAIN-SIP 的纯 Java GB28181 视频监控平台，内嵌 ZLMediaKit 流媒体（通过 [zlm4j](https://gitee.com/aizuda/zlm4j) JNI 封装），无需单独部署流媒体服务器。

## 特性

- **全量信令**，兼容 GB/T 28181-2011 / 2016 / 2022
  - 注册/注销（Digest 鉴权，密码留空则跳过校验）
  - 心跳保活、目录查询/订阅、设备信息/状态查询
  - 实时点播（INVITE/ACK/BYE + SDP 协商，UDP / TCP 被动收流）
  - 历史录像检索、回放、下载（含倍速）
  - PTZ 云台控制（方向/变倍/预置位/光圈聚焦）
  - 设备控制（录像控制、布防撤防、远程重启、告警复位、强制 I 帧）
  - 报警通知、移动位置（GPS）上报落库
  - 目录 / 移动位置订阅（SUBSCRIBE），NOTIFY 增量上报
- **内嵌流媒体**：zlm4j 把 ZLMediaKit native 库（.so/.dll/.dylib）按平台打包进 jar，`Native.load` 自动加载，零外部依赖。设备推送的 PS 流被自动转封装为 RTSP / RTMP / HTTP-FLV / HLS / WebRTC。
- **SQLite 存储**：设备、通道、报警、录像信息持久化，开箱即用，无需额外数据库。
- **Web 管理界面**：设备/通道列表、实时点播、录像回放、PTZ 控制盘、报警查看。
- **注解式信令框架**：`@Endpoint` + `@Mapping` 把 SIP 方法 / MANSCDP CmdType 路由到处理方法。

## 运行环境

- JDK 17+（pom 默认 Java 21）
- 运行平台需被 zlm4j 支持：Linux / Windows / macOS 的 x86_64 或 aarch64
- 无需单独安装 ZLMediaKit、MySQL

## 快速开始

```bash
mvn clean package -DskipTests
java -jar target/demo-0.0.1-SNAPSHOT.jar
```

启动后访问管理界面：`http://<服务器IP>:6666/`

## 配置（application.yml）

```yaml
server:
  port: 6666            # Web/REST 端口

sip:
  ip: 192.168.1.100     # SIP 服务监听 IP（设备能访问到的地址）
  id: 41010500002000000001   # SIP 服务器 20 位国标编号
  domain: 4101050000    # SIP 域，通常取 id 前 10 位
  port: 5060            # SIP 监听端口
  password: 12345678    # 设备接入密码，留空则不鉴权

  media-ip: 192.168.1.100    # 媒体对外 IP（写入下发给设备的 SDP）
  media-stream-mode: TCP     # 收流模式：UDP / TCP（TCP=被动，ZLM 监听等设备连接）
  http-port: 8080            # ZLM HTTP（http-flv/hls）端口
  rtsp-port: 554             # ZLM RTSP 端口
  rtmp-port: 1935            # ZLM RTMP 端口
  rtc-port: 0                # ZLM WebRTC 端口（0=关闭）
  invite-timeout: 10         # 点播等待设备响应超时（秒）
```

设备侧将 SIP 服务器地址/端口/编号、接入密码按上面配置填写即可注册。

## REST 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET  | `/api/device/list` | 设备列表 |
| GET  | `/api/device/{deviceId}/channels` | 设备通道列表 |
| POST | `/api/device/{deviceId}/catalog/refresh` | 刷新目录 |
| POST | `/api/device/{deviceId}/subscribe/catalog` | 目录订阅 |
| POST | `/api/stream/play?deviceId=&channelId=` | 实时点播，返回多协议播放地址 |
| POST | `/api/stream/playback?deviceId=&channelId=&startTime=&endTime=` | 历史回放（epoch 秒） |
| POST | `/api/stream/download?deviceId=&channelId=&startTime=&endTime=&speed=` | 历史下载 |
| POST | `/api/stream/stop?callId=` | 停止流（发 BYE） |
| GET  | `/api/stream/sessions` | 活动会话列表 |
| POST | `/api/control/ptz?deviceId=&channelId=&leftRight=&upDown=&inOut=&hSpeed=&vSpeed=&zSpeed=` | PTZ 方向/变倍 |
| POST | `/api/control/ptz/stop` | PTZ 停止 |
| POST | `/api/control/preset?deviceId=&channelId=&cmd=&index=` | 预置位（cmd 0x81 设置/0x82 调用/0x83 删除） |
| POST | `/api/control/fi` | 光圈聚焦 |
| POST | `/api/control/record?deviceId=&channelId=&record=` | 录像控制 |
| POST | `/api/control/guard?deviceId=&setGuard=` | 布防/撤防 |
| POST | `/api/control/reboot?deviceId=` | 远程重启 |
| POST | `/api/control/alarm/reset` | 告警复位 |
| POST | `/api/records/query?deviceId=&channelId=&startTime=&endTime=&type=` | 录像检索（时间 ISO8601） |
| GET  | `/api/records?deviceId=&channelId=` | 已检索录像列表 |
| GET  | `/api/alarms` | 报警记录 |

## 工程结构

```
src/main/java/com/example/demo/
├── core/                       # 信令框架核心
│   ├── annotation/             # @Endpoint @Mapping
│   ├── config/                 # SipConfig / BeanConfig（SIP 协议栈）
│   ├── handlerMapping/         # 消息分发（SIP Method / MANSCDP CmdType）
│   ├── service/                # SIPProcessorObserver（消息总入口）
│   └── util/                   # SipUtil / XmlUtil / MD5Util
├── endpoint/
│   └── gbEndpoint.java         # 信令统一接入点
└── gb/
    ├── command/                # 下行命令：点播/PTZ/录像/订阅/设备控制
    ├── handler/                # 上行处理：注册/心跳/目录/报警/录像/位置
    ├── media/                  # MediaServer（zlm4j）/ ZlmNative
    ├── sip/                    # SIP 请求工厂 / 发送器 / 会话管理 / SDP 构建
    ├── storage/                # SQLite DAO（设备/通道/报警/录像）
    ├── entity/                 # 实体
    └── web/                    # REST 控制器
src/main/resources/
├── application.yml
└── static/index.html           # Web 管理界面
```

## 说明

- 媒体播放：HTTP-FLV 地址形如 `http://media-ip:8080/rtp/<streamId>.live.flv`，浏览器端可用 flv.js / hls.js 播放。
- 国标版本兼容：信令格式在 2011/2016/2022 间基本一致，差异主要在 MANSCDP 报文体字段，已做容错解析（含海康未转义字符兼容）。