第三方 MQTT 转发

当前版本通过 Broker + 转发器（Forwarder） 将 ThinkLink 消息转发到第三方 MQTT Broker。

无需在设备侧开启任何“第三方转发”开关，也无需在“服务器配置”中配置任何第三方平台。旧版本中的这两处配置已经停用。只需配置 Broker，并开启对应的转发器规则；匹配订阅 Topic 的消息会自动转发。

典型数据流如下：

ThinkLink 内部 Broker（AS 或 ThinkLink）
        ↓ Source Broker / Subscription Topic
转发器规则（可选 JavaScript 转换）
        ↓ Target Broker
第三方 MQTT Broker（Customize）

1. 创建 Broker 连接

进入 高级功能 → Broker。一个转发规则通常需要一个来源连接和一个目标连接。

来源 Broker

按需要选择以下内部类型之一：

• AS：ThinkLink Application Server 的 MQTT 消息。
• ThinkLink：经过 ThinkLink 平台处理的消息。

内部 Broker 的地址和租户凭据由平台自动填写，无需前往服务器配置页面获取或维护。

第三方目标 Broker

新增一个 Customize 类型的 Broker，并填写第三方服务商提供的信息：

• 名称和启用状态。
• MQTT URL，例如 mqtt://host:1883 或 mqtts://host:8883。
• 用户名和密码（第三方要求时）。
• CA 证书、客户端证书等 TLS 信息（第三方要求时）。

保存并启用后，先检查 Broker 列表中的运行状态。连接正常时应为 RUNNING；若出现 ERROR，查看 ErrMsg 并检查 URL、端口、凭据、证书和网络连通性。

2. 创建并开启转发器

进入 高级功能 → 转发器 → 新增，填写：

字段	说明
名称	转发规则名称
启用	开启后规则才会订阅和转发消息
Source Broker	要订阅的来源 Broker
Target Broker	要发布到的目标 Broker
Subscription Topic	来源 Broker 上的订阅 Topic，支持 MQTT 的 + 和 # 通配符
Custom Script	可选；转换 Topic、消息内容或 retain 选项
备注 / 提交说明	可选；用于说明规则和版本变更

保存并开启转发器后，所有匹配 Subscription Topic 的消息都会自动发送到 Target Broker，设备侧不需要做任何额外设置。

Source Broker 和 Target Broker 不允许同时选择 AS/ThinkLink 内部类型，以避免无意义的内部循环。常见的第三方转发组合是：

Source Broker = AS 或 ThinkLink
Target Broker = Customize

3. 可选：转换脚本

不配置脚本时，转发器保留原 Topic 和原消息内容。需要适配第三方数据格式时，可使用以下入口函数：

function forwardScript({ topic, msg, org_params }) {
  if (!msg?.telemetry_data) return null

  return {
    topic: `${org_params.target_topic_prefix}/${msg.device_id}`,
    option: {
      retain: false
    },
    msg: {
      temperature: msg.telemetry_data.T,
      humidity: msg.telemetry_data.H
    }
  }
}

输入参数：

参数	类型	说明
topic	string	收到消息时的原始 MQTT Topic
msg	Object	解析后的消息内容
org_params	Object	只读组织参数，可在 系统管理 → 服务器配置 → 组织参数 中维护共享常量；这里不是第三方转发开关或 Broker 配置

返回对象支持：

字段	类型	说明
topic	string	发布到目标 Broker 的 Topic
msg	Object	发布的消息内容
option	Object	可选 MQTT 发布选项，例如 { retain: true }

返回 null 或不返回内容可丢弃该消息。

4. 版本历史和公共转发器

每次保存转发器脚本都会产生版本快照，可在编辑器中查看详情或还原。还原会生成一个新的版本记录，不会删除原有历史。

系统平台可以维护公共转发器。公共规则在租户侧可见但只读；选择具体组织时，规则可以引用该组织的 Broker 和 org_params。只有选择 Source Broker 后，Subscription Topic 才为必填项。

5. 排障顺序

1. 确认来源和目标 Broker 均已启用，目标 Broker 状态为 RUNNING。
2. 检查 ErrMsg、主机、端口、账号密码和 TLS 证书。
3. 确认转发器本身已启用。
4. 确认 Subscription Topic 与实际消息 Topic 匹配。
5. 暂时关闭自定义脚本，确认原消息能否直通；随后再排查脚本返回值。

6. 启动与订阅恢复（2.00.070）

同一组织的转发 Broker 并行加载，某个连接较慢不会让其他 Broker 依次等待。规则启用时，来源 Broker 离线也会先登记订阅需求；连接恢复后自动发起订阅。登记成功不代表已经订阅成功，只有成功收到 SUBACK 才确认订阅。连接期间失败的订阅每 3 秒自动重试，断线后等连接恢复再继续。

启动时，规则会在原连接超时上限内等待自己启用的目标 Broker 就绪，再登记源订阅；无关规则独立继续。目标超时后仍登记源订阅，目标不可用时沿用跳过转发策略，不新增消息缓冲或离线补发保证。

• 持久会话（clean: false 且 sessionPresent: true）恢复时，只补订未确认或新登记的主题；会话丢失或使用 clean 会话时，重建仍需要的订阅。
• 多个脚本共用一个主题时，移除其中一个脚本不影响其他脚本；最后一个回调移除后才退订。
• 重连不重复注册消息监听器；同一条收到的消息即使命中多个过滤器，同一脚本回调也只执行一次。旧连接迟到的订阅／退订确认不会覆盖新连接状态。
• 等待连接或订阅期间删除、替换规则，不会被旧异步任务重新恢复。

这些改进减少漏订阅和本地重复处理，不提供业务消息的 exactly-once 保证。MQTT 重投递或发送端重复发送仍可能产生重复消息；需要业务去重时应使用消息标识。

排障时同时检查来源与目标连接、订阅确认和真实消息流，不能只依据规则已启用或 Broker 已连接判断转发成功。