设备调试

设备调试用于在 GatewayRuntime Web 中直接验证采集设备或数据转发目标的通信能力。使用时需要先选中真实设备或转发目标，再进入详情页的“调试”标签；“测试数据”用于批量生成演示通道、设备和变量。

完整报文调试

CustomPacketMaster 可以按 Hex 或文本发送完整自定义报文，并选择仅发送或发送并等待。配置和操作方法参见完全自定义报文采集。

调试前先看术语

术语	现场理解
Broker	MQTT、Kafka、RabbitMQ 等消息系统的服务端，现场可理解为“消息中转服务器”。
Topic	消息发送或订阅的主题/路径，类似外部系统约定的数据通道名称。
Payload	消息正文，也就是实际发送的数据内容。
RPC 写入	外部系统反写点位。只有确认现场设备允许远程控制时，才应对控制类点位开启。
目标变量属性	某个转发目标对单个变量的外部映射，例如外部字段名、从站地址或写入权限。
DTU / DTU ID	透传终端及其编号，用于区分哪台远端设备正在接入。
QoS / Retain	MQTT 的投递等级和保留消息开关。普通测试先按现场 Broker 约定填写，不清楚时不要随意开启 Retain。

MQTT、Kafka、RabbitMQ 等调试页需要现场存在对应的服务端或 Broker。页面会提供发布、订阅、客户端列表等表单，但执行结果取决于目标服务连接状态。

现场调试原则

调试页直接面向真实设备或真实外部系统。现场排查时先证明“能读、读得对、日志正常”，再考虑写入或发布测试消息。

原则	说明
先读后写	先读取只读点或安全点，确认通道、站号、地址和数据类型正确后，再测试写入。
先单点后批量	先用 1 个地址验证，再扩展到连续地址、点表导入或批量转发。
先测试环境后生产	有条件时先在 PLC 模拟器、测试 Broker 或测试 Topic 中验证。
写入需要现场确认	涉及启停、复位、设定值、阀门、电机和联锁的点位，写入前必须确认设备处于允许远程控制状态。
调试后恢复日志级别	临时打开 Debug 或 Trace 后，联调结束应恢复为 Info，避免长期产生大量日志。

功能入口

采集设备调试

进入“开发配置 → 采集配置”，先切换到“设备显示”，再在左侧设备状态列表中选择一个设备。右侧出现设备详情后，点击“调试”标签。

步骤	说明
切换设备显示	“变量显示”用于看点位列表，“设备显示”用于打开设备详情。设备调试入口只在设备详情中显示。
选择设备	点击左侧设备行，不是点击变量行。右侧标题会显示“设备名称 - 详细信息”。
打开调试	在设备详情的“设备信息、通道日志、设备日志、调试”标签中选择“调试”。
执行测试	根据插件类型显示对应调试界面。通用驱动显示 Foundation 读写，MQTT/Kafka/RabbitMQ 等显示消息调试。

数据转发目标调试

进入“开发配置 → 数据转发”，选择一个转发组，再选择一个转发目标。右侧详情区点击“调试”标签，可验证 MQTT、Kafka、RabbitMQ、ModbusSlave、OpcUaServer 等转发插件的发送、发布或服务端状态。

对象	调试入口	适用场景
采集设备	采集配置 → 设备显示 → 设备详情 → 调试	验证 PLC、仪表、OPC、MQTT 采集设备的读写、订阅或协议状态。
数据转发目标	数据转发 → 选择目标 → 详情区 → 调试	验证转发目标的消息发布、订阅管理、客户端连接或服务端统计。

支持的调试类型

选择设备或转发目标后，调试标签会按插件类型显示对应界面。所选插件没有调试入口时，页面会提示该对象没有可用调试能力。

调试类型	显示条件	主要用途
Foundation	通用读写调试界面	按地址读取、写入，查看读取结果和操作历史。
OPC UA	OPC UA 采集插件	浏览节点、读取/写入节点、导出节点、导入变量、创建订阅。
OPC DA	OPC DA 采集插件	浏览 OPC DA 项、读取/写入项、订阅变量变化。
MQTT Client	MQTT Client 采集或转发插件	发布 MQTT 消息，维护订阅主题，查看消息日志。
MQTT Server	MQTT Server 采集或转发插件	发布消息，查看主题统计、客户端连接并踢出客户端。
Gateway MQTT 专用采集	GatewayMqttCollectClient 或 GatewayMqttCollectServer	查看共享传输、逐来源状态、远端目录、诊断和变量同步；不提供任意 Topic 发布。
SyncBridge	SyncBridge 数据转发目标	查看逐 Peer 连接、配置修订、序号、积压、延迟，并执行受控配置同步或全量值请求。
Kafka	Kafka 转发插件	向指定 Topic 发布消息，并通过日志确认发送结果。
RabbitMQ	RabbitMQ 转发插件	使用 Routing Key 发布消息，并通过日志确认发送结果。
CAN	CAN 采集插件	发送 CAN 帧，按 CAN ID 读取帧。
IEC61850 Master	IEC 61850 客户端插件	查看连接、模型浏览、节点读写、RCB/GOOSE、数据集、控制与 SOE。
IEC61850 Server	IEC 61850 服务端插件	查看服务端状态、数据模型、客户端连接、属性读写和变量映射。
ZeroMQ	ZeroMQ 插件	按主题发布 ZeroMQ 消息。

Gateway MQTT 专用采集和 SyncBridge 使用独立调试页，不会先显示普通 MQTT 调试表单。完整配置与页面说明参见 Gateway MQTT 专用采集 和 SyncBridge 网关同步。

Foundation 读写调试

Foundation 是通用读写调试界面，ModbusMaster 等常见采集驱动会显示此界面。它适合验证地址、数据类型、长度和写入值是否与现场设备一致。

配置项	说明
地址	要读取或写入的寄存器、节点或协议地址。地址格式由设备插件决定，例如 Modbus 寄存器地址、PLC 地址或自定义协议地址。
数据类型	读取或写入时使用的数据类型。页面提供 String、Boolean、Byte、Int16、UInt16、Int32、UInt32、Int64、UInt64、Float、Double、Decimal。
数组长度	批量读取连续地址时使用。普通单点读取保持为 1。
写入值	执行写入时下发的值。填写格式必须与数据类型匹配；数组或复杂类型按插件要求填写。
读取	按表单中填写的地址、数据类型和长度读取设备数据。
写入	将“写入值”下发到表单中填写的地址。执行前应确认变量权限和现场设备允许写入。
读取结果	显示最近一次读取的结果、错误信息或返回值。

操作建议：

1. 先选择在线设备，再进入调试。
2. 先用只读地址做读取验证，确认通道、站号、超时和地址格式正确。
3. 写入前确认现场设备处于允许远程控制的状态。
4. 如果读取失败，先看“设备日志”和“通道日志”，再检查通道 IP、端口、串口参数、站号、超时和地址。

写入前建议逐项确认：

检查项	通过标准
地址	已经用同一地址或相邻只读地址验证过读取正常。
数据类型	写入类型与 PLC 或仪表点表一致，没有字节序、比例换算或小数位争议。
写入值	值在现场允许范围内，不会触发保护、联锁或误动作。
权限	变量读写权限、RPC 写入开关和外部系统权限都符合现场要求。
回读	需要确认写入生效时，可读取同一地址或反馈点验证结果。

MQTT Client 调试

MQTT Client 调试包含“发布消息”和“状态与订阅”两个标签。它可以出现在 MQTT 采集客户端，也可以出现在 MQTT Client 数据转发目标中。

发布消息

配置项	说明
主题	要发布到 Broker 的 Topic。建议使用现场约定的测试 Topic，避免影响生产订阅者。
消息内容	发布的 Payload。可填写普通文本或 JSON 字符串。
QoS	发布质量等级：0 - 最多一次、1 - 至少一次、2 - 恰好一次。
保留消息	是否设置 MQTT Retain 标志。开启后 Broker 可能保存最后一条保留消息，生产环境需谨慎。
发布	调用当前设备或目标的 MQTT 发布接口。成功与否取决于 Broker 连接状态、认证、Topic 权限和网络。
消息日志	显示调试 WebSocket 连接状态、收发消息时间和消息内容。

状态与订阅

配置项	说明
连接状态	显示客户端是否已连接 Broker，用于判断发布和订阅是否具备通信条件。
主题	要订阅的 Topic，可填写普通主题或通配主题。
QoS	订阅使用的 QoS 等级。
订阅	将当前 Topic 加入订阅列表。
订阅列表	显示已订阅 Topic、QoS 和取消订阅操作。
刷新	重新获取当前订阅列表。
取消	取消指定 Topic 的订阅。

排查顺序：

1. 确认目标配置中的 IP 地址、端口、连接类型、客户端 ID、用户名和密码与 Broker 一致。
2. 使用 TLS 时，检查证书名称、CA、目标主机和证书吊销检查设置。
3. 订阅无消息时，确认 Topic 是否匹配，Broker 是否允许该账号订阅，生产端是否实际发布。
4. 发布失败时，先看调试页消息日志，再看“转发目标日志”或“设备日志”。

MQTT Server 调试

MQTT Server 调试包含“发布消息”和“状态监控”两个标签。它适合验证 MQTT 服务端插件是否正在监听、客户端是否接入、主题订阅是否存在。

发布消息

配置项	说明
主题	服务端向已连接客户端发布的 Topic。
消息内容	要发送给客户端的 Payload。
QoS	发布质量等级。客户端订阅 QoS 与服务端发布 QoS 会共同影响最终投递等级。
保留消息	是否发布为保留消息。
发布	从当前 MQTT Server 插件向客户端发布消息。

状态监控

区域	说明
主题统计	显示 Topic 名称和订阅数量，用于判断客户端是否订阅到预期主题。
客户端列表	显示 ClientId、用户名、远端地址、连接时间。
踢出客户端	断开指定客户端连接。执行前应确认不会影响生产通信。
刷新	重新加载主题统计或客户端列表。

Kafka 调试

Kafka 调试页用于向指定 Topic 发布消息，适合验证 Kafka 地址、认证、Topic 权限和序列化内容。

配置项	说明
Topic	Kafka Topic 名称。数据转发目标中默认可使用变量 Topic 模板，调试时可手动填写测试 Topic。
消息内容	要发送的消息体。建议先发送小型 JSON 或纯文本验证连通性。
发布	调用 Kafka 发布接口。失败时检查服务地址、安全协议、SASL 机制、用户名、密码和发布超时时间。
消息日志	显示调试 WebSocket 状态和调试消息。

Kafka 目标常用属性：

配置项	说明
服务地址	Kafka Bootstrap 地址。多个 Broker 按 Kafka 连接串约定填写。
发布超时时间	单次发布等待时间，单位毫秒。网络慢或 Kafka 繁忙时可适当增大。
安全协议	Kafka 连接安全协议。无认证内网常用 Plaintext；启用认证或加密时按集群要求选择。
SASL 机制	Kafka 使用 SASL 认证时的认证机制，必须与集群配置一致。
用户名 / 密码	SASL 认证账号。未启用 SASL 时留空。
变量、设备、报警 Topic 模板	不同数据类型写入的 Topic。模板展开后的 Topic 必须允许当前账号写入。
启用离线缓存 / 内存队列上限 / 并发上传数量	控制发送失败后的补发、积压上限和上传并发。要求顺序严格时并发上传数量保持为 1。

RabbitMQ 调试

RabbitMQ 调试页用于按 Routing Key 发布消息。目标连接参数在数据转发目标抽屉中配置。

配置项	说明
Routing Key	发布消息使用的路由键。应与交换机类型和队列绑定规则匹配。
消息内容	要发送的 Payload。
发布	调用 RabbitMQ 发布接口。失败时检查交换机、队列、认证和网络。
消息日志	显示调试连接和消息记录。

RabbitMQ 目标常用属性：

配置项	说明
IP 地址 / 端口	RabbitMQ 服务地址和端口，默认端口通常为 5672。
用户名 / 密码	RabbitMQ 账号密码。
虚拟主机	RabbitMQ Virtual Host，账号必须有该虚拟主机的写入权限。
交换机名称	发布使用的交换机名称。
交换机类型	交换机类型，例如 direct、topic、fanout、headers，必须与实际交换机一致。
声明队列 / 声明交换机	是否由插件自动创建队列或交换机。生产环境已有统一队列规范时通常关闭。
发布超时时间	单次发布等待时间，单位毫秒。

MQTT 转发目标配置抽屉

数据转发目标的插件属性在目标配置抽屉中维护。选择 MQTT Client Producer 后，抽屉会显示 MQTT 连接、TLS、认证、QoS、Topic 模板、离线缓存和队列参数。

配置项	说明
目标名称	当前转发目标名称，同一转发组内应唯一。
启用	控制目标是否运行。启用后才会创建运行态目标并显示对应调试入口。
插件	选择数据转发插件，例如 MqttClientProducer、MqttServerProducer、KafkaProducer、RabbitMQProducer。
日志级别	控制目标运行日志详细程度。调试阶段可临时使用 Debug 或 Trace，稳定后恢复为 Info。
启动超时	目标启动等待时间，单位秒。外部服务连接慢时可适当增大。
IP 地址 / 端口 / 连接类型	MQTT Broker 地址、端口和连接方式。WebSocket 连接还需要填写 WebSocket 路径。
客户端 ID / 保活时间 / 清除会话	MQTT 客户端身份、心跳保活和会话保留策略。
启用 SSL / TLS 证书配置	TLS 连接相关参数，包括目标主机名、客户端证书、CA、协议和证书吊销检查。
用户名 / 密码	Broker 认证信息。
QoS 等级 / 保留消息	默认发布 QoS 和 Retain 策略。
RPC 写入 Topic / 数据请求 Topic / RPC 脚本	外部系统反向写入、主动请求快照和自定义 RPC 处理使用。
设备、变量、报警、插件事件 Topic 模板	不同数据类型的上传 Topic。Topic 为空时，对应数据类型不会上传。
设备、变量、报警、插件事件实体脚本	上传前重组对应数据。脚本输出的新字段可以继续用于 Topic 模板和上传模板。
上传模板配置	打开模板弹窗，分别维护变量、设备、报警和插件事件的消息内容。留空时使用默认 JSON。
JSON 缩进格式化 / JSON 忽略 Null	默认 JSON 输出格式控制。
启用离线缓存 / 缓存文件最大行数	外部服务不可用时的本地缓存策略。
上传分片大小 / 内存队列上限 / 并发上传数量	控制补发批量、内存积压和并发上传。

MQTT 转发目标联调时，建议先使用最小模板验证链路，例如变量 Topic 填写 ThingsGateway/Variable/${DeviceName}，上传模板先只保留变量名和值；确认 Broker 能收到消息后，再增加时间、质量码、扩展字段或业务字段。Topic 模板和上传模板中的占位符都要来自上传数据或实体脚本输出，名称写错会导致 Topic 或消息体生成失败。

Webhook 目标与 MQTT 的模板入口相同，但 Topic 模板表示最终请求 URL。配置 Webhook 时，应把变量、设备、报警或插件事件 Topic 填写为实际接口地址；不需要发送的数据类型保持 Topic 为空。

OPC UA 和 OPC DA 调试

OPC 调试分为“节点浏览”和“订阅管理”。OPC UA 与 OPC DA 的页面结构相近，但节点属性和浏览结果由对应服务端返回。

功能	说明
节点树	浏览服务端地址空间。可展开节点、选择节点并查看详情。
节点详情	显示 NodeId、浏览名称、显示名称、当前值、状态码和时间戳等信息。
读取节点	对选中节点执行读取。
写入节点	对可写节点下发值。写入前确认权限和现场状态。
导出 Excel	将选中节点导出为 Excel，用于离线整理变量。
导入数据库	将选中节点导入为变量配置。导入后仍需检查变量名称、地址、数据类型和采集周期。
创建订阅	输入一个或多个 NodeId，创建订阅组。
消息日志	显示订阅推送消息，便于确认变化通知是否到达。

IEC61850 调试

IEC61850 Master 和 Server 调试页覆盖模型浏览、读写、订阅状态、客户端状态和 SOE 查询。现场使用前应先确认设备模型、逻辑设备、逻辑节点、功能约束和证书/TLS 配置。

调试页	关键功能
IEC61850 Master	连接状态、模型浏览、节点读写、RCB 订阅状态、GOOSE 订阅状态、数据集操作、控制操作、SOE 事件。
IEC61850 Server	服务端状态、数据模型、客户端连接、属性读写、变量映射统计、SOE 事件。

常见注意事项：

1. 对象引用和功能约束必须与服务端模型一致。
2. 控制操作前应确认控制模型、权限和现场联锁条件。
3. SOE 页签需要设备或服务端产生事件记录；没有事件时列表会保持为空。
4. TLS 场景需先在“证书管理”中维护证书，再在插件属性中选择。

CAN 和 ZeroMQ 调试

类型	配置项	说明
CAN	CAN ID	支持十六进制或十进制标识。
CAN	数据	十六进制字节字符串，例如 01 02 03 04。
CAN	扩展帧	控制是否使用扩展帧格式。
ZeroMQ	Topic	发布主题。
ZeroMQ	Payload	发布内容。

测试数据生成

“测试数据”位于采集配置页右上角“显示更多”菜单中，用于生成测试通道、设备和变量。

配置项	说明
数据类型	可选择普通测试数据或 DTU 测试数据。
变量数量	普通测试数据下生成的变量数量。
设备数量	要生成的设备数量。
从站地址	生成测试设备时使用的从站地址或连接信息。
启用数据转发	普通测试数据下是否同时生成数据转发相关配置。
生成	按表单中填写的参数生成测试配置。执行前应确认不会覆盖或混淆生产配置。

日志与故障处理

现象	处理建议
调试标签不显示	确认已切换到“设备显示”并选中设备，或在数据转发页选中目标；再确认插件支持调试。
调试页提示无可用调试能力	所选插件没有匹配的调试界面。可查看插件名是否为 MQTT、Kafka、RabbitMQ、OPC、IEC61850、CAN、ZeroMQ 或 Foundation 支持类型。
Foundation 读取失败	检查通道连接、设备状态、地址格式、数据类型、数组长度、站号、超时和设备日志。
写入失败	检查变量/设备是否允许写入、写入值格式、现场设备权限和 RPC 写入开关。开启写入检查时，还要确认设备回读值能立即与写入值一致。
MQTT 发布失败	检查 Broker 地址、端口、TLS、账号密码、Topic 权限、QoS 和目标日志。
MQTT 订阅无消息	检查 Topic 通配规则、生产端是否发布、Broker 是否允许订阅、客户端是否在线。
Kafka 发布失败	检查服务地址、认证、安全协议、Topic 权限和发布超时。
RabbitMQ 发布失败	检查交换机、Routing Key、虚拟主机、账号密码、队列绑定和网络连通性。
数据转发目标调试为空	目标需要启用并进入运行态；禁用目标不会显示对应调试入口。

相关链接

• 采集配置
• 数据转发
• 系统日志
• 插件参考