ThinkLink

中文

English

中文

English

Appearance

第三方 MQTT 转发 ​

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

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

典型数据流如下：

text
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 内部类型，以避免无意义的内部循环。常见的第三方转发组合是：

text
Source Broker = AS 或 ThinkLink
Target Broker = Customize

订阅 Topic 与协议 ​

按 Source Broker 类型填写 Subscription Topic：

Source Broker数据类型Subscription Topic协议说明
ThinkLink物模型解析后的遥测数据/v32/{tenant}/tkl/up/telemetry/#ThinkLink 协议
ASLoRaWAN 解密后的上行原始数据/v32/{tenant}/as/up/data/#AS 协议
AS多网关数据收集完成后的完整上行消息/v32/{tenant}/as/up/dataAll/#AS 协议

将 {tenant} 替换为实际组织账号（可在个人中心查看），不要原样保留占位符。# 表示该组织下所有设备；只转发一台设备时，将 # 替换为该设备的 DevEUI。例如，组织账号为 mtfac 时，遥测数据订阅 Topic 为 /v32/mtfac/tkl/up/telemetry/#，AS 上行原始数据为 /v32/mtfac/as/up/data/#。

3. 可选：转换脚本 ​

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

javascript
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
    }
  }
}

输入参数：

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

返回对象支持：

字段类型说明
topicstring发布到目标 Broker 的 Topic
msgObject发布的消息内容
optionObject可选 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 已连接判断转发成功。

设备状态主题（2.00.084） ​

在 ThinkLink 来源规则中可订阅 /v32/{tenant}/tkl/device/status/{eui}，或在授权组织范围内使用 /v32/{tenant}/tkl/device/status/+。转发器自身不要求设备侧第三方转发开关，但状态消息的产生要求设备 notify_offline="TRUE"，默认关闭。此消息没有 telemetry_data，上面的示例脚本会丢弃它；使用原消息直通或按状态格式处理。消息体、重连查询及口径差异见状态通知。

2.00.091 应用属性与独立日志 ​

微应用参数统一存入对应设备 app_attrs，三维配置使用 app_attrs.__transform_3d。停止使用顶层 transform_3d 和旧 modifyTransform3d 动作，脚本改用 modifyAttrs；物模型和 RPC 仍是顶层浅合并，嵌套修改需保留其他子字段。应用属性仅在显式配置转发字段后参与转发，不能假设 MQTT 自动推送所有变化。操作日志、运维日志通过独立接口管理，以可选 eui 关联设备，不写入项目内部存储或 app_attrs。

参见参数归属、局部更新与三维迁移和独立日志及历史附件迁移。平台迁移只负责旧三维与数据库结构；各项目参数、历史日志和用户脚本需分别迁移。源码适配、数据库迁移、部署、浏览器验收与 MQTT 联调分别记录。

自定义客户端 ID（2.00.099） ​

Broker 新增/编辑支持可选 options.client_id，适用于 Customize、AS、ThinkLink 三种类型。非空字符串原样用作 MQTT clientId；未配置、null、空字符串或纯空白时，按 ${tenant_code}.${name}_${timestamp} 自动生成，列表显示“自动生成”。自动值不写回自定义配置；清空自定义值后下次连接恢复自动生成，无需数据库迁移。

json
{
  "options": {
    "client_id": "tenantA-forwarder-main"
  }
}

这是 Broker 选项片段，不是完整保存请求；编辑时保留其他 options。修改后沿用现有流程断开旧连接并重建连接，可能短暂中断转发。自定义 ID 应避免同一 Broker 上非预期冲突，以免连接互相替换；固定 ID 本身不保证持久会话恢复或消息可靠性。验证重连、SUBACK、订阅恢复、多个脚本共用 topic、真实目标消息；目标离线不新增缓冲或离线补发保证，不能只看 RUNNING。MQTT 重投递仍可能重复，业务去重需消息标识。

Copyright © 2025 ThinkLink Email : info@manthink.cn