ThingsBoard MQTT
插件用途
连接 ThingsBoard MQTT 端点，发布网关遥测和设备属性；开启变量权限后，还可处理 ThingsBoard Gateway RPC 写入。
转发组范围、触发、分批、缓存和启停见数据转发。本页只说明 ThingsBoard 连接、固定 Topic、变量 RPC 权限和专用调试。
功能入口
进入“开发配置 → 数据转发”，按以下顺序配置：
- 保存转发组范围、触发、定时间隔、在线过滤和批处理策略。
- 新增目标，选择“ThingsBoard MQTT”，填写目标基本信息。
- 打开“目标属性”，按 ThingsBoard 的 MQTT 端点、Token 认证和 TLS 配置连接。
- 保存并启用目标，在 ThingsBoard 中确认网关设备在线，再打开目标“调试”。
目标基本信息
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 所属转发组 | - | 必须选择已保存的转发组。 |
| 目标名称 | - | 必填，同组唯一。建议包含租户、网关和环境名称。 |
| 启用 | 开启 | 关闭时不会连接 ThingsBoard。 |
| 日志级别 | Info | 排查连接或发布问题时临时使用 Debug。 |
| 启动超时 | 60 秒 | 页面可填 1～3600 秒。 |
目标属性
连接配置
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 连接类型 | Tcp | Tcp 连接 MQTT TCP 端点；WebSocket 连接 WebSocket 端点。 |
| IP地址 | localhost | ThingsBoard 主机名或 IP，不要带协议前缀。 |
| 端口 | 1883 | 明文 MQTT 常用 1883，TLS 常用 8883；WebSocket 端口按平台配置。 |
| WebSocket路径 | /mqtt | 仅 WebSocket 生效，必须以 / 开头。 |
| 客户端ID | 空 | 留空时自动生成；固定 ID 需在平台侧保持唯一。 |
| MQTT协议版本 | V500（MQTT 5） | ThingsBoard 端点必须支持该版本；不支持时选择平台要求的版本。 |
| 清除会话 | 开启 | 开启时断线清除会话；需要持久会话时关闭。 |
| 保活时间 | 60 秒 | MQTT Keep Alive 秒数，按平台限制设置。 |
TLS 与认证
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 启用SSL | 关闭 | 启用 TLS 后使用平台 TLS 端口，并确认服务器证书可验证。 |
| SSL目标主机名 | 空 | 填证书 SAN 中的 DNS 名称；留空时使用 IP地址。 |
| 客户端证书名称 | 空 | 双向 TLS 时从证书管理选择带私钥的客户端证书。 |
| CA名称 | 空 | 使用自定义 CA 时选择 CA 证书。 |
| 允许不受信任证书 | 开启 | 当前默认值为开启，仅用于开发环境自签名证书；生产环境必须关闭。 |
| SSL协议版本 | None（系统默认） | 只有平台明确要求时选择 TLS 版本。 |
| 检查证书吊销 | 关闭 | 按安全策略开启。 |
| 用户名 | 空 | ThingsBoard 通常将设备 Access Token 放在用户名字段。 |
| 密码 | 空 | 按平台认证方式填写；使用 Token 时通常留空。 |
消息设置
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| QoS等级 | AtMostOnce（0） | 按 ThingsBoard 部署要求选择 QoS 0、1 或 2。 |
| 保留消息 | 关闭 | 通常保持关闭；只有平台明确要求保留状态时开启。 |
| 详细日志 | 关闭 | 短时间排查 MQTT 连接和消息时开启，完成后关闭。 |
ThingsBoard MQTT 目标不使用通用设备/变量/报警 Topic 模板，当前版本固定使用以下 Topic：
| 用途 | 固定 Topic |
|---|---|
| 设备属性 | v1/gateway/attributes |
| 遥测 | v1/gateway/telemetry |
| RPC 请求 | v1/gateway/rpc |
设备属性和遥测的键名来自网关设备、变量名称和当前转发组范围；不能通过本目标修改成自定义 Topic。
目标变量属性
| 参数 | 默认值 | 说明 |
|---|---|---|
| 允许RPC写入 | 开启 | 允许 ThingsBoard Gateway RPC 写入该变量。只为允许控制的点开启。 |
变量必须已在转发组范围内；新增目标变量属性不会把变量加入转发组。
缓存与容量
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 启用失败重试缓存 | 开启 | 建议保持开启，平台或网络不可用时保留遥测和设备连接消息，恢复后自动补发。 |
| 缓存文件最大行数 | 262144 | CacheDB 出站记录上限，超过后删除最旧数据。 |
| 上传分片大小 | 2000 | 每次补发的最大记录数。平台限流时减小。 |
| 内存队列上限 | 100000 | 内存缓冲上限，设备连接队列和普通消息都会受容量影响。 |
| 过滤离线数据 | 关闭 | 开启后目标出队时过滤离线变量；转发组在线过滤也会生效。 |
| 并发上传数量 | 1 | 当前目标使用单连接发布，保持 1。 |
目标调试
进入“开发配置 → 数据转发”，选择 ThingsBoard 目标，打开“调试 → 协议调试 · ThingsBoard”。
| 功能 | 作用 |
|---|---|
| ThingsBoard 协议调试 | 查看连接状态、执行测试发布并检查平台返回结果。 |
调试面板会显示连接状态、端点、客户端 ID、TLS、QoS、Retain、设备连接队列、当前目标变量数量、订阅数和三个固定 Topic。RPC 反写必须使用测试设备和允许测试的变量，并单独确认现场反馈。
验证方法
- 确认主机、端口、MQTT 版本、凭据和 TLS。
- 确认转发组包含一个测试变量。
- 在 ThingsBoard 网关设备或遥测页面查看该变量。
- 核对设备、键名、值和时间与 GatewayRuntime 一致。
- 需要 RPC 时，确认目标变量权限后执行一次安全写入，并核对响应和变量值。
常见问题
| 现象 | 检查方法 |
|---|---|
| 平台没有遥测 | 主机、端口、设备 Token、MQTT 版本、固定遥测 Topic、转发组范围和平台设备状态。 |
| 认证失败 | 设备 Token 或凭据、客户端ID、TLS 和端点端口。 |
| 遥测键缺失 | 源变量名称、转发组范围、变量值和目标日志。 |
| RPC 写入失败 | 目标变量权限、源变量写权限、ThingsBoard RPC 正文和目标日志。 |
| 连接反复断开 | 保活时间、平台限制、TLS、防火墙和网络稳定性。 |
| 设备连接消息积压 | 检查平台是否接受 v1/gateway/attributes，启用失败重试缓存，并查看设备连接队列和 CacheDB 待处理数量。 |
| 修改 Topic 没有效果 | ThingsBoard 目标使用固定 Topic，不能通过通用 Topic 模板覆盖；请检查平台端订阅和目标类型。 |