# Owl（GoWVP）开源视频监控管理平台 API 调研报告

> 调研目标：为 Vol.Pro 后端对接 Owl 提供技术方案依据  
> 仓库地址：https://github.com/gowvp/owl  
> 调研日期：2026-05-06

---

## 一、API 认证方式

Owl 采用 **JWT Token** 认证机制，所有业务 API（除登录、健康检查、Webhook 回调外）均需在请求头中携带 Token。

### 1.1 登录获取 Token

- **URL**: `POST /login`
- **请求参数**:
  ```json
  {
    "data": "<RSA加密后的JSON字符串>"
  }
  ```
  - 加密前内容示例：`{"username":"admin","password":"admin"}`
  - 公钥获取：`GET /login/key`，返回 Base64 编码的 RSA 公钥（PEM 格式）
- **响应示例**:
  ```json
  {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": "admin"
  }
  ```
- **Token 有效期**: 3 天
- **使用方式**: 请求头携带 `Authorization: Bearer <token>`

### 1.2 修改凭据

- **URL**: `PUT /users`
- **说明**: 需先校验旧密码，同样使用 RSA 加密传输

---

## 二、设备管理 API

> 设备类型支持：`GB28181`、`ONVIF`、`RTMP`、`RTSP`

### 2.1 设备列表查询

- **URL**: `GET /devices`
- **认证**: 需 JWT
- **请求参数** (Query):
  | 参数 | 类型 | 说明 |
  |------|------|------|
  | `page` | int | 页码，默认 1 |
  | `size` | int | 每页大小 |
  | `key` | string | 关键词模糊搜索（名称/国标编号） |
- **响应**:
  ```json
  {
    "items": [
      {
        "id": "gb_34020000001320000001",
        "type": "GB28181",
        "device_id": "34020000001320000001",
        "name": "NVR-01",
        "transport": "UDP",
        "stream_mode": 1,
        "ip": "192.168.1.100",
        "port": 5060,
        "is_online": true,
        "registered_at": "2026-05-06T10:00:00Z",
        "keepalive_at": "2026-05-06T10:05:00Z",
        "keepalives": 30,
        "expires": 3600,
        "channels": 4,
        "address": "192.168.1.100:5060",
        "password": "",
        "username": "",
        "ext": {}
      }
    ],
    "total": 100
  }
  ```

### 2.2 设备详情

- **URL**: `GET /devices/:id`
- **响应**: 单条 Device 对象（同上）

### 2.3 添加设备

- **URL**: `POST /devices`
- **认证**: 需 JWT
- **请求体**:
  ```json
  // GB28181 设备
  {
    "type": "GB28181",
    "device_id": "34020000001320000001",
    "name": "摄像头1",
    "password": "123456"
  }

  // ONVIF 设备
  {
    "type": "ONVIF",
    "ip": "192.168.1.100",
    "port": 80,
    "username": "admin",
    "password": "12345",
    "name": "ONVIF摄像头"
  }
  ```
- **说明**: GB28181 设备实际注册靠设备主动 SIP 注册，此接口用于预录入设备信息

### 2.4 修改设备

- **URL**: `PUT /devices/:id`
- **请求体** (`EditDeviceInput`):
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `device_id` | string | 20 位国标编号 |
  | `name` | string | 设备名称 |
  | `password` | string | 注册密码 |
  | `stream_mode` | int | 0:UDP, 1:TCP_PASSIVE, 2:TCP_ACTIVE |
  | `username` | string | ONVIF 用户名 |
  | `ip` | string | ONVIF IP |
  | `port` | int | ONVIF 端口 |

### 2.5 删除设备

- **URL**: `DELETE /devices/:id`

### 2.6 查询设备目录（刷新通道）

- **URL**: `POST /devices/:id/catalog`
- **说明**: 向 GB28181 设备发送 Catalog 查询指令，拉取通道列表
- **响应**: `{"msg": "ok"}`（异步执行）

### 2.7 ONVIF 设备发现

- **URL**: `GET /onvif/discover`
- **说明**: SSE 流式返回发现的 ONVIF 设备

---

## 三、通道管理 API

### 3.1 通道列表查询

- **URL**: `GET /channels`
- **认证**: 需 JWT
- **请求参数** (Query):
  | 参数 | 类型 | 说明 |
  |------|------|------|
  | `page` | int | 页码 |
  | `size` | int | 每页大小 |
  | `did` | string | 父设备 ID |
  | `device_id` | string | 国标编码 |
  | `key` | string | 名称/国标编码模糊搜索，ID 精确搜索 |
  | `is_online` | string | 是否在线过滤 |
  | `type` | string | 通道类型：GB28181/ONVIF/RTMP/RTSP |
  | `app` | string | 应用名 |
  | `stream` | string | 流 ID |
- **响应**:
  ```json
  {
    "items": [
      {
        "id": "gb_34020000001320000001_34020000001320000001",
        "did": "gb_34020000001320000001",
        "device_id": "34020000001320000001",
        "channel_id": "34020000001320000001",
        "name": "通道01",
        "ptztype": 1,
        "is_online": true,
        "is_playing": false,
        "type": "GB28181",
        "app": "rtp",
        "stream": "gb_34020000001320000001_34020000001320000001",
        "has_recording": true,
        "config": {}
      }
    ],
    "total": 100
  }
  ```

### 3.2 设备与通道关联列表

- **URL**: `GET /devices/channels`
- **说明**: 返回设备列表，每个设备包含 `children`（通道数组），并按在线状态排序
- **响应**:
  ```json
  {
    "items": [
      {
        "id": "gb_xxx",
        "name": "NVR-01",
        "is_online": true,
        "children": [
          {
            "id": "gb_xxx_xxx",
            "name": "通道01",
            "is_online": true,
            "has_recording": true
          }
        ]
      }
    ],
    "total": 10
  }
  ```

### 3.3 添加通道（RTMP/RTSP）

- **URL**: `POST /channels`
- **请求体** (`AddChannelInput`):
  ```json
  {
    "type": "RTMP",
    "name": "推流通道1",
    "device_id": "",
    "device_name": "",
    "app": "live",
    "stream": "stream01",
    "config": {
      "is_auth_disabled": false,
      "session": "",
      "media_server_id": "",
      "push_addr": ""
    }
  }
  ```

### 3.4 修改通道

- **URL**: `PUT /channels/:id`
- **请求体** (`EditChannelInput`):
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `device_id` | string | 国标编码 |
  | `name` | string | 通道名称 |
  | `ptztype` | int | 云台类型 |
  | `is_online` | bool | 是否在线 |
  | `ext` | object | 扩展属性 |
  | `app` | string | 应用名（RTMP/RTSP） |
  | `stream` | string | 流 ID |
  | `config` | StreamConfig | 流配置 |

### 3.5 删除通道

- **URL**: `DELETE /channels/:id`
- **限制**: 仅允许删除 RTMP/RTSP 类型通道

---

## 四、实时流地址获取 API

### 4.1 获取播放地址

- **URL**: `POST /channels/:id/play`
- **认证**: 需 JWT
- **说明**: 根据通道类型自动处理拉流逻辑
  - **GB28181**: Owl 通过 SIP 邀请设备推流到 ZLM，自动开启 RTP Server
  - **RTMP**: 检查是否已推流，直接从 ZLM 获取播放地址
  - **RTSP**: 通过 ZLM 添加流代理（AddStreamProxy），再返回地址
  - **ONVIF**: 直接从 ZLM 获取播放地址
- **响应** (`playOutput`):
  ```json
  {
    "app": "rtp",
    "stream": "gb_34020000001320000001_34020000001320000001",
    "items": [
      {
        "label": "ZLM",
        "ws_flv": "ws://host:port/proxy/sms/rtp/gb_xxx.live.flv",
        "http_flv": "http://host:port/proxy/sms/rtp/gb_xxx.live.flv",
        "rtmp": "rtmp://host:port/rtp/gb_xxx",
        "rtsp": "rtsp://host:port/rtp/gb_xxx",
        "webrtc": "webrtc://host:port/proxy/sms/index/api/webrtc?app=rtp&stream=gb_xxx&type=play",
        "hls": "http://host:port/proxy/sms/rtp/gb_xxx/hls.fmp4.m3u8"
      }
    ]
  }
  ```

### 4.2 停止播放

- **URL**: `POST /channels/:id/stop`
- **说明**: 幂等操作，始终返回成功
  - GB28181: 发送 SIP BYE + 关闭 ZLM RTP Server
  - ONVIF/RTSP/RTMP: 调用 ZLM `close_streams` 关闭流
- **响应**: `{"msg": "ok"}`

### 4.3 快照相关

- **刷新快照**: `POST /channels/:id/snapshot`
  - 请求体可指定 `within_seconds`（秒内有效则返回缓存）和 `url`（指定取流地址）
  - 响应: `{"link": "http://host/channels/:id/snapshot?token=xxx"}`
- **获取快照图片**: `GET /channels/:id/snapshot?token=xxx`
  - 直接返回 JPEG 图片流

---

## 五、回放流地址获取 API（云录像）

Owl 的录像回放功能由 Owl 自身管理（非设备 SD 卡录像），底层依赖 ZLM 的 MP4 录制。

### 5.1 查询录像列表

- **URL**: `GET /recordings`
- **认证**: 需 JWT
- **请求参数** (Query):
  | 参数 | 类型 | 说明 |
  |------|------|------|
  | `page` | int | 页码 |
  | `size` | int | 每页大小 |
  | `cid` | string | 通道 ID |
  | `app` | string | 应用名 |
  | `stream` | string | 流 ID |
  | `start_ms` | int64 | 开始时间戳（毫秒） |
  | `end_ms` | int64 | 结束时间戳（毫秒） |
- **响应**:
  ```json
  {
    "items": [
      {
        "id": 1,
        "cid": "gb_xxx_xxx",
        "app": "rtp",
        "stream": "gb_xxx_xxx",
        "started_at": "2026-05-06T10:00:00Z",
        "ended_at": "2026-05-06T10:05:00Z",
        "duration": 300.5,
        "path": "/recordings/rtp/gb_xxx_xxx/20260506/xxx.mp4",
        "size": 10485760
      }
    ],
    "total": 50
  }
  ```

### 5.2 获取时间轴

- **URL**: `GET /recordings/timeline?cid=xxx&start_ms=xxx&end_ms=xxx`
- **响应**:
  ```json
  {
    "items": [
      {
        "id": 1,
        "start_ms": 1714982400000,
        "end_ms": 1714982700000,
        "duration": 300.5
      }
    ]
  }
  ```

### 5.3 获取月度统计

- **URL**: `GET /recordings/monthly?cid=xxx&year=2026&month=5`
- **响应**:
  ```json
  {
    "year": 2026,
    "month": 5,
    "days": 31,
    "has_video": "101010..."  // 每天是否有录像，'1'有/'0'无
  }
  ```

### 5.4 HLS 回放播放

- **URL**: `GET /recordings/channels/:cid/index.m3u8?start_ms=xxx&end_ms=xxx&token=xxx`
- **说明**: 动态生成 m3u8 播放列表，将指定时间范围内的多个 MP4 片段拼接为 HLS (VOD)
- **Content-Type**: `application/vnd.apple.mpegurl`

### 5.5 下载录像

- **URL**: `GET /recordings/:id/download`
- **说明**: 返回 MP4 文件流，支持 HTTP Range 请求（边下载边播放）

### 5.6 静态文件播放

- **URL**: `GET /static/recordings/{path}?token=xxx`
- **说明**: 直接访问 MP4/fMP4 文件，同样支持 Range 请求

---

## 六、云台控制 API

### 6.1 PTZ 控制

- **URL**: `POST /channels/:id/ptz/control`
- **认证**: 需 JWT
- **请求体** (`ptzControlInput`):
  | 字段 | 类型 | 必填 | 说明 |
  |------|------|------|------|
  | `action` | string | 是 | 动作类型：`continuous` / `stop` / `absolute` / `relative` / `preset` |
  | `direction` | string | 否 | 方向（continuous 时用）：`up` / `down` / `left` / `right` / `zoom_in` / `zoom_out` |
  | `speed` | float64 | 否 | 速度 0-1 |
  | `x` | float64 | 否 | X 轴位置（absolute/relative） |
  | `y` | float64 | 否 | Y 轴位置 |
  | `zoom` | float64 | 否 | 缩放值 |
  | `preset_id` | string | 否 | 预置位 ID |
  | `preset_op` | string | 否 | 预置位操作：`goto` / `set` / `remove` |
- **当前实现限制**: 代码中**仅实现了 `continuous` 和 `stop`**，其他动作类型会返回错误
- **响应**:
  ```json
  {
    "msg": "PTZ 控制指令已发送"
  }
  ```
- **注意**: 目前代码中直接调用 GB28181 Server 的 PTZControl 方法，未区分协议类型（ONVIF PTZ 支持标记为 TODO）

---

## 七、设备状态查询 API

### 7.1 在线状态

Owl 没有单独的"设备状态查询"接口，设备状态包含在设备/通道列表查询中：

- **设备在线状态**: `GET /devices` 或 `GET /devices/:id` → `is_online`
- **通道在线状态**: `GET /channels` 或 `GET /devices/channels` → `is_online`
- **通道播放状态**: `is_playing`

### 7.2 设备模型关键状态字段

| 字段 | 说明 |
|------|------|
| `is_online` | 是否在线（SIP 注册成功且心跳正常） |
| `registered_at` | 最近一次注册时间 |
| `keepalive_at` | 最近一次心跳时间 |
| `keepalives` | 心跳间隔（秒） |
| `expires` | 注册有效期（秒） |
| `address` | 设备网络地址（如 `192.168.1.100:5060`） |
| `transport` | 信令传输协议（`UDP` / `TCP`） |
| `channels` | 通道数量 |

### 7.3 注册与心跳机制（SIP 层）

- **注册**: GB28181 设备主动向 Owl 的 SIP 端口（默认 5060）发送 REGISTER 请求
  - Owl 支持 Digest 鉴权，密码可设备单独配置或使用全局默认密码
  - 注册成功后 Owl 自动查询 DeviceInfo 和 Catalog
- **心跳**: 设备按 `Keepalives` 间隔发送 MESSAGE 心跳
  - Owl 通过 `keepalive_at` 和 `expires` 判断设备是否离线
  - 例如：设备侧超时 3 秒 × 3 次，则约 9+x 秒收不到心跳认为离线
- **注销**: 设备发送 Expires=0 的 REGISTER 请求

> **重要**: 注册和心跳是 **SIP 协议层**自动完成的，没有对应的 HTTP API。Vol.Pro 只需通过 HTTP API 查询设备列表即可获知在线状态。

---

## 八、Owl 与 ZLMediaKit 联动机制

### 8.1 架构关系

```
摄像机/NVR --(SIP/RTP)--> Owl --(HTTP API/Webhook)--> ZLMediaKit
                                    ^
                                    | (反向代理播放)
前端播放器 --(HTTP/WebSocket)---> Owl /proxy/sms/xxx
```

### 8.2 Owl 配置 ZLM 的 Hook 回调

Owl 启动时会自动连接 ZLM，并通过 `SetServerConfig` 接口设置以下 Webhook 地址（前缀为 `http://{owl_host}:{owl_port}/webhook`）：

| Hook 接口 | 方法 | 说明 |
|-----------|------|------|
| `/webhook/on_server_started` | POST | ZLM 启动时触发，Owl 将所有 RTMP 通道置为离线 |
| `/webhook/on_server_keepalive` | POST | ZLM 定时保活（默认 10s），Owl 更新节点在线状态 |
| `/webhook/on_publish` | POST | 推流鉴权（RTMP/RTSP/RTP），Owl 校验是否允许推流 |
| `/webhook/on_play` | POST | 播放鉴权，Owl 更新通道播放状态为 playing |
| `/webhook/on_stream_changed` | POST | 流注册/注销时触发，Owl 根据录像模式决定是否启动录制 |
| `/webhook/on_stream_none_reader` | POST | 无人观看时触发，Owl 根据录像模式决定是否关闭流 |
| `/webhook/on_stream_not_found` | POST | 播放不存在的流时触发，Owl 触发按需拉流（ONVIF/RTSP） |
| `/webhook/on_rtp_server_timeout` | POST | RTP Server 超时未收到数据 |
| `/webhook/on_record_mp4` | POST | MP4 切片录制完成，Owl 将录像信息入库 |

### 8.3 Owl 调用 ZLM 的 API

通过 `internal/core/sms/driver_zlm.go` 封装调用：

| ZLM API | Owl 封装方法 | 说明 |
|---------|-------------|------|
| `openRtpServer` | `OpenRTPServer` | 开启 RTP 收流端口（GB28181 用） |
| `closeRtpServer` | `CloseRTPServer` | 关闭 RTP 端口 |
| `close_streams` | `CloseStreams` | 强制关闭流 |
| `addStreamProxy` | `AddStreamProxy` | 添加 RTSP 拉流代理 |
| `getSnap` | `GetSnapshot` | 获取流截图 |
| `startRecord` | `StartRecord` | 开始 MP4 录制 |
| `stopRecord` | `StopRecord` | 停止 MP4 录制 |
| `getServerConfig` | `GetServerConfig` | 获取配置（含端口信息） |
| `setServerConfig` | `SetServerConfig` | 设置配置（含 Hook 地址） |
| `restartServer` | `RestartServer` | 重启 ZLM（rtc 端口变更时） |

### 8.4 播放地址生成规则

Owl 通过反向代理 `/proxy/sms/*path` 将所有播放请求转发到 ZLM，前端无需直接访问 ZLM。

生成逻辑（`GetStreamLiveAddr`）：

| 协议 | URL 格式示例 |
|------|-------------|
| **WS-FLV** | `ws://owl_host/proxy/sms/{app}/{stream}.live.flv` |
| **HTTP-FLV** | `http://owl_host/proxy/sms/{app}/{stream}.live.flv` |
| **HLS(fMP4)** | `http://owl_host/proxy/sms/{app}/{stream}/hls.fmp4.m3u8` |
| **WebRTC** | `webrtc://owl_host/proxy/sms/index/api/webrtc?app={app}&stream={stream}&type=play` |
| **RTMP** | `rtmp://owl_host:1935/{app}/{stream}` |
| **RTSP** | `rtsp://owl_host:554/{app}/{stream}` |

### 8.5 联动流程示例（GB28181 实时播放）

1. 前端调用 `POST /channels/:id/play`
2. Owl 向 ZLM 调用 `openRtpServer` 开启 UDP/TCP 收流端口
3. Owl 通过 SIP 发送 INVITE 给设备，SDP 中携带 ZLM 的收流地址
4. 设备通过 RTP 向 ZLM 推流
5. ZLM 触发 `on_publish` → `on_stream_changed` Hook
6. Owl 返回包含播放地址的 JSON 给前端
7. 前端通过 `/proxy/sms/...` 播放流
8. 无人观看时，ZLM 触发 `on_stream_none_reader`
9. Owl 判断无需录像 → 返回 `Close: true` → ZLM 关闭流
10. Owl 发送 SIP BYE 结束会话

---

## 九、其他相关 API

### 9.1 流媒体服务器管理

- `GET /media_servers` - 查询媒体服务器列表
- `PUT /media_servers/:id` - 修改媒体服务器配置

### 9.2 推流管理

- `GET /stream_pushs` - 查询推流列表（含 RTMP 推流地址）
- `POST /stream_pushs` - 添加推流
- `PUT /stream_pushs/:id` - 修改推流
- `DELETE /stream_pushs/:id` - 删除推流

### 9.3 事件/告警管理

- `GET /events` - 分页查询 AI 检测事件
- `GET /events/:id` - 事件详情
- `GET /events/image/*path` - 获取事件快照图片（无需认证）

### 9.4 配置管理

- `GET /configs/info` - 获取 SIP 等配置信息
- `PUT /configs/info/sip` - 修改 SIP 配置

### 9.5 系统接口

- `GET /health` - 健康检查
- `GET /app/metrics/api` - API 实时监控指标
- `GET /app/version/check` - 检查新版本

---

## 十、Vol.Pro 对接建议

### 10.1 对接方式

Vol.Pro 后端直接通过 **HTTP REST API** 调用 Owl，无需处理 SIP 协议。

### 10.2 关键对接流程

```
1. 登录 Owl → 获取 JWT Token（缓存）
2. 定时同步设备列表 → GET /devices
3. 定时同步通道列表 → GET /channels 或 GET /devices/channels
4. 用户点击播放 → POST /channels/:id/play → 获取播放地址 → 前端播放
5. 用户停止播放 → POST /channels/:id/stop
6. 回放查询 → GET /recordings?cid=xxx&start_ms=xxx&end_ms=xxx
7. 回放播放 → GET /recordings/channels/:cid/index.m3u8?start_ms=xxx&end_ms=xxx
8. 云台控制 → POST /channels/:id/ptz/control
```

### 10.3 注意事项

1. **Token 管理**: JWT 有效期 3 天，建议在 Vol.Pro 中缓存并处理过期刷新
2. **播放地址代理**: 前端播放地址建议走 Owl 的 `/proxy/sms/...` 路径，无需暴露 ZLM 直接地址
3. **按需拉流**: GB28181 实时播放是按需拉流，首次播放可能有 1-3 秒延迟（SIP 信令 + ZLM 准备）
4. **录像模式**: 通道支持 `always` / `ai` / `none` 三种录像模式，通过 `POST /channels/:id/record_mode` 设置
5. **PTZ 限制**: 当前 Owl 仅支持 `continuous`（持续移动）和 `stop`（停止），预置位等功能未完整实现
6. **心跳与注册**: 不要尝试通过 HTTP 模拟设备注册，这是 SIP 层自动完成的
7. **ONVIF PTZ**: README 中标记为"未支持"（`[ ] ONVIF PTZ control support`）

---

*报告整理完毕，供 Vol.Pro 后端架构设计参考。*