MQTT 客户端转发
把已经采集到的变量发布到 MQTT Broker。开始前准备好 Broker 地址、端口、认证信息和允许发布的主题；不要把本页示例主题直接用于生产控制。
上传第一个值
0. 准备接收端
已有可用 Broker 时，直接使用它提供的连接信息，跳到下一步。没有 Broker 时，可以在运行 GatewayRuntime 的同一台电脑上安装 Mosquitto，做一次仅限本机的练习。
Windows 安装后，在 Mosquitto 安装目录打开 PowerShell，运行：
.\mosquitto.exe -p 18885 -v
Linux 安装发行版提供的 Mosquitto 后，在终端运行：
mosquitto -p 18885 -v
保持这个窗口运行。启动日志应显示本地模式和端口 18885；提示端口占用时，换一个未占用端口，并同步修改下面的网关与订阅端端口。
再开一个终端订阅本例主题。Windows 在同一安装目录运行：
.\mosquitto_sub.exe -h 127.0.0.1 -p 18885 -i manual-reader -t thingsgateway/demo/modbus -v
Linux 使用相同参数，将命令名改为 mosquitto_sub；没有此命令时安装发行版提供的 Mosquitto 客户端包。订阅窗口暂时没有输出是正常的，完成下面的转发配置后才会收到数据。
本机练习的连接信息为：IP 127.0.0.1、端口 18885、用户名和密码留空、SSL 关闭。不要加载生产配置文件。Mosquitto 当前版本的 -p 监听仅允许本机连接，不能拿这套配置供远程网关使用；正式环境应使用有认证和相应主题权限的 Broker。参见 Mosquitto 启动参数。
1. 选择要上传的变量
- 打开“开发配置 → 数据转发”，新增转发组
Demo_MQTT_Group。 - “变量范围”选“手动选择”，“触发模式”选“定时”，“定时间隔”填
1000，保存。 - 重新编辑这个组，在“转发变量”中搜索
Demo_Modbus_Value，选择Demo_Modbus_Device.Demo_Modbus_Value，点击旁边加号，再保存。 - 使用自己的点位时，把上一步换成实际设备与变量。添加方法见维护组变量。
2. 新增 MQTT 目标
选中这个组，点击“新增目标”，名称填 Demo_MQTT_Target，插件选“MQTT 客户端转发”。切换到“插件属性”页签，填写：
| 配置项 | 这次怎么填 |
|---|---|
| 连接类型 | 普通 MQTT TCP 连接选“TCP连接” |
| IP地址 | Broker 的 IP 或主机名，不带 tcp:// 和端口 |
| 端口 | Broker 实际端口；上面的本机练习填 18885，不要保留默认 1883 |
| 客户端ID | gateway-manual-demo，确保不与其他客户端重复 |
| 用户名、密码 | 按 Broker 账号填写；仅允许匿名的测试 Broker 才留空 |
| 启用SSL | 按 Broker 要求设置；TLS 连接同时配置端口和可信证书 |
| 变量Topic模板 | thingsgateway/demo/modbus，Broker 必须允许该主题 |
| 设备、报警、插件事件Topic模板 | 本次留空 |
| 变量实体脚本、上传模板 | 本次留空，使用默认 JSON |
| 变量列表上传 | 保持开启 |
| 变量字典上传 | 保持关闭 |
其余参数保持默认，保存并启用组和目标。等目标运行正常后继续。
本例只验证发布。连接生产 Broker 前，应按需要关闭变量属性中的“允许RPC写入”，并限制 Broker 账号的主题权限，不要把默认写入入口暴露给无关客户端。
3. 在订阅端查看消息
使用你已有的 MQTT 客户端连接同一个 Broker，客户端 ID 不要与网关重复，订阅 thingsgateway/demo/modbus。
使用上面已经打开的 mosquitto_sub 窗口即可查看本机练习结果。网关目标里的“调试 → 协议调试 · MqttClient → 状态与订阅”用于管理目标自身的订阅，不是独立接收端，也不是消息内容查看窗口。
等待几个周期，应收到包含设备名、变量名和值的 JSON 消息。对于上一课的点位，检查 DeviceName 为 Demo_Modbus_Device、Name 为 Demo_Modbus_Value、Value 为 1234。默认列表模式最外层是数组，不要按单个对象解析。
订阅窗口先显示主题 thingsgateway/demo/modbus，后面是 JSON。消息中与本次操作有关的字段如下，其余字段省略：
[
{
"Name": "Demo_Modbus_Value",
"DeviceName": "Demo_Modbus_Device",
"Value": 1234,
"RawValue": 1234,
"IsOnline": true,
"RegisterAddress": "40001"
}
]
看到实际消息后，才算完成上传。手动点击“发布消息”只证明可以手动发送，不能证明转发组已经选中了正确变量。
本机练习结束后，先停用本例 MQTT 目标，再在订阅端和 Broker 窗口分别按 Ctrl+C 退出。不要停止其他项目正在使用的 Broker。
换成正式配置
读通默认 JSON 后，再按接收端要求调整主题、上传模板、脚本、QoS 和缓存。不要同时修改全部选项，否则很难判断是哪一步导致没有消息。
目标基本信息
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 所属转发组 | - | 必须选择已保存的转发组；目标只接收该组范围内的变量。 |
| 目标名称 | - | 必填，同一转发组内不能重复。建议包含 Broker 和环境名称。 |
| 启用 | 开启 | 关闭时 MQTT 客户端不会连接 Broker。 |
| 日志级别 | Info | 排查连接、订阅或发布问题时临时使用 Debug，完成后恢复。 |
| 启动超时 | 60 秒 | 页面可填 1～3600 秒。 |
目标属性
连接配置
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 连接类型 | Tcp | Tcp 连接使用 tcp://IP:端口；WebSocket 使用 ws://IP:端口/WebSocket路径。TLS 开启后分别变为 ssl 和 wss。 |
| IP地址 | localhost | 填 MQTT Broker 主机名或 IP，不要带协议前缀和端口。 |
| 端口 | 1883 | TCP 明文通常为 1883，TLS 常用 8883；WebSocket 端口按 Broker 配置填写。 |
| WebSocket路径 | /mqtt | 仅 WebSocket 生效。必须以 / 开头；输入 mqtt 时系统会自动补成 /mqtt。 |
| 客户端ID | 空 | 留空时每次连接自动生成 GUID；固定客户端 ID 必须在 Broker 上唯一。 |
| MQTT协议版本 | V311（MQTT 3.1.1） | 选择 Broker 支持的协议版本；不要用 MQTT 5 配置连接 MQTT 3.1.1 专用端点。 |
| 清除会话 | 开启 | 开启时断线后清除会话和订阅状态；需要持久会话时关闭，并确认 Broker 支持持久会话。 |
| 保活时间 | 60 秒 | MQTT Keep Alive 秒数。应小于 Broker 的最大允许值，网络不稳定时不要设置过小。 |
安全认证
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 启用SSL | 关闭 | Broker 使用 TLS 时开启。开启后客户端使用 ssl/wss，端口和证书必须与 Broker Listener 匹配。 |
| SSL目标主机名 | 空 | 用于校验 Broker 证书 SAN；证书不是按 IP 签发时填写证书中的 DNS 名称。留空时使用 IP地址。 |
| 客户端证书名称 | 空 | 双向 TLS 时，从“证书管理”选择带私钥的客户端证书；单向 TLS 可留空。 |
| CA名称 | 空 | 使用自定义 CA 时选择 CA 证书；系统信任公有 CA 时可留空。 |
| 允许不受信任证书 | 关闭 | 仅临时测试自签名证书。生产环境必须关闭，否则客户端会接受无法验证的证书。 |
| SSL协议版本 | None（系统默认） | 通常保持系统默认；只有 Broker 明确要求时选择 TLS 1.2 或 TLS 1.3。 |
| 检查证书吊销 | 关闭 | 按企业安全策略开启；开启后客户端会校验证书吊销状态。 |
| 用户名 | 空 | Broker 启用用户名认证时填写。 |
| 密码 | 空 | 与用户名配套填写；不要放入上传模板、截图或日志。 |
消息配置
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| QoS等级 | AtMostOnce（0） | 按接收端要求选择 0、1 或 2。QoS 2 需要 Broker 和客户端都支持，吞吐成本最高。 |
| 保留消息 | 关闭 | 开启后每个发布 Topic 保留最后一条消息；状态类数据才使用。停用时要在 Broker 侧清理旧 Retained Message。 |
| RPC写入Topic | RpcWrite | 填主题前缀，不要填写 + 或 #。客户端订阅 {前缀}/+，响应发布到 {前缀}/{请求编号}/Response。 |
| 历史读取RPC Topic | RpcHistory | 填不含 MQTT 通配符的主题前缀。请求为 {前缀}/{请求编号}，分块响应为 {前缀}/{请求编号}/Response。 |
| 数据请求Topic | 空 | 收到该主题的任意消息后，立即发布当前目标的变量、设备和报警快照；不需要快照时留空。 |
| 设备Topic模板 | 空 | 设备消息 Topic。留空则不发布设备模型；可使用 ${Name}、${PluginName} 等设备字段。 |
| 变量Topic模板 | ThingsGateway/Variable | 变量消息 Topic；可使用 ${DeviceName}、${Name} 等变量字段按设备或变量分组。 |
| 报警Topic模板 | 空 | 报警消息 Topic。留空则不发布报警模型。 |
| 插件事件Topic模板 | 空 | 插件事件 Topic。留空则不发布插件事件模型。 |
| RPC脚本 | 空 | 从表达式选择器选择 MQTT 动态 RPC 脚本，处理 RPC 请求和响应；不需要自定义处理时留空。 |
Topic 模板只决定消息路由；变量是否进入目标仍由转发组范围决定。${字段名} 必须存在于对应实体或实体脚本结果中。
目标变量属性
该插件继承通用的 数据1 至 数据10 预留文本字段，并额外提供 RPC 权限控制。变量必须已经在转发组范围内，目标变量属性不会把变量加入转发组。
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 允许RPC写入 | 开启 | 开启后，外部客户端可以通过 RPC 写入当前变量；只对明确允许远程控制的变量开启。 |
| 数据1～数据10 | 空 | 按项目约定填写附加文本。MQTT 不会自动把这些值发布，需由实体脚本或上传模板显式引用。 |
数据与脚本
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 详细日志 | 关闭 | 开启后记录每次发布的内容或计数，短时间排查使用。 |
| JSON缩进格式化 | 开启 | 关闭可减小消息体；开启便于人工查看。 |
| JSON忽略Null | 开启 | 关闭后保留 null 字段。 |
| 设备列表上传 | 开启 | 设备数据按列表发布；关闭则逐条发布。 |
| 变量列表上传 | 开启 | 变量数据按列表发布；关闭则逐条发布。 |
| 变量字典上传 | 关闭 | 仅变量列表开启时生效，按 DeviceName → Name → Value 组织。 |
| 报警列表上传 | 开启 | 报警数据按列表发布；关闭则逐条发布。 |
| 报警字典上传 | 关闭 | 仅报警列表开启时生效，按设备和变量组织。 |
| 插件事件列表上传 | 开启 | 插件事件按列表发布；关闭则逐条发布。 |
| 设备/变量/报警/插件事件实体脚本 | 空 | 从表达式选择器选择对应脚本，输出对象再参与 Topic 和 payload 渲染。 |
上传模板字段
在“上传模板配置”中分别为变量、设备、报警和插件事件选择 Text 或 Json 模式并插入 ${字段名}，保存前先执行预览；模板留空时使用默认 JSON 序列化。
| 数据类型 | 可用字段 |
|---|---|
| 变量 | Id、Name、DeviceName、Value、RawValue、LastSetValue、CollectGroup、CollectTime、CreateTime、ChangeTime、IsOnline、DataType、Unit、RegisterAddress、OtherMethod、Description、ProtectType、RpcWriteEnable、Remark1～Remark5、ValueInited、IsMemory |
| 设备 | Id、Name、ActiveTime、DeviceStatus、PluginName、Description、LastErrorMessage、Remark1～Remark5 |
| 报警 | AlarmId、VariableId、Name、DeviceName、AlarmCode、AlarmLevel、AlarmLimit、AlarmText、RecoveryCode、AlarmTime、EventTime、FinishTime、ConfirmTime、ConfirmText、AlarmType、EventType、Remark1～Remark5 |
| 插件事件 | DeviceName、ObjectValue |
实体脚本会先改变上传对象，再参与 Topic 分组和模板渲染；占位符必须与脚本输出一致。对应 Topic 模板留空时，该类数据不会发布。
缓存与容量
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 启用失败重试缓存 | 开启 | 建议保持开启，Broker 暂时不可达时保留数据并在恢复后补发。 |
| 缓存文件最大行数 | 262144 | CacheDB 出站记录上限，超过后删除最旧数据。 |
| 上传分片大小 | 2000 | 每次从缓存读取的最大记录数；Broker 较慢时减小。 |
| 内存队列上限 | 100000 | 内存缓冲上限，超过后优先转 CacheDB，持续超限仍可能丢弃旧数据。 |
| 过滤离线数据 | 关闭 | 开启后目标出队时过滤离线变量；转发组在线过滤也会生效。 |
| 并发上传数量 | 1 | MQTT 客户端由单连接顺序发布，保持 1。 |
目标调试
进入“开发配置 → 数据转发”，选择 MQTT 客户端目标，打开“调试 → 协议调试 · MqttClient”。
| 功能 | 作用 |
|---|---|
| 发布消息 | 向测试 Topic 发布小型消息，检查 QoS、Retain 和返回结果。 |
| 状态与订阅 | 新增、查询或取消目标自身的主题订阅；接收正文使用独立 MQTT 客户端查看。 |
| 取消订阅 | 移除测试订阅。 |
协议操作要求目标在线。RPC 写入应使用独立测试 Topic 和允许测试的变量。
常见问题
| 现象 | 检查方法 |
|---|---|
| 目标未连接 | 先看目标日志中的连接或认证错误，核对 Broker 地址、端口、凭据和 TLS 设置。 |
| 目标已连接，接收端没有消息 | 先检查组内是否确实添加了变量、组和目标是否启用，再核对发布与订阅主题是否相同、Broker 是否允许发布和订阅。 |
| 连接反复断开 | 保活时间、TLS、Broker 限制、防火墙和网络稳定性。 |
| Topic 不正确 | Topic 模板、${字段名}、实体脚本输出和组别名。 |
| 出现意外保留消息 | 关闭“保留消息”，并在 Broker 或客户端流程中清理旧保留消息。 |
| RPC 写入失败 | RPC Topic、目标变量权限、请求正文、变量数据类型和源变量写权限。 |
| 模板正文无效 | 模板预览、占位符、JSON 语法和实体脚本输出。 |
| TLS 握手失败 | IP、SSL目标主机名、客户端证书、CA、SSL协议版本、证书有效期和“允许不受信任证书”设置。 |
| 发布失败后消息消失 | 检查“启用失败重试缓存”、CacheDB 待处理数量、内存队列上限和缓存文件最大行数。 |