任意Topic主题

这页复用 MQTT 任意主题 / 第三方 Broker 接入说明，方便在当前目录下直接查看。

1. 适合哪些设备

这条路（自建接入 / 外置 MQTT 网络组件）适合下面这类 MQTT 设备：

1. 设备 Topic 改不了。
2. 设备已经接在第三方 Broker 上。
3. 存量设备很多，不方便改成平台标准 Topic。

要先说明一件很容易误解的事：

"任意主题设备"不等于"只能透传"。

在自建接入模式里，你仍然可以把主题类型配置成：

1. THING_MODEL：消息体已经是标准物模型 JSON。
2. PASSTHROUGH：消息体还是厂商自定义格式，需要编解码。

MQTT 自建接入 · 快速接入主线

接外置 Broker / 任意 Topic，按这 6 步走

01先把产品身份定下来

创建 MQTT 产品

接入方式选 MQTT，联调期建议打开 allowInsert。

02平台去连第三方 Broker

创建 MQTT 网络组件

填 host、port、username、password、clientIdPrefix。

03决定消息归属产品与处理方式

配置主题映射

每条映射填 topicPattern + topicCategory + productKey + qos。

04绑定成功模式会变自建

绑定产品 + 添加设备

产品详情 → 连接信息 → 管理自建接入，切到自建接入模式，再添加设备。

05一键复制，不用再回产品

设备详情拿连接信息

进入设备详情 → 设备连接信息，直接复制自建 host、账号、ClientID。

06最终用主题测试工具验证

写 preDecode + 跑通上下行

脚本里写 preDecode 提取 deviceId，透传再补 decode/encode。

2. 先分清 4 个对象

任意主题模式里，最容易混的是"到底该在哪一层配"。

对象	你在哪里配	它负责什么
产品	产品管理	定义 productKey、物模型、编解码、自动注册、产品级下行主题
连接信息	产品详情 → 连接信息	绑定自建 MQTT 网络组件，查看当前接入模式
MQTT 网络组件	网络组件 → MQTT	连接第三方 Broker，订阅任意 Topic，做主题映射
协议脚本	产品驱动 / IDE 调试器	处理 preDecode、decode、encode

3. 平台处理链路

任意主题模式下，平台大致按这个顺序处理：

1. MQTT 网络组件先连上第三方 Broker。
2. 网络组件按 topicPattern 订阅消息。
3. 平台先根据主题映射确定这条消息属于哪个产品。
4. 第三方 MQTT 场景下，平台会继续执行产品脚本里的 preDecode，拿 deviceId。
5. 如果主题分类是 THING_MODEL，平台按标准 JSON 继续处理；如果是 PASSTHROUGH，继续走 decode / encode。
6. 下行时再根据产品绑定的网络组件，把消息发回对应 Broker。

这里有两个关键细节：

1. productKey 识别优先看主题映射里是否显式配置，第一次联调建议直接填上。
2. 就算 topicCategory = THING_MODEL，通常也要考虑 deviceId 怎么识别，因为这时已经没有标准 Topic 可用。

4. 接入步骤

第一步：创建 MQTT 产品

在产品管理里新建产品时，接入方式还是选 MQTT。

第一次联调时，产品层最值得先看一眼的 3 个配置是：

1. allowInsert：联调期设备可能还没预创建，建议先打开。
2. decoderType / encoderType：上报和下发不是普通字符串时，需要确认编码方式。
3. downTopic：如果设备订阅的是固定主题，建议先在产品里把下行 Topic 固定住。

第二步：创建 MQTT 网络组件

网络组件负责的是"平台怎么去连 Broker"，不是"设备怎么连平台"。

第一次联调时，先把这些基础连接参数填好：

字段	作用
host	第三方 Broker 地址
port	Broker 端口
username	Broker 账号
password	Broker 密码
clientIdPrefix	平台作为客户端连上去的 ClientID 前缀
connectTimeout	连接超时时间（毫秒）

第三步：配置主题映射

进入网络组件详情 → 主题订阅，逐条添加要订阅的 Topic。

每一条主题映射，最关键的字段是这几个：

字段	作用	第一次联调建议
topicPattern	实际订阅的主题模式，支持 + 和 #	先用最小范围，不要一上来订 #
topicCategory	按物模型还是透传处理	必填
qos	MQTT QoS	一般先用 1
productKey	把这条 Topic 明确归属到哪个产品	建议显式填上
enabled	是否启用	联调时保持启用

topicCategory 选择规则：

选项	什么时候选
THING_MODEL	payload 已经是标准物模型 JSON
PASSTHROUGH	payload 还是私有协议，需要编解码

用主题模式测试工具

网络组件详情页有一个"主题模式测试工具"，输入设备实际 Topic，立刻告诉你能否匹配、匹配到了哪个产品。联调时强烈推荐先在这里自测一次。

第四步：绑定网络组件到产品

路径就在 产品详情 → 连接信息：

1. 打开"连接信息"页。
2. 点击 管理自建接入。
3. 选择一个已经配置完整、而且处于运行状态的 MQTT 组件。
4. 绑定成功后，回到连接信息页确认当前模式切到了 自建接入。

第五步：添加设备并拿连接信息（推荐）

新版本推荐直接从 设备详情 拿连接信息，不用再回产品详情翻。

路径：设备管理 → 新增设备 → 设备详情 → 设备连接信息。

自建接入模式下，页面会直接给出：

1. 连接地址：自建 MQTT 网络组件的 host / port
2. Username / Password：来自网络组件配置
3. ClientID：按下面规则拼好并支持一键复制
4. 该设备要发送和订阅的 Topic 列表

自建接入 ClientID 规则

ClientID = ProductKey.DeviceId

host、用户名、密码都来自产品绑定的 MQTT 网络组件。

第六步：写 preDecode 识别设备

任意主题模式下，真正最容易卡住的是 deviceId。

平台会执行产品脚本里的 preDecode 去识别设备号。识别来源可以是：

1. Topic
2. payload
3. Topic 和 payload 结合

下面这个例子演示"从 Topic 最后一段取设备号"：

var preDecode = (payload, context) => {
  var result = {};
  var topic = "";

  if (context && context.upTopic) {
    topic = context.upTopic;
  } else if (context && context.topic) {
    topic = context.topic;
  }

  var parts = topic.split("/");
  if (parts.length > 0) {
    result.deviceId = parts[parts.length - 1];
  }

  return result;
};

如果消息是透传模式，还要继续补：

1. decode：把设备上报转成属性或事件。
2. encode：把平台下发转成设备能识别的报文。

第七步：下行与自动回复

如果设备订阅的下行 Topic 不是平台默认主题，第一次联调建议先在产品里把 downTopic 固定住。

常用占位符至少支持：

1. #{productKey} / / ${productKey} / {productKey}
2. #{deviceId} / / ${deviceId} / {deviceId}

如果你在 decode 结果里返回了 replyPayload，平台会自动尝试回复。

自动回复踩坑提醒

• 返回 1 条带 replyPayload 的结果，平台就回 1 次。
• 返回 10 条都带 replyPayload，平台就会回 10 次。

联调期通常只建议保留一条回复。

5. 最稳的联调顺序

建议按这个顺序来：

1. 先创建产品。
2. 再创建并启动 MQTT 网络组件。
3. 在主题映射里明确填上 productKey。
4. 把 topicCategory 选对。
5. 写通 preDecode，确认能稳定拿到 deviceId。
6. 如果是透传，再补 decode 和 encode。
7. 最后调下行和自动回复。

6. 最容易踩的坑

1. topicPattern 能匹配，但 productKey 没配，自动提取又没成功。
2. topicCategory 选错，导致 JSON 被当透传，或者透传被当 JSON。
3. preDecode 没返回稳定的 deviceId。
4. Broker ACL 不够，平台没法订阅上行 Topic 或发布下行 Topic。
5. 网络组件虽然配置了，但没启动，或者产品还没绑定这个组件。
6. 忘了绑定产品，连接信息页面仍然停留在"平台直连"模式。

继续排查可以直接看 MQTT 常见问题。