版本: v1.1 修改日期: 2026-05-29 编制日期: 2026-03-12 适用范围: 已通过 Modbus（或其他协议）采集全量点位的设备，需按 MQTT 主题拆分为多设备类的场景

本手册规范「全量点位设备」经 Modbus 等协议采集全量数据后，按 MQTT 主题拆分为多个设备类采集的配置流程。完成后可正确配置 MQTT Consumer 输入、创建新设备类属性，并确保拆分前后的 「属性标识」 与 「标准化名称」 一致，便于数据追溯与系统对接。

1 整体流程

图 1 MQTT 主题拆分配置四步流程

2 前提条件

• 设备已按 「标准化名称」 完成统一命名
• 「全量点位设备」的配置中，「标准化名称」 与 「属性标识」 已建立并保持一一对应关系

图 2 全量点位设备属性配置示意

ℹ️ 术语说明:

• 「全量点位设备」：原设备，通过 Modbus 或其他协议采集全量数据
• 「标准化名称」：按统一规则命名的设备/点位名称，对应数仓字段
• 「属性标识」：采集数据匹配用字段，与 「标准化名称」 一一对应
• MQTT Consumer：Telegraf 中订阅 MQTT 主题并解析为指标的输入插件

3 操作步骤

3.1 确认拆分目标与主题

1. 确认「全量点位设备」（如 dmRbqn03dV）当前通过 Modbus 采集全量数据。

2. 确定拆分出的新设备类数量及各自对应的 MQTT 主题（例如 conn/device/25003/dmRbqn03dV/#，或更细粒度主题）。

3. 按下表记录以下信息，供后续配置使用：

   信息项	示例	说明
   「主题列表」	conn/device/25003/dmRbqn03dV/#	MQTT 订阅主题
   「租户变量」	${TENANT_ID}	租户标识
   「模板变量」	${TEMPLATE_NAME}	模板名称
   「设备类型」	${DEVICE_TYPE}	设备类型标识

3.2 新增 MQTT Consumer 输入配置

在对应采集配置中新增一段 [[inputs.mqtt_consumer]]，按实际环境填写变量与主题。

配置模板:

[[inputs.mqtt_consumer]]
    name_override = "${TEMPLATE_NAME}${DEVICE_TYPE}"
    alias = "${TEMPLATE_NAME}@input.mqtt_data"
    servers = ["${EMQX_BROKER_SERVER}"]
    topics = [
        "conn/device/25003/dmRbqn03dV/#"
    ]
    client_id = "{\"userId\":${EMQX_BROKER_USER_ID},\"telegraf\":\"${TENANT_ID}@${TEMPLATE_NAME}${DEVICE_TYPE}@input\"}"
    username = "${EMQX_BROKER_USERNAME}"
    password = "${EMQX_BROKER_PASSWORD}"
    persistent_session = false
    data_format = "json"
    json_query = "fields"
    json_string_fields = ["*"]

💡 topics 字段是拆分核心配置，按本次拆分的目标主题填写；其余变量通过环境变量注入，通常无需修改。

3.3 配置新设备类属性

1. 在平台中为本次拆分出的新设备类创建或选择对应设备类。
2. 按属性配置规则设置 「属性标识」 并保存。

⚠️ 属性配置核心规则: 新设备类的 「属性标识」 = 「全量点位设备」的 「标准化名称」，必须完全一致，不得改名、翻译或缩写。

图 3 新设备类属性配置示意

3.4 校验与发布

按以下顺序执行校验、下发与验证：

⚠️ 若数据验证未见新设备类数据上报，优先排查 MQTT 主题匹配、「属性标识」 大小写与 「标准化名称」 是否完全一致。

4 常见问题