EdgeX 文档

6. 影子设备设计

6.1 核心设计理念

  • 统一内部数据面：Shadow Device 作为唯一可读写模型，所有数据操作通过 Shadow Core 进行。
  • 统一控制面：所有写操作进入原子接口与审计链，确保数据一致性。
  • 统一扩展面：南向/北向均可热插拔，系统重启零丢数。

6.2 分层架构

┌───────────────────────────────────────────────────────────────────────────┐
│ 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 Ingress
                                │
┌───────────────────────────────┴───────────────────────────────────────────┐
│ Points Layer                                                               │
│  - Normalize  - Unit Convert  - Timestamp Align  - Batch Publish QoS0/1/2 │
└───────────────────────────────┬───────────────────────────────────────────┘
                                │
                     Southbound Drivers (Modbus/CAN/IEC/...)

6.3 关键流程

6.3.1 采集入影子时序

  1. 驱动采集原始值写入 Points。
  2. Points 完成归一化并以统一报文批量发布至 ShadowIngress。
  3. Shadow Core 原子落地内存并追加 WAL。
  4. 触发边缘计算与虚拟公式增量更新。
  5. 北向适配器通过统一 API 拉取或订阅结果。

6.3.2 北向写入控制时序

  1. 北向适配器请求授权与限流。
  2. 调用 Shadow Core 写入接口。
  3. Shadow Core 追加 WAL 并通知订阅者。
  4. 记录审计日志并返回版本确认。

6.3.3 重启恢复时序

  1. 进程启动后加载 WAL 最新段。
  2. Shadow Core 回放至内存。
  3. 重建虚拟引擎依赖缓存。
  4. 恢复北向适配器游标并继续服务。
  5. 目标：500ms 内完成恢复。

6.4 核心数据结构

6.4.1 点位标准报文（Points -> ShadowIngress）

messageId: "uuid"
qos: 0|1|2
deviceId: "physical-device-id"
timestamp: "2026-03-04T12:00:00.000Z"
points:
  - pointId: "pack_voltage"
    value: 742.3
    unit: "V"
    quality: "good"
    samplePeriodMs: 1000
meta:
  source: "modbus-driver"
  sequence: 123456

6.4.2 真实影子设备结构

shadowDeviceId: "shadow-rack-01"
physicalDeviceId: "rack-01"
version: 202603040001
updatedAt: "2026-03-04T12:00:00.001Z"
points:
  pack_voltage:
    value: 742.3
    unit: "V"
    rw: "r"
    samplePeriodMs: 1000

6.4.3 虚拟影子设备结构

virtualDeviceId: "virtual-energy-mix-01"
version: 202603040010
formulaPoints:
  A: "device1.temp + device2.humidity"
dependencies:
  - "device1.temp"
  - "device2.humidity"

6.4.4 WAL 记录结构

offset: 987654321
eventType: "shadow-write"
shadowDeviceId: "shadow-rack-01"
version: 202603040001
payloadHash: "sha256:..."
createdAt: "2026-03-04T12:00:00.001Z"

6.5 一致性校验

  • 接口输入：时间点 t 或版本号区间。
  • 校验对象：真实影子、虚拟影子、北向缓存。
  • 判定条件：三端 value + version + timestamp + quality 全量一致。
  • 输出结果：pass/fail、差异点位、差异来源、修复建议。

6.6 性能与容量目标

  • 影子单机读写延迟：P99 ≤ 5ms。
  • 虚拟公式计算：P99 ≤ 15ms。
  • 虚拟点位传播延迟：≤ 100ms（单核 2GHz 基准）。
  • 稳态吞吐：5 万点/秒持续 24h 零丢数。