7.3 KiB
网关 Owl 模块检查报告 2026-06-03
基准文档:
doc/对接文档/GoWVP接口文档.md(3419行, ~40个API) 检查范围:gateway/src/IntegrationGateway.Adapters.Owl/(OwlAdapter.cs, OwlAuthHelper.cs) 日期: 2026-06-03
1. 覆盖率概览
GoWVP 接口文档共 40 个 REST 端点，当前 OwlAdapter 覆盖了 8 个（20%）。
| 模块 | 文档端点数 | 已实现 | 缺失 |
|---|---|---|---|
| 控制台 | 1 | 0 | 1 |
| 推流列表 | 4 | 0 | 4 |
| 拉流代理 | 4 | 0 | 4 |
| 国标设备 | 6 | 3 | 3 |
| 国标通道 | 3 | 3 | 0 |
| 通道管理 | 4 | 2 | 2 |
| AI 检测 | 4 | 0 | 4 |
| 事件 | 5 | 0 | 5 |
| 区域管理 | 2 | 0 | 2 |
| 配置管理 | 2 | 0 | 2 |
| 流媒体 | 2 | 0 | 2 |
| ONVIF | 3 | 0 | 3 |
| 合计 | 40 | 8 | 32 |
2. 已实现接口对照
| GoWVP 端点 | OwlAdapter 方法 | 能力接口 | 状态 |
|---|---|---|---|
| GET /devices | GetDevicesAsync | IHasFlatDevices | ✅ |
| PUT /devices/{id} | PushMetadataAsync | IAcceptsMetadataPush | ✅ |
| POST /channels/{id}/play | GetLiveUrlAsync | IHasStreams | ✅ |
| POST /channels/{id}/ptz | PtzControlAsync / PtzStopAsync | IHasStreams | ✅ |
| POST /channels/{id}/snapshot | GetSnapshotAsync | IHasStreams | ✅ |
| GET /recordings | GetRecordingsAsync | IHasRecordings | ✅ |
| (未映射) | GetPlaybackUrlAsync | IHasStreams | ⚠️ 自拼URL |
| GET /health | HealthCheckAsync | IGatewayAdapter | ✅ |
3. 缺失项详细清单
3.1 控制台监控（1个）
| 端点 | 用途 | 影响 |
|---|---|---|
| GET /stats | CPU/内存/磁盘/网络实时监控 | 管理端无法查看 Owl 服务器健康度 |
建议: OwlAdapter 增加 GetStatsAsync()，返回 CPU/内存/磁盘 JSON，Capabilities.HasStats = true。
3.2 推流管理（4个）
| 端点 | 说明 |
|---|---|
| POST /stream_pushs | 添加推流通道 |
| GET /stream_pushs | 分页查询推流列表 |
| PUT /stream_pushs/{id} | 编辑推流 |
| DELETE /stream_pushs/{id} | 删除推流 |
影响: 管理端无法从 Vol.Pro 直接添加/管理 Owl 推流通道，需登录 Owl 控制台操作。
3.3 拉流代理（4个）
| 端点 | 说明 |
|---|---|
| POST /stream_proxys | 添加拉流代理 |
| GET /stream_proxys | 分页查询拉流列表 |
| PUT /stream_proxys | 编辑拉流代理 |
| DELETE /stream_proxys/{id} | 删除拉流代理 |
影响: 同推流，非 GB28181 的 RTSP/RTMP 通道无法通过管理端管理。
3.4 国标设备扩展（3个）
| 端点 | 说明 | 当前替代 |
|---|---|---|
| GET /devices/channels | 一键获取所有设备+通道列表 | 无 — 当前 GetDevicesAsync 只返回 NVR，不展开通道 |
| POST /devices | 添加 GB28181 设备 | 无 |
| POST /devices/{id}/catalog | 查询设备目录 | 无 |
关键缺失: GET /devices/channels 直接返回设备+通道的联合结果，比单独调 /devices + /channels 高效。当前适配器在 GetDevicesAsync 中只映射了 NVR 设备（IsParent=true），没有展开下级通道。
3.5 通道管理（2个）
| 端点 | 说明 |
|---|---|
| POST /channels | 添加 RTMP/RTSP 通道 |
| DELETE /channels/{id} | 删除通道 |
| GET /channels | 通道列表(独立) |
半缺失: GET /channels 和 PUT /channels/{id} 虽未直接调用，但流和 PTZ 接口已间接使用通道 ID。
3.6 AI 检测能力（4个）
| 端点 | 说明 |
|---|---|
| POST /channels/{id}/ai/enable | 启用 AI 检测 |
| POST /channels/{id}/ai/disable | 禁用 AI 检测 |
| POST /channels/{id}/zones | 添加 AI 检测区域 |
| GET /channels/{id}/zones | 获取检测区域 |
影响: Owl 的 AI 人数统计/区域入侵能力无法通过网关管理端开启/配置。
3.7 AI 事件管理（5个）
| 端点 | 说明 |
|---|---|
| GET /events | 分页查询 AI 事件（按通道/标签/时间筛选） |
| GET /events/{id} | 事件详情 |
| PUT /events/{id} | 更新事件 |
| DELETE /events/{id} | 删除事件 |
| GET /events/image/{path} | 获取事件快照图片 |
战略缺失: Owl AI 事件（人员检测、车辆检测、入侵告警等）是视频智能监控的核心数据。当前网关零接入，意味着：
- 规则引擎无法以"人数越限"为条件触发动作
- AI 事件不能同步到 Vol.Pro 告警表
- 事件快照无法在大屏展示
建议: 通过 IHasAlarms 接口暴露 AI 事件，映射 StandardAlarm { AlarmId=event.id, Level=重要/普通, Title=label, Content=快照路径 }。
3.8 系统管理（4个）
| 端点 | 说明 |
|---|---|
| GET /configs/info | 查询配置 |
| PUT /configs/info/sip | 修改 SIP 配置 |
| GET /media_servers | 流媒体列表 |
| PUT /media_servers/{id} | 修改流媒体 |
影响: 运维类接口，暂不阻塞业务。
3.9 ONVIF（3个）
| 端点 | 说明 |
|---|---|
| GET /onvif/devices-discover | ONVIF 设备发现 |
| POST /onvif | 添加 ONVIF 设备 |
| GET /onvif/discover | ONVIF 设备发现(SSE) |
4. 现有代码问题项
4.1 设备列表只返回 NVR 不展开通道
GetDevicesAsync → MapDevice 将所有设备映射为 IsParent=true, Category="硬盘录像机"，不查询也不返回通道子设备。这导致：
- Vol.Pro 设备树中 Owl 设备全是父设备，无摄像头子节点
- 前端预览按钮要求
DeviceGroup='视频设备'的叶子设备，找不到子设备
GET /devices/channels 可一次性返回设备+通道，相比两次调用更高效。
4.2 OwlDevice 模型字段不完整
当前 OwlDevice 只有 8 个字段（Id, Name, IsOnline, Protocol, Address, Port, Transport），GoWVP 返回的 Device 至少有 20+ 个字段，缺失包括：
| 缺失字段 | 说明 | 用途 |
|---|---|---|
| Manufacturer | 厂商 | 设备详情显示 |
| Model | 型号 | 设备详情显示 |
| Firmware | 固件版本 | 运维 |
| Longitude/Latitude | 经纬度 | 地图标记 |
| ChannelCount | 通道数 | 统计 |
| Status/RegisterWay | 注册方式 | GB28181 状态 |
| CreatedAt/UpdatedAt | 时间戳 | 同步管理 |
4.3 HealthCheck 端点路径可能错误
代码调 GET /health，但 GoWVP 文档显示控制台唯一端点 GET /stats。需确认 Owl 实际实现。
4.4 GetPlaybackUrlAsync 手工拼 URL
直接拼接 /recordings/channels/{id}/index.m3u8?start_ms=&end_ms=&token=，未调用 Owl API。虽然功能通常可用，但依赖内部路径约定，Owl 版本升级可能失效。
4.5 无 PTZ 预设位/巡航支持
GoWVP PTZ 接口 POST /channels/{id}/ptz/control 支持 action: preset/patrol/scan/stop，当前仅实现 continuous 方向移动和 stop。
5. 优先级建议
| 优先级 | 项目 | 说明 |
|---|---|---|
| 🔴 P0 | 设备列表展开通道 | 前端无法展示摄像头设备 |
| 🔴 P0 | AI 事件接入 IHasAlarms | 规则引擎无法获知人数/入侵 |
| 🟠 P1 | 使用 GET /devices/channels | 替代当前单独调 /devices |
| 🟠 P1 | OwlDevice 字段补全 | 设备详情展示 |
| 🟡 P2 | AI 检测启停 | 远程控制 Owl AI |
| 🟡 P2 | 推流/拉流 CRUD | 管理端统一通道管理 |
| ⚪ P3 | 预设位/巡航 PTZ | 高级云台功能 |
| ⚪ P3 | 系统管理接口 | 运维便捷性 |
| ⚪ P3 | ONVIF 设备发现 | 部署时的设备发现 |