数据转发

数据转发用于把 GatewayRuntime 已采集到的变量、设备状态、报警和插件事件发送到外部系统，也可以写入内置实时数据、历史数据或历史报警目标。页面按“转发组（一组要发送的数据范围和触发规则）+ 转发目标（数据出口）”组织配置。

术语速查

术语	现场含义
转发组	一组要对外发送的数据范围和触发规则。
转发目标	数据出口，例如 MQTT、Kafka、RabbitMQ、Webhook、Modbus 从站、实时库、历史库。
目标变量属性	某个转发目标对单个变量的外部映射，例如外部字段名、Modbus 从站地址、目标数据类型、是否允许反写。
触发模式	决定什么时候发送数据：值变化、固定周期、或两者都触发。
Cron 表达式	定时表达式。普通周期上报优先填写毫秒数，例如 1000 表示 1 秒；固定时刻执行再使用 Cron。
在线过滤	只发送在线变量。开启后，离线设备下的变量不会进入转发。
采集组	变量上的业务分组，可用于筛选或分批转发。
数据组	转发组内的分批字段，可把同一批数据按业务单元拆开。
RPC 写入	外部系统反写点位。只有控制类点位才建议开启。
离线缓存	外部系统短时不可用时，先把待发送数据保存在本地，恢复后再补发。
DtuId	DTU 或透传终端编号，用于 Modbus 从站等场景区分远端终端。
Topic / URL / 表名模板	外部系统接收数据的位置或路径，可引用变量、设备、时间等字段。

页面入口

菜单路径：开发配置 → 数据转发。

区域	说明
转发组列表	显示全部转发组，可新增、编辑、删除、启停和重启组。
转发目标列表	显示所选转发组下的目标，列表顶部会提示“所属转发组”，避免在多个组之间维护目标时误选范围。可新增、编辑、删除、启停、重启、配置变量属性和执行冗余切换。
详情区	按“详细信息、转发组日志、转发目标日志、调试”标签展示所选组和目标的运行信息。
刷新间隔	详情区右上角可设置自动刷新节奏，便于观察目标在线状态和最近活跃时间。

先判断：变量有值为什么还没转发

变量在采集页面有当前值，只说明采集侧正常，不代表一定会发到外部系统。数据要成功发出，必须同时满足以下条件。

条件	现场判断方式
变量在转发组范围内	手动选择范围下，变量必须先加入组变量；按设备或采集组筛选时，名称必须完全匹配。
转发组已启用	转发组禁用后，组下所有目标都不会运行。
触发条件满足	只选“变化”时，值不变化就不会周期发送；需要周期上报时选择包含“定时”的触发模式。
在线过滤没有拦截	开启在线过滤后，离线设备下的变量不会进入转发。
转发目标已启用并在线	目标未启用、启动失败、认证失败或外部系统不可达时不会发送。
外部映射正确	Topic（消息主题）、URL、表名、模板、变量别名或目标变量属性（单个变量在该目标下的外部映射）错误，可能导致发送失败或对方无法解析。
日志没有错误	优先查看转发目标日志，再查看转发组日志。

现场排查时按这张表从上往下检查，先用少量变量联调成功，再扩大到正式点表。

基本概念

概念	说明
转发组	一组参与转发的数据范围和触发规则。一个转发组可以挂多个转发目标。
转发目标	一个具体的数据出口，例如 MQTT、Kafka、RabbitMQ、Webhook、ModbusSlave、OpcUaServer、SyncBridge、实时数据、历史数据或历史报警。
组变量	转发组内的变量成员和组内变量设置。手动范围下它决定组成员；其它范围下它用于维护别名、数据组和触发策略。
目标变量属性	某个变量在某个转发目标下的外部映射属性，例如从站地址、目标数据类型、外部字段、RPC 写入权限或自定义数据字段。
目标冗余	为关键目标配置备用目标，主目标异常时按离线状态或脚本判断切换。
调试	对当前转发目标打开插件调试界面，验证发布、订阅、客户端连接或服务端状态。

推荐配置流程

1. 在“插件管理”确认目标插件已启用。
2. 新增转发组，确定变量范围、触发模式、在线过滤和分批策略。
3. 如果范围选择“手动选择”，在转发组抽屉中维护组变量。
4. 在转发组下新增一个或多个转发目标，选择插件并填写连接参数。
5. 如需要变量级映射，打开目标的“变量属性”抽屉维护目标变量属性。
6. 启用转发组和转发目标，观察详情区的在线状态、最近活跃时间和错误信息。
7. 进入“调试”标签验证 MQTT、Kafka、RabbitMQ 等目标是否能发布消息。
8. 稳定后把日志级别从 Trace 或 Debug 调回 Info，减少运行日志量。

联调前确认

数据转发通常需要和上位机、MES、SCADA、云平台或数据库负责人一起确认。开始配置前，至少确认以下内容。

项目	需要确认
数据范围	是全部变量、某些设备、某个采集组，还是手动挑选关键点位。
上报方式	按变化上报、固定周期上报，还是变化和定时都需要。
外部地址	Broker、数据库或 HTTP 接口的 IP、端口、账号、密码、证书和防火墙策略。
数据格式	外部系统要求的设备编号、变量名称、字段名、单位、时间格式和消息结构。
断网策略	外部系统不可用时是否缓存、缓存多久、恢复后是否补发。
验收方式	对方通过哪个页面、表、Topic 或日志确认已收到正确数据。

联调建议先用一个小范围转发组，只放少量变量。确认外部系统能收到并解析正确后，再扩大到正式点表。

转发组配置

点击转发组面板右上角新增按钮，或点击已有转发组的编辑按钮，打开转发组配置抽屉。

配置项	说明
名称	转发组名称，建议体现业务范围，例如“生产线A_实时上传”。
启用	控制该组是否参与运行。禁用后组下目标不会启动。
日志级别	控制组级运行日志详细程度。调试阶段可临时使用 Debug 或 Trace。
变量范围	决定哪些变量进入该组。可选全部变量、手动选择、采集设备、采集组。
范围配置	当范围为采集设备或采集组时填写匹配名称，多个名称用英文逗号分隔。选择采集设备时，名称以“采集配置”和“内存计算”中显示的设备名称为准；选择采集组时，名称以变量中的采集组为准。
触发模式	可选择变化、定时、定时或变化。
定时间隔	触发模式包含定时时使用，可填写毫秒数或 Cron 定时表达式，例如 1000 或 */5 * * * * *。现场常规周期优先填毫秒数。
在线过滤	开启后只转发在线设备下的变量。
分批模式	控制一次触发后如何拆分数据，可选不分批、全部合并、按数据组、按设备或按采集组分批。
最大批量	单批最大变量数量。变量很多时用于控制单次消息大小。
排序	控制转发组显示顺序。
描述	记录组用途、范围或维护注意事项。

容易填错的转发组配置

配置	使用说明
变量范围 + 范围配置	选择“采集设备”时，范围配置填写设备名称，采集设备和内存计算设备都按设备名称匹配；选择“采集组”时，范围配置填写变量中的采集组名称。多个名称用英文逗号分隔，名称写错会导致组内没有数据。
触发模式	“变化”只在变量值变化时触发；“定时”按间隔触发；“定时或变化”两种情况都会触发。对外部系统有固定上报周期要求时选择包含定时的模式。
定时间隔	填毫秒数或 Cron 定时表达式。1 秒一次应填写 1000，需要固定时刻执行时再填写 Cron；不要填写 00:00:01 这类时间格式。
在线过滤	开启后，离线设备下的变量不会进入转发。需要外部系统看到离线值或离线状态时不要开启。
分批模式	按设备、采集组或数据组分批，会影响 Topic 模板和上传模板中可使用的数据边界。外部系统要求“一台设备一条消息”时选择按设备。
最大批量	不是变量总数限制，而是每批消息包含的变量数量上限。消息太大、接口超时或 Broker 限制单包大小时调小。

变量范围选择

范围	适用场景
全部变量	所有启用采集变量都进入转发组，适合整站上传。
手动选择	只转发手动加入的变量，适合关键点位或小范围试点。
采集设备	按设备名称筛选变量，适合同一设备、一组现场设备或内存计算设备的数据转发。
采集组	按变量的采集组筛选，适合按业务分组转发。

分批模式选择

分批模式	适用场景
不分批	按触发数据直接进入目标，适合数据量小或目标本身会处理批量的场景。
全部	将一次触发的数据尽量合并为批次，再受“最大批量”限制拆分，适合外部系统按批接收。
按数据组	按组变量中的“数据组”拆分，适合外部系统按业务单元接收。
按设备	按变量所属设备拆分，适合每台设备一个消息或一个 Topic 的场景。
按采集组	按变量采集组拆分，适合现场已按采集组规划数据边界的项目。

组变量维护

手动选择范围下，组变量列表就是该组实际成员；其它范围下，组变量列表主要用于变量级覆盖。

配置项	说明
变量	选择要加入或覆盖配置的变量。
启用	控制该变量是否参与当前转发组。
数据组	给变量设置业务分组，分批模式为“按数据组”时使用。
更新	覆盖该变量的触发方式。
组触发	开启后该变量变化可以唤醒整个转发组。
别名	转发时使用的变量名称，可用于对接外部系统字段名。

手动选择范围下，“组变量”就是该转发组的成员名单。只有先把变量加入组变量，后续目标变量属性中的 Modbus 地址、外部字段或自定义数据才会生效。范围为全部变量、采集设备或采集组时，组变量主要用于给已匹配变量补充别名、数据组和触发覆盖。

“组触发”关闭后，变量仍可以随定时触发或其它变量触发一起被转发，但它自身变化不会唤醒整个转发组。适合把温度、状态等辅助字段随主变量一起上传，而不希望辅助字段频繁触发整组消息的场景。

转发目标配置

先选中一个转发组，再点击转发目标面板右上角新增按钮，打开转发目标配置抽屉。目标列表顶部显示当前“所属转发组”，新增目标会自动归属到该组；编辑已有目标时，也应先确认列表提示的组名与目标实际业务范围一致。

配置项	说明
所属转发组	当前目标归属的转发组。目标只消费该组匹配出的变量。
目标名称	同一转发组内唯一，用于日志、冗余候选和导入导出定位。
启用	控制该目标是否运行。启用后才会进入运行态并支持调试。
插件	数据转发插件完整名称对应的显示项。选择后动态显示插件属性。
日志级别	控制目标运行日志详细程度。
启动超时	目标连接或初始化的等待时间，单位秒。
描述	记录目标用途、外部系统地址或维护说明。
插件目标属性	由所选插件动态提供。不同插件显示不同字段；逐字段说明见 插件属性详表。
启用冗余	为该目标配置备用目标。
冗余目标	启用冗余后选择同组备用目标。备用目标必须使用相同插件，不能是当前目标本身，不能已经作为其它目标的备用目标，也不要再启用自己的冗余。
冗余模式	按离线状态切换，或通过脚本判断切换。离线切换适合主目标不可用时自动接管；脚本切换适合按业务条件、目标质量或外部状态决定是否切换。
冗余扫描间隔	检查主目标状态的间隔，单位毫秒，最小 10000。
冗余脚本	脚本切换模式下使用。选择脚本切换时必须选择脚本。

容易填错的目标通用配置

配置	使用说明
启动超时	目标启动、连接或初始化允许等待的时间，单位秒。外部系统响应慢时可适当增大；设置过短可能导致目标反复启动失败。
日志级别 / 详细日志	联调时可使用 Debug、Trace 或开启详细日志查看发送内容；稳定运行后调回 Info，避免日志量过大。
启用离线缓存	外部系统短时不可用时把待发送数据写入本地缓存。对数据完整性要求高的历史数据、报警和上报目标建议开启，并预留磁盘空间。
上传分片大小	每次补发或上传的记录数。目标接口超时、数据库压力大或 Broker 限制消息大小时调小。
内存队列上限	目标发送不过来时允许在内存中排队的数据量。超过上限时，开启离线缓存会优先写入磁盘；未开启缓存或缓存写入失败时，旧数据可能被丢弃。
过滤离线数据	开启后不上传离线变量产生的数据。需要保留最后值或离线状态给上级系统时谨慎开启。
并发上传数量	同一目标同时发送的任务数量。外部系统要求严格顺序、数据库写入有顺序依赖时保持 1；确认目标能承受并发后再增大。
冗余扫描间隔	目标冗余启用后检查主目标状态的间隔，单位毫秒，最小 10000。间隔过小会增加检查频率，网络抖动时也更容易频繁切换。
冗余目标	只能选择同一转发组下、插件相同的其它目标。备用目标需要单独配置连接参数、Topic、模板、账号密码和缓存策略，不能只依赖主目标配置。

离线缓存适合网络或外部系统短时不可用的场景，不等于无限保存。缓存文件达到最大行数后会清理最旧数据；现场要求完整追溯时，应同时评估磁盘空间、缓存文件最大行数、上传分片大小和外部系统恢复后的补发能力。

目标已经被其它目标选为备用时，页面会阻止它再开启自己的冗余。这样可以避免一个目标同时承担多个主备角色，造成切换关系不清晰。

运行态状态与 CacheDB 诊断

启用转发组和转发目标后，右侧“详细信息”和目标卡片会显示目标的运行态摘要。运行态信息来自当前内存实例，适合判断目标是否真正创建、初始化、启动、在线，以及是否存在离线缓存积压。

信息项	说明
插件运行态	显示插件实例是否创建、运行类型、是否已启动、初始化是否成功、调度循环是否创建、可见变量数和可见设备数。目标启用但实例未创建或初始化失败时，优先查看转发目标日志。
在线状态	显示目标或目标内部通道的在线情况。MQTT、Kafka、RabbitMQ、Webhook、数据库等目标的在线判断来源不同，应结合最近错误和目标日志确认。
可靠历史	历史数据和历史报警目标会显示是否支持可靠历史同步、Journal 目标键和不支持原因。只有标准 SQL 写入链路才能纳入冗余历史的补写与去重。
CacheDB 出站队列	显示启用离线缓存后的模型数、内存队列、CacheDB 积压、重试保留数量、最早积压时间和异常信息。积压持续增长时，说明目标发送速度低于产生速度，或外部系统仍不可用。
最近活跃时间 / 最近错误	用于判断目标最近一次成功处理数据的时间和最新异常。排障时先看最近错误，再导出目标日志。

CacheDB 出站队列为空表示当前没有待补发数据，不代表外部系统一定在线；在线状态、最近错误和调试页需要一起判断。启用离线缓存的目标恢复后，系统会按上传分片、并发数和外部系统响应能力逐步补发，积压下降速度取决于这些配置和目标端吞吐。

MQTT 目标属性

选择 MqttClientProducer 后，目标抽屉显示 MQTT 客户端连接、TLS、认证、Topic 模板、离线缓存和队列配置。

配置项	说明
IP 地址 / 端口	MQTT Broker 地址和端口。普通 TCP 默认常用端口为 1883，TLS 常用端口为 8883。
连接类型	选择 Tcp 或 WebSocket。使用 WebSocket 时还要填写 WebSocket 路径。
WebSocket 路径	Broker 的 WebSocket 接入路径，例如 /mqtt。只有连接类型为 WebSocket 时使用。
客户端 ID	MQTT 客户端标识。Broker 要求固定客户端时必须填写；留空时按 Broker 或插件默认规则处理。
保活时间	MQTT Keep Alive，单位秒。网络不稳定时不宜设置过小。
清除会话	开启后每次连接都不保留旧会话；需要 Broker 保留会话状态时关闭。
MQTT 协议版本	与 Broker 支持版本保持一致，常用 V311。
启用 SSL	开启 TLS 连接。启用后需要配置目标主机、证书和 CA。
SSL 目标主机名	用于校验证书中的域名或主机名。使用 IP 访问但证书签发给域名时，应填写证书中的域名。
客户端证书名称	从“证书管理”选择客户端证书。Broker 要求双向 TLS 时填写。
CA 名称	从“证书管理”选择 CA 证书，用于校验 Broker 证书链。
允许不受信任证书	调试自签名证书时可临时开启；生产环境建议关闭，并配置正确 CA。
SSL 协议版本	TLS 协议版本。无法握手时再按 Broker 要求指定，通常保持默认即可。
检查证书吊销	是否检查证书吊销状态。生产环境需要证书吊销校验时开启。
用户名 / 密码	Broker 认证账号密码。无认证时留空。
QoS 等级	默认发布质量等级。AtMostOnce 延迟低但不保证送达；AtLeastOnce 可能重复；ExactlyOnce 开销最高。
保留消息	是否发布为 Retain 消息。开启后 Broker 会保存最后一条消息，新订阅者可能立即收到旧值。
RPC 写入 Topic	接收外部 MQTT 写入请求的 Topic 前缀。填写 tg/rpc/write 时，请求发送到 tg/rpc/write/<请求标识>，响应从 tg/rpc/write/<请求标识>/Response 读取。
数据请求 Topic	收到该 Topic 的任意消息后触发一次全量上传，适合外部系统主动拉取最新快照。
RPC 脚本	处理 MQTT RPC 消息的脚本。需要按现场约定解析消息、选择写入目标或组织应答内容时使用。
详细日志	输出更详细的目标运行日志。排查模板、Topic 或发送失败时临时开启。
JSON 缩进格式化 / JSON 忽略 Null	控制默认 JSON Payload 的可读性和空值输出。
设备列表上传 / 变量列表上传 / 报警列表上传 / 插件事件列表上传	控制对应数据是否合并为列表上传。关闭后逐条上传。
变量字典上传 / 报警字典上传	列表上传开启时可用，把数据整理成“设备名称 → 变量名称 → 数据”的字典结构。
设备 Topic 模板 / 变量 Topic 模板 / 报警 Topic 模板 / 插件事件 Topic 模板	控制不同数据类型的发布 Topic。Topic 为空时，对应数据类型不会上传。
设备实体脚本 / 变量实体脚本 / 报警实体脚本 / 插件事件实体脚本	上传前重组字段，脚本输出字段可继续用于 Topic 模板和上传模板。
上传模板配置	打开模板弹窗，分别维护变量、设备、报警和插件事件 Payload 模板。用于外部系统要求固定 JSON 字段、固定文本格式或平台专用消息体的场景。
启用离线缓存	发送失败时是否写入本地缓存等待补发。关闭时失败数据不会重试。
缓存文件最大行数	缓存文件保留行数上限。离线时间很长时，超过上限会清理最旧数据；需要长时间离线补发时应按数据量和磁盘容量调大。
上传分片大小	单次上传或补发的最大记录数。目标系统压力大时调小。
内存队列上限	内存中允许积压的数据量。超过后，启用离线缓存会优先落盘；不能落盘时会丢弃旧数据。
过滤离线数据	开启后，离线变量数据不会继续上传。
并发上传数量	同一目标同时上传的任务数量。需要保持严格顺序时保持为 1。

上传结构与模板

Topic 模板和上传模板都使用 ${属性名} 占位符，例如 ThingsGateway/Variable/${DeviceName} 或 name=${Name},value=${Value}。占位符必须来自实际上传数据或实体脚本输出字段；字段名写错会导致 Topic 或 Payload 生成失败。

配置	使用建议
列表上传	外部系统希望一次接收一批数据时开启，消息体是数组。
逐条上传	外部系统只接受单点消息，或 Topic 需要按每个变量单独分组时使用。
字典上传	外部系统希望按设备和变量名直接索引数据时使用。只有变量或报警列表上传开启时生效。
上传模板配置	外部系统要求固定文本、特殊 JSON 字段名或非默认 Payload 结构时使用。留空则使用默认 JSON。

模板配置建议先从最小内容开始联调，例如只上传变量名和值；确认外部系统接收成功后，再增加设备名、时间、质量码、自定义数据字段等内容。Topic 为空表示该类数据不上传，适合只上报变量、不上报告警或插件事件的项目。

上传模板配置弹窗按数据类型分区维护。变量模板只影响变量上传，设备模板只影响设备状态上传，报警模板只影响报警上传，插件事件模板只影响插件事件上传。模板中引用的字段必须来自该数据类型本身或实体脚本输出；字段名写错时，目标日志会记录模板展开失败。

SOE 事件记录配置

IEC61850 相关插件出现“SOE 事件记录配置”按钮时，可打开弹窗维护事件记录数据库和缓存参数。

配置项	说明
启用	开启后记录 SOE 事件。未启用时，不写入 SOE 事件记录。
数据库连接串	SOE 事件写入的数据库连接信息，默认示例为 DataSource=SOE.db。使用外部数据库时，应改为现场数据库连接串，并确认账号具备建表、写入和清理权限。
数据库类型	选择连接串对应的数据库类型。类型和连接串不一致会导致写入失败。
表名	SOE 事件表名，默认 soeEventLog。外部报表或审计系统已有固定表名时，按对方约定填写。
保存天数	SOE 事件保留周期。设置过短会影响追溯，设置过长需要评估数据库容量。
时区偏移	SOE 事件时间写入使用的时区，例如 +08:00。跨时区部署时应与报表系统约定一致。
启用离线缓存	数据库短时不可用时，把事件写入本地缓存等待补写。对事件追溯要求高的现场建议开启。
队列上限	内存中允许等待写入的事件数量。事件频率高或数据库偶发慢写时可增大，并同步评估内存占用。
缓存文件最大行数	本地缓存文件保留行数上限。超过上限会清理较早事件。
分片大小	每次写入或补写的事件数量。数据库压力大或写入超时时调小。

Kafka 目标属性

配置项	说明
服务地址	Kafka Bootstrap 地址，例如 127.0.0.1:9092。多个 Broker 按 Kafka 连接串约定填写。
发布超时时间	单次发布等待时间，单位毫秒。
用户名 / 密码	SASL 用户名和密码。未启用 SASL 认证时留空。
安全协议	Kafka 连接安全协议。无认证内网常用 Plaintext；启用认证或加密时按 Kafka 集群要求选择。
SASL 机制	SASL 认证机制，必须与 Kafka 集群配置一致。
Topic 模板	设备、变量、报警、插件事件 Topic 模板分别控制不同数据类型写入哪个 Topic。模板展开后的 Topic 必须允许当前账号写入。
缓存与队列	使用“启用离线缓存、缓存文件最大行数、上传分片大小、内存队列上限、过滤离线数据、并发上传数量”控制失败补发和吞吐。

Kafka 集群启用认证时，应同时确认“安全协议、SASL 机制、用户名、密码”。例如集群要求 SASL_SSL 时，不能只填写账号密码；集群使用 SCRAM 时，SASL 机制也必须选择对应的 SCRAM 方式。

RabbitMQ 目标属性

配置项	说明
IP 地址 / 端口	RabbitMQ 服务地址和端口，默认端口通常为 5672。
用户名 / 密码	RabbitMQ 账号密码。
虚拟主机	RabbitMQ Virtual Host。账号必须拥有该虚拟主机的写入权限。
交换机名称	发布消息使用的交换机名称。
交换机类型	交换机类型，例如 direct、topic、fanout、headers，必须与 RabbitMQ 中实际交换机一致。
声明队列	是否由插件自动声明队列。队列由平台统一创建时建议关闭。
声明交换机	是否由插件自动声明交换机。没有创建权限时应关闭。
启用发布确认	开启后等待 RabbitMQ Broker 返回发布确认。对消息可靠性要求高时保持开启；关闭后吞吐可能更高，但发布失败不一定能及时发现。
要求路由成功	开启后要求消息至少路由到一个队列。Routing Key 没有匹配队列绑定时会按失败处理，便于发现“发布成功但无人消费”的配置问题。
发布超时时间	单次发布等待时间，单位毫秒。
Topic 模板	在 RabbitMQ 中作为 Routing Key 使用。Routing Key 必须匹配队列绑定规则，否则消费者可能收不到消息。

RabbitMQ 中“交换机”和“队列”是两层概念：目标把消息发布到交换机，Topic 模板展开后的值作为 Routing Key，队列通过绑定规则接收匹配的消息。消息发布失败时，先查看“启用发布确认”和“要求路由成功”的结果；消息显示发布成功但消费者无数据时，优先检查虚拟主机、交换机名称、交换机类型、队列绑定和 Routing Key 是否一致。

ThingsBoard 目标属性

ThingsBoard 目标用于按 ThingsBoard Gateway MQTT 协议上传遥测、属性并接收 RPC。选择该目标后，按普通 MQTT 客户端方式填写 Broker 地址、端口、WebSocket、TLS、客户端 ID、用户名和密码。

配置项	说明
IP 地址 / 端口	ThingsBoard MQTT 接入地址和端口。普通 MQTT 常用 1883，TLS 常用 8883，以平台配置为准。
用户名 / 密码	ThingsBoard 设备凭据或网关凭据。平台使用 Access Token 时，通常把 Token 填入用户名，密码留空或按平台要求填写。
启用 SSL	ThingsBoard 使用 TLS 接入时开启，并选择 CA、客户端证书或允许不受信任证书。生产环境建议配置可信 CA。
客户端 ID	MQTT 客户端标识。平台要求固定客户端 ID 时填写；不要求时可留空。
QoS 等级 / 保留消息	按 ThingsBoard 接收策略选择。遥测数据通常不建议使用保留消息。
详细日志	联调 ThingsBoard Topic、认证或 RPC 时临时开启。
缓存与队列	使用“启用离线缓存、缓存文件最大行数、上传分片大小、内存队列上限、过滤离线数据、并发上传数量”控制离线补发。

ThingsBoard 目标按平台约定发送固定主题：遥测数据发送到网关遥测主题，设备属性发送到网关属性主题，RPC 请求从网关 RPC 主题接收。配置时重点确认平台侧网关设备是否已创建、凭据是否正确、变量所属设备名称是否能映射到 ThingsBoard 设备。

ThingsBoard 不需要在页面中维护普通 MQTT 的变量 Topic 模板、实体脚本或上传模板配置，也不提供“数据1至数据10”这类通用变量字段。变量所属设备名称会作为平台侧设备识别信息的一部分；设备名不一致时，平台可能无法把遥测归到预期设备。

Modbus 从站目标属性

Modbus 从站用于把网关内变量映射为 Modbus 寄存器，供上位机或其它主站读取、写入。配置时先确定通讯方式，再配置变量的从站地址。

配置项	说明
通道类型	选择目标运行方式。TcpService 表示网关监听端口等待主站连接；TcpClient 表示网关主动连接远端；SerialPort 表示串口从站；UdpSession 表示 UDP 会话。
远程地址	TcpClient 或 UDP 场景使用，填写远端 IP:端口 或 域名:端口；现场要求带协议时按要求填写 tcp://、ssl:// 等前缀。
本地绑定地址	TcpService 或 UDP 场景使用，填写本机监听地址，例如 0.0.0.0:502；启用 TLS 监听时可按现场约定填写 ssl://0.0.0.0:端口。
启用 SSL	TCP 场景下启用 TLS。启用后按现场证书要求选择服务端证书、客户端证书或 CA 证书。
SSL 目标主机名	客户端模式校验证书时使用，通常填写证书中的域名。
允许不受信任证书	调试自签名证书时可临时开启；生产环境建议关闭。
串口 / 波特率 / 数据位 / 校验位 / 停止位	串口模式使用，必须与主站或串口服务器配置一致。
DTR / RTS / 握手方式	串口硬件流控相关配置。现场没有明确要求时保持默认。
最大并发数	同时处理请求的数量。主站要求严格顺序访问时保持 1；确认主站和链路能承受并发请求后再增大。
组包缓存时间	通道等待一帧报文组装完成的时间窗口，单位毫秒，最小 100。它用于处理 TCP 粘包、拆包或串口分段到达，不是变量值缓存。主站报文经常被拆成多段、日志中出现半包或解析失败时可适当增大；设置过大会增加请求响应延迟。
连接超时 / 最大连接数 / 客户端清理时间	TCP 服务端连接管理参数。上位机数量较多时确认最大连接数足够。
心跳内容 / 心跳是否 Hex / 心跳时间	TCP 客户端模式下可用于保持连接。心跳是否 Hex 开启后，内容按十六进制字节解析。
DtuId / DtuId 是否 Hex / Dtu 服务类型	DTU 或透传终端编号，用于识别哪台远端设备正在接入。终端上报文本编号时直接填写；上报十六进制字节时开启 DtuId 是否 Hex。
Modbus 类型	选择 ModbusTcp 或 ModbusRtu，需与主站访问方式一致。
默认站号	未在变量地址中单独指定站号时使用。
数据解析顺序	多字节数值的字节序。主站读到数值颠倒或异常时重点检查。
字符串反转字节	外部主站读写字符串出现相邻字节颠倒时开启。它只影响字符串类数据，不用于调整整型或浮点数的字节序。
多站点模式	需要一个从站目标响应多个站号时开启。
允许 RPC 写入 / 立即写入内存	控制外部系统是否允许反写网关变量，以及写入请求是否先立即更新从站内存值。
发送延时时间	从站响应前的等待时间，单位毫秒。部分串口链路、网关透传或老旧主站要求响应节奏较慢时可设置。
客户端权限列表	TCP 服务端模式下按客户端 IP 控制访问和写入。列表为空时不按 IP 限制；列表不为空时，未命中的 IP 不能访问该从站，命中的 IP 再按“是否允许写入”决定能否写入。* 表示匹配所有客户端；需要允许所有客户端读取但禁止写入时，可配置 * 并关闭“是否允许写入”。

变量属性中最重要的是“从站变量地址”和“数据类型”。从站变量地址应按 Modbus 主站将要读取的寄存器地址填写，例如线圈、输入寄存器或保持寄存器地址；数据类型要与主站解析方式一致。某个变量不允许外部主站写入时，关闭该变量属性中的“允许 RPC 写入”。

DTU 接入时，DtuId 用于识别哪台远端终端正在连接。终端上报文本编号时直接填写文本；上报十六进制字节时开启 DtuId 是否 Hex。主站需要只读访问时，应同时关闭目标级和变量级写入权限，或在客户端权限列表中配置 * 并关闭写入。客户端权限列表一旦填写，未匹配到的 TCP 客户端不能访问该从站。

客户端权限列表只约束 TCP 服务端接入的客户端。串口、TCP 客户端主动连接、UDP 会话不按该列表筛选访问端。列表中的空行不会保存；需要允许多个上位机时，为每个 IP 单独添加一行，或使用 * 作为兜底规则。

Webhook 目标属性

Webhook 用于把变量、设备、报警或插件事件通过 HTTP 请求推送到外部系统。Webhook 的 Topic 模板就是请求 URL，因此需要把变量 Topic、设备 Topic、报警 Topic 或插件事件 Topic 填写为实际接口地址。

配置项	说明
签名密钥	钉钉机器人加签模式使用。企微、飞书或普通 HTTP 接口不需要时留空。
自定义请求头	JSON 格式请求头，例如 {"Authorization":"Bearer token"}。用于对接需要 Token 或自定义 Header 的系统。
消息格式	Raw 直接发送默认 JSON 或模板内容；Text 适合钉钉、企微、飞书文本消息；Markdown 适合钉钉、企微 Markdown 消息。
请求超时(秒)	外部接口响应超时时间。接口慢时可增大，过大则会延长失败重试周期。
Topic 模板	在 Webhook 中作为 URL 使用。对应 Topic 为空时，该类数据不会发送。
上传模板配置	外部接口要求固定 JSON 字段、文本格式或机器人消息格式时使用。

Webhook 的“变量 Topic 模板、设备 Topic 模板、报警 Topic 模板、插件事件 Topic 模板”都表示请求 URL。对接钉钉、企业微信或飞书机器人时，把机器人 Webhook 地址填到需要发送的数据类型 Topic 中，再按机器人要求选择 Text 或 Markdown。

上传模板配置

MQTT、Kafka、RabbitMQ、Webhook 等目标的“上传模板配置”用于改写消息体。点击该字段旁的配置按钮后，会打开模板配置弹窗。

配置项	说明
变量内容模板	变量数据上传时使用。可用 ${Name}、${Value}、${DeviceName}、${CollectTime}、${CollectGroup}、${Remark1} 至 ${Remark5} 等占位符。
设备内容模板	设备状态上传时使用。适合外部系统要求固定设备字段名或固定 JSON 结构的场景。
报警内容模板	报警和恢复事件上传时使用。建议保留报警名称、等级、触发值、事件时间和处理所需的设备信息。
插件事件内容模板	插件事件上传时使用。用于把插件连接、断开、错误或其它事件转换为外部系统需要的内容。

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

模板字段名必须与外部系统约定一致。模板写错时，目标仍可能完成发送，但外部系统会因为字段缺失、格式不对或时间格式错误而无法入库或解析。

SyncBridge 目标属性

SyncBridge 用于在两个 ThingsGatewayRuntime 之间同步通道、设备、变量和变量变化数据。配置时需要一端提供服务端监听，另一端作为客户端连接；两端校验令牌必须一致。

配置项	说明
IsServer（服务端模式）	开启后该目标等待另一端连接；关闭后该目标主动连接服务端地址。两端不能都关闭服务端模式，否则没有一端监听。
IsMaster（主端模式）	开启后作为主端发起同步；关闭后作为从端接收或响应同步。双端联动时只让一端作为主端，避免同步方向混乱。
UpdateChange（同步变量变化）	开启后同步变量变化事件，适合需要两端变量值实时同步的场景。只同步配置时关闭。
ServerUri（服务端地址）	客户端模式下填写可访问的服务端地址，例如 192.168.1.20:7777。服务端模式下该项不作为连接目标使用。
VerifyToken（校验令牌）	同步桥连接校验令牌。两端必须完全一致，生产环境应改为强度较高的值。
HeartbeatInterval（心跳间隔）	心跳间隔，单位毫秒，最小 3000。网络不稳定时可适当增大，过小会增加心跳压力并放大网络抖动影响。

配置建议：

1. 先在服务端所在网关新增 SyncBridge 目标，开启“服务端模式”，并设置校验令牌。
2. 再在客户端所在网关新增 SyncBridge 目标，关闭“服务端模式”，服务端地址填写第一台网关的可访问地址，校验令牌填写相同值。
3. 只让一端开启“主端模式”，避免两端同时作为主端反复同步。
4. 启用后查看转发目标日志，确认连接、心跳和同步结果。

历史数据目标属性

历史数据目标用于把变量值写入历史数据库。它适合报表、追溯、趋势分析和长周期存储。配置前应先确认数据库账号有建表、写入和清理历史数据的权限。

配置项	说明
数据库类型	选择目标数据库类型，应与连接字符串和驱动环境一致。
自定义 SQL 模式	开启后按自定义模板或脚本组织历史表结构和写入语句。不了解目标表结构时保持关闭。
分表策略	控制历史数据是否按时间等策略拆分到不同表，变量量大或保存周期长时用于降低单表压力。
连接字符串	数据库连接信息，包含服务器、端口、库名、账号、密码和加密策略。生产环境不要使用默认示例密码。
数值历史表名 / 字符串历史表名	数值类变量和字符串类变量分别写入的表名。外部报表已固定表名时需保持一致。
保留天数	历史数据保留周期。设置过短会影响追溯，设置过长需要评估磁盘容量。
历史表脚本	用于自定义建表或写入逻辑。只有数据库表结构有特殊要求时使用。
时区偏移	写入时间的时区，例如 +08:00。跨时区部署或数据库统一使用 UTC 时要特别确认。
强制插入	开启后收到数据就写入历史库，不再按采样策略减少写入量。变量多或周期短时会显著增加数据库压力。
默认采样策略	未单独配置变量属性时采用的采样方式。变化采样适合状态量，间隔采样适合固定周期趋势，条件采样适合按表达式判断是否入库。
默认采样间隔	默认采样策略为间隔时使用，单位毫秒。
默认条件表达式	默认采样策略为条件时使用，表达式返回满足条件才写入。
自定义模板配置	自定义 SQL 模式下维护字段模板。外部数据库表名、字段名或写入规则固定时使用；不了解外部表结构时保持关闭，使用系统默认表结构。
缓存与队列	数据库不可用时可开启离线缓存；上传分片大小控制每批写入数量；并发上传数量需要结合数据库承载能力设置。
双库镜像	可选备用数据库和一致性维护参数。用于同一历史目标同时保留两份数据库副本；启用前先阅读下方支持范围。

“强制插入”和“采样策略”不要同时当作普通开关理解：强制插入开启后，只要转发组产生数据就写入历史库；关闭后才主要依赖默认采样策略或变量属性采样策略控制入库频率。

历史数据冗余可靠性

在启用网关冗余并保持历史可靠性开启时，历史数据目标的标准 SQL 写入链路会记录本机 Journal，并在切换、断线恢复或重启后补写未完成入库的记录。写入时会使用记录唯一键进行去重，避免同一条历史数据因主备重放或重启补发被重复写入。

检查项	说明
数据库类型	使用 SqlServer、MySql、Sqlite 或 PostgreSql。
写入模式	关闭自定义 SQL 模式，不填写历史表脚本，使用系统默认历史表结构。
缓存配置	对追溯要求高的目标建议开启离线缓存，并按断网时间和变量写入量配置缓存文件最大行数、上传分片大小和磁盘容量。
不适用范围	QuestDB、TDengine、自定义 SQL、历史表脚本或其它动态写入逻辑不纳入该去重与补写机制，需要由现场自行验证。

目标详情中的“可靠历史”标签和“Journal目标键”可用于确认该历史数据目标是否纳入主备补偿。需要查看待对端同步、待写入数据库或单条 Journal 事件时，进入“系统管理 → 系统设置 → 双机热备”的“历史数据保护”区域。

双库镜像

历史数据目标和历史报警目标都可在各自的“双库镜像”配置中启用主库、备用库同步写入与一致性维护。启用前先准备两个独立的物理数据库位置，并确认表结构、账号权限、网络和磁盘容量均满足长期写入要求。

配置项	说明
启用	开启主库与备用库双写、Journal 和一致性维护。关闭时目标只写主库。
备用库类型 / 连接字符串	选择备用数据库并填写连接信息。主库和备用库必须指向不同物理数据库，不能只填写同一实例、同一文件或同一目标的等价连接串。
Journal 最大待提交量	限制尚未提交到两库的事件数量。需要按峰值写入量和最长故障时间配置，并预留本机磁盘空间。
对端待复制上限	限制一侧数据库可见、但尚未复制到另一侧的事件数量。持续接近上限时应检查备用库连通性、账号权限和写入性能。
一致性检查间隔	按分钟定时比较两库；填 0 表示不启动定时检查。大时间范围和高写入量会增加数据库负载。
自动修复	定时检查发现缺失记录后执行双向补齐。生产启用前先通过手动比较和修复验证表结构、时间范围与写入权限。

目标详情可查看主库、备用库、Journal 和积压状态，按指定时间范围比较两库，并选择“主库 → 备用库”或“备用库 → 主库”补齐缺失记录。手动修复前先确认方向，避免把错误一侧当作权威数据源。

支持边界

双库镜像仅支持 SqlServer、MySql、Sqlite、PostgreSql 的标准历史数据表和标准历史报警表。QuestDB、TDengine、自定义 SQL 模式、历史表脚本、历史报警表脚本不支持。双库镜像保护一个转发目标的两个数据库副本；双机热备历史补偿保护两个网关节点之间的待写事件，二者相互独立，可按现场需求分别启用。

历史数据变量属性

在目标变量属性抽屉中，可为单个变量覆盖历史入库规则。

配置项	说明
采样策略	控制该变量在当前历史数据目标中的入库方式。
采样间隔	间隔采样时使用，单位毫秒。
条件表达式	条件采样时使用，适合只在设备运行、工艺允许或数值达到条件时记录历史。

实时数据目标属性

实时数据目标用于把变量最新值写入实时表，供外部系统读取当前状态。与历史数据不同，实时表更关注“当前值”，通常每个变量保留最新记录。

配置项	说明
数据库类型	选择实时数据写入的数据库类型。
连接字符串	实时库连接信息。账号需要具备建表、更新和写入权限。
实时表名	保存变量最新值的表名。外部系统已按固定表名读取时，需要与对方约定一致。
实时表脚本	自定义实时表结构或写入逻辑。只有对接已有表结构时使用。
时区偏移	写入时间的时区。需要和外部系统展示时间保持一致。
缓存与队列	实时数据也可配置缓存和队列。实时性要求高时不要把上传分片设置过大。

历史报警目标属性

历史报警目标用于保存报警和恢复事件，供报警追溯、统计和导出。配置前应确认转发组范围包含需要记录报警的变量。

配置项	说明
数据库类型	选择历史报警写入的数据库类型。
分表策略	报警量大或保留周期长时使用，便于分期保存和查询。
连接字符串	历史报警库连接信息。
历史报警表名	保存报警事件的表名。
保留天数	历史报警保留周期。需要满足现场审计或追溯要求。
历史报警表脚本	自定义报警表结构或写入逻辑。
时区偏移	报警事件时间写入时使用的时区。
最小报警等级	只保存该等级及以上的报警。等级越高通常越严重；如果希望记录全部报警，保持较低等级。
缓存与队列	数据库短时不可用时用于缓存报警事件。报警数据通常应开启缓存并确认磁盘空间。
双库镜像	可选备用数据库和一致性维护参数；配置方式和支持边界与上方“双库镜像”一致。

最小报警等级用于减少低级别报警入库。设置为 3 时，只保存等级大于等于 3 的报警；如果现场需要完整追溯，不要把该值设得过高。

历史报警冗余可靠性

在启用网关冗余并保持历史可靠性开启时，历史报警目标的标准 SQL 写入链路会记录本机 Journal，并在切换、断线恢复或重启后补写未完成入库的报警和恢复事件。写入时会使用记录唯一键进行去重，避免同一报警事件因主备重放或重启补发被重复写入。

检查项	说明
数据库类型	使用 SqlServer、MySql、Sqlite 或 PostgreSql。
写入模式	不填写历史报警表脚本，使用系统默认历史报警表结构。
缓存配置	报警用于追溯或审计时建议开启离线缓存，并预留足够磁盘空间，避免数据库短时不可用或重启期间产生记录缺口。
不适用范围	历史报警表脚本或其它动态写入逻辑不纳入该去重与补写机制，需要由现场自行验证。

目标详情中的“可靠历史”标签和“Journal目标键”可用于确认该历史报警目标是否纳入可靠同步。若报警恢复或报警产生后长时间未补写，优先检查目标日志、CacheDB 出站队列、系统设置中的 Journal 状态和 Epoch 租约。

目标变量属性

当外部系统需要变量级映射时，选中转发目标，点击目标卡片中的“变量属性”按钮，打开目标变量属性抽屉。

配置项	说明
变量	选择要配置的变量。可选范围受转发组变量范围影响。
插件变量属性	由目标插件提供。没有变量级属性的目标，无需维护该部分配置。
新增变量属性	清空当前编辑状态，开始新增一条变量属性。
添加/更新变量属性	保存当前变量属性配置。
已配置变量列表	显示当前目标下已配置变量，可继续编辑或删除对应变量属性。

手动选择范围下，应先在转发组的组变量中加入变量，再到目标变量属性中配置该变量的外部映射。目标变量属性只决定“这个目标如何使用该变量”，不决定变量是否属于转发组。

如果转发组是手动选择范围，目标变量属性里保存的变量必须先存在于组变量中。直接在目标变量属性中新增变量映射，不会把该变量加入转发组，也不会让它开始转发。各插件提供的目标变量属性字段见 插件属性详表。

常见用途：

1. 为变量配置外部系统中的字段名、地址或点位编号。
2. 为 Modbus 从站变量设置从站变量地址、数据类型和写入权限。
3. 为 MQTT、Kafka、RabbitMQ、Webhook 等目标维护数据1至数据10等自定义字段，供上传模板或外部系统识别使用。

ThingsBoard 目标的变量属性只用于控制“允许 RPC 写入”，不维护数据1至数据10；历史数据目标的变量属性用于覆盖采样策略、采样间隔和条件表达式。维护目标变量属性前，应先确认当前目标插件实际提供的字段。

调试转发目标

选中目标后，在右侧详情区点击“调试”。目标必须启用并进入运行态后才会显示对应调试页；禁用目标不会显示调试页。

MQTT Client 发布与订阅

功能	说明
发布消息	填写 Topic、Payload、QoS、Retain 后发布一条测试消息。
状态与订阅	查看连接状态，新增订阅 Topic，刷新订阅列表，取消订阅。
消息日志	查看调试 WebSocket 状态和收发消息。

MQTT Server 状态监控

功能	说明
主题统计	查看各 Topic 的订阅数量。
客户端列表	查看 ClientId、用户名、远端地址和连接时间。
踢出客户端	断开指定客户端连接。执行前确认不会影响生产通信。

Kafka 与 RabbitMQ 发布

目标	调试项	排查重点
Kafka	Topic、消息内容、发布按钮	服务地址、认证、安全协议、Topic 权限、超时。
RabbitMQ	Routing Key、消息内容、发布按钮	交换机、虚拟主机、队列绑定、账号密码、Routing Key。

日志查看

详情区提供“转发组日志”和“转发目标日志”两个标签。目标无法启动、发布失败、冗余未切换时，优先查看目标日志，再回到配置抽屉检查连接参数。

日志	说明
转发组日志	组级范围计算、触发、批处理和组运行错误。
转发目标日志	外部连接、发布、缓存、队列和插件运行错误。
日志级别	调试时使用 Debug 或 Trace，排查结束后恢复 Info。
导出	需要归档或提交问题时，可导出日志并记录目标配置。

目标冗余

目标冗余用于主备转发目标。主目标异常时，系统可切换到备用目标继续转发，减少数据转发中断时间。

配置项	说明
主目标	开启冗余的目标。
备用目标	同一转发组下的其它普通目标。建议使用相同插件类型，并单独填写备用系统的连接地址、账号、Topic、模板和缓存配置。
故障切换	主目标离线或异常时切换到备用目标。
脚本触发	通过脚本判断是否切换，适合更复杂的业务条件。
扫描间隔	系统检查冗余状态的周期。
手动切换	目标卡片中出现冗余切换操作时，可手动切换主备。

配置注意：

1. 主目标和备用目标必须在同一转发组内。
2. 一个备用目标不要同时作为多个主目标的备用目标。
3. 作为备用目标的目标不应再开启自己的冗余配置。
4. 主备目标的变量范围来自同一转发组，但插件属性仍需分别配置。
5. 备用目标只是接管发送，不会自动复制主目标的连接参数。上线前应手动切换一次，确认备用目标能正常发送。

脚本切换模式下，脚本返回值决定是否切换。脚本异常、脚本未选择或返回结果不符合预期时，冗余不会按业务条件切换；排查时先查看转发目标日志，再检查脚本输入和返回值。

导入导出

页面提供数据转发配置导入、导出能力，适合备份、迁移和批量调整。

功能	说明
导出配置	导出当前数据转发配置，包含转发组、目标和相关变量配置。
导入配置	从配置文件导入转发组、目标和变量属性。
导入结果	导入后查看失败行和错误信息，按提示修正后重新导入。

常见问题

现象	处理建议
转发目标没有启动	检查目标和所属转发组是否启用，插件是否启用，目标连接参数是否正确。
没有数据发出	检查转发组变量范围、变量启用状态、触发模式、在线过滤和组变量成员。
定时转发不触发	确认触发模式包含定时，并检查定时间隔是否为毫秒数或 Cron 定时表达式。
变化转发不触发	确认变量实际发生变化；若希望某变量唤醒整组，检查“组触发”。
MQTT 发布失败	检查 Broker、端口、TLS、账号密码、Topic 权限和目标日志。
Kafka 发布失败	检查服务地址、认证、安全协议、Topic 权限和发布超时。
RabbitMQ 发布失败	检查交换机、Routing Key、虚拟主机、队列绑定和认证。
目标冗余未切换	检查主目标冗余配置、备用目标选择、扫描间隔和脚本返回值。
CacheDB 积压持续增长	检查外部系统是否恢复、目标是否在线、上传分片和并发数是否过小、数据库或 Broker 是否限流；必要时导出目标日志并评估磁盘空间。
可靠历史显示不支持	检查目标是否为历史数据或历史报警目标，数据库类型是否为 SqlServer、MySql、Sqlite 或 PostgreSql，是否启用了自定义 SQL 或历史表脚本。
历史数据保护存在待对端同步 / 待写入数据库	在“系统设置 → 双机热备 → 历史数据保护”中按目标键筛选，确认对端链路、目标数据库、数据库写入授权和离线缓存恢复情况。
调试页为空	确认已选中转发目标，并且目标已启用并进入运行态。

相关链接

• 设备调试
• 插件属性详表
• 插件参考
• 系统日志