MyEMS 开源能源管理系统整体架构解析与多协议 Modbus / OPC UA 接入实施规范

一、为什么需要先理解“架构”，再谈接入规范

能源管理系统真正难的地方，往往不在“能不能读到数”，而在“读到的数能不能长期可信、能不能被持续汇总与追溯”。MyEMS 之所以在很多场景里显得好落地，是因为它把能源数据的生命周期拆成了清晰的管道：先解决多源接入与协议适配，再进入清洗、规范化、聚合与对外服务，最后才是可视化与报表。换句话说，接入规范的价值不是把寄存器读出来那么简单，而是要把“读—校验—归档—重算—展示”这条链路的边界、职责与容错规则定清楚，让后续扩展（更多表计、更多子系统、更高频率）不至于把系统拖垮。

二、MyEMS 的整体架构：从“感知”到“决策”的一条直线

从宏观上看，MyEMS 的架构可以用一条数据主线来概括：采集 → 清洗/规范化 → 聚合 → API 服务 → 前端呈现。围绕这条主线，系统又被拆成若干相对独立的组件与服务，使得每一段都可以单独运维、扩容或更换实现方式。

1) 数据接入与采集侧（系统的最前端）

在 MyEMS 的组件体系里，数据采集并不是随便起一个脚本去轮询设备，而是由专门的采集/适配服务承担。例如官方材料中明确列出过面向 Modbus TCP 的专用采集服务（myems-modbus-tcp），并且整体项目由数据库、API、管理 UI、Web UI 以及一系列后台数据处理服务共同组成。

这意味着：计量仪表、网关、PLC 或第三方系统并不“直接写库”，而是通过协议适配器把物理世界的寄存器、对象节点或报文，转成系统内部可以理解的数据点上报流。

对现场来说，这一层要解决三类事情：

• 连通性：IP/端口（以太网）或串口参数（RS485），包括超时、重试与会话管理；
• 语义映射：把“寄存器地址 / OPC UA NodeId”变成“哪个空间、哪块表、哪个能源类型、哪个物理量”；
• 节奏控制：采集周期、批量读取策略、并发上限，避免把现场总线或设备压垮。

2) 数据管道层：清洗 → 规范化 → 聚合（保证“可算”的关键）

原始采集值往往是“带噪声的电表寄存器片段”，不一定适合直接拿来做分项计量或费用分析。MyEMS 把后面这段做成流水线：

• 清洗（cleaning）：剔除明显不合理值、处理断连造成的脏数据、做基本的范围与跳变判断；
• 规范化（normalization）：把不同来源的数值统一到系统内部的物理量含义、单位体系与命名约定上，使上层不再关心“你到底是从 40001 还是从某个 OPC UA 变量读上来的”；
• 聚合（aggregation）：按时间粒度、空间/设备维度做汇总，给报表、看板与同比环比提供稳定底座。

官方组件清单里对 cleaning / normalization / aggregation 都有独立服务层面的体现，这种拆法的好处是：当接入规模变大时，你可以只对“采集”或只对“聚合”做横向扩容，而不会把责任搅在一起。

3) 服务与存储侧：API、关系型库与时序型历史的分工

MyEMS 后端以 Python 系技术栈为主，并通过 API 服务向外提供访问入口；前端（管理端与 Web 端）再通过接口拿到结构化结果去做表单、看板与报表。存储层面通常会把配置/元数据（空间、表计档案、用户权限、能源类型定义等）放进关系型库，而把高频采集结果与历史交给更适合时间维度写入与查询的机制来管理；同时系统也强调跨平台与多数据库/云平台的兼容能力。

在“接入规范”视角下，你要记住一件很务实的事：采集侧关注的是“点对点通信”，而 API + 存储侧关注的是“这些点如何成为可追溯的资产数据”。

三、多协议接入的总原则：先建模型，再配驱动

不管用 Modbus 还是 OPC UA，最稳妥的落地方式都是同一套方法论：

1. 先把“资产模型”定下来：空间层级（区域/产线/楼层等）、计量点归属（哪块表属于哪路回路）、能源介质类型（电/水/气/热……）、物理量语义（总有功电能、瞬时功率、流量、温差……）。
2. 再建“点位字典”：每个物理量表计下面挂哪些寄存器或节点；每个寄存器/节点必须回答三个问题：它是什么、怎么解释字节、跟哪个单位与系数挂钩。
3. 最后才进“连接参数”：IP/端口/从站号/串口/波特，或者 OPC UA 的端点与安全策略——这些属于“通道配置”，不应反过来决定你的数据模型。

只要模型在前，后面换协议、换网关、甚至把一组表计从 Modbus TCP 迁到 OPC UA 网关后面，都不会把系统逻辑打散。

四、Modbus（TCP / RTU）接入实施规范：把“寄存器读对”变成可复制的工程

Modbus 在现场最常见，也最容易踩坑的点在于：能读到数 ≠ 能把这个数用对。下面给出一套偏“规范体”的做法。

1) 通道与设备对象的界定

• 对 Modbus TCP：一个数据源通常对应一台以太网表计或一个网关下的一个从站，配置里要明确 host、port（常见 502）、轮询间隔（采集周期），并在改动后按系统提示重启对应采集服务以使配置生效。
• 对 Modbus RTU：仍要先定义串口资源（COM/tty、波特率、奇偶校验、停止位、超时），再在报文中靠 slave_id（unit identifier）区分不同从站设备；本质上 RTU 只是把“链路”从 TCP 换成串口帧格式，寄存器映射思想不变。

这里的规范要点是：一个通道只承载它能稳定承载的数量。不要为了省端口把几十台表硬塞进同一条慢速 RS485 链路却把轮询间隔压得极小，否则你会收获“偶尔丢点、偶尔整条链路卡死”的经典症状。

2) 寄存器映射与数据类型解释（最容易出事故的地方）

以 Modbus TCP 的点位配置为例，系统层面的关键点通常包括：slave_id、function_code（常用 0x03 读保持寄存器/0x04 读输入寄存器）、offset（起始寄存器偏移）、number_of_registers（连续寄存器数），以及 format/字节序处理（例如用类似 Python struct 的格式描述把多个 16-bit 寄存器拼成 32-bit float，并处理 byte-swap）。

据此，接入规范应当强制要求每个点位记录以下内容（文字条目式即可）：

• 物理量名称：例如“总有功电能累计值（import）”而不是“40001”；
• 寄存器引用：function_code + offset + 寄存器数量；
• 数据类型与字节序：float32/int32/uint32…以及高低字顺序是否需要交换；
• 单位与比例系数：读上来是 Wh 还是 kWh、是否 ×0.01、是否 ÷1000；
• 取值范围/死区阈值：用于清洗阶段的合理性判断（例如电能回退、明显溢出或负值瞬态）。

做到这一步，你的“40001”就不再是魔法数字，而是可被审查、可被回滚的配置资产。

3) 采集周期与并发控制

Modbus 的“周期”要跟着用途走：分项计费与能耗结算往往分钟级足够；而功率、电流、电压这类需要观察突变的场景，才可能考虑更密。规范上建议把采集周期写成一个显式字段，并为每条链路设定最大并发与超时重试上限，避免出现“越采越慢”的恶性循环。

4) 异常处理与连续性保障（断点缓存/续传思维）

现场网络不可能永远稳。MyEMS 的资料与实施文档多次强调：当网关与后端之间中断时，采集侧应具备本地缓存能力，等恢复后再继续上传，从而保护数据连续性。

因此接入规范里要把下面几条写死：

• 采集服务/网关对“写失败”不能 silently drop，至少要有持久化队列或环形缓存；
• 恢复后要按时间递增顺序回填（避免把历史统计冲乱）；
• 对设备掉线要有明确的状态标记（online/offline/last_seen），别让“离线值”混进能耗合计里。

五、OPC UA 接入实施规范：把“对象模型”用起来，而不是只当另一个寄存器表

OPC UA 相比 Modbus 最大的区别是：它天生带信息模型（Namespace、NodeId、变量/属性、层级结构），更适合用来对接 SCADA、BAS、历史库或成套设备控制器。MyEMS 的文档体系中也把 OPC UA 作为可配置的数据采集选项，并给出类似 {"url":"opc."}形态的端点配置入口。

1) 连接与身份：把安全策略当“必选项”

OPC UA 的数据源配置首先要确定：

• 端点 URL（opc.tcp://host:port之类）；
• 安全策略与模式（None/Sign/SignAndEncrypt，取决于现场合规与设备能力）；
• 身份认证方式（匿名/用户名密码/证书）；
• 连接池与会话超时、重连退避策略。

规范建议：即便初期测试用 None，也要把“未来切到证书”的配置路径留出来（信任列表、应用证书、吊销检查），否则后期改造成本会翻倍。

2) 节点集订阅策略：不要滥用轮询，尽量用订阅（MonitoredItems + Subscriptions）

在 OPC UA 世界里，“读值”有两种气质：

• 被动轮询（定期 Read）：简单，但在大规模点位时会把负载与延迟一起抬高；
• 订阅通知：更接近工业实时系统的正确姿势——你告诉服务端“我关心这些 NodeId 的变化或周期发布”，由服务端推送。

实施规范应明确：

• 对每个节点要记录 NamespaceIndex + Identifier（字符串或数字均可，但要统一）；
• 区分“采样间隔”与“发布间隔”：采样是服务端多久取一次源值，发布是你多久收到一帧通知；
• 对缓慢变化的累计量（如电能），可以用较长发布间隔；对功率类，再用更密的节奏。

3) 语义绑定：NodeId 必须映射到资产模型

这一步和 Modbus 的“寄存器→物理量”本质一样，只是对象更丰富：

你需要把 OPC UA 变量节点映射到“空间—设备—能源类型—物理量—单位—系数”，并把节点的数据类型（Double/Int/Float…）与工程单位来源（如果对方有 EU 信息）记录下来，防止“数值对但单位错”。

4) 诊断与质量码（StatusCode）

OPC UA 通常会带状态码/质量位。接入规范必须要求：下游清洗层能识别“坏质量/不确定”的样本，并将其与正常样本隔离（可标记、可补算，但不参与当期能耗结算）。否则“看起来有值”会变成最危险的假象。

六、把两条协议纳入同一套“配置治理”

真正成熟的接入，不是各自写两份说明书，而是共用一套治理：

• 版本化点位表：任何寄存器偏移、节点路径、系数修改都要走变更记录；
• 环境隔离：测试网关/测试数据源先跑通，再同步到生产，避免“改一个点把整条线打挂”；
• 健康度面板：看采集成功率、平均轮询耗时、离线设备数、缓存积压长度——这些指标比单纯看曲线更能提前止血。

当 MyEMS 的采集适配（如 myems-modbus-tcp 等）、清洗、规范化、聚合与 API 这条管道被协议规范“喂入干净、可追溯的输入”时，上面的分项计量、对比分析、报表与可视化才会稳定可用，而不是不断在“数据对不上”的泥潭里拉扯。

综上，MyEMS 的架构优势不在于某一个协议有多花哨，而在于它把能源数据当成一条受控生产线：接入规范负责把原料（点位值与语义）标准化，组件分工负责把中间工序解耦，最终让能源管理回到它该有的状态——可观测、可核算、可持续迭代。