SecMPS/doc/整合方案/SecMPS_整合方案_v2.0_最终评估报告.md

SecMPS 整合方案 — 最终评估报告

评估日期: 2026-05-16
评估对象: SecMPS_最终整合方案_v2.0.md
参考依据: Owl API 文档 / Owl GitHub / ZLMediaKit 官方文档 / ZLMediaKit GitHub / 数据字典设计

---

一、评估方法

以资深架构师经验，对整合方案进行三个维度的交叉验证：

1. 方案自洽性：章节间逻辑是否一致，API 定义 ↔ 数据模型 ↔ 同步策略是否闭环
2. 对 Owl+ZLMediaKit 的准确性：方案定义的接口和流程是否与 Owl v1.3.0 / ZLMediaKit master 实际行为匹配
3. 工程可落地性：是否所有细节都有明确定义，是否存在"开发时再说"的模糊地带

共发现 14 个问题，按严重程度分为 P0（阻塞实施）、P1（影响质量）、P2（优化项）。

---

二、P0 — 必须修复（4 项）

P0-1：第四章示例代码与 A3 接口规范矛盾

问题描述： §四示例代码（第 263-265 行）在每次同步时写入 DeviceName = d.Name 和 DeviceCategory = d.Category。但 A3 接口规范明确说"网关不碰管理员字段，首次入库写全量，后续仅更新网关负责的列"。这导致管理员手动改过的设备名称每次同步后被网关覆盖。

影响：管理员的设备重命名操作会被同步覆盖，用户投诉

解决方案：

// 区分首次入库与增量更新
if (entity.DeviceId == 0) // 首次入库
{
    entity.DeviceName = d.Name;
    entity.DeviceCategory = d.Category;
    entity.DeviceGroup = d.Group;
}
// 增量更新：只写网关负责的字段
entity.IsOnline = d.IsOnline ? "在线" : "离线";
entity.IsParent = d.IsParent ? "是" : "否";
entity.ExtraData = d.ExtraDataJson;
entity.LastSyncTime = DateTime.UtcNow;

---

P0-2：A3 设备同步中 parentSourceId → ParentDeviceId 解析链路缺失

问题描述： A3 请求中设备携带 parentSourceId: "1001"（第三方 ID），但 Vol.Pro 需要 ParentDeviceId（本地主键）。从第三方 ID 到本地主键的映射逻辑完全未定义。

影响：子设备无法挂到父设备下，设备树断裂

解决方案： 同步前先做映射表查询：

// 批量取出当前网关所有设备
var allIds = await _db.base_device
    .Where(x => x.GatewayNodeId == nodeId)
    .ToDictionaryAsync(x => (x.AdapterCode, x.SourceId), x => x.DeviceId);

// 解析 parentSourceId
int? parentDeviceId = null;
if (!string.IsNullOrEmpty(d.ParentSourceId))
    allIds.TryGetValue((d.AdapterCode, d.ParentSourceId), out var pid);
    parentDeviceId = pid > 0 ? pid : null;

entity.ParentDeviceId = parentDeviceId;

补充到 §四 代码示例中。

---

P0-3：网关重启注册时 NodeId 分配逻辑未定义

问题描述： 网关重启再次调用 A1 /register，gateway_nodes 表中 NodeCode 已存在。当前文档只说注册流程，没有说明是覆盖还是报错。如果新建 NodeId，则 base_device.GatewayNodeId 指向旧 ID 断裂。

影响：网关重启后设备归属丢失

解决方案： A1 接口改为 Upsert 逻辑：

POST /register → 
  NodeCode 匹配 → 更新 AdapterTypes/BaseUrl/IsOnline=在线 → 返回已有 NodeId
  NodeCode 不匹配 → 插入新记录 → 返回新 NodeId → 401（防止未授权节点）

补充到 §2.1 流程描述和 A1 API 规范中。

---

P0-4：Owl 管理端口错误

问题描述： Owl README 和 Docker Compose 明确 Owl Web 管理端口 = 15123。方案 appsettings.json 和 §七部署拓扑均写 owl_host:80。

影响：网关无法连接 Owl，所有视频功能不可用

解决方案：

• appsettings.json 中 Owl BaseUrl → http://owl_host:15123
• §七部署拓扑中 Owl 端口标记为 :15123
• 注意：ZLM 自身 HTTP 端口是 8000，但由 Owl 内部调用，网关不接触

---

三、P1 — 影响实施质量（6 项）

P1-1：PTZ 接口仅实现 continuous + stop

问题描述： owl_api_research.md §6.1 和 Owl GitHub 确认：Owl 代码中仅实现了 continuous（持续移动）和 stop（停止），preset（预置位）、absolute（绝对定位）、relative（相对定位）均返回错误。ONVIF PTZ 标记为 TODO。 方案 §2.3 适配器矩阵和 B7 API 没有注明此限制。

影响：开发前端云台面板时做了预置位下拉等功能，部署后不可用

解决方案：

• B7 接口标注："仅支持 continuous (方向移动) + stop (停止)"
• 前端云台面板：仅显示方向键（↑↓←→）+ 停止按钮，不显示预置位
• OwlAdapter.PtzControlAsync 实现：ONVIF 设备直接返回错误

---

P1-2：视频通道在 base_device 和 video_channel 中的双重身份不清

问题描述： §6 Owl 同步说 "Upsert base_device(ParentDeviceId=NVR) + video_channel"，但 §3.6 层级示例中摄像机是叶子节点没有子设备。一个 Owl 通道到底是 base_device 的子记录还是 video_channel 的独立记录？还是两者都是？

影响：开发者不清楚通道数据写入哪张表的哪个字段

解决方案： 明确：一个 Owl 通道 = 2 条记录：

1. base_device 子记录（DeviceName="通道01", DeviceCategory=摄像机, ParentDeviceId=NVR的DeviceId, ExtraData=null）
2. video_channel 扩展记录（DeviceId=通道的DeviceId, OwlStreamApp, OwlStreamName, HasPtz, SnapshotUrl） 在 §3.6 层级示例中增加通道示例：

NVR (IsParent=是)
├── 通道01 (base_device子记录, video_channel.OwlStreamApp="rtp")
├── 通道02 (base_device子记录, video_channel.OwlStreamApp="rtp")

---

P1-3：回放取流与实时取流走不同的 Owl 端点

问题描述：

• 实时播放：POST /channels/:id/play
• 回放播放：GET /recordings/channels/:cid/index.m3u8?start_ms=&end_ms=&token= 两者是 Owl 的不同端点，方案 B6 只有一个 /live 路径。

影响：回放功能无法对接 Owl

解决方案： B6 拆分为两个端点：

GET  /streams/{adapter}/{channelId}/live          → Owl POST /channels/:id/play
GET  /streams/{adapter}/{channelId}/playback?start=&end=  → Owl GET /recordings/channels/:cid/index.m3u8

IHasStreams 接口不变（已有 GetLiveUrlAsync 和 GetPlaybackUrlAsync），只修正 B 组 API 路径。

---

P1-4：告警确认后 Vol.Pro 本地状态更新不闭环

问题描述： B9 调网关确认告警写回第三方成功，但 iot_alarm.State 谁来更新？当前文档没有说明这个回写链路。

影响：管理端显示告警仍为"未确认"，需等下次 A4 同步才刷新

解决方案： B9 确认成功后，Vol.Pro 侧同步更新本地：

POST /alarms/{adapter}/{alarmId}/confirm 成功 →
  Vol.Pro 更新 iot_alarm SET State='已确认', ConfirmTime=NOW()

不需要网关二次推送。在 B9 接口规范中补充此说明。

---

P1-5：video_record 同步策略缺失

问题描述： §六同步策略有设备同步、告警同步、反向控制，但没有录像记录的同步时机和频率。

影响：录像数据永远不会写入 video_record 表

解决方案： 补充 §六：Owl 录像数据同步策略 ——

• 方式一（推荐）：管理端点击"查看回放"时，网关实时调 Owl GET /recordings → 返回给管理端 → 同时写入 video_record 表
• 方式二（备选）：网关定时（每 10 分钟）调 Owl GET /recordings → 走 A3 扩展同步 → 写入 video_record 建议先用方式一，方式二在 Phase 3 优化时引入。

---

P1-6：AdapterCode 双段格式无约束

问题描述： "mc4:31号库房" 中分隔符 : 和实例名字符集没有规范。如果实例名包含 : 会导致解析歧义。

影响：网关配置或同步时数据损坏

解决方案： 定义格式规范（补充到 §2.2）：

AdapterCode = "{AdapterType}:{InstanceName}"
  AdapterType: 字母数字，对应网关注册的 Adapter 类名（如 MC4、Owl）
  InstanceName: 字母数字下划线，对应具体网关实例（如 31ku）
分隔符: ':'
示例: "MC4:31ku"、"Owl:main"、"HikvisionISC:center"

---

四、P2 — 优化项（4 项）

P2-1：子设备离线状态级联规则（明确即可）

问题描述： §2.1 说网关离线 → 设备离线，但网关在线时父设备（采集器）离线，子设备是否级联标记离线？

解决方案： 网关在 A3 同步时如实上报每个子设备的 isOnline（MC4.0 树中已有此信息），Vol.Pro 不做推断，信任网关数据。在 §六同步策略中补充此行说明即可。

---

P2-2：数据字典初始化运维指引（补充附录）

问题描述： 方案依赖 7 个数据字典（DeviceCategory 18 值、DeviceGroup 5 值、IsParent/IsOnline/Enable/IsControlPoint/AlarmLevel/State），但没有初始化指引。

解决方案： 在文档末尾增加「附录 A：字典初始化清单」，列出每个字典的 Code/Name/Value 对照表，运维人员在 Vol.Pro 管理端按表创建。

---

P2-3：video_channel 流地址字段用途说明（补充注释）

问题描述： video_channel 有 OwlStreamApp/OwlStreamName/SnapshotUrl，B6 取流实时调网关获取。这些字段的实际用途没说。

解决方案： 注明为缓存——首次取流后写入 video_channel，下次先查缓存，缓存过期（或 Owl 重启后）再调 B6 实时获取。在 video_channel 表注释中补充说明。

---

P2-4：Owl AI 事件可接入告警（建议纳入 Phase 1 可选范围）

问题描述： Owl 有 YOLO 本地检测 + GET /events 接口，AI 事件可走 A4 告警同步。

解决方案： 在 OwlAdapter 中可选实现 IHasAlarms，将 GET /events 的 AI 检测事件映射为 StandardAlarm（AlarmLevel=提示或普通）。在 §六同步策略中补充可选说明，建议 Phase 1 范围中列入。

---

五、架构正确性确认

以下方面经过 Owl+ZLMediaKit 双文档验证，确认正确：

验证项	状态
三层架构（前端→网关→Owl）不直接接触 ZLM	✅
Owl 代理播放地址 /proxy/sms/...	✅
Owl RTP 收流→ZLM 转协议→多格式输出的链路	✅
Owl Webhook 自动配置 ZLM（启动时 SetServerConfig）	✅
JWT Token 管理 + RSA 加密登录	✅
设备/通道 CRUD 对应 Owl API	✅
取流端点返回 WS-FLV/HTTP-FLV/HLS/WebRTC/RTMP/RTSP	✅
Owl↔ZLM 联动（OpenRtpServer/CloseRtpServer/AddStreamProxy 等）	✅
按需拉流 + 30s 无人观看自动关闭（ZLM on_stream_none_reader → Owl 通知 ZLM 关流）	✅
云录像由 Owl 管理（ZLM MP4 录制→Owl on_record_mp4 hook→入库）	✅
GB28181 设备注册与心跳是 SIP 层自动完成（Vol.Pro 只查 HTTP API）	✅
播放地址通过 Owl /proxy/sms/ 反向代理到 ZLM（前端不直接访问 ZLM）	✅

---

六、总结

优先级	数量	类型
P0	4	阻塞性缺陷（代码矛盾、链路缺失、端口错误、注册逻辑缺失）
P1	6	实施质量影响（PTZ限制、通道身份、回放端点、告警闭环、录像缺失、格式规范）
P2	4	优化项（级联规则、字典指引、缓存说明、AI事件）
✅	12	已验证正确

总体评价：方案架构方向完全正确，Owl+ZLMediaKit 对接路径准确。14 个问题中 P0/P1 共 10 项，全部为配置级或接口路径级微调，不涉及架构推翻。修复后可直接作为实施基准。

---

本报告应作为 SecMPS_最终整合方案_v2.0.md 的修正依据。建议将 P0/P1 问题修复合入方案文档后再开始 Phase 1。