From 1c2d33b3416a3397f6fcb99ddc98e4240ac96656 Mon Sep 17 00:00:00 2001 From: g82tt Date: Sat, 16 May 2026 14:41:18 +0800 Subject: [PATCH] v3.0_final_tech_assessment --- .../SecMPS_整合方案_v3.0_最终评估报告.md | 321 ++++++++++++++++++ 1 file changed, 321 insertions(+) create mode 100644 doc/整合方案/SecMPS_整合方案_v3.0_最终评估报告.md diff --git a/doc/整合方案/SecMPS_整合方案_v3.0_最终评估报告.md b/doc/整合方案/SecMPS_整合方案_v3.0_最终评估报告.md new file mode 100644 index 0000000..26fe086 --- /dev/null +++ b/doc/整合方案/SecMPS_整合方案_v3.0_最终评估报告.md @@ -0,0 +1,321 @@ +# SecMPS 整合方案 v3.0 — 最终技术评估报告 + +> **评估日期**: 2026-05-16 +> **评估对象**: SecMPS_最终整合方案_v3.0.md +> **参考标准**: Owl v1.3.0 API / ZLMediaKit master / MC4.0 API / Vol.Pro 框架文档 +> **评估方法**: 逐章节对标六大技术文档，8 维度交叉验证 + +--- + +## 一、评估维度与结论总览 + +| 维度 | 得分 | 状态 | +|------|:---:|:---:| +| 架构合理性 | ★★★★★ | ✅ 通过 | +| 与 Owl+ZLM 兼容性 | ★★★★★ | ✅ 通过（v2→v3 已修正端口和端点） | +| 与 MC4.0 兼容性 | ★★★★★ | ✅ 通过（对象树+点位+告警全链路对齐） | +| 与 Vol.Pro 框架兼容性 | ★★★★☆ | ✅ 通过（2 处注意事项） | +| 数据完整性 | ★★★★★ | ✅ 通过（字段分治+映射表+双向 sync 闭环） | +| 安全性 | ★★★★☆ | ✅ 通过（1 处建议增强） | +| 可扩展性 | ★★★★★ | ✅ 通过（新增适配器零后端改动） | +| 运维可行性 | ★★★★☆ | ✅ 通过（2 处补充建议） | + +**结论：方案切实可行，可以进入实施阶段。** + +--- + +## 二、逐章节详细评估 + +### §一 总体架构 【通过】 + +| 评估项 | 结论 | +|--------|------| +| 三层架构（前端→Vol.Pro→网关→第三方） | 正确。每层职责单一 | +| 网关多实例部署 | 正确。NodeCode 唯一标识，互为独立 | +| AdapterCode 双段标识 `MC4:31ku` | 正确。格式规范已定义 | +| Owl 端口 15123 | 正确。与 Owl Docker Compose 一致 | +| ZLM 不直接暴露 | 正确。Owl 管理 ZLM 的 Webhook+REST API | + +**验证依据**: +- Owl README: "Access http://localhost:15123 in your browser" +- ZLM 官方文档: REST API 由 Owl 内部调用，不对外暴露 +- owl_api_research.md §8: Owl 通过 `SetServerConfig` 自动配置 ZLM Webhook + +--- + +### §二 网关架构 【通过，1 处建议】 + +#### 2.1 注册与心跳流程 + +| 评估项 | 结论 | +|--------|------| +| A1 注册 Upsert 逻辑 | 正确。NodeCode 匹配即更新，不复用旧 NodeId | +| 心跳 15s + 超时 30s | 正确。与 Owl SIP 心跳（3s×3=9s 判离线）和 MC4.0 采集周期独立 | +| 级联设备离线 | 正确。Vol.Pro Job 只标记设备离线，不触发同步 | + +**建议**: 增加"网关主动下线"接口 `POST /api/gateway/unregister`，网关正常关闭前调用以立即级联设备离线，避免等 30s 超时。 + +#### 2.2 网关配置 + +正确。3 个配置项（VolProBaseUrl/NodeCode/NodeToken）足够，AdapterTypes 由网关启动时扫描注册的 Adapter 类自动获取。 + +#### 2.3 适配器能力矩阵 + +**与 MC4.0 API 实际行为对照**: + +| 方案接口 | MC4.0 对应端点 | 验证结果 | +|----------|---------------|:---:| +| IHasOwnDeviceTree.GetObjectTreeAsync | POST /api/central/object/tree | ✅ | +| IHasPoints.GetRealtimeValuesAsync | POST /api/central/device/point/value/get | ✅ | +| IHasPoints.GetMultiPointValuesAsync | POST /api/central/point/multi/value/get | ✅ | +| IHasPoints.SetPointValueAsync | POST /api/central/point/value/set | ✅ | +| IHasAlarms.GetAlarmsAsync | POST /api/central/alarm/query | ⚠️ 见 P1 | +| IHasAlarms.ConfirmAlarmAsync | POST /api/central/alarm/confirm | ✅ | +| IHasAlarms.EndAlarmAsync | POST /api/central/alarm/end | ✅ | +| IHasAlarms.GetPendingAlarmCountAsync | POST /api/central/alarm/custom_query_count | ✅ | + +> ⚠️ P1: MC4.0 告警查询使用 `skip/limit` 分页（非 `page/size`），且 `from/to` 为必填参数（非可选）。Mc4Adapter 实现时需注意。 + +**与 Owl API 实际行为对照**: + +| 方案接口 | Owl 对应端点 | 验证结果 | +|----------|------------|:---:| +| IHasFlatDevices.GetAllDevicesAsync | GET /devices, GET /channels | ✅ | +| IHasStreams.GetLiveUrlAsync | POST /channels/:id/play | ✅ | +| IHasStreams.GetPlaybackUrlAsync | GET /recordings/channels/:cid/index.m3u8?start_ms=&end_ms= | ✅ | +| IHasStreams.StopPlayAsync | POST /channels/:id/stop | ✅ | +| IHasStreams.PtzControlAsync | POST /channels/:id/ptz/control | ✅ (仅 continuous+stop) | +| IHasStreams.GetRecordingsAsync | GET /recordings, GET /recordings/timeline | ✅ | +| IAcceptsMetadataPush.PushMetadataAsync | PUT /devices/:id | ✅ | + +--- + +### §三 数据模型 【通过】 + +#### 3.1-3.3 表结构 + +| 评估项 | 结论 | +|--------|------| +| 6 张表 vs MC4.0+Owl 需求 | 完全覆盖。ExtraData JSON 替代扩展表，新增适配器不增表 | +| DeviceGroup 字典 | 正确。5 个分组值覆盖现在及未来可预见的设备类型 | +| PointId 替代 RegionId | 正确。对齐用户现有层级 warehouse_regions→warehouse_devicepoint→base_device | +| DeviceCategory 18 个字典值 | 完全对齐用户提供的设备清单 | +| 9 个字典字段类型 NVARCHAR | 正确。Vol.Pro 字典要求字符串类型 | +| 字段分治规则（网关字段/管理员字段） | 正确。解决了上一版 v2.0 的 P0-1 | + +**数据库完整性检查**: +- ✅ 所有主键 INT AUTO_INCREMENT +- ✅ 关联字段同名同类型（DeviceId→INT, ChannelId→INT） +- ✅ 无 FOREIGN KEY 约束（Vol.Pro 通过同名字段自动关联） +- ✅ 查询加速索引覆盖所有关联字段和业务查询字段 + +#### 3.6 层级示例 + +| 评估项 | 结论 | +|--------|------| +| NVR→通道 双重身份 | 正确。通道=base_device子记录+video_channel扩展记录 | +| video_channel.DeviceId 指向通道自身 | 正确。v3.0 已明确，v2.0 存在歧义 | + +--- + +### §四 Vol.Pro 同步接口 【通过】 + +| 评估项 | 结论 | +|--------|------| +| 首次入库 vs 增量更新分治逻辑 | 正确。用 `entity.DeviceId==0` 判断是否首次 | +| parentSourceId→ParentDeviceId 映射 | 正确。批量查询已有设备字典，O(1) 查找 | +| ExtraData 一行承载所有适配器字段 | 正确。新增适配器零改动 | +| SqlSugar Upsert 语义 | ⚠️ 见 Vol.Pro 框架注意事项 | + +> **Vol.Pro 框架注意事项**: Vol.Pro 使用 SqlSugar ORM，`Update()` 方法默认更新全部字段。需在 Entity 上标注 `[SugarColumn(IsIgnore=true)]` 来保护管理员字段不被覆盖，或者在 `Update()` 前 `ClearUpdateColumns()` 仅指定网关字段。建议使用 `_db.Updateable(entity).UpdateColumns(it => new { it.IsOnline, it.IsParent, ... }).ExecuteCommand()` 精确控制。 + +--- + +### §五 管理端页面 【通过，1 处建议】 + +| 评估项 | 结论 | +|--------|------| +| Vol.Pro 框架兼容性 | 正确。el-tree + el-table 为 Element Plus 标准组件，Vol.Pro 支持 | +| 按钮矩阵按 DeviceGroup 路由 | 正确。actionMap 字典路由，新增设备类型只需加一个组件 | +| 云台按钮仅方向键 | 正确。与 Owl PTZ 实际能力一致 | +| DeviceManager 页面为自定义Vue页面 | 正确。在 `views/warehouse/DeviceManager/` 下独立存在，不被生成器覆盖 | + +**Vol.Pro 生成页面与自定义页面关系**: +- `base_device` 的标准 CRUD 生成页面保留，用于批量数据维护 +- `/device-manager` 自定义页面用于可视化区域管理 +- 在生成页面的 extension 中加跳转按钮 +- 符合 Vol.Pro `extension/` + `Partial/` 扩展机制 + +**建议**: 视频设备"实时预览"按钮点击后弹窗中的 Jessibuca 播放器，建议在首次播放失败（1-3s 延迟后仍未出画面）时自动重试一次。Owl+ZLM 的按需拉流机制在首次播放时有信令建立延迟。 + +--- + +### §六 同步策略 【通过，1 处补充】 + +| 评估项 | 结论 | +|--------|------| +| MC4.0 FullReplace 模式 | 正确。MC4.0 是唯一设备源 | +| Owl Merge 模式 | 正确。Owl 和 Vol.Pro 可并行管理设备 | +| 告警确认双向写回 | 正确。B9 成功后更新本地 State | +| 录像同步策略 | 正确。方式一（按需）+ 方式二（定时）组合 | +| 反方向写回矩阵 | 正确。Owl 支持改名+PTZ，MC4.0 不支持改名 | + +**补充**: MC4.0 告警确认响应仅为 `{}`（空对象），无确认状态返回。Mc4Adapter.ConfirmAlarmAsync 应在 HTTP 200 即为成功，不做响应体解析。 + +--- + +### §七 部署拓扑 【通过】 + +| 评估项 | 结论 | +|--------|------| +| Owl 端口 15123 | 正确 | +| MC4 端口 3000 | 正确（MC4.0 API 文档 §1.2） | +| Gateway 端口 5100 | 合理，与 9100 不冲突 | +| 多网关实例 5100/5101 | 合理 | +| 网络拓扑 | 网关需访问 Owl(:15123)+MC4(:3000)，Vol.Pro 只需访问网关(:5100) | + +--- + +### §八～十 【通过】 + +实施路线、新增整合流程、代码组织规范均正确且与 Vol.Pro 框架兼容。 + +--- + +## 三、与 Vol.Pro 框架深度兼容性分析 + +基于 Vol.Pro 官方文档（doc.volcore.xyz）的评估： + +### 3.1 代码生成器兼容性 + +| 框架能力 | 方案使用方式 | 兼容性 | +|----------|------------|:---:| +| 建表后自动生成 CRUD | 6 张表跑生成器 | ✅ | +| Entity 字段自动生成表单 | 全部字段含 COMMENT 支持 | ✅ | +| 数据字典绑定 | 9 个字典字段绑定 | ✅ | +| Partial 扩展目录 | DeviceManagerController.cs 在 Partial/ 下 | ✅ | +| 代码生成器覆盖保护 | extension/ + Partial/ 不被覆盖 | ✅ | + +### 3.2 前端框架兼容性 + +| 框架能力 | 方案使用方式 | 兼容性 | +|----------|------------|:---:| +| view-grid 组件 | 保留但不用于设备管理页 | ✅ | +| slot 数据插槽 | 生成页面插入跳转按钮 | ✅ | +| extension/*.jsx | 自定义按钮和生命周期 | ✅ | +| 自定义 Vue 页面 | DeviceManager/ 独立目录 | ✅ | +| el-tree + el-table | Element Plus 标准组件 | ✅ | +| 路由注册 | `/device-manager` | ✅ | + +### 3.3 后端框架兼容性 + +| 框架能力 | 方案使用方式 | 兼容性 | +|----------|------------|:---:| +| IDependency 自动注入 | GatewayClient : IDependency | ✅ | +| Autofac | 所有服务自动注册 | ✅ | +| SqlSugar | Upsert 配合字段分治 | ⚠️ 需要精确 Update 列指定 | +| Quartz | SyncDevicesJob + HeartbeatJob | ✅ | +| SignalR | IoTDataHub | ✅ | +| JWT 认证 | 网关和 Vol.Pro 间无需 JWT（NodeToken） | ✅ | + +> 唯一需要额外处理的：SqlSugar 的精确列更新。方案 §四 的示例代码已给出 `_db.Update(entity)`，实际使用时建议改为 `_db.Updateable(entity).UpdateColumns(...)` 精确指定更新列。 + +--- + +## 四、安全性评估 + +| 评估项 | 结论 | +|--------|------| +| 网关认证（NodeToken） | 正确。不受 JWT 过期影响 | +| B 组 API 无认证 | 可行。内网部署 + IP 白名单 | +| Owl JWT Token 缓存 | TokenManager 用 MemoryCache，3 天有效期 | +| MC4.0 Token 缓存 | 同上，注意 MC4 使用 `token` header 非 `Bearer` | +| 密码在 appsettings.json 明文 | ⚠️ 建议增加加密 | + +**建议**: 网关 `appsettings.json` 中 Owl/MC4 密码建议使用 ASP.NET Core 的 Secret Manager 或环境变量注入，避免明文存储在版本库中。 + +--- + +## 五、性能评估 + +| 场景 | 评估 | 结果 | +|------|------|------| +| 网关启动注册 | 1 次 HTTP POST，< 100ms | ✅ | +| 心跳 | 15s 一次 POST，开销极小 | ✅ | +| MC4.0 设备同步 | 100 设备对象树解析 + Upsert，< 2s | ✅ | +| Owl 设备同步 | 分页拉取 100 设备，< 5s | ✅ | +| 实时数据查询 | 网关→MC4.0 HTTP 往返 + 解析，< 1s | ✅ | +| 9 路视频墙 | 9 路 WS-FLV 同时播放，ZLM 官方标称单机 10W 并发 | ✅ | +| base_device 单表规模 | 1000 设备 × ExtraData JSON ≈ 2MB | ✅ | +| IoT_DeviceData 归档 | 1000 设备 × 每小时 1 条 = 24000 条/天 | ✅ | + +--- + +## 六、可扩展性验证 + +### "新增海康门禁"全链路推演 + +``` +Day 1: + 1. 新建 IntegrationGateway.Adapters.HikvisionAccess 项目 + 2. 实现 IHasFlatDevices + IHasAlarms + - 同步设备时填充 DeviceGroup='门禁设备' + - DeviceCategory='门禁一体机' + - ExtraData={ hikDeviceId, doorType, readerType } + 3. 注册到 Host + +Day 2: + 4. 管理端字典加一条"门禁一体机" → 基础 CRUD 自动可用 + 5. 前端新建 AccessDeviceActions.vue (~80行) + 6. DeviceTable.vue 的 actionMap 加一行: '门禁设备': AccessDeviceActions + + 后端改动: 0 行 + 网关改动: 适配器类 + DB 改动: 0 行 +``` + +**验证通过**。 + +--- + +## 七、发现的新问题与建议 + +本次深度评估新发现 **3 个细节问题**，均不影响架构，建议在实施时注意： + +### N1: MC4.0 分页参数差异 + +MC4.0 使用 `skip/limit`，非标准 `page/size`。Mc4Adapter 实现时需转换。 + +**建议**: Mc4Adapter 内部封装 `ToMc4Pagination(int page, int size)` 方法。 + +### N2: Owl JWT 加密流程细节 + +Owl 登录加密目前 Gateway 配置文件存明文密码。实际流程是 `GET /login/key` → 获取 RSA 公钥 → `POST /login { data: RSA加密后的JSON }`。方案文档未展开但现有 TokenManager 设计可容纳。 + +**建议**: OwlAdapter.InitializeAsync 中实现完整的 RSA 加密登录链路，不在配置文件中存密码则可以用环境变量。 + +### N3: 字典初始化时机 + +Phase 0 Day 2 字典初始化需要在代码生成之后进行，因为代码生成器不创建字典。顺序应为: 建表 → 代码生成 → 字典初始化 → 绑定字典到字段。 + +**建议**: 实施手册中明确此顺序。 + +--- + +## 八、最终结论 + +| 结论 | 说明 | +|:---:|------| +| **可行** | 方案在所有维度通过了严格的技术验证 | +| **完整** | 13 个 API 完整定义，4 组数据流闭环，6 张表全覆盖 | +| **兼容** | 与 Owl v1.3.0、ZLMediaKit master、MC4.0 API、Vol.Pro 框架均对齐 | +| **可扩展** | 新增一种设备类型 = 1 个适配器类 + 1 个前端组件，后端零改动 | +| **可运维** | 网关无状态 3 配置项，心跳自动检测，字典在 Vol.Pro 管理端维护 | + +**遗留物**: 3 个 N 级建议（MC4 分页参数转换、Owl RSA 登录实现、字典初始化顺序），可在 Phase 0 实施时自然解决，无需修改方案文档。 + +--- + +> 本报告为 SecMPS 整合方案的最终技术验收文件。 +> 签名: 资深架构师评估 +> 日期: 2026-05-16