插件参考

插件参考用于查阅采集插件和数据转发插件的地址格式、连接参数、上传参数和变量级参数。配置插件时，应先确认现场协议、设备地址、端口、账号、证书和外部系统接收规则，再在页面中按字段填写。

如果现场只需要逐项核对“每个插件属性该填什么”，请直接查看 插件属性详表。本页保留地址格式、典型配置和插件说明，详表按当前版本页面字段逐项列出。

先看术语

本文会保留页面中的英文配置名，方便和界面、点表、外部系统文档对应。第一次配置前，先按下面的现场含义理解这些词。

术语	现场理解
Other	无普通通讯通道插件。插件自己管理连接，或本身不需要 TCP、UDP、串口通道。
Cron 表达式	定时表达式。普通周期优先填毫秒数，例如 1000 表示 1 秒；需要固定时刻执行时再使用 Cron。
RPC 写入	外部系统反写点位。只有控制类点位、且现场允许远程控制时才建议开启。
目标变量属性	某个转发目标对单个变量的外部映射，例如外部字段名、Modbus 从站地址、采样策略或写入权限。
StreamAsync	串口异步读写方式。串口稳定时保持默认，遇到阻塞或读取不及时再结合驱动要求调整。
DTU ID / DtuId	DTU 或透传终端编号，用于区分哪台远端设备正在接入。
Broker	MQTT、Kafka、RabbitMQ 等消息系统的服务端，现场可理解为“消息中转服务器”。
Topic / Routing Key / URL	外部系统接收数据的位置、主题或请求地址，必须和对方系统约定一致。
Payload	消息正文，也就是实际发送的数据内容。

使用顺序

1. 先选择插件，确认通道或目标的连接方式。
2. 再填写插件属性，完成连接、认证、超时、缓存和上传格式等配置。
3. 最后维护变量属性（单个变量在采集或转发目标下的地址、写入权限等映射），配置变量地址、写入权限、采样策略或自定义字段。

现场查找方法

现场配置时不要从本文开头一路读到结尾。先按项目要接入的协议或外部系统定位插件，再核对对应的地址格式、插件属性和变量属性。

现场问题	优先查看
PLC 或仪表读不到数据	对应采集插件的“地址格式”和“插件属性”。
数值明显不对	数据类型、数据解析顺序、字符串长度、BCD、字节序转换参数。
多台设备共用一个通道	站号、从站地址、DTU ID、通道连接方式和打包长度。
外部系统收不到数据	对应数据转发插件的连接参数、Topic/URL/表名、上传模板和缓存设置。
外部系统要反写控制	目标级和变量级 允许 RPC 写入，以及现场控制权限。
需要历史追溯	历史数据目标、历史报警目标、采样策略、保留天数和离线缓存。

配置前应先准备设备手册、点表、通讯参数、上位系统接口说明和安全边界。无法确定字节序或地址格式时，先用 设备调试 单点读取验证，再批量导入点表。

当前版本完整属性核对

本节按当前运行时实际暴露的插件属性核对。现场阅读时先看“公共属性组”，再到“插件核对表”确认某个插件是否还有专属字段；如果表中写“无页面插件属性”，表示该插件没有额外插件属性，仍然需要维护设备名称、执行间隔、变量地址等基础配置。

数据转发组属性

数据转发组不是插件，但它决定变量是否进入转发链路。变量有值却没有转发时，应先核对本表。

配置项	现场说明
名称	转发组显示名称，同一系统内应保持唯一，建议体现业务范围，例如 MES_关键点位。
描述	记录该组用途、对接系统、验收人或维护边界。
启用	关闭后，组内所有目标都不会运行。
日志级别	组日志详细程度。联调可临时用 Debug 或 Trace，稳定后调回 Info。
排序	页面显示顺序，数值越小越靠前。
变量范围模式	决定变量来源。Manual 为手动选择，All 为全部变量，CollectDevice 按设备筛选，CollectGroup 按采集组筛选。
范围配置	CollectDevice 时填写设备名称，CollectGroup 时填写采集组名称，多个值用英文逗号分隔。
触发模式	Change 按变化触发，Interval 按定时触发，IntervalOrChange 变化和定时都触发。
定时转发间隔	定时触发时使用。普通周期优先填毫秒数，例如 1000；固定时刻再使用 Cron 表达式。
仅在线变量	开启后离线变量不会进入转发。现场要保留离线前最后值时不要开启。
批处理模式	决定一次触发后如何拆批，例如不拆批、按数据组拆批。
最大批量	单次批处理最大变量数。外部接口超时或消息体过大时调小。

组变量属性只影响“变量在本组内如何参与转发”，不等于目标变量属性。

配置项	现场说明
变量	当前转发组包含的变量。手动范围下必须先加入这里，目标变量属性才会生效。
启用	关闭后该变量不参与本组转发。
数据组	用于按业务单元拆批，例如产线、区域、设备组。
更新模式	单变量触发方式，可覆盖组级触发模式。
参与组触发	关闭后该变量仍可随批次上传，但它自己的变化不会唤醒整组。
别名	上传时使用的外部变量名。为空时通常使用原变量名称。
排序	本组内变量输出顺序。

采集公共属性组

属性组	包含属性	现场说明
采集重试	失败重试次数、读写占空比、写优先	适用的采集插件会显示这些字段。失败重试用于偶发超时重试；读写占空比控制写入较多时穿插读取；写优先用于控制指令需要更快下发的场景。
Foundation 通用读写	读写超时时间、帧前时间、字符串反转字节、数据解析顺序	适用于按地址读写的驱动。超时和帧前时间解决慢设备或串口间隔问题；字符串反转和数据解析顺序用于修正字节序。
打包读取	最大打包长度	控制一次合并读取的最大地址长度。点位多时可提高效率，设备不支持大包时调小。
Modbus 打包规则	FC1/FC2/FC3/FC4 最大读取数量、FC15/FC16 最大批量写入数量	仅用于 Modbus 主站。按实际功能码分别限制每帧位或寄存器数量，替代旧的单一“最大打包长度”。
DTU	DTU ID	通过 DTU 或透传终端接入时填写终端编号；直连设备通常留空。

采集插件核对表

插件	已确认属性
Memory	无页面插件属性。只维护内存变量本身，不需要通讯链路属性。
Modbus 主站	采集重试、Foundation 通用读写、Modbus 打包规则、DTU；专属属性：Modbus类型用于选择 TCP/RTU 等协议形态，默认站号为从站地址，可被变量地址中的站号覆盖。
Siemens S7	采集重试、Foundation 通用读写、打包读取；专属属性：PLC类型选择 S200/S300/S400/S1200/S1500 等型号，Rack/Slot 按 PLC 机架槽号填写，LocalTSAP 仅在现场指定 TSAP 时填写。
DLT645-2007	采集重试、Foundation 通用读写、DTU；专属属性：默认地址为 12 位表地址，密码和操作员代码用于写表或特殊读取，前导符报文头默认 FEFEFEFE。
OPC UA 客户端	采集重试；专属属性：连接Url、登录账号、登录密码、数据变化触发条件、安全策略、名称标识、证书、是否使用SourceTime、加载服务端数据类型、激活订阅、更新频率、死区、最大组大小、心跳频率。
OPC DA 客户端	采集重试；专属属性：OPC服务器IP、OPC服务器名称、服务端时间、订阅模式、检测重连频率、死区、最大组大小、订阅更新频率。远程 DA 还要确认 DCOM 权限。
MQTT 采集客户端	连接类型、IP地址、端口、WebSocket路径、启用SSL、SSL目标主机名、客户端证书名称、CA名称、允许不受信任证书、SSL协议版本、检查证书吊销、客户端ID、用户名、密码、保活时间、清除会话、MQTT协议版本、QoS等级、详细日志、连接超时时间、检查清除时间。
MQTT 采集服务端	连接类型、端口、WebSocket路径、启用SSL、服务器证书名称、CA名称、允许不受信任证书、SSL协议版本、检查证书吊销、允许连接ID前缀、用户名、密码、详细日志、检查清除时间。
Gateway MQTT 专用采集客户端	固定 Topic 根、远程写入、快照/请求/离线超时、来源/目录/RPC/载荷/速率/并发边界；共享 Broker 连接和多个 RemoteKey 来源。
Gateway MQTT 专用采集服务端	与专用 Client 相同的协议边界；单监听、服务端证书，以及每来源精确 ClientId、独立账号和可选证书指纹。
CAN 主站	采集重试、Foundation 通用读写；专属属性：端点地址选择 CAN 适配器和通道，波特率为仲裁段速率，数据相位波特率只对 CAN FD 有效，协议模式选择 CAN2.0/CAN FD，启用BRS 控制数据段变速率，内部终端电阻按总线接线选择，硬件滤波器CANID列表用于只接收指定 CAN ID。
Allen-Bradley ControlLogix	采集重试、Foundation 通用读写、打包读取；专属属性：Slot 为 CPU 槽号，Backplane 表示是否通过背板寻址。
Allen-Bradley PCCC	采集重试、Foundation 通用读写、打包读取；无其它页面插件属性，重点核对变量地址格式。
DCON 主站	采集重试、Foundation 通用读写、打包读取、DTU；专属属性：Station 为 DCON 站号。
HJ212 主站	采集重试、Foundation 通用读写；无其它页面插件属性，重点核对地址格式和链路参数。
汇川 Inovance	采集重试、Foundation 通用读写、打包读取、DTU；专属属性：ModbusType 选择底层 Modbus 方式，InovanceType 选择汇川协议或设备类型，Station 为站号。
KELID2008	采集重试、Foundation 通用读写；无其它页面插件属性。
三菱 1E	采集重试、Foundation 通用读写、打包读取；专属属性：PLCID 按三菱 1E 通讯配置填写。
三菱 3E	采集重试、Foundation 通用读写、打包读取；专属属性：NetWorkID、IOModuleStation、IOModuleID、PLCID 按三菱网络号、站号、模块号和 PLC 编号填写。
ModbusC1	采集重试、Foundation 通用读写、打包读取、DTU；专属属性：ModbusType 选择协议形态，Station 为站号。
ModbusC20	采集重试、Foundation 通用读写、打包读取、DTU；专属属性：ModbusType 选择协议形态，Station 为站号。
Omron FINS	采集重试、Foundation 通用读写、打包读取；专属属性：ICF、GCT、DNA、DA2、SNA、SA2、SID 为 FINS 帧寻址字段，需与欧姆龙网络配置一致。
SECS	采集重试、Foundation 通用读写、打包读取；专属属性：DeviceID 为 SECS 设备标识。
TIANXIN	采集重试、Foundation 通用读写、打包读取、DTU；专属属性：Station 为站号。
TS550	采集重试、Foundation 通用读写；无其它页面插件属性。
Vigor	采集重试、Foundation 通用读写、打包读取、DTU；专属属性：Station 为站号。
IEC 61850 客户端	采集重试；专属属性：IED IP地址、IED 端口、ConnectTimeout（连接超时 ms）、最大打包数量、UpdateRate（更新频率 ms）、SCL 配置文件路径、启用 RCB 报告订阅、RCB 报告 ID、RCB 引用列表、ReportBufTime、ReportIntgPd、RCB TrgOps、RCB OptFlds、RCB单请求写入、ReportReservationTimeSeconds（BRCB预留时间秒）、BRCB清空缓冲、启用 GOOSE 订阅、GOOSE 控制块引用、GOOSE 网络接口 ID、GOOSE APP-ID、使用 URCB（非缓冲报告）、IED 认证密码、RequestTimeout（请求超时 ms）、最大 PDU 大小、启用 TLS 加密连接、TLS 客户端证书、TLS CA 证书、TLS 链式验证、TLS 仅允许已知证书、SOE事件记录配置。变量辅助属性包含对象引用（辅助）、功能约束（辅助）和允许写入，主要由导入或模型生成使用。
OPC AE	采集重试；专属属性：OpcAeUrl 为 AE 服务连接地址，CheckRate 为检测重连周期。
ZeroMQ 采集客户端	连接地址、Socket 类型、绑定模式、订阅主题前缀、高水位标记、详细日志、检查清除时间。
EDPF_NT	无页面插件属性。
LKSIS	无页面插件属性。
USBScaner	无页面插件属性。

数据转发目标公共属性组

属性组	包含属性	现场说明
目标基础属性	名称、描述、启用、插件名称、日志级别、启动超时、启用冗余、冗余目标、冗余模式、冗余扫描间隔、冗余切换判断脚本	所有转发目标都有。目标未启用或启动超时会导致不发送；冗余只在主备目标明确时使用。
离线缓存	启用离线缓存、缓存文件最大行数、上传分片大小、内存队列上限、过滤离线数据、并发上传数量	外部系统短时不可用时用于补发。关键历史、报警和平台上传建议开启；实时性和顺序要求高时谨慎调大并发。
模板与脚本	详细日志、JSON缩进格式化、JSON忽略Null、设备列表上传、变量列表上传、变量字典上传、报警列表上传、报警字典上传、插件事件列表上传、设备Topic模板、变量Topic模板、报警Topic模板、插件事件Topic模板、设备实体脚本、变量实体脚本、报警实体脚本、插件事件实体脚本、上传模板配置	MQTT、Kafka、RabbitMQ、Webhook、ZeroMQ 等通用上传目标使用。Topic 决定发往哪里，实体脚本和上传模板决定发什么内容。
通道型目标	通道类型、远程地址、本地绑定地址、启用SSL、SSL目标主机名、SSL客户端证书、SSL服务端证书、SSL CA证书、允许不受信任证书、SSL协议、检查证书吊销、串口、波特率、数据位、校验位、停止位、DtrEnable、RtsEnable、异步流、握手方式、串口输入缓冲区大小、串口输出缓冲区大小、最大并发数、组包缓存时间、连接超时、最大连接数、客户端清理时间、心跳内容、心跳是否Hex、心跳时间、DtuId、DtuId是否Hex、Dtu服务类型	Modbus 从站、IEC104 从站等需要监听或连接 TCP/串口/DTU 的目标使用。服务端模式重点核对本地绑定地址和防火墙。
MQTT 生产者公共项	连接类型、端口、WebSocket路径、启用SSL、CA名称、允许不受信任证书、SSL协议版本、检查证书吊销、用户名、密码、QoS等级、保留消息、RPC写入Topic、历史查询Topic、数据请求Topic、RPC脚本	MQTT 客户端生产者和 MQTT 服务端生产者共用。历史查询 Topic 默认 RpcHistory，用于受限的历史记录、数值序列和报警 RPC。
通用变量属性	数据1、数据2、数据3、数据4、数据5、数据6、数据7、数据8、数据9、数据10	单个变量在某个目标下的自定义字段，可用于 Topic、Routing Key、URL 或上传模板。

数据转发目标插件核对表

目标插件	已确认目标属性	已确认目标变量属性
Modbus 从站	目标基础属性、通道型目标；专属属性：Modbus类型、默认站号、数据解析顺序、字符串反转字节、多站点模式、允许 RPC 写入、立即写入内存、发送延时时间、客户端权限列表。	从站变量地址、数据类型、允许 RPC 写入。
MQTT 客户端生产者	目标基础属性、离线缓存、模板与脚本、MQTT 生产者公共项；专属属性：IP地址、SSL目标主机名、客户端证书名称、客户端ID、保活时间、清除会话、MQTT协议版本。	数据1、数据2、数据3、数据4、数据5、数据6、数据7、数据8、数据9、数据10、允许RPC写入。
MQTT 服务端生产者	目标基础属性、离线缓存、模板与脚本、MQTT 生产者公共项；专属属性：服务器证书名称、允许连接ID前缀。	数据1、数据2、数据3、数据4、数据5、数据6、数据7、数据8、数据9、数据10、允许RPC写入。
ThingsBoard 客户端生产者	目标基础属性、离线缓存；专属属性：连接类型、IP地址、端口、WebSocket路径、启用SSL、SSL目标主机名、客户端证书名称、CA名称、允许不受信任证书、SSL协议版本、检查证书吊销、客户端ID、用户名、密码、保活时间、清除会话、MQTT协议版本、QoS等级、保留消息、详细日志。	允许RPC写入。
OPC UA 服务端	目标基础属性；专属属性：服务地址、名称标识、安全策略、允许RPC写入、用户名、密码、服务端证书名称。	数据类型、允许RPC写入。
Kafka 生产者	目标基础属性、离线缓存、模板与脚本；专属属性：服务地址、发布超时时间、用户名、密码、安全协议、SASL机制。	数据1、数据2、数据3、数据4、数据5、数据6、数据7、数据8、数据9、数据10。
RabbitMQ 生产者	目标基础属性、离线缓存、模板与脚本；专属属性：IP地址、端口、用户名、密码、声明队列、声明交换机、启用发布确认、要求路由成功、交换机类型、发布超时时间、虚拟主机、交换机名称。	数据1、数据2、数据3、数据4、数据5、数据6、数据7、数据8、数据9、数据10。
历史数据目标	目标基础属性、离线缓存；专属属性：数据库类型、自定义SQL模式、分表策略、连接字符串、数值历史表名、字符串历史表名、保留天数、历史表脚本、时区偏移、强制插入、默认采样策略、默认采样间隔、默认条件表达式、自定义模板配置、双库镜像。	采样策略、采样间隔、条件表达式。
实时数据目标	目标基础属性、离线缓存；专属属性：数据库类型、连接字符串、实时表名、实时表脚本、时区偏移。	无页面目标变量属性。
历史报警目标	目标基础属性、离线缓存；专属属性：数据库类型、分表策略、连接字符串、历史报警表名、保留天数、历史报警表脚本、时区偏移、最小报警等级、双库镜像。	无页面目标变量属性。
Webhook	目标基础属性、离线缓存、模板与脚本；专属属性：签名密钥、自定义请求头、消息格式、Timeout（请求超时秒）。Webhook 的变量 Topic 模板就是请求 URL。	数据1、数据2、数据3、数据4、数据5、数据6、数据7、数据8、数据9、数据10。
SyncBridge	目标基础属性；专属属性：Role、LocalPeerId、ListenUri、RemoteUri、VerifyToken、传输证书、CA、目标主机、TLS、认证心跳、实时批量/Ack、配置块、自动同步策略、Hub 同步并发和远程 RPC 开关。	无页面目标变量属性。
IEC104 从站	目标基础属性、通道型目标；专属属性：IsWithTimeInfo、Station、DeviceRpcEnable、SendDelayTime。	StartAddress、DataType、VariableRpcEnable。
IEC 61850 服务端	目标基础属性；专属属性：IED 名称、IED 端口、厂商名称、允许写入、CallbackResultTimeoutMs（回调超时 ms）、SCL 配置文件路径、GOOSE 网卡接口、启用 GOOSE 发布、报告DataSet名称、URCB名称、BRCB名称、报告ConfRev、报告TrgOps、报告OptFlds、报告BufTime、报告IntgPd、GOOSEDataSet名称、GOOSE控制块名称、GOOSE控制块AppID、GOOSEConfRev、GOOSE固定偏移、GOOSE最小时间、GOOSE最大时间、GOOSE VLAN优先级、GOOSE VLAN ID、GOOSE APPID、GOOSE目标MAC、SOE事件记录配置、IEC 61850 版本、最大连接数、启用动态数据集、启用文件服务、启用日志服务、报告缓冲区大小、BRCB包含ResvTms、RCB包含Owner、文件服务路径、启用 TLS 加密连接、TLS 服务器证书、TLS CA 证书、TLS 链式验证、TLS 仅允许已知证书。	对象引用、数据类型、允许写入、控制模型、GOOSE 发布。
ZeroMQ 生产者	目标基础属性、离线缓存、模板与脚本；专属属性：连接地址、Socket类型、绑定模式、高水位标记。	数据1、数据2、数据3、数据4、数据5、数据6、数据7、数据8、数据9、数据10。

地址数据转换参数

部分采集插件直接读取设备的原始字节。此时可在变量地址后使用分号（;）追加转换参数，用来指定字节顺序、字符串长度或编码方式。同一台设备下，不同变量可以使用不同的转换参数。

适用范围

这些转换参数主要用于 Modbus 主站、Siemens S7、DLT645-2007 等按字节解析数据的采集插件。OPC UA、OPC DA、MQTT 等插件通常由服务端或消息内容直接提供数据，不需要在地址里追加这些字节解析参数。

通用转换参数

参数	写法	使用说明
数据格式	data=ABCD、data=BADC、data=CDAB、data=DCBA	用于 4 字节数值的字节顺序。浮点数读出来特别大、特别小或正负异常时，优先检查此项。
字符串长度	len=N	字符串变量必须指定读取字节数，例如 len=10。未指定长度时，字符串读写容易失败或读到多余内容。
BCD 格式	bcd=C8421、bcd=C5421、bcd=C2421、bcd=C3、bcd=Gray	设备使用 BCD 编码时填写。电表、仪表类设备读数不符合预期时，应按设备协议确认 BCD 格式。
字符编码	encoding=UTF-8、encoding=ASCII、encoding=Default、encoding=Unicode	字符串出现乱码时填写。应与设备实际编码一致。
变长字符串	vsl=true	用于带长度头的字符串，常见于 S7 字符串。启用后仍需配合 len=N 指定最大长度。

示例

• 40001;data=CDAB：读取 Modbus 保持寄存器，并按小端字节交换解析。
• 40001;len=10;encoding=UTF-8：读取 10 字节 UTF-8 字符串。
• 40001;bcd=C8421：按 BCD 8421 编码解析读数。
• DB1.DBW0;vsl=true;len=20：读取 S7 数据块中的变长字符串，最大 20 字节。

插件特有地址参数

插件	参数	写法	使用说明
Modbus 主站	站号	s=N	覆盖插件属性中的默认站号。一个通道下存在多个从站时，可在变量地址中单独指定。
Modbus 主站	写入功能码	w=6 或 w=16	指定写保持寄存器时使用单寄存器写入还是多寄存器写入。写入失败或设备只支持其中一种功能码时使用。
Modbus 主站	读取功能码	f=N	直接指定读取功能码。只有现场协议对地址区和功能码有特殊约定时使用。
Modbus 主站	位索引	.N	读取寄存器中的某一位，例如 40001.3。适合一个寄存器内拆分多个状态位。
Siemens S7	宽字符串	W=true	按 WString/Unicode 字符串解析。普通字符串乱码或长度不对时，按 PLC 字符串类型确认是否需要开启。

采集插件

采集插件用于从 PLC、仪表、OPC 服务、MQTT Broker 等外部设备或系统读取数据。

Modbus 主站

地址格式

地址范围	寄存器	读写用途	示例
00001~09999	线圈	可读可写	00001
10001~19999	离散输入	只读	10001
30001~39999	输入寄存器	只读	30001
40001~49999	保持寄存器	可读可写	40001

插件属性

配置项	默认值	填写说明
Modbus 类型	按页面选择	ModbusTcp 用于以太网 Modbus TCP；ModbusRtu 用于串口 RTU。选错后通常表现为连接失败、超时或报文无响应。
默认站号	1	从站地址。一个通道只连接一台设备时填写设备站号；同一通道下多个站号可在变量地址中用 s=N 覆盖。
FC1 最大读取线圈位数量	1600	单次 FC1 请求最多读取的线圈位数量，范围 1～2000。
FC2 最大读取离散输入位数量	1600	单次 FC2 请求最多读取的离散输入位数量，范围 1～2000。
FC3 最大读取保持寄存器数量	100	单次 FC3 请求最多读取的保持寄存器数量，范围 1～125。
FC4 最大读取输入寄存器数量	100	单次 FC4 请求最多读取的输入寄存器数量，范围 1～125。
FC15 最大批量写入线圈位数量	1968	单次 FC15 请求最多写入的线圈位数量，范围 1～1968。
FC16 最大批量写入寄存器数量	123	单次 FC16 请求最多写入的寄存器数量，范围 1～123。
读写超时时间	3000 毫秒	单次读写等待时间。串口、无线或远程网络较慢时可增大；过大则故障响应变慢。
帧前时间	0 毫秒	发送报文前等待时间。部分串口转换器或老设备需要报文间隔时设置。
字符串反转字节	关闭	字符串按字反转。字符串内容相邻两个字符颠倒时尝试开启。
数据解析顺序	按现场选择	数值字节序。浮点数或整数读值异常时调整。
DTU ID	留空	通过 DTU/透传设备接入且需要按终端 ID 区分设备时填写；直连设备通常留空。
失败重试次数	3	单次读写失败后的重试次数。网络偶发抖动可适当增大，长期故障不宜设置过高。
读写占空比	3	写入任务较多时，执行若干次写入后穿插读取，避免长时间只写不读。控制指令密集时可按现场节奏调整。
写优先	关闭	开启后有写入任务时优先下发写入。适合控制指令要求更快响应的场景；普通采集保持关闭即可。

升级检查

Modbus 主站已删除旧 MaxPack（最大打包长度）字段。升级后请逐个打开 Modbus 主站设备并检查以上六项规则，不要假设旧值会自动映射。单个变量的读取长度或一次批量写入数量超过对应上限时，系统会在构造报文前返回校验错误；现场设备支持量小于协议上限时，应按设备手册继续调低。

Siemens S7

地址格式

前缀	区域	示例	使用说明
I	输入区	I0.0、IB0、IW0、ID0	读取输入点、输入字节、输入字或输入双字。
Q	输出区	Q0.0、QB0、QW0、QD0	读取或写入输出区。
M	中间存储区	M0.0、MB0、MW0、MD0	读取或写入 M 区。
DB	数据块	DB1.DBX0.0、DB1.DBB0、DB1.DBW0、DB1.DBD0	按 DB号.地址 填写。
AI	模拟输入	AI0、AIW0	读取模拟输入。
AQ	模拟输出	AQ0、AQW0	读取或写入模拟输出。
T	定时器	T0	读取定时器。
C	计数器	C0	读取计数器。
V	S200 V 区	V0、VB0、VW0、VD0	S200 常用地址区。

S7 字符串应按 PLC 中实际定义填写：固定长度字符串使用 len=N；带长度头的字符串使用 vsl=true;len=N；宽字符串使用 W=true。

插件属性

配置项	默认值	填写说明
PLC 类型	按页面选择	选择 S200、S200Smart、S300、S400、S1200 或 S1500。型号选错时，连接或地址解析可能失败。
Rack	0	机架号。S7-1200/1500 通常为 0；S7-300/400 按实际硬件配置填写。
Slot	0	槽号。现场常见 S7-300 CPU 在 2，S7-1200/1500 常为 0 或按设备配置填写。连接不上时优先核对 Rack/Slot。
LocalTSAP	0	本地 TSAP。普通连接保持默认；现场要求指定 TSAP 或使用特殊网关时按 PLC 通信配置填写。
最大打包长度	200	单次合并读取长度。点位多时可提高效率；读写超时或 PLC 拒绝请求时调小。
读写超时时间	3000 毫秒	单次请求等待时间。跨网段、VPN 或网络质量差时可适当增大。
帧前时间	0 毫秒	发送请求前等待时间。普通以太网连接保持默认。
字符串反转字节	关闭	字符串字节顺序异常时使用。
数据解析顺序	按现场选择	数值字节序。数值读错但地址正确时调整。
失败重试次数	3	通信失败后的重试次数。
读写占空比	3	写入任务较多时控制读写穿插节奏。
写优先	关闭	控制指令需要优先下发时开启。

DLT645-2007

地址格式

DLT645-2007 使用 8 位十六进制数据标识作为变量地址。需要指定电表地址时，在地址后追加 s=12位表地址。

示例	说明
02010100	A 相电压。
02020100	A 相电流。
02030000	瞬时总有功功率。
00000000	当前组合有功总电能。
00010000	当前正向有功总电能。
02010100;s=111111111111	读取指定 12 位表地址的 A 相电压。

插件属性

配置项	默认值	填写说明
默认地址	111111111111	默认电表地址。只接一块表时可在此填写；多块表共用通道时，可在变量地址中用 s=... 覆盖。
密码	留空	电表写入或特殊读取需要密码时填写；普通读取通常留空。
操作员代码	留空	电表要求操作员代码时填写。
前导符报文头	FEFEFEFE	DLT645 报文前导符。大多数电表保持默认；报文解析异常时按电表说明书确认。
读写超时时间	3000 毫秒	读表等待时间。红外、无线或串口链路较慢时可增大。
帧前时间	0 毫秒	报文发送前等待时间。
字符串反转字节	关闭	字符串类数据解析异常时使用。
数据解析顺序	按现场选择	数值字节序。
DTU ID	留空	通过 DTU 区分终端时填写。
失败重试次数	3	读表失败后的重试次数。
读写占空比	3	有写入任务时的读写穿插节奏。
写优先	关闭	写入电表参数需要优先执行时开启。

OPC UA 客户端

地址格式

OPC UA 变量地址填写服务端节点标识，例如：

• ns=2;s=Channel1.Device1.Tag1
• ns=2;i=1001

插件属性

配置项	默认值	填写说明
连接 Url	opc.tcp://127.0.0.1:49320	OPC UA 服务地址。应填写服务端实际暴露的 opc.tcp://主机:端口。
登录账号	留空	服务端要求用户名认证时填写。匿名访问时留空。
登录密码	留空	与登录账号配套填写。
数据变化触发条件	StatusValue	订阅变化的触发条件。通常保持默认；若只关心状态或时间戳变化，按服务端要求调整。
安全策略	关闭	开启后使用安全连接，通常需要客户端证书并在服务端信任。证书未被信任时连接会失败。
名称标识	ThingsGateway_OPC_UA_Master	客户端应用名称，服务端审计和证书信任列表中会显示该名称。
证书	留空	启用安全策略或服务端要求客户端证书时，从证书管理中选择。
是否使用 SourceTime	开启	开启后变量时间使用 OPC UA 服务端时间；关闭后使用网关接收时间。服务端时间不准时建议关闭。
加载服务端数据类型	开启	连接后读取服务端节点数据类型，便于变量类型匹配。点位非常多导致首次连接慢时，可在确认类型配置正确后关闭。
激活订阅	开启	开启后通过订阅接收变化；关闭后按采集周期主动读取。服务端订阅能力差或订阅不稳定时可关闭。
更新频率	1000 毫秒	订阅更新间隔。越小响应越快，服务端压力越高。
死区	0	模拟量变化死区百分比。数值小幅波动频繁上报时可设置，减少无意义变化。
最大组大小	500	单个订阅组的最大节点数。点位多时用于拆分订阅，服务端拒绝大订阅时调小。
心跳频率	3000 毫秒	与服务端保持会话的心跳间隔。网络不稳定时可适当增大。
失败重试次数	3	读写失败后的重试次数。
读写占空比	3	写入较多时控制读写穿插节奏。
写优先	关闭	写入指令需要优先处理时开启。

OPC DA 客户端

地址格式

OPC DA 变量地址填写服务端项名称，例如：

• Channel1.Device1.Group1.Tag1

插件属性

配置项	默认值	填写说明
OPC 服务器 IP	localhost	OPC DA 服务所在主机。远程访问时填写服务器 IP 或主机名，并确认 DCOM 权限。
OPC 服务器名称	Kepware.KEPServerEX.V6	OPC DA Server 的 ProgID。必须与服务器上注册的名称一致。
服务端时间	开启	开启后使用 OPC DA 服务端时间戳；服务端时间不可靠时关闭。
订阅模式	开启	开启后使用 OPC 订阅获取变化；关闭后按采集周期读取。
检测重连频率	10 分钟	定期检查并重连的间隔。服务端经常断开时可适当缩短。
死区	0	订阅死区百分比。模拟量微小波动很多时使用。
最大组大小	500	单个订阅组最大项数。服务端无法承载大组时调小。
订阅更新频率	1000 毫秒	订阅刷新间隔。越小实时性越高，服务端压力越大。
失败重试次数	3	读写失败后的重试次数。
读写占空比	3	写入较多时控制读写穿插节奏。
写优先	关闭	写入指令需要优先处理时开启。

运行环境

OPC DA 依赖 Windows COM/DCOM。远程访问时，需要同时确认 Windows 防火墙、DCOM 权限、账号权限和 OPC Server 注册信息。

MQTT 采集客户端

配置入口

在“采集配置”中新增或编辑 MQTT 采集客户端设备，然后为设备新增变量，在变量地址中填写 Topic、字段路径和可选条件脚本。条件脚本需要先在“开发配置 → 脚本管理”中创建为“数据转换”脚本并编译成功。

地址格式

MQTT 采集客户端既可以从 Broker 订阅遥测消息，也可以向设备发布控制命令。变量地址使用以下固定顺序的八段格式：

订阅主题;JSONPath1||JSONPath2;条件脚本;发布主题;载荷模式;Retain;RPC响应主题;RPC超时毫秒

段	使用说明
订阅主题	遥测 MQTT Topic。可填写精确主题或 MQTT 通配主题；与 JSONPath 必须同时填写或同时留空。
JSONPath	Payload 中的单值字段路径。多个候选路径使用 `
条件脚本	可选的已编译数据转换脚本；脚本返回 true 时才更新变量。
发布主题	设备控制 Topic，不能使用 +、#。留空时变量不支持 MQTT 控制发布。
载荷模式	Json 或 RawString。省略时为 Json；仅在发布主题存在时填写。
Retain	true 或 false，省略时为 false。瞬时命令应保持 false。
RPC 响应主题	可选。与 RPC 超时毫秒成对填写后，网关等待设备确认。
RPC 超时毫秒	100 至 60000 的整数；仅在填写响应主题时填写。

只读变量可以继续使用前三段，例如 vendor/device;$.data.temperature;TelemetryCondition。只写变量可将前三段留空，例如 ;;;factory/a/reboot;RawString;false。同时读取和写入的变量示例为：

factory/a/status;$.power;;factory/a/command;Json;false

控制写入

在变量编辑器中选择 MQTT Collect 设备后，地址区域会显示“遥测读取”“控制写入”和“RPC 回执”三个区域。发布主题为空时，载荷模式、Retain 和回执配置不会保存。切换为只读或只写权限时，系统会清除不再允许的控制或遥测字段。QoS 由设备属性统一控制，不在变量上单独配置。

载荷模式	写入表达式结果	发送内容
Json	任意合法 JSON 值	保持 JSON 原始文本并按 UTF-8 发布。对象、数组、数字和布尔值均可使用。
RawString	JSON 字符串	取字符串内容并按 UTF-8 发布。例如写入表达式返回 "REBOOT" 时，设备收到 REBOOT。

RawString 不接受数字、布尔、对象、数组或 null。需要把页面值映射为设备命令时，应在变量的写入表达式中返回字符串。发布成功只表示 MQTT 客户端或网关 Broker 已接受该消息，不会修改变量当前值；变量值仍由后续遥测消息更新。

RPC 回执

需要设备确认时，在发布主题和响应主题的最后一个层级各填写一次 {RequestId}，例如：

发布主题：factory/a/command/{RequestId}
响应主题：factory/a/response/{RequestId}

网关为每次写入生成 32 位小写请求标识。设备从请求 Topic 最后一层取得该标识，并在超时前向对应响应 Topic 发布以下 JSON：

{
  "success": true,
  "message": "optional diagnostic text"
}

success 必须为 JSON Boolean。true 时变量写入显示设备确认成功；false 时显示 message 或固定失败原因。响应不需要在 JSON 中重复 requestId，网关以实际响应 Topic 精确关联。保留消息、错误响应 Topic、无效 JSON 或缺少合法 success 的消息不会完成写入等待。客户端会在确认响应 Topic 订阅成功后才发布需要确认的命令；超时、断线、服务停止或变量路由重载会明确返回失败，不会重发控制命令。重载在实际发布前发生时，不会向旧 Topic 发送命令；重载后才到达的旧响应不会影响新配置。

以下 Payload 用于说明路径写法：

{
  "data": {
    "items": [
      { "value": 12.5 },
      { "value": 18.2 }
    ],
    "temperature": 31
  },
  "a.b": "special"
}

变量地址	结果或用途
vendor/device;data.temperature	结果为 31，可以省略根符号 $。
vendor/device;$.data.temperature	结果为 31。
vendor/device;$.data.items[0].value	结果为 12.5，使用括号数组下标。
vendor/device;data.items.1.value	结果为 18.2，数组下标也可以使用点号形式。
vendor/device;$['a.b']	结果为 "special"，属性名包含 . 时使用括号属性。
`vendor/device;$.data.temperature
`vendor/device;$.data.temperature

字段路径规则

规则	说明
根节点	$ 表示完整 Payload JSON 根节点；普通路径可以省略 $。
对象属性	使用 data.temperature 或 $.data.temperature。
数组下标	支持 items[0].value 和 items.0.value。下标必须是大于或等于 0 的整数。
特殊属性名	属性名包含 . 或 `
大小写	先按属性名精确匹配；精确名称不存在时，才使用唯一的忽略大小写匹配。若 Payload 同时包含 Temperature 和 temperature，路径 TEMPERATURE 因匹配不唯一而不会更新。
候选字段	使用 `路径1
字段缺失	字段不存在、数组越界或路径格式错误时跳过本次变量更新，保留变量原值。
JSON 空值	Payload 中明确存在的 null 属于有效字段，会按空值更新；它与字段不存在不同。

当前路径用于把一条 MQTT 消息映射到一个变量，因此不支持数组通配符 [*]、递归选择 ..、过滤表达式 [?()] 或一次返回多个节点的路径。

条件脚本

条件是“数据转换”脚本，脚本的 raw 参数为完整 Payload JSON。配置步骤如下：

1. 打开“开发配置 → 脚本管理”，新增“数据转换”脚本。
2. 在脚本编辑器的“输入参数”中按需新增 Topic 或 MqttTopic，数据类型选择“字符串”。
3. 编写返回布尔值的脚本并点击“编译并保存”。
4. 把脚本名称填写到变量地址第三段，例如 vendor/device;$.data.temperature;TelemetryCondition。

以下示例要求消息来自指定实际 Topic，并且 Payload 类型为 telemetry：

var payload = (System.Text.Json.JsonElement)raw;

return Topic == "devices/device-01/up"
    && payload.TryGetProperty("type", out var type)
    && type.GetString() == "telemetry";

条件脚本按以下规则执行：

• raw 始终是完整 Payload JSON，不是变量字段路径选中的单个值。
• Topic 和 MqttTopic 输入参数获得消息实际发布 Topic。例如变量配置为 devices/+/up 时，脚本中可以得到 devices/device-01/up。
• 同一条消息中，同名条件脚本只执行一次，多个变量可以共用同一个条件。
• 条件返回 false、脚本名称不存在、脚本抛出异常或返回值无法转换为布尔值时，本次消息不会更新相关变量，并记录警告日志。

发布客户端 ID

MQTT Broker 转发给订阅客户端的消息不包含原发布者 ClientId，因此 MQTT 采集客户端条件脚本无法读取发布者 ClientId。即使声明 ClientId 或 MqttClientId 输入参数，也只能得到空字符串；不要把采集客户端自身的 ClientId 当作发布者身份。

通配 Topic

devices/+/up;$.data.temperature 会让所有匹配设备的消息更新同一个变量。需要按设备分别保存变量时，请为每台设备配置精确 Topic；只需要过滤部分设备时，也可以在条件脚本中读取实际 Topic 后返回 true 或 false。

插件属性

配置项	默认值	填写说明
连接类型	Tcp	普通 MQTT 使用 Tcp；Broker 提供 WebSocket 接入时选择 WebSocket。
IP 地址	localhost	Broker 地址，可填写 IP 或域名。
端口	1883	Broker 端口。TLS 常见端口为 8883，以 Broker 配置为准。
WebSocket 路径	/mqtt	仅 WebSocket 连接使用，必须与 Broker 路径一致。
启用 SSL	关闭	Broker 要求 TLS/WSS 时开启。开启后应继续确认目标主机名、证书和 CA。
SSL 目标主机名	留空	校验证书时使用的主机名。用 IP 连接但证书签发给域名时，填写证书中的域名。
客户端证书名称	留空	Broker 要求双向 TLS 时，从证书管理中选择客户端证书。
CA 名称	留空	需要校验 Broker 服务端证书时选择 CA 证书。
允许不受信任证书	开启	自签名证书联调时可临时开启；生产环境建议关闭。关闭后证书不受信任会导致连接失败。
SSL 协议版本	None	通常保持默认；TLS 握手失败或平台指定版本时再调整。
检查证书吊销	关闭	对证书吊销有合规要求时开启。开启后网络无法访问吊销列表可能导致连接失败。
客户端 ID	留空	Broker 需要固定 ClientId 或保留会话时填写。留空时由系统生成或按连接库规则处理。
用户名	留空	Broker 启用账号认证时填写。
密码	留空	与用户名配套填写。
保活时间	60 秒	MQTT Keep Alive。网络不稳定时不要设置过小。
清除会话	开启	开启后每次连接不保留旧订阅状态；需要 Broker 保留会话时关闭，并配合固定客户端 ID。
MQTT 协议版本	V311	与 Broker 支持版本一致。连接被 Broker 拒绝时检查此项。
QoS 等级	AtMostOnce	AtMostOnce 延迟低但可能丢消息；AtLeastOnce 至少送达但可能重复；ExactlyOnce 最可靠但开销最大。
详细日志	关闭	联调 Topic、认证、证书或消息解析时临时开启；稳定运行后关闭。
连接超时时间	3000 毫秒	建立连接的等待时间。跨网或 Broker 响应慢时可增大。
检查清除时间	60000 毫秒	定期清理连接和消息状态的间隔。普通场景保持默认。

MQTT 采集服务端

MQTT 采集服务端由网关监听 MQTT 客户端连接，变量地址格式与 MQTT 采集客户端相同。

服务端字段路径、候选字段、大小写、缺失字段和条件失败处理规则与上一节一致。服务端能够根据接收消息的 MQTT 会话识别发布客户端，因此条件脚本还可以在“输入参数”中声明字符串类型的 ClientId 或 MqttClientId：

var payload = (System.Text.Json.JsonElement)raw;

return ClientId == "device-01"
    && payload.TryGetProperty("type", out var type)
    && type.GetString() == "telemetry";

使用 devices/+/up 等通配 Topic 时，服务端可以结合实际 Topic 和 ClientId 做条件过滤；如果每台设备需要独立变量，仍建议配置精确 Topic，避免多个发布端更新同一变量。

配置项	默认值	填写说明
连接类型	Tcp	监听普通 MQTT 或 WebSocket MQTT。
端口	1883	网关本机监听端口。部署前确认端口未被占用，并按防火墙策略放行。
WebSocket 路径	/mqtt	WebSocket 客户端连接路径。
启用 SSL	关闭	客户端要求 TLS/WSS 连接到网关时开启。
服务器证书名称	留空	网关作为 MQTT 服务端时提供给客户端的证书。启用 SSL 时通常需要选择。
CA 名称	留空	需要校验客户端证书时选择 CA。
允许不受信任证书	开启	双向证书联调时可临时开启；生产环境建议关闭。
SSL 协议版本	None	握手失败或安全策略要求指定版本时调整。
检查证书吊销	关闭	需要证书吊销校验时开启。
允许连接 ID 前缀	留空	只允许指定前缀的客户端 ID 接入。留空表示不按前缀限制。
用户名	留空	需要账号认证时填写。
密码	留空	与用户名配套填写。
QoS 等级	AtMostOnce	控制发布和 RPC 回执使用该 QoS；AtMostOnce 延迟低但可能丢消息，AtLeastOnce 至少送达但可能重复，ExactlyOnce 开销最大。
详细日志	关闭	联调客户端连接、认证和消息时临时开启。
检查清除时间	60000 毫秒	定期清理连接和消息状态的间隔。

Gateway MQTT 专用采集客户端与服务端

Gateway MQTT 专用采集只处理 ThingsGateway 当前固定协议，变量地址固定为 RemoteKey/RemoteVariableId。Client 模式通过一条共享 Broker 连接接收多个来源；Server 模式通过一个监听端口接入多个来源，并精确绑定每个来源的 ClientId、账号和可选证书指纹。

不要把本节插件与前面的普通 MQTT 采集混用。普通 MQTT 采集地址是 Topic、JSONPath 和控制 Topic 组合；专用采集地址只包含来源键和远端变量 ID。完整属性、边缘 Producer 准备、变量同步和专用调试页参见 Gateway MQTT 专用采集。

数据转发插件

数据转发插件用于把采集数据、设备状态、报警或插件事件推送到外部系统，也可向外提供 Modbus、OPC UA、MQTT 等服务端能力。

Modbus 从站

插件属性

配置项	默认值	填写说明
Modbus 类型	按页面选择	ModbusTcp 用于 TCP 从站；ModbusRtu 用于串口从站。
默认站号	1	对外提供的默认从站号。
数据解析顺序	按现场选择	外部主站读写多字节数值时使用的字节序。数值颠倒或浮点异常时调整。
字符串反转字节	关闭	外部主站读写字符串出现相邻字节颠倒时开启。
多站点模式	开启	开启后可按多个站号响应。只提供单站点时可关闭，减少误访问。
允许 RPC 写入	开启	控制外部主站是否允许写入该目标下变量。关闭后目标下所有变量都只读。
立即写入内存	开启	外部主站写入后先更新从站内存，主站再次读取能立即看到新值；真实设备控制是否完成，仍要看采集侧写入结果。
发送延时时间	0 毫秒	响应前等待时间。部分主站需要较慢响应节奏时设置。
客户端权限列表	留空	TCP 服务端模式下按客户端 IP 控制访问。留空不限制；填了列表后，未匹配的客户端不能访问。

客户端权限列表包含“允许的客户端 IP”和“是否允许写入”。填写 * 表示匹配所有客户端。只开放读取时，可填写 * 并关闭写入；只允许上位机写入时，按上位机 IP 单独配置。

Modbus 从站同时需要填写通道参数。最容易填错的通道字段如下。

配置项	默认值	填写说明
通道类型	TcpService	TcpService 表示网关监听端口等待主站连接；TcpClient 表示网关主动连接远端；SerialPort 表示串口从站；UdpSession 表示 UDP 会话。
远程地址	127.0.0.1:502	TCP 客户端或 UDP 远端地址。使用 TcpClient 时必须填写；UDP 场景至少填写远程地址或本地绑定地址之一。
本地绑定地址	0.0.0.0:502	TCP 服务端或 UDP 本地监听地址。使用 TcpService 时必须填写；需要让其它主机访问时使用 0.0.0.0:端口 或本机实际 IP。
启用 SSL / SSL 服务端证书	关闭 / 留空	TCP 服务端启用 TLS 时必须选择服务端证书；TCP 客户端启用 TLS 时按对端要求配置 CA、客户端证书和目标主机名。
允许不受信任证书	开启	调试自签名证书时可开启。生产环境建议关闭，并选择可信 CA。
组包缓存时间	500 毫秒	等待报文组装完成的时间窗口，最小 100。用于处理 TCP 粘包、拆包或串口分段到达，不是变量值缓存。解析半包、偶发报文不完整时可增大；数值过大会增加响应延迟。
心跳内容 / 心跳是否 Hex / 心跳时间	留空 / 关闭 / 60000 毫秒	TCP 客户端模式下用于维持连接。对端要求十六进制心跳时开启 Hex，并填写连续十六进制字节。
DtuId / DtuId 是否 Hex / Dtu 服务类型	留空 / 关闭 / 默认	DTU 或透传网关接入时用于识别远端终端。终端上报文本编号时直接填写文本；上报字节编号时开启 Hex。

变量属性

配置项	默认值	是否必填	填写说明
从站变量地址	留空	是	外部主站访问的 Modbus 地址。必须避免不同变量地址冲突。
数据类型	Int16	否	外部主站按该类型解析寄存器值。读到数值颠倒、精度错误或布尔位不对时，应同时检查数据类型、地址和字节序。
允许 RPC 写入	开启	否	控制该变量是否允许外部主站写入。只有目标级和变量级都开启时，该变量才可写。

MQTT 客户端生产者

连接配置

配置项	默认值	填写说明
连接类型	Tcp	普通 MQTT 使用 Tcp；Broker 提供 WebSocket 接入时选择 WebSocket。
IP 地址	localhost	Broker 地址。
端口	1883	Broker 端口。
WebSocket 路径	/mqtt	WebSocket 连接路径。
启用 SSL	关闭	Broker 要求 TLS/WSS 时开启。
SSL 目标主机名	留空	用于证书主机名校验。证书域名与连接地址不一致时填写证书域名。
客户端证书名称	留空	Broker 要求客户端证书时选择。
CA 名称	留空	用于校验 Broker 服务端证书。
允许不受信任证书	开启	自签名证书联调时可临时开启；生产环境建议关闭。
SSL 协议版本	None	通常保持默认，握手失败或平台指定版本时调整。
检查证书吊销	关闭	需要证书吊销校验时开启。
客户端 ID	留空	Broker 要求固定 ClientId、会话保持或权限绑定时填写。
用户名	留空	Broker 认证用户名。
密码	留空	Broker 认证密码。
保活时间	60 秒	MQTT Keep Alive。网络不稳定时不要设置过小。
清除会话	开启	开启后每次连接不保留旧会话；需要 Broker 保留会话时关闭，并固定客户端 ID。
MQTT 协议版本	V311	与 Broker 支持版本一致。
QoS 等级	AtMostOnce	上传质量等级。关键数据可考虑更高 QoS，但需接受重复或性能开销。
保留消息	关闭	开启后 Broker 保存最后一条消息，新订阅者可能立即收到旧值。遥测数据通常不建议开启。

RPC 和请求触发

配置项	默认值	填写说明
RPC 写入 Topic	留空	外部系统写入变量的主题前缀。填写 tg/rpc/write 后，请求主题为 tg/rpc/write/<请求标识>，响应主题为 tg/rpc/write/<请求标识>/Response。
数据请求 Topic	留空	外部系统向该 Topic 发送任意消息后，目标会触发一次设备、变量、报警等数据上传。
RPC 脚本	留空	需要自定义 MQTT RPC 请求解析、写入逻辑或响应内容时选择脚本。

上传和缓存配置

配置项	默认值	填写说明
启用离线缓存	关闭	外部系统不可用或发送失败时，把未发送数据写入本地缓存等待补发。关闭时发送失败的数据不会重试。
缓存文件最大行数	262144	单个缓存文件保留的最大行数。超过上限会清理较早数据，不是无限保存。
上传分片大小	2000	每次从队列或缓存取出的最大记录数。接口超时、消息体过大或外部系统处理慢时调小。
内存队列上限	100000	内存中允许积压的数据量。超过后，开启离线缓存会优先落盘；关闭缓存时可能丢弃旧数据。
过滤离线数据	关闭	开启后不上传离线变量数据。需要外部系统看到离线设备最后值时谨慎开启。
并发上传数量	1	同一目标同时上传的任务数量。顺序要求严格时保持 1；确认目标支持并发后再增大。
详细日志	关闭	联调 Topic、模板、脚本或发送失败时临时开启；稳定运行后关闭。
JSON 缩进格式化	开启	开启后消息体易读；关闭后消息体更小。
JSON 忽略 Null	开启	开启后不输出空值字段；外部系统要求字段固定时关闭。
设备列表上传	开启	同一批设备数据合并为列表上传；关闭时逐条上传。
变量列表上传	开启	同一批变量数据合并为列表上传；关闭时逐条上传。
变量字典上传	关闭	变量列表上传时可整理为“设备名称 → 变量名称 → 变量数据”的字典结构。
报警列表上传	开启	同一批报警数据合并为列表上传；关闭时逐条上传。
报警字典上传	关闭	报警列表上传时可整理为“设备名称 → 变量名称 → 报警数据”的字典结构。
插件事件列表上传	开启	同一批插件事件合并为列表上传；关闭时逐条上传。
设备 Topic 模板	留空	设备数据上传 Topic。为空时不上传设备数据。
变量 Topic 模板	ThingsGateway/Variable	变量数据上传 Topic，可使用变量或设备字段组成分组 Topic。
报警 Topic 模板	留空	报警数据上传 Topic。为空时不上传报警数据。
插件事件 Topic 模板	留空	插件事件上传 Topic。为空时不上传插件事件。
上传模板配置	默认模板	需要自定义消息体时配置。模板字段必须与外部系统约定一致。

变量属性

配置项	默认值	是否必填	填写说明
数据1~数据10	留空	否	变量在该目标下的自定义字段，可用于 Topic 模板或上传模板，例如外部点位编号、业务编码、区域编号。
允许 RPC 写入	开启	否	控制该变量是否允许外部 MQTT RPC 写入。

MQTT 服务端生产者

MQTT 服务端生产者由网关监听 MQTT 客户端连接，再把转发数据发布给已连接客户端。

配置项	默认值	填写说明
连接类型	Tcp	监听普通 MQTT 或 WebSocket MQTT。
端口	1883	网关本机监听端口。部署前确认端口未被占用。
WebSocket 路径	/mqtt	WebSocket 客户端连接路径。
启用 SSL	关闭	客户端要求 TLS/WSS 连接到网关时开启。
服务器证书名称	留空	启用 SSL 时选择网关提供给客户端的证书。
CA 名称	留空	需要校验客户端证书时选择 CA。
允许不受信任证书	开启	自签名证书联调时可临时开启；生产环境建议关闭。
SSL 协议版本	None	握手失败或有安全要求时调整。
检查证书吊销	关闭	需要证书吊销校验时开启。
允许连接 ID 前缀	留空	只允许指定前缀的客户端 ID 接入。留空不按前缀限制。
用户名	留空	需要认证时填写。
密码	留空	与用户名配套填写。
QoS 等级	AtMostOnce	发布给客户端的默认 QoS。
保留消息	关闭	开启后已连接或新订阅客户端可能收到最后一条保留消息。
RPC 写入 Topic	留空	外部客户端写入变量的主题前缀，请求和响应规则与 MQTT 客户端生产者一致。
数据请求 Topic	留空	客户端向该 Topic 发送任意消息后触发一次全量上传。
RPC 脚本	留空	需要自定义 MQTT RPC 请求解析、写入逻辑或响应内容时选择脚本。

变量属性与 MQTT 客户端生产者相同。上传模板、缓存和列表/字典上传配置也按 MQTT 客户端生产者填写。

ThingsBoard 客户端生产者

ThingsBoard 客户端生产者按 ThingsBoard Gateway MQTT 协议上传数据，并接收 ThingsBoard 下发的 RPC。Topic 由 ThingsBoard 协议固定，用户主要维护连接、认证、TLS、QoS、缓存和变量写入权限。

配置项	默认值	填写说明
连接类型	Tcp	与 ThingsBoard MQTT 接入方式一致。
IP 地址	localhost	ThingsBoard MQTT 服务地址。
端口	1883	ThingsBoard MQTT 端口；TLS 接入通常使用 8883，以平台配置为准。
WebSocket 路径	/mqtt	仅 WebSocket 连接时使用。
启用 SSL	关闭	使用 TLS 时开启，并配置证书或 CA。
SSL 目标主机名	留空	校验证书时使用的主机名，通常填写证书中的域名。
客户端证书名称	留空	ThingsBoard 要求双向 TLS 时选择。
CA 名称	留空	用于校验 ThingsBoard 服务端证书。
允许不受信任证书	开启	调试自签名证书时可临时开启；生产环境建议关闭。
SSL 协议版本	None	通常保持默认，握手失败时按平台要求调整。
检查证书吊销	关闭	需要证书吊销校验时开启。
客户端 ID	留空	平台要求固定客户端 ID 时填写。
用户名	留空	ThingsBoard 设备凭据。使用 Access Token 时通常填入此项。
密码	留空	平台要求密码时填写；Access Token 模式通常可留空。
保活时间	60 秒	MQTT Keep Alive。
清除会话	开启	是否每次连接清除会话。
MQTT 协议版本	V500	与 ThingsBoard 支持的 MQTT 协议版本保持一致。
QoS 等级	AtMostOnce	上传质量等级。遥测量大时需结合平台吞吐选择。
保留消息	关闭	遥测数据通常不建议开启。
详细日志	关闭	联调认证、Topic 或 RPC 时临时开启。

ThingsBoard 目标使用平台固定 Topic，不维护普通 MQTT 的设备、变量、报警、插件事件 Topic 模板，也不提供上传模板配置。需要自定义 Payload 或按业务字段分组时，应使用 MQTT、Kafka、RabbitMQ 或 Webhook 等通用转发目标。

变量属性：

配置项	默认值	是否必填	填写说明
允许 RPC 写入	开启	否	控制该变量是否允许 ThingsBoard RPC 写入。

OPC UA 服务端

OPC UA 服务端目标用于把网关变量发布为 OPC UA 节点，供外部 OPC UA 客户端读取或写入。

配置项	默认值	填写说明
服务地址	opc.tcp://127.0.0.1:49321	OPC UA 服务监听地址。需要多个地址时用分号分隔。对外访问时应填写客户端可达的地址。
名称标识	ThingsGateway_OPC_UA_Server	OPC UA 服务端应用名称，客户端连接和证书信任时会看到该名称。
安全策略	关闭	开启后客户端需要按签名或加密策略连接，并信任服务端证书；关闭时允许匿名连接。
允许 RPC 写入	开启	控制 OPC UA 客户端是否允许写入网关变量。生产只读发布时建议关闭。
用户名	留空	客户端账号认证用户名。无账号认证时可留空。
密码	留空	与用户名配套填写。
服务端证书名称	留空	OPC UA 服务端证书。启用安全策略时客户端需要信任该证书。

变量属性：

配置项	默认值	是否必填	填写说明
数据类型	Object	否	OPC UA 客户端看到和写入该节点时使用的数据类型。客户端提示类型不匹配时，应按变量实际值类型调整。
允许 RPC 写入	开启	否	只有目标级和变量级都开启时，OPC UA 客户端才可写入该变量。

Kafka 生产者

配置项	默认值	填写说明
服务地址	127.0.0.1:9092	Kafka Bootstrap 地址，通常填写 主机:端口。多个 Broker 按 Kafka 连接串约定填写。
发布超时时间	5000 毫秒	单次发布等待时间。网络慢或 Broker 繁忙时可适当增大。
用户名	留空	SASL 认证用户名。未启用 SASL 时留空。
密码	留空	SASL 认证密码。未启用 SASL 时留空。
安全协议	Plaintext	普通内网无认证常用 Plaintext；启用认证或加密时按 Kafka 集群要求选择。
SASL 机制	Plain	必须与 Kafka 集群配置一致，例如 Plain、ScramSha256 或 ScramSha512。

Kafka Topic 模板展开后必须是目标集群允许写入的 Topic 名称。启用认证时，安全协议、SASL 机制、用户名和密码需要成组配置；只填写账号密码但安全协议仍为 Plaintext，通常无法连接启用认证的集群。

变量属性：

配置项	默认值	是否必填	填写说明
数据1~数据10	留空	否	自定义字段，可在 Topic 模板或上传模板中使用。

RabbitMQ 生产者

配置项	默认值	填写说明
IP 地址	localhost	RabbitMQ 服务地址。
端口	5672	RabbitMQ 服务端口。
用户名	guest	认证用户名。
密码	guest	认证密码。
声明队列	关闭	开启后由网关自动声明队列。生产环境如果队列由平台统一创建，建议关闭。
声明交换机	关闭	开启后由网关自动声明交换机。账号没有创建权限时应关闭。
交换机类型	topic	必须与 RabbitMQ 中交换机实际类型一致，常见值包括 direct、topic、fanout、headers。
启用发布确认	开启	等待 Broker 返回发布确认。可靠性要求高时保持开启；关闭后发布失败不一定能及时暴露。
要求路由成功	开启	要求消息至少路由到一个队列。Routing Key 没有命中任何绑定时会按失败处理。
发布超时时间	5000 毫秒	发布等待时间。Broker 繁忙或网络慢时可适当增大。
虚拟主机	/	RabbitMQ Virtual Host。必须与账号权限所在虚拟主机一致。
交换机名称	TG	发布使用的交换机名称。

变量、设备、报警和插件事件的 Topic 模板在 RabbitMQ 中作为 Routing Key 使用。Routing Key 必须能被目标队列绑定规则匹配；开启“要求路由成功”后，未匹配任何队列会直接暴露为发布失败，便于排查绑定规则错误。

变量属性：

配置项	默认值	是否必填	填写说明
数据1~数据10	留空	否	自定义字段，可在 Routing Key 模板或上传模板中使用。

历史数据目标

历史数据目标用于把变量值写入历史数据库。变量是否入库由转发组范围、目标采样策略和变量属性共同决定。

配置项	默认值	填写说明
数据库类型	SqlServer	选择历史数据写入的数据库类型，连接字符串必须与数据库类型匹配。
自定义 SQL 模式	关闭	开启后按自定义模板或脚本组织历史表结构和写入语句。不了解目标表结构时保持关闭。
分表策略	按页面选择	历史数据量大或保留周期长时，用于按时间等策略拆分表。
连接字符串	示例连接串	数据库连接信息，包含服务器、端口、库名、账号、密码和加密策略。
数值历史表名	historyNumberValue	数值类变量写入的历史表名。
字符串历史表名	historyStringValue	字符串类变量写入的历史表名。
保留天数	3650	历史数据保留周期。设置前应评估追溯要求和磁盘容量。
历史表脚本	留空	自定义建表或写入逻辑。只有对接已有表结构或特殊入库规则时使用。
时区偏移	+08:00	写入时间的时区偏移。跨时区部署或统一 UTC 入库时必须重点确认。
强制插入	关闭	开启后收到数据即写入，不按采样策略减少记录量。变量多或周期短时会显著增加数据库压力。
默认采样策略	Change	未配置变量属性时使用。变化采样适合状态量，间隔采样适合趋势，条件采样适合按工况记录。
默认采样间隔	留空	默认采样策略为间隔时使用，单位毫秒。
默认条件表达式	留空	默认采样策略为条件时使用，表达式满足时才入库。
自定义模板配置	按需维护	自定义 SQL 模式下维护字段模板。字段名、数据类型和 SQL 逻辑必须与目标数据库一致。

冗余可靠性：启用网关冗余并保持历史可靠性开启时，SqlServer、MySql、Sqlite、PostgreSql 的标准 SQL 历史数据目标支持本机 Journal、切换或重启后的补写，以及记录唯一键去重。QuestDB、TDengine、自定义 SQL 模式和历史表脚本不纳入该机制；需要断线或重启补发时，应同时开启离线缓存并确认磁盘容量。

变量属性：

配置项	默认值	是否必填	填写说明
采样策略	Change	否	该变量在历史目标中的入库方式。
采样间隔	留空	否	间隔采样时使用，单位毫秒。
条件表达式	留空	否	条件采样时使用。适合只在设备运行、工艺允许或数值满足条件时记录历史。

实时数据目标

实时数据目标用于把变量最新值写入实时表，供外部系统读取当前状态。

配置项	默认值	填写说明
数据库类型	SqlServer	选择实时数据写入的数据库类型。
连接字符串	示例连接串	实时库连接信息。账号需要具备建表、更新和写入权限。
实时表名	realValue	保存变量最新值的表名。
实时表脚本	留空	自定义实时表结构或写入逻辑时选择。
时区偏移	+08:00	写入时间使用的时区，需要和外部系统展示时间保持一致。

实时性要求高时，不宜把上传分片大小设置过大；外部数据库短时不可用时，可开启离线缓存减少数据丢失。

历史报警目标

历史报警目标用于保存报警和恢复事件，供报警追溯、统计和导出。

配置项	默认值	填写说明
数据库类型	SqlServer	选择历史报警写入的数据库类型。
分表策略	按页面选择	报警量大或保留周期长时使用。
连接字符串	示例连接串	历史报警库连接信息。
历史报警表名	historyAlarm	保存报警事件的表名。
保留天数	3650	历史报警保留周期，需要满足现场审计或追溯要求。
历史报警表脚本	留空	自定义报警表结构或写入逻辑时选择。
时区偏移	+08:00	报警事件时间写入时使用的时区。
最小报警等级	0	只保存该等级及以上报警。希望记录全部报警时保持较低等级。

冗余可靠性：启用网关冗余并保持历史可靠性开启时，SqlServer、MySql、Sqlite、PostgreSql 的标准历史报警目标支持本机 Journal、切换或重启后的补写，以及记录唯一键去重。填写历史报警表脚本或使用其它动态写入逻辑时不纳入该机制；报警用于追溯时，应同时开启离线缓存并确认磁盘容量。

报警数据用于追溯时，建议开启离线缓存并确认磁盘空间，避免数据库短时不可用造成记录缺失。

Webhook

Webhook 目标把数据发送到 HTTP 接口。变量 Topic 模板默认是 http://127.0.0.1:7502/ThingsGateway/Variable，在 Webhook 中 Topic 模板会作为最终请求 URL 使用。

配置项	默认值	填写说明
签名密钥	留空	钉钉机器人加签模式使用的 Secret；企业微信、飞书或普通 HTTP 接口不需要时留空。
自定义请求头	留空	JSON 格式请求头，例如 {"Authorization":"Bearer token"}。格式错误会导致请求失败。
消息格式	Raw	Raw 直接发送默认 JSON 或模板内容；Text 适配钉钉、企微、飞书文本消息；Markdown 适配钉钉、企微 Markdown 消息。
请求超时	10 秒	HTTP 请求等待时间。接口响应慢时可增大，过大则会延长失败重试周期。

配置 Webhook 时，应把变量、设备、报警或插件事件 Topic 模板填写为实际 URL；对应 Topic 为空的数据类型不会上传。普通 HTTP 接口通常使用自定义请求头传递 Token；机器人加签只在平台开启加签时填写签名密钥。

变量属性：

配置项	默认值	是否必填	填写说明
数据1~数据10	留空	否	自定义字段，可在 URL 模板或上传模板中使用。

SyncBridge

SyncBridge 用于让一个 HubServer 通过单个 mTLS 监听端口汇聚多个 EdgePublisher，同步转发组范围内的配置和实时变量值。

配置项	默认值	填写说明
Role	必填	Hub 选择 HubServer，边缘端选择 EdgePublisher。
LocalPeerId	空	当前节点稳定且唯一的身份。
ListenUri	0.0.0.0:7777	Hub 监听地址。
RemoteUri	空	Edge 连接的 Hub 地址。
VerifyToken	空	TLS 后的第二层握手密钥，不提供公开默认值。
TransportCertificateName / TransportCaCertificateName	空	当前节点证书和验证对端的私有 CA，均为必填。
TransportTargetHost	空	Edge 校验 Hub 证书使用的目标主机名。
HeartbeatIntervalMs	5000 毫秒	认证心跳周期，范围 1000 至 60000。
RealtimeFlushIntervalMs	20 毫秒	实时值合并窗口。
MaxRealtimeBatchVariables / MaxRealtimeBatchBytes	2000 / 262144	单个实时批次的变量数和字节上限。
RealtimeAckTimeoutMs	3000 毫秒	等待 Hub 应用确认的超时。
MaxConfigChunkBytes	524288	单个配置块字节上限。
ConfigSyncMode	OnChangeAndReconnect	Edge 自动比较配置的时机。
MaxConcurrentConfigurationSyncPeers	4	Hub 同时请求多个 Edge 的并发上限。
AllowRemoteRpc	关闭	桥级反向写入总开关。

SyncBridge 不需要维护变量级属性，变量范围由数据转发组决定。完整的证书准备、Hub/Edge 配置、字段所有权、专用调试和排障方法参见 SyncBridge 网关同步。

上传模板配置

带“上传模板配置”的转发插件可自定义消息体。

配置项	默认值	填写说明
变量内容模板	留空	变量数据上传模板，可使用 ${Name}、${Value}、${DeviceName}、${CollectTime}、${CollectGroup}、${Remark1} 至 ${Remark5} 等占位符。
设备内容模板	留空	设备状态上传模板。外部系统要求固定设备字段或固定消息格式时填写。
报警内容模板	留空	报警事件上传模板。建议保留报警名称、等级、触发值、事件时间和设备信息。
插件事件内容模板	留空	插件事件上传模板。用于连接、断开、错误等插件事件的外部通知。

模板留空时使用默认 JSON。字段后可追加格式符，例如 ${CollectTime:long} 输出 Unix 毫秒时间戳，${CollectTime:yyyy-MM-dd HH:mm:ss} 输出格式化时间。只输入 json 输出 JSON 数组；只输入 json_dict 输出字典结构；输入 dict:模板内容 可按设备和变量组织字典结果。

模板适合外部系统字段固定、机器人消息格式固定、或 Topic 与 Payload 都需要引用变量字段的场景。模板占位符写错时，对应字段会无法得到预期值，外部系统会表现为入库失败、字段为空或解析失败。

公共配置说明

采集插件公共配置

配置项	默认值	填写说明
失败重试次数	3	单次读写失败后的重试次数。网络或串口偶发抖动时可适当增大；长期故障设置过高会拖慢故障反馈。
读写占空比	3	写入请求较多时，执行若干次写入后穿插读取，避免长时间只写不读。
写优先	关闭	开启后有写入任务时优先处理写入。适合控制指令需要尽快下发的场景。

数据转发缓存公共配置

配置项	默认值	填写说明
启用离线缓存	关闭	发送失败时写入本地缓存等待补发。历史数据、报警和关键上报建议开启。
缓存文件最大行数	262144	缓存文件保留行数上限。外部系统长时间不可用时，超过上限会清理较早数据。
上传分片大小	2000	每次上传或补发的最大记录数。接口超时、数据库压力大或消息体过大时调小。
内存队列上限	100000	内存中允许积压的数据量。超过上限时，开启离线缓存会优先落盘；未开启缓存或无法落盘时，旧数据可能被丢弃。
过滤离线数据	关闭	开启后不上传离线变量数据。需要外部系统看到离线设备最后值时谨慎开启。
并发上传数量	1	同一目标同时上传的任务数量。顺序要求严格时保持 1；确认目标支持并发后再增大。

变量自定义字段

数据转发插件的变量属性通常包含“数据1”到“数据10”。这些字段不会改变变量采集值，主要用于外部系统对接时补充业务信息，例如外部点位编号、区域编号、设备编码、工艺段或告警分组。Topic 模板、URL 模板或上传模板需要这些字段时再填写；不使用时可留空。

相关链接

• 采集配置
• 插件管理
• 插件属性详表
• 设备调试