sjmushet/xml-exporter-be Docker 镜像 - 轩辕镜像

电表数据自定义XML导出器 Docker镜像文档

镜像概述和主要用途

本Docker镜像是一个轻量级工具，专为电表数据处理设计，可将电表采集的能源数据（如用电量、电压、电流、功率等）转换为标准化XML格式并导出。镜像基于精简基础镜像构建，资源占用低，部署便捷，适用于能源监控系统、能源管理平台及数据分析系统的数据集成环节，帮助实现电表数据与上层系统的无缝对接。

核心功能和特性

核心功能

• 数据格式转换：将电表原始数据（支持JSON、CSV等格式输入）转换为符合用户定义规范的XML格式。
• 自定义数据映射：支持通过配置文件定义电表数据字段（如energy_consumption、voltage）与XML元素/属性的映射关系。
• 定时导出：可配置定时任务，按设定时间间隔（如每5分钟）自动导出XML文件。
• 多电表支持：支持同时处理多个电表设备的数据，每个电表可独立配置导出规则。

特性

• 轻量级：基于Alpine或Distroless基础镜像，镜像体积小（<50MB），运行时内存占用低（<30MB）。
• 灵活配置：通过外部配置文件（YAML/XML）自定义映射规则，无需修改镜像代码。
• 错误处理：内置数据校验机制，对异常数据（如缺失字段、格式错误）进行日志记录并跳过，保证导出过程稳定。
• 日志输出：支持多级别日志（DEBUG/INFO/WARN/ERROR），便于问题排查。

使用场景和适用范围

适用场景

• 工业能源监控：工厂、车间的能源管理系统中，将分布式电表数据统一转换为XML格式，供能源监控平台汇总分析。
• 商业建筑能源管理：办公楼、商场等场所的电表数据（如租户用电量）导出为XML后，对接物业管理系统或计费系统。
• 智能电网数据采集：电力公司对用户侧电表数据进行集中处理，通过XML格式接入电网调度或数据分析平台。
• 能源数据分析前置处理：为能源消耗趋势分析、节能优化模型提供标准化XML数据源。

适用范围

• 支持主流电表协议（如Modbus、DL/T 645等）输出的数据（需配合数据采集模块将协议数据转换为JSON/CSV输入）。
• 适用于Linux x86_64/ARM架构的Docker环境（如边缘计算网关、工业服务器、云服务器）。

使用方法和配置说明

前提条件

• 已安装Docker Engine（20.10+）或Docker Compose（2.0+）。
• 电表数据输入源（如通过MQTT、HTTP接口或本地文件提供JSON/CSV格式数据）。
• 用于存放配置文件和导出文件的宿主机目录（需保证容器有读写权限）。

部署示例

1. Docker Run 命令部署

bash
docker run -d \
  --name energy-meter-xml-exporter \
  --restart unless-stopped \
  -v /path/to/host/config:/app/config \  # 挂载配置文件目录（含映射规则和电表列表）
  -v /path/to/host/exports:/app/exports \  # 挂载XML导出文件目录（宿主机路径）
  -e EXPORT_INTERVAL=300 \  # 导出间隔（秒），默认300（5分钟）
  -e LOG_LEVEL=info \        # 日志级别：debug/info/warn/error，默认info
  -e DATA_INPUT_TYPE=file \  # 数据输入类型：file（本地文件）/mqtt（MQTT订阅），默认file
  energy-meter-xml-exporter:latest

2. Docker Compose 部署

创建docker-compose.yml文件：

yaml
version: '3.8'
services:
  xml-exporter:
    image: energy-meter-xml-exporter:latest
    container_name: energy-meter-xml-exporter
    volumes:
      - ./config:/app/config  # 宿主机配置目录（存放映射规则和电表列表）
      - ./exports:/app/exports  # 宿主机导出目录（存放生成的XML文件）
    environment:
      - EXPORT_INTERVAL=300  # 导出间隔（秒）
      - LOG_LEVEL=info
      - DATA_INPUT_TYPE=mqtt  # 示例：使用MQTT订阅电表数据
      - MQTT_BROKER=mqtt://192.168.1.100:1883  # MQTT broker地址（当DATA_INPUT_TYPE=mqtt时必填）
      - MQTT_TOPIC=energy/meters/#  # MQTT订阅主题（当DATA_INPUT_TYPE=mqtt时必填）
    restart: unless-stopped

启动容器：docker-compose up -d

配置说明

环境变量参数

配置文件说明

容器依赖CONFIG_DIR目录下的以下配置文件（需用户提前创建）：

1. 电表列表配置（meters.yml）

定义需处理的电表设备信息，示例：

yaml
meters:
  - id: "meter_001"  # 电表唯一标识（需与输入数据中的电表ID对应）
    name: "Factory_Main_Meter"  # 电表名称（将作为XML中的`<meter_name>`元素）
    type: "three_phase"  # 电表类型（自定义，用于XML分类）
    mapping_config: "mapping_meter001.xml"  # 该电表的数据映射规则文件（位于CONFIG_DIR下）
  - id: "meter_002"
    name: "Workshop_A_Meter"
    type: "single_phase"
    mapping_config: "mapping_meter002.xml"  # 不同电表可使用不同映射规则

2. 数据映射规则配置（如mapping_meter001.xml）

定义电表数据字段与XML元素的映射关系，示例：

xml
<mapping>
  <!-- XML根元素配置 -->
  <root_element name="EnergyData" namespace="[***]">
    <attribute name="timestamp" value="${system.timestamp}" />  <!-- 系统时间，内置变量 -->
    <attribute name="meter_id" value="${meter.id}" />  <!-- 引用meters.yml中的电表ID -->
  </root_element>
  
  <!-- 数据字段映射：将输入数据中的字段映射到XML子元素 -->
  <fields>
    <field input="energy_consumption" output_element="TotalEnergy">  <!-- 用电量 -->
      <attribute name="unit" value="kWh" />  <!-- 元素属性 -->
      <format type="number" precision="2" />  <!-- 格式化：保留2位小数 -->
    </field>
    <field input="voltage" output_element="Voltage">  <!-- 电压 -->
      <attribute name="unit" value="V" />
    </field>
    <field input="current" output_element="Current">  <!-- 电流 -->
      <attribute name="unit" value="A" />
    </field>
  </fields>
</mapping>

• ${system.timestamp}：内置变量，自动填充当前导出时间（格式：ISO 8601，如2024-05-20T10:30:00Z）。
• ${meter.id}：引用meters.yml中电表的id字段。
• input：电表输入数据中的字段名（如JSON输入中的energy_consumption字段）。
• output_element：生成的XML子元素名称。

输出示例

导出的XML文件（如energy_data_meter_001_202405201030.xml）内容示例：

xml
<EnergyData xmlns="[***]" timestamp="2024-05-20T10:30:00Z" meter_id="meter_001">
  <TotalEnergy unit="kWh">1250.68</TotalEnergy>
  <Voltage unit="V">220.5</Voltage>
  <Current unit="A">15.2</Current>
</EnergyData>

注意事项

• 配置文件需保证格式正确（YAML/XML语法无误），否则容器启动时会报错并退出。
• 宿主机挂载目录需赋予容器读写权限（可通过chmod 777 /path/to/dir临时测试，生产环境建议通过UID/GID映射限制权限）。
• 若使用MQTT输入，需确保容器可访问MQTT broker，网络策略需开放对应端口（默认1883）。
• 导出文件命名格式为energy_data_${meter.id}_${timestamp}.xml（timestamp为导出时间，格式：YYYYMMDDHHMM）。