影子设备系统联动关系文档

1. 系统架构与组件关系

1.1 分层架构

┌───────────────────────────────────────────────────────────────────────────┐
│ Northbound Adapters (MQTT / OPC UA / REST / Modbus-TCP Server / Others) │
│  - AuthN/AuthZ  - Rate Limit  - Audit Log  - Dynamic Mount/Unmount       │
└───────────────────────────────┬───────────────────────────────────────────┘
                                │
                         Shadow Service API
               read/write/subscribe/consistency-check
                                │
┌───────────────────────────────┴───────────────────────────────────────────┐
│ Shadow Core (唯一内部模型中心)                                            │
│  - Real Shadow Store (Memory + WAL)                                       │
│  - Virtual Shadow Engine (公式依赖图 + 增量计算)                           │
│  - Edge Compute Engine (差值/步长/滑动平均/阈值)                           │
│  - Atomic Dispatcher (CAS + 序列号 + QoS ACK)                             │
│  - Shadow Device Optimizer (RTT/MTU/Gap 优化)                             │
└───────────────────────────────┬───────────────────────────────────────────┘
                                │
                           Shadow Ingress
                                │
┌───────────────────────────────┴───────────────────────────────────────────┐
│ Points Layer                                                               │
│  - Normalize  - Unit Convert  - Timestamp Align  - Batch Publish QoS0/1/2 │
└───────────────────────────────┬───────────────────────────────────────────┘
                                │
                     Southbound Drivers (Modbus/CAN/IEC/...)

1.2 核心组件关联关系

组件	功能	关联组件	数据流向
Shadow Core	核心数据管理	所有组件	中心枢纽
Shadow Device Optimizer	采集优化	Shadow Core	双向
Virtual Shadow Engine	虚拟设备计算	Shadow Core	双向
Points Layer	数据归一化	驱动层、Shadow Ingress	单向
Shadow Ingress	数据接入	Points Layer、Shadow Core	单向
Northbound Adapters	北向接口	Shadow Core	双向
Southbound Drivers	南向驱动	Points Layer	单向

2. 关键流程与数据样例

2.1 采集入影子时序

步骤 1: 驱动采集原始值

驱动：Modbus 驱动

原始数据：

{
  "deviceId": "rack-01",
  "register": 40001,
  "value": 7423,
  "timestamp": "2026-03-20T12:00:00.000Z"
}

步骤 2: Points 归一化

归一化后数据：

{
  "messageId": "uuid-123",
  "qos": 1,
  "deviceId": "rack-01",
  "channelId": "modbus-1",
  "timestamp": "2026-03-20T12:00:00.000Z",
  "points": [
    {
      "pointId": "pack_voltage",
      "value": 742.3,
      "unit": "V",
      "quality": "good",
      "samplePeriodMs": 1000
    }
  ],
  "meta": {
    "source": "modbus-driver",
    "sequence": 123456
  }
}

步骤 3: Shadow Core 原子落地

影子设备数据：

{
  "shadowDeviceId": "shadow-rack-01",
  "physicalDeviceId": "rack-01",
  "channelId": "modbus-1",
  "version": 1,
  "updatedAt": "2026-03-20T12:00:00.001Z",
  "points": {
    "pack_voltage": {
      "value": 742.3,
      "unit": "V",
      "rw": "r",
      "samplePeriodMs": 1000,
      "quality": "good",
      "timestamp": "2026-03-20T12:00:00.000Z",
      "version": 1
    }
  },
  "communicationProfile": {
    "deviceId": "rack-01",
    "channelId": "modbus-1",
    "protocolType": "modbus",
    "ewmaRTT": 50000,
    "currentMTU": 1024,
    "currentGap": 128,
    "lastUpdated": "2026-03-20T12:00:00.001Z"
  }
}

步骤 4: WAL 记录

WAL 记录：

{
  "offset": 1,
  "eventType": "shadow-write",
  "shadowDeviceId": "shadow-rack-01",
  "version": 1,
  "payloadHash": "a1b2c3d4e5f6",
  "createdAt": "2026-03-20T12:00:00.001Z",
  "payload": "{...}"
}

步骤 5: 边缘计算与虚拟公式更新

虚拟设备计算：

{
  "virtualDeviceId": "virtual-energy-mix-01",
  "version": 1,
  "updatedAt": "2026-03-20T12:00:00.050Z",
  "formulaPoints": {
    "total_voltage": "rack-01.pack_voltage * 2"
  },
  "dependencies": ["rack-01.pack_voltage"],
  "points": {
    "total_voltage": {
      "value": 1484.6,
      "unit": "V",
      "rw": "r",
      "timestamp": "2026-03-20T12:00:00.050Z",
      "version": 1
    }
  }
}

2.2 北向写入控制时序

步骤 1: 北向适配器请求

请求数据：

{
  "shadowDeviceId": "shadow-rack-01",
  "pointId": "control_setpoint",
  "value": 800.0,
  "qos": 2,
  "timestamp": "2026-03-20T12:01:00.000Z"
}

步骤 2: Shadow Core 写入

更新后影子设备：

{
  "shadowDeviceId": "shadow-rack-01",
  "physicalDeviceId": "rack-01",
  "channelId": "modbus-1",
  "version": 2,
  "updatedAt": "2026-03-20T12:01:00.001Z",
  "points": {
    "pack_voltage": {
      "value": 742.3,
      "unit": "V",
      "rw": "r",
      "samplePeriodMs": 1000,
      "quality": "good",
      "timestamp": "2026-03-20T12:00:00.000Z",
      "version": 1
    },
    "control_setpoint": {
      "value": 800.0,
      "unit": "V",
      "rw": "rw",
      "timestamp": "2026-03-20T12:01:00.000Z",
      "version": 2
    }
  }
}

步骤 3: WAL 记录

WAL 记录：

{
  "offset": 2,
  "eventType": "shadow-write",
  "shadowDeviceId": "shadow-rack-01",
  "version": 2,
  "payloadHash": "f6e5d4c3b2a1",
  "createdAt": "2026-03-20T12:01:00.001Z",
  "payload": "{...}"
}

步骤 4: 通知订阅者

订阅者收到：

{
  "deviceId": "shadow-rack-01",
  "points": {
    "control_setpoint": {
      "value": 800.0,
      "unit": "V",
      "rw": "rw",
      "timestamp": "2026-03-20T12:01:00.000Z",
      "version": 2
    }
  }
}

2.3 RTT/MTU/Gap 优化时序

步骤 1: 驱动采集 RTT 数据

RTT 数据：

{
  "deviceId": "rack-01",
  "rtt": 50000, // 50ms
  "timestamp": "2026-03-20T12:00:00.000Z"
}

步骤 2: Shadow Core 更新 RTT

调用：UpdateDeviceRTT("rack-01", 50000)

步骤 3: 优化器计算

RTT 管理器：计算 EWMA RTT = 50000
MTU 管理器：协商 MTU = 1024（基于 RTT < 100ms）
Gap 优化器：优化 Gap = 128（基于 MTU=1024, RTT=50ms）

步骤 4: 更新影子设备通信画像

通信画像：

{
  "deviceId": "rack-01",
  "channelId": "modbus-1",
  "protocolType": "modbus",
  "ewmaRTT": 50000,
  "currentMTU": 1024,
  "currentGap": 128,
  "rttSamples": [50000, 52000, 48000],
  "lastUpdated": "2026-03-20T12:00:00.001Z"
}

3. 数据结构关联关系

3.1 核心数据结构

数据结构	关联结构	描述
ShadowIngressMessage	ShadowDevice	点位标准报文，用于从 Points Layer 到 Shadow Core
ShadowDevice	DeviceCommunicationProfile	真实影子设备，包含通信画像
VirtualDevice	ShadowDevice	虚拟影子设备，依赖真实设备点位
WALRecord	ShadowDevice/VirtualDevice	写前日志，确保数据一致性
DeviceCommunicationProfile	RTT/MTU/Gap 数据	设备通信画像，包含优化参数

3.2 数据流向图

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Southbound      │     │ Points Layer    │     │ Shadow Ingress  │
│ Drivers         │────>│ Normalize/Align │────>│ Data Ingest     │
└─────────────────┘     └─────────────────┘     └────────────┬────┘
                                                             │
┌─────────────────┐     ┌─────────────────┐     ┌────────────▼────┐
│ Northbound      │<────│ Shadow Service  │<────│ Shadow Core     │
│ Adapters        │     │ API             │     │ (Memory + WAL)  │
└─────────────────┘     └─────────────────┘     └────────────┬────┘
                                                             │
┌─────────────────┐     ┌─────────────────┐     ┌────────────▼────┐
│ Virtual Shadow  │<────│ Edge Compute    │<────│ Shadow Device   │
│ Engine          │     │ Engine          │     │ Optimizer       │
└─────────────────┘     └─────────────────┘     └─────────────────┘

4. 关键接口与调用关系

4.1 核心接口

接口	功能	调用方	实现方
WriteShadowDevice	写入影子设备	Points Layer	Shadow Core
WriteShadowPoint	写入影子点位	Northbound Adapters	Shadow Core
GetShadowDevice	获取影子设备	Northbound Adapters	Shadow Core
UpdateDeviceRTT	更新设备RTT	Southbound Drivers	Shadow Core
CreateVirtualDevice	创建虚拟设备	Northbound Adapters	Virtual Shadow Engine
Subscribe	订阅影子设备更新	Northbound Adapters	Shadow Core

4.2 调用关系示例

驱动采集流程：
- 驱动 → Points Layer → Shadow Ingress → Shadow Core.WriteShadowDevice → WAL 追加 → 通知订阅者
北向控制流程：
- Northbound Adapter → Shadow Core.WriteShadowPoint → WAL 追加 → 通知订阅者
RTT 优化流程：
- 驱动 → Shadow Core.UpdateDeviceRTT → ShadowDeviceOptimizer → 更新通信画像 → WAL 追加
虚拟设备计算流程：
- Shadow Core 通知 → Virtual Shadow Engine → 公式计算 → 更新虚拟设备 → 通知订阅者

5. 一致性与可靠性保证

5.1 一致性机制

WAL 机制：所有写操作先写 WAL，再更新内存
版本控制：每个影子设备和点位都有版本号
CAS 操作：确保并发写入的一致性
QoS 支持：支持消息可靠传递

5.2 可靠性机制

重启恢复：通过 WAL 回放恢复状态
数据校验：定期一致性检查
错误处理：完善的错误处理和重试机制
审计日志：记录所有操作日志

6. 性能优化策略

6.1 数据优化

批量处理：Points Layer 批量发布
缓存机制：虚拟设备公式缓存
增量计算：虚拟设备增量更新

6.2 通信优化

RTT 优化：基于 EWMA 的 RTT 统计
MTU 优化：动态协商 MTU
Gap 优化：基于 MTU 和 RTT 的 Gap 优化

6.3 存储优化

内存存储：实时数据内存存储
WAL 压缩：定期 WAL 压缩
异步写入：非阻塞 WAL 写入

7. 系统扩展与集成

7.1 扩展点

北向适配器：支持 MQTT、OPC UA、REST、Modbus-TCP Server 等
南向驱动：支持 Modbus、CAN、IEC 等协议
边缘计算规则：可扩展的边缘计算规则

7.2 集成方式

标准 API：RESTful API
消息队列：MQTT 订阅
工业协议：OPC UA、Modbus-TCP

8. 测试与验证

8.1 功能测试

单元测试：100% 代码覆盖率
集成测试：各组件集成测试
端到端测试：完整流程测试

8.2 性能测试

吞吐量测试：5 万点/秒持续 24h
延迟测试：P99 ≤ 5ms
稳定性测试：7×24 小时运行

8.3 可靠性测试

故障恢复：模拟各种故障场景
数据一致性：验证数据一致性
容错能力：测试系统容错能力

9. 部署与运维

9.1 部署方式

容器化部署：Docker 容器
裸机部署：直接运行
边缘部署：资源受限环境

9.2 运维监控

健康检查：系统健康状态
性能监控：关键指标监控
日志管理：集中式日志管理

10. 总结

影子设备系统实现了完整的边缘计算数据管理方案，通过统一的数据面、控制面和扩展面，提供了高效、可靠、可扩展的数据管理能力。系统集成了 RTT、MTU、Gap 优化器，实现了采集数据的智能优化和关联，为边缘计算提供了强大的数据基础。