354 lines
12 KiB
Markdown
354 lines
12 KiB
Markdown
# SecMPS 整合方案（最终版）：IntegrationGateway + 统一设备管理
|
||
|
||
> **版本**: v2.0
|
||
> **日期**: 2026-05-16
|
||
> **状态**: 待实施
|
||
> **替代**: v1.0 系列方案文档
|
||
|
||
---
|
||
|
||
## 一、总体架构
|
||
|
||
```
|
||
前端层
|
||
web.vite 管理端（设备管理+网关管理） warehouse 大屏（Map/Live/IoT/Alarm）
|
||
| HTTP REST | HTTP REST + SignalR
|
||
v v
|
||
Vol.Pro 后端 (api_sqlsugar)
|
||
DeviceManagerController / GatewayNodeController / SignalR Hubs
|
||
Quartz: SyncDevicesJob / RealtimePollJob / AlarmPollJob
|
||
数据库: 8 张表 (base_device / gateway_nodes / 扩展表...)
|
||
| 注册/下发设备/心跳/同步数据
|
||
v
|
||
IntegrationGateway 实例A (:5100) IntegrationGateway 实例B (:5101)
|
||
NodeCode: gw-31ku NodeCode: gw-11ku
|
||
Adapters: MC4 / Owl Adapters: MC4 / HikvisionISC
|
||
| HTTP | HTTP
|
||
v v
|
||
MC4.0 (:3000) Owl (:80) MC4.0 (:3000) 海康ISC (:80)
|
||
```
|
||
|
||
### 网关多实例架构（方案 C+）
|
||
|
||
- Vol.Pro 管理网关实例：gateway_nodes 表注册所有网关节点
|
||
- 网关启动时主动注册：POST /api/gateway/register 上报 NodeCode/Token/AdapterTypes/BaseUrl
|
||
- Vol.Pro 下发顶层设备：Base_Device.GatewayNodeId 关联设备归属
|
||
- 网关无状态：配置只有 3 个值（NodeCode/Token/VolProUrl），挂了重装即恢复
|
||
- AdapterCode 双段标识："mc4:31号库房" 区分同类型多实例
|
||
- 心跳机制：网关每 15s 上报心跳，Vol.Pro 超 30s 无心跳级联设备离线
|
||
|
||
---
|
||
|
||
## 二、IntegrationGateway 设计
|
||
|
||
### 2.1 项目结构（位于 gateway/ 独立文件夹）
|
||
|
||
```
|
||
gateway/
|
||
├── IntegrationGateway.sln
|
||
└── src/
|
||
├── IntegrationGateway.Host/ # WebAPI (:5100)
|
||
| ├── Controllers/
|
||
| | ├── HealthController.cs
|
||
| | ├── DevicesController.cs
|
||
| | ├── PointsController.cs
|
||
| | ├── StreamsController.cs
|
||
| | ├── AlarmsController.cs
|
||
| | ├── SyncController.cs
|
||
| | └── RegisterController.cs # 网关注册/心跳
|
||
| ├── appsettings.json # { NodeCode, Token, VolProUrl }
|
||
| └── Program.cs
|
||
├── IntegrationGateway.Core/
|
||
| ├── Abstractions/ → 7 个分型接口
|
||
| ├── Models/ → 10 个标准化模型
|
||
| └── Infrastructure/ → AdapterRegistry / TokenManager / RateLimiter
|
||
├── IntegrationGateway.Adapters.Owl/
|
||
└── IntegrationGateway.Adapters.MC4/
|
||
```
|
||
|
||
### 2.2 网关注册与心跳流程
|
||
|
||
```
|
||
管理端: gateway_nodes 表新增记录 → 生成 NodeCode + Token
|
||
网关配置: appsettings.json { NodeCode, Token, VolProUrl }
|
||
网关启动 → POST /api/gateway/register { nodeCode,token,adapterTypes,baseUrl }
|
||
Vol.Pro 校验 Token → 更新 AdapterTypes/BaseUrl/IsOnline=1
|
||
响应: { gatewayNodeId, devices: [Base_Device WHERE GatewayNodeId=当前网关] }
|
||
网关根据 AdapterCode 分流 → Adapter 连接第三方 → 发现子设备
|
||
网关 → POST /api/gateway/sync → Vol.Pro 写入 Base_Device 及子设备
|
||
网关每 15s → POST /api/gateway/heartbeat { nodeCode, token }
|
||
Vol.Pro 后台任务: IsOnline=1 且 LastHeartbeat < now-30s → IsOnline=0 → 级联设备离线
|
||
```
|
||
|
||
### 2.3 网关配置
|
||
|
||
```json
|
||
{
|
||
"VolProBaseUrl": "http://localhost:9100",
|
||
"NodeCode": "gw-31ku",
|
||
"NodeToken": "xxxxxxxxxx"
|
||
}
|
||
```
|
||
|
||
适配器类型由网关启动时扫描已注册的 Adapter 类自动获取，无需在配置中声明。
|
||
|
||
### 2.4 适配器能力矩阵
|
||
|
||
| 接口 | Owl | MC4.0 | 门禁(未来) |
|
||
|------|:---:|:-----:|:----------:|
|
||
| IHasOwnDeviceTree | ❌ | ✅ | ❌ |
|
||
| IHasFlatDevices | ✅ | ❌ | ✅ |
|
||
| IHasPoints | ❌ | ✅ | ❌ |
|
||
| IHasStreams | ✅ | ❌ | ❌ |
|
||
| IHasAlarms | ⚠️ | ✅ | ✅ |
|
||
| IAcceptsMetadataPush | ✅ | ❌ | ⚠️ |
|
||
|
||
### 2.5 双向同步引擎
|
||
|
||
| 方向 | 说明 | MC4.0 | Owl |
|
||
|------|------|-------|-----|
|
||
| PullToVolPro | 第三方→Vol.Pro | FullReplace | Merge |
|
||
| PushToSource | Vol.Pro→第三方 | 告警确认/控制 | 元数据/PTZ |
|
||
| Bidirectional | 先写第三方再更新本地 | 告警确认 | — |
|
||
|
||
### 2.6 Gateway API
|
||
|
||
```
|
||
# 注册与心跳
|
||
POST /api/gateway/register { nodeCode, token, adapterTypes, baseUrl }
|
||
POST /api/gateway/heartbeat { nodeCode, token }
|
||
|
||
# 设备与数据
|
||
GET /api/gateway/devices?adapter=&page=&size=
|
||
GET /api/gateway/devices/sync?adapter=
|
||
GET /api/gateway/realtime/{adapter}/{deviceId}
|
||
POST /api/gateway/realtime/{adapter}/control
|
||
GET /api/gateway/streams/{adapter}/{id}/live
|
||
POST /api/gateway/streams/{adapter}/{id}/ptz
|
||
GET /api/gateway/alarms/{adapter}?from=&to=
|
||
POST /api/gateway/alarms/{adapter}/{id}/confirm
|
||
GET /api/gateway/health
|
||
```
|
||
|
||
---
|
||
|
||
## 三、数据模型（8 张表）
|
||
|
||
### 3.1 区域表 warehouse_regions（现有）
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| Id | int PK |
|
||
| RegionName | nvarchar(255) |
|
||
| ParentId | int? (自引用树) |
|
||
|
||
### 3.2 网关节点表 gateway_nodes（新建）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| NodeId | INT AUTO_INCREMENT | 网关节点ID |
|
||
| NodeCode | NVARCHAR(50) | 网关唯一编码（管理端配置） |
|
||
| NodeName | NVARCHAR(100) | 网关名称 |
|
||
| NodeToken | NVARCHAR(100) | 认证令牌（管理端生成） |
|
||
| AdapterTypes | NVARCHAR(200) | 适配器类型（网关上报） |
|
||
| BaseUrl | NVARCHAR(200) | 网关地址（网关上报） |
|
||
| LastHeartbeat | DATETIME | 上次心跳时间 |
|
||
| IsOnline | TINYINT DEFAULT 0 | 在线状态 |
|
||
| Enable | TINYINT DEFAULT 1 | 启用 |
|
||
|
||
### 3.3 统一设备主表 Base_Device
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| DeviceId | INT AUTO_INCREMENT | Vol.Pro内部ID |
|
||
| DeviceName | NVARCHAR(100) | 本地名称 |
|
||
| AdapterCode | NVARCHAR(50) | "mc4:31号库房"（类型:实例） |
|
||
| SourceId | NVARCHAR(100) | 第三方原始ID |
|
||
| DeviceCategory | INT | 1=视频 2=IoT 3=门禁 4=道闸 5=报警 |
|
||
| RegionId | INT? | 所属区域ID |
|
||
| GatewayNodeId | INT? | 所属网关节点ID |
|
||
| IsParent | TINYINT | 是否父设备 |
|
||
| ParentDeviceId | INT? | 父设备自引用 |
|
||
| IsOnline | TINYINT | 在线状态 |
|
||
| MapModelId | NVARCHAR(100) | VgoMap模型ID |
|
||
| MapModelScale | FLOAT | |
|
||
| MapModelRotation | NVARCHAR(100) | |
|
||
| Lat/Lng | DOUBLE | WGS84 |
|
||
| ExtraData | TEXT | 适配器原始JSON |
|
||
| LocalOverrides | TEXT | 本地覆盖JSON |
|
||
| SyncVersion | BIGINT | 乐观锁 |
|
||
| LastSyncTime | DATETIME | |
|
||
|
||
唯一约束: (AdapterCode, SourceId)
|
||
|
||
### 3.4 扩展表
|
||
|
||
- Device_Video_Ext: 视频设备扩展（OwlDeviceId, Protocol, ChannelCount）
|
||
- Video_Channel: 视频通道扩展（OwlChannelId, DeviceId, OwlStreamApp/Name, HasPtz, SnapshotUrl）
|
||
- Video_Record: 录像记录（ChannelId, OwlRecordId, StartedAt, FilePath）
|
||
- Device_IoT_Ext: IoT设备扩展（Mc4DeviceId, PointIndex, Unit, IsControlPoint, ObjectType）
|
||
- IoT_DeviceData: 历史归档（DeviceId→子设备, PointValue, 仅存快照）
|
||
- IoT_Alarm: 通用告警（SourceAlarmId, DeviceId, AlarmLevel, State）
|
||
|
||
### 3.5 层级示例
|
||
|
||
```
|
||
gateway_nodes: gw-31ku (32号库房网关, MC4+Owl)
|
||
|
||
warehouse_regions: 厂区 → 新库区 → 31号库房
|
||
|
||
Base_Device (RegionId=3, GatewayNodeId=gw-31ku.NodeId):
|
||
东北角高位摄像机 (Category=1, Device_Video_Ext)
|
||
人员计数摄像机 (Category=1, Device_Video_Ext)
|
||
动环采集器 (Category=2, IsParent=1, Device_IoT_Ext)
|
||
├── 温湿度探头 (ParentDeviceId=采集器, Device_IoT_Ext.PointIndex=0)
|
||
├── 空调控制器 (ParentDeviceId=采集器, Device_IoT_Ext.IsControlPoint=1)
|
||
├── 除湿机 (ParentDeviceId=采集器)
|
||
└── 紧急报警按钮 (ParentDeviceId=采集器)
|
||
```
|
||
|
||
---
|
||
|
||
## 四、管理端统一设备页面
|
||
|
||
### 4.1 布局
|
||
|
||
```
|
||
+------------------+---------------------------------------+
|
||
| 顶部工具栏 | |
|
||
+------------------+---------------------------------------+
|
||
| 左侧区域树 | 右侧设备列表 |
|
||
| | |
|
||
| 📁 厂区 | 区域:31号库房 最后同步:05-15 |
|
||
| 📁 新库区 | +---------------------------------+ |
|
||
| 📁 31号库房 ● | | ▸动环采集器 MC4.0 █在线 | |
|
||
| 📁 11号库房 | | 东北角摄像机 Owl █在线 | |
|
||
| | +---------------------------------+ |
|
||
| [+新建区域] | |
|
||
+------------------+---------------------------------------+
|
||
```
|
||
|
||
### 4.2 前端文件
|
||
|
||
```
|
||
web.vite/src/views/warehouse/DeviceManager/
|
||
├── index.vue # 主页面
|
||
├── components/
|
||
│ ├── RegionTree.vue # el-tree 区域树
|
||
│ ├── DeviceTable.vue # el-table 可展开行
|
||
│ ├── DeviceEditDialog.vue # 编辑弹框
|
||
│ ├── MapBindingPanel.vue # 地图绑定面板
|
||
│ ├── VideoDeviceActions.vue # 视频按钮组
|
||
│ └── IoTDeviceActions.vue # IoT按钮组
|
||
└── api/deviceManager.js
|
||
```
|
||
|
||
### 4.3 后端 API
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| GET /api/DeviceManager/GetRegionTree | 区域树+设备数量 |
|
||
| GET /api/DeviceManager/GetDevicesByRegion | 区域设备列表(含子设备) |
|
||
| PUT /api/DeviceManager/{deviceId} | 更新设备(含地图绑定) |
|
||
| POST /api/DeviceManager/SyncFromGateway | 手动同步 |
|
||
|
||
### 4.4 操作按钮矩阵
|
||
|
||
| Category | 按钮 |
|
||
|----------|------|
|
||
| 1-视频 | 实时预览/云台控制/查看回放/获取快照/同步通道 |
|
||
| 2-IoT | 查看实时数据/设备控制/刷新点位/查看告警 |
|
||
| 3-门禁 | 远程开门/查看记录/查看告警 |
|
||
| 4-道闸 | 抬杆/落杆/查看记录 |
|
||
|
||
---
|
||
|
||
## 五、同步策略
|
||
|
||
### MC4.0 → 区域树+设备
|
||
- type=1 节点 → 名称匹配 warehouse_regions → 绑区或新建
|
||
- type=2 节点 → Upsert Base_Device, RegionId=叶子区域, GatewayNodeId=当前网关
|
||
- 模式: FullReplace, 频率限制: 2次/秒
|
||
|
||
### Owl → 设备
|
||
- GET /devices → Upsert Base_Device (Category=1, IsParent=1)
|
||
- GET /channels → Upsert Base_Device (ParentDeviceId=NVR)
|
||
- Owl 无区域概念 → RegionId=NULL, 管理员手动分配
|
||
- 模式: Merge
|
||
|
||
### 反方向写回
|
||
|
||
| 操作 | Owl | MC4.0 |
|
||
|------|:---:|:-----:|
|
||
| 设备改名 | ✅ PUT /devices/:id | ❌ |
|
||
| 告警确认 | ⚠️ | ✅ |
|
||
| 设备控制 | ✅ PTZ | ✅ 点位写值 |
|
||
|
||
---
|
||
|
||
## 六、部署拓扑
|
||
|
||
```
|
||
Docker: Owl+ZLM (:80) MC4.0-1 (:3000) MC4.0-2 (:3000)
|
||
| | |
|
||
+----------+-----------+-------------------+
|
||
|
|
||
+----------+-----------+
|
||
| Gateway gw-31ku | Gateway gw-11ku
|
||
| :5100 | :5101
|
||
+----------+-----------+
|
||
|
|
||
+----------+-----------+
|
||
| VolPro.WebApi |
|
||
| :9100 |
|
||
| MySQL / Redis |
|
||
+----------+-----------+
|
||
|
|
||
+--------------+---------------+
|
||
| web.vite :9000 warehouse :9200 |
|
||
+--------------------------------+
|
||
```
|
||
|
||
---
|
||
|
||
## 七、实施路线
|
||
|
||
| 阶段 | 工期 | 内容 |
|
||
|------|------|------|
|
||
| Phase 0 | Day 1-2 | Gateway骨架 + 8张表建表 + 代码生成 |
|
||
| Phase 1 | Day 3-6 | OwlAdapter + 管理端视频设备页 |
|
||
| Phase 2 | Day 7-11 | Mc4Adapter + IoT管理 + 区域树匹配 + SignalR |
|
||
| Phase 3 | Day 12-17 | warehouse端改造 + 全链路联调 |
|
||
| Phase 4 | Day 18-20 | 验证 + 缓冲 |
|
||
|
||
总计: 18-20 个工作日
|
||
|
||
---
|
||
|
||
## 八、新增整合流程
|
||
|
||
以接入「海康门禁」为例：
|
||
1. 新建 IntegrationGateway.Adapters.HikvisionAccess 项目
|
||
2. 实现 IHasFlatDevices + IHasAlarms
|
||
3. 注册到 Host → 网关启动时自动上报到 Vol.Pro
|
||
4. 前端新增 AccessDeviceActions.vue (~80行)
|
||
5. Vol.Pro 后端零改动
|
||
总工作量: 1-2 天
|
||
|
||
---
|
||
|
||
## 九、代码组织规范
|
||
|
||
| 代码类型 | 路径 | 被覆盖? |
|
||
|----------|------|:---:|
|
||
| 第三方对接 | gateway/ | ❌ |
|
||
| 扩展Controller | Controllers/*/Partial/ | ❌ |
|
||
| Entity扩展 | DomainModels/*/partial/ | ❌ |
|
||
| 前端业务逻辑 | extension/warehouse/*.jsx | ❌ |
|
||
| 自定义页面 | views/warehouse/DeviceManager/ | ❌ |
|
||
| 自动生成代码 | 生成器默认路径 | ✅ |
|
||
|
||
---
|
||
|
||
> 取代: V1.0 系列所有整合方案文档
|