MQTT 客户端转发
把已经采集到的变量发布到 MQTT Broker。开始前准备好 Broker 地址、端口、认证信息和允许发布的主题；不要把本页示例主题直接用于生产控制。
上传第一个值
0. 准备接收端
已有可用 Broker 时，直接使用它提供的连接信息，跳到下一步。没有 Broker 时，可以在运行 TGateway 的同一台电脑上安装 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 tgateway/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模板 | tgateway/demo/modbus，Broker 必须允许该主题 |
| 设备、报警、插件事件Topic模板 | 本次留空 |
| 变量实体脚本、上传模板 | 本次留空，使用默认 JSON |
| 变量列表上传 | 保持开启 |
| 变量字典上传 | 保持关闭 |
其余参数保持默认，保存并启用组和目标。等目标运行正常后继续。
本例只验证发布。连接生产 Broker 前，应按需要关闭变量属性中的“允许RPC写入”，并限制 Broker 账号的主题权限，不要把默认写入入口暴露给无关客户端。
3. 在订阅端查看消息
使用你已有的 MQTT 客户端连接同一个 Broker，客户端 ID 不要与网关重复，订阅 tgateway/demo/modbus。
使用上面已经打开的 mosquitto_sub 窗口即可查看本机练习结果。网关目标里的“调试 → 协议调试 · MqttClient → 状态与订阅”用于管理目标自身的订阅，不是独立接收端，也不是消息内容查看窗口。
等待几个周期，应收到包含设备名、变量名和值的 JSON 消息。对于上一课的点位，检查 DeviceName 为 Demo_Modbus_Device、Name 为 Demo_Modbus_Value、Value 为 1234。默认列表模式最外层是数组，不要按单个对象解析。
订阅窗口先显示主题 tgateway/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 专用端点。 |
| 清除会话 | 开启 | MQTT 3.1.1 下开启表示建立干净会话；需要恢复会话时关闭，并配套固定客户端 ID 和 Broker 的会话保留配置。MQTT 5 的保留期限还取决于会话过期设置，需在 Broker 侧核对。 |
| 保活时间 | 60 秒 | MQTT Keep Alive 秒数。应小于 Broker 的最大允许值，网络不稳定时不要设置过小。 |
Unknown 不是自动协商。当前 V310 发送的协议名称与 MQTT 3.1 标准要求存在差异，成熟 Broker 可能直接拒绝；优先使用已被双方支持的 V311 或 V500，保存后确认新连接和新消息。修改客户端 ID 只改变会话身份，不会改变载荷中的设备或变量身份。
安全认证
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 启用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 | 空 | 接收包含 Source 和 RequestId 的快照请求，按目标配置发布快照及完成标记；不需要时留空。 |
| 设备Topic模板 | 空 | 设备消息 Topic。留空则不发布设备模型；可使用 ${Name}、${PluginName} 等设备字段。 |
| 变量Topic模板 | TGateway/Variable | 变量消息 Topic；可使用 ${DeviceName}、${Name} 等变量字段按设备或变量分组。 |
| 报警Topic模板 | 空 | 报警消息 Topic。留空则不发布报警模型。 |
| 插件事件Topic模板 | 空 | 插件事件 Topic。留空则不发布插件事件模型。 |
| RPC脚本 | 空 | 从表达式选择器选择 MQTT 动态 RPC 脚本，处理 RPC 请求和响应；不需要自定义处理时留空。 |
Topic 模板只决定消息路由；变量是否进入目标仍由转发组范围决定。${字段名} 必须存在于对应实体或实体脚本结果中。
直接调用插件方法
在“消息配置”中设置“插件方法RPC Topic”，默认 RpcMethod，留空则此连接不接收方法请求。向固定主题发布实例类型、编号、方法名和位置参数，响应主题为 RpcMethod/Response，不追加请求编号。被调用设备或目标必须开启“允许方法调用”；MQTT 目标自己的该开关只控制它作为被调用对象的方法。
该协议不使用下文变量/历史请求的编号或 RPC 脚本。请求禁止 Retain，方法入口不额外设置载荷大小上限；MQTT 协议和 Broker 的报文配置仍生效。请求和响应主题不得与其他 RPC 或快照主题冲突。认证、完整示例、结果和重复调用行为见插件方法调用。
快照请求、写入与历史读取
请求当前快照
- 为目标配置一个专用“数据请求Topic”，独立客户端先订阅实际数据 Topic 和该请求 Topic 下的响应。
- 每次生成一个唯一的 32 位小写十六进制 RequestId，向请求 Topic 发送下列结构：
{"Source":"TGateway","RequestId":"6e8c1a7445064ad6b4bb5d5af9cf28b1"}
- 在数据 Topic 核对变量、设备和报警快照；只会发布目标已配置的对应模型。
- 在
数据请求Topic/Response/RequestId核对相同RequestId和Success=true。快照结束标记与数据正文分别读取，任意文本消息不能代替请求结构。
改变请求 Topic 只改变控制入口与完成响应路径，不改变变量发布 Topic。检查结果时排除旧保留消息，按本次唯一编号及新接收窗口匹配。
验证外部写入
向 RPC写入Topic/请求编号 发送按设备名、变量名组织的 JSON，例如：
{"Demo_Modbus_Device":{"Demo_Modbus_Value":1700}}
订阅对应的 RPC写入Topic/请求编号/Response，逐变量检查业务结果，再用源端或独立协议读取核对 1700。同时检查变量本身可写、RPC 使能、目标变量属性“允许RPC写入”和目标成员范围。关闭当前目标的许可不应影响正常采集与上传。自定义 RPC 脚本、权限和其他入口见反向 RPC。
枚举历史目标
“历史读取RPC Topic”使用独立前缀。请求发到 前缀/请求编号，正文编号必须相同，例如：
{"requestId":"6e8c1a7445064ad6b4bb5d5af9cf28b1","operation":"targets","responseChunkBytes":4096,"input":null}
响应位于 前缀/请求编号/Response。先检查 success，按 chunkIndex 和 chunkCount 收齐，分别 Base64 解码后依序拼接，再解压 gzip 并解析 JSON。没有历史目标时可正确返回空列表；数据请求快照不会自动创建历史。查询实际记录还需配置数据库存储及允许的查询范围。
目标变量属性
该插件继承通用的 数据1 至 数据10 预留文本字段，并额外提供 RPC 权限控制。变量必须已经在转发组范围内，目标变量属性不会把变量加入转发组。
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 允许RPC写入 | 开启 | 开启后，外部客户端可以通过 RPC 写入当前变量；只对明确允许远程控制的变量开启。 |
| 数据1～数据10 | 空 | 按项目约定填写附加文本。MQTT 不会自动把这些值发布，需由实体脚本或上传模板显式引用。 |
消息、模板与缓存
数据与脚本
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 详细日志 | 关闭 | 发布日志包含主题和数量，不保存完整消息正文。开启且目标为 Trace 时使用 Trace 级摘要；其他情况下使用 Debug 级摘要，仍受目标日志阈值过滤。原文在独立订阅端查看。 |
| JSON缩进格式化 | 开启 | 关闭可减小消息体；开启便于人工查看。 |
| JSON忽略Null | 开启 | 控制默认实体序列化时是否省略 null 属性；内容模板显式生成的 null 不会自动删除。 |
| 设备列表上传 | 开启 | 设备数据按列表发布；关闭则逐条发布。 |
| 变量列表上传 | 开启 | 变量数据按列表发布；关闭则逐条发布。 |
| 变量字典上传 | 关闭 | 仅变量列表开启时生效，按设备名、变量名形成两层字典，叶子为完整变量实体或脚本输出对象；读取叶子的 Value 取得值。 |
| 报警列表上传 | 开启 | 报警数据按列表发布；关闭则逐条发布。 |
| 报警字典上传 | 关闭 | 仅报警列表开启时生效，按设备和变量组织。 |
| 插件事件列表上传 | 开启 | 插件事件按列表发布；关闭则逐条发布。 |
| 设备/变量/报警/插件事件实体脚本 | 空 | 从表达式选择器选择对应脚本，输出对象再参与 Topic 和 payload 渲染。 |
上传模板字段
需要配置数字类型、列表、字典、逐条消息及常用格式函数时，按上传模板与消息格式完成预览，再在独立订阅端核对实际外层结构。Topic 模板决定路由，实体脚本决定对象，内容模板决定正文，应分别检查。
在“上传模板配置”中分别为变量、设备、报警和插件事件选择 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 发布确认与最终业务落库是不同阶段，不能仅凭目标在线或缓存归零判断数据库已写入。
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 启用失败重试缓存 | 开启 | 建议保持开启，Broker 暂时不可达时保留数据并在恢复后补发。 |
| 缓存文件最大行数 | 262144 | CacheDB 出站记录上限，超过后删除最旧数据。 |
| 上传分片大小 | 2000 | 变化记录的缓存读取批量上限；完整周期快照可保留组批次边界，不能据此推算每条消息的点数。 |
| 内存队列上限 | 100000 | 对各模型的待落盘队列分别计数，完整快照按批次计数，不是目标总变量数或内存字节数。达到上限后先转入 CacheDB；落盘失败保留已接收记录并拒绝新记录，由上游重试。 |
| 过滤离线数据 | 关闭 | 开启后目标出队时过滤离线变量；转发组在线过滤也会生效。 |
| 并发上传数量 | 1 | MQTT 客户端由单连接顺序发布，保持 1。 |
目标调试
进入“开发配置 → 数据转发”，选择 MQTT 客户端目标，打开“调试 → 协议调试 · MqttClient”。
| 功能 | 作用 |
|---|---|
| 发布消息 | 向测试 Topic 发布小型消息，检查 QoS、Retain 和返回结果。 |
| 状态与订阅 | 新增、查询或取消目标自身的主题订阅；接收正文使用独立 MQTT 客户端查看。 |
| 取消订阅 | 移除测试订阅。 |
协议操作要求目标在线。RPC 写入应使用独立测试 Topic 和允许测试的变量。
看懂运行概览
在调试页先核对目标名称、所属组、对象身份和当前冗余角色，再进入“运行状态”。“已启动”“初始化成功”“在线”分别表示生命周期、初始化结果和 Broker 连接，不能互相代替。
| 指标 | 检查方法 |
|---|---|
| 变量数、设备数 | 核对当前目标输入范围，不能当作 Broker 客户端数或已经成功上传的记录数。 |
| 累计成功/失败、最近成功/失败时间 | 触发一条新测试数据，比较前后快照并结合目标日志判断本次操作；累计成功不等于订阅端已接收。 |
| 最后活动时间 | 用于观察目标是否继续工作，不能代替载荷内的来源采集时间。 |
| 每秒速率、接收/发送字节、最近耗时 | 当前目标未提供的指标显示 —，表示无此指标，不代表零流量或零耗时。 |
公开特殊方法在“特殊方法”模块选择。使用发布方法时，按当前参数提示填写主题和字节载荷，在独立订阅端核对原文；它与组周期上传各自触发，不能用一次特殊方法发送证明组范围或实体模板已经正确。
常见问题
| 现象 | 检查方法 |
|---|---|
| 目标未连接 | 先看目标日志中的连接或认证错误，核对 Broker 地址、端口、凭据和 TLS 设置。 |
| 目标已连接，接收端没有消息 | 先检查组内是否确实添加了变量、组和目标是否启用，再核对发布与订阅主题是否相同、Broker 是否允许发布和订阅。 |
| 连接反复断开 | 保活时间、TLS、Broker 限制、防火墙和网络稳定性。 |
| Topic 不正确 | Topic 模板、${字段名}、实体脚本输出和组别名。 |
| 出现意外保留消息 | 关闭“保留消息”，并在 Broker 或客户端流程中清理旧保留消息。 |
| RPC 写入失败 | RPC Topic、目标变量权限、请求正文、变量数据类型和源变量写权限。 |
| 模板正文无效 | 模板预览、占位符、JSON 语法和实体脚本输出。 |
| TLS 握手失败 | IP、SSL目标主机名、客户端证书、CA、SSL协议版本、证书有效期和“允许不受信任证书”设置。 |
| 发布失败后消息消失 | 检查“启用失败重试缓存”、CacheDB 待处理数量、内存队列上限和缓存文件最大行数。 |