反向 RPC 详解

反向 RPC 不是一个单独菜单，而是外部系统通过 Web API、MQTT、OPC UA Server、Modbus Slave 等入口向 TGateway 发起写入或控制请求的能力集合。使用前需要同时确认变量写入权限、角色授权和对应协议入口配置。

先看术语

术语	现场理解
反向 RPC	外部系统主动调用网关。现场可理解为“上位系统反向下发写入、控制或查询请求”。
RPC 写入	外部系统反写点位。只有控制类点位、且现场确认允许远程控制时才建议开启。
RPC 写入 Topic	MQTT 场景下外部系统发送写入请求的主题前缀。请求和响应 Topic 必须按双方约定一致。
目标级写入开关	转发目标或服务端插件上的总开关，关闭后该目标下的变量不能被外部系统写入。
变量级写入开关	单个变量上的写入开关，只有目标级和变量级都允许时，外部系统才可写入该变量。
Broker	MQTT 消息服务端，负责接收和分发 Topic 消息。

反向 RPC 的含义

在 TGateway 中，反向 RPC 可以理解为“外部系统反向调用网关写入能力”。外部系统不是只被动接收网关上传的数据，而是可以向网关发起写入、控制或查询请求；网关完成权限校验、变量校验和插件写入后，再返回执行结果。

链路	说明
Web API 写入	外部系统登录后调用变量写入接口。
MQTT RPC	外部系统向约定 Topic 发布 RPC 请求，网关处理后发布响应。
OPC UA Server	外部 OPC UA 客户端写入网关暴露的节点。
Modbus Slave	外部 Modbus 主站写入网关映射的线圈或寄存器。
调试页写入	运维人员在 TGateway Web 中通过变量写入弹窗或设备调试页验证写入链路。

写入前置条件

反向 RPC 是否成功，不只取决于外部请求格式，还取决于变量、权限和插件能力。

检查项	说明
变量读写权限	变量应允许写入。只读变量不应执行写入。
RPC 写入开关（允许外部系统反写点位）	变量或插件属性中需要允许 RPC 写入时，应确认对应开关已开启。
写入检查	如果启用写入检查，写入成功后会再次读取变量并比较回读值。只写变量、写入后延迟生效、存在比例换算或回写取整的点位不宜随意开启。
插件写入能力	采集插件或服务端插件必须支持对应写入方式。
设备在线状态	写入真实设备时，通道和设备应处于可通信状态。
角色 API 权限	Web 用户或集成账号需要拥有对应 API 权限，例如变量写入、调试写入或 MQTT 调试发布。

变量写入弹窗可用于现场快速验证变量本身是否支持写入。

Web API 写入

Web API 写入适合上位系统、MES、SCADA、运维平台或自研程序直接调用 TGateway。

步骤	操作
登录	调用认证接口获取 Bearer Token，或在 Web 已登录状态下调试。
授权	在“系统管理 → 角色管理 → 授权”中为集成账号角色分配变量写入 API 权限。
写入	调用当前 API 文档中的变量写入接口：/api/gatewaywritevariablecontroller/setvariablevalue。
验证	在变量列表、变量详情、设备日志或 RPC 日志中确认写入结果。

API 权限可在角色授权抽屉中搜索变量写入相关权限。

请求体通常按“设备名称 → 变量名称 → 写入值”的结构组织。接口路径、认证方式和返回结构请按 网关 API 文档 中的接口说明调用。

调用采集插件特殊方法

变量配置了“特殊方法（其他方法）”后，同一个变量写入接口会执行插件方法，而不是普通点位写入。方法变量仍需满足可写、允许 RPC 写入、设备未暂停和角色授权等前置条件。

例如，OPC UA 客户端的方法变量选择 CallMethodByNodeIdAsync，变量地址填写对象节点与方法节点，外部请求把方法输入参数作为变量值：

{
  "OPC设备": {
    "启动方法": [123, "start"]
  }
}

参数的最外层数组表示方法参数列表。方法只有一个数组参数时应提交双层数组，例如 [[1, 2, 3]]。具体变量配置和 OPC UA 参数转换规则见 OPC UA 客户端。MQTT RPC 脚本解析出相同的设备名称、变量名称和 JSON 值后，也会进入同一方法调用链路。

MQTT RPC

MQTT RPC 适合外部系统已经使用 MQTT Broker 的场景。网关作为 MQTT Client Producer 或 MQTT Server 相关目标时，可通过目标属性配置 RPC Topic 和脚本。

配置项	说明
RPC 写入 Topic	外部系统发布写入请求的 Topic 前缀。填写 tg/rpc/write 时，请求发送到 tg/rpc/write/<请求标识>，响应从 tg/rpc/write/<请求标识>/Response 读取。
数据请求 Topic	外部系统请求最新数据快照的 Topic。收到消息后，网关会按目标配置上传变量、设备或报警数据。
RPC 脚本	RPC 消息脚本，用于自定义请求解析、写入目标选择、结果处理或响应结构。
QoS 等级	RPC 消息发布/订阅质量等级。关键写入建议结合 Broker 能力选择合适 QoS。
用户名 / 密码	Broker 认证信息。
启用 SSL / TLS 证书配置	TLS 场景下的证书、CA、目标主机和协议配置。

MQTT Client 调试页可用于验证发布和订阅链路。

调试项	说明
发布消息	填写 Topic、Payload、QoS、Retain 后发布测试消息。
状态与订阅	查看客户端连接状态，新增或取消订阅 Topic。
消息日志	观察调试 WebSocket、发布、订阅和响应消息。

OPC UA Server 与 Modbus Slave

服务端类插件允许外部客户端主动连接网关，再通过协议写入节点或寄存器。

插件类型	写入方式	重点配置
OPC UA Server	外部 OPC UA 客户端写入网关暴露的节点。	服务地址、安全策略、用户名密码、服务端证书、目标级写入开关和变量级写入开关。
Modbus Slave	外部 Modbus 主站写入线圈或保持寄存器。	监听地址、站号、从站变量地址、变量数据类型、目标级写入开关、变量级写入开关、客户端权限列表。

OPC UA Server 的“安全策略”开启后，客户端需要按签名或加密策略连接，并信任服务端证书；关闭时允许匿名连接。OPC UA 写入必须同时满足目标配置中的“允许RPC写入”和变量属性中的“允许RPC写入”，任一关闭都会使对应变量不可写。

Modbus Slave 的“客户端权限列表”只对 TCP 服务端模式接入的客户端 IP 生效。列表为空时不按 IP 限制；列表不为空时，未命中的 TCP 客户端不能访问该从站；命中的客户端再按“是否允许写入”决定能否写入。* 表示匹配所有客户端。只允许读取时，可配置 * 并关闭“是否允许写入”；只允许指定上位机写入时，按上位机 IP 分条配置。

Modbus Slave 写入还要同时满足目标级“允许RPC写入”和变量级“允许RPC写入”。“立即写入内存”开启后，外部主站写入会先更新网关中的从站内存值，便于主站立即读到新值；实际设备是否完成控制，还要看变量所属采集设备的写入结果。

调试与验证

反向 RPC 上线前建议按以下顺序验证：

1. 在“采集配置”中确认变量读写类型、数据类型、地址和写入检查。
2. 使用变量列表的“写入”弹窗验证单变量能否成功写入。
3. 在采集配置中选择设备，使用“更多功能 → 调试”验证协议地址读写能力。
4. 如果走 MQTT，使用 MQTT Client 或 MQTT Server 调试页验证 Topic、QoS 和消息日志。
5. 如果走 Web API，使用角色授权抽屉确认 API 权限，再查看 RPC 日志和操作日志。

Foundation 调试页适合验证通用地址读写。

权限配置建议

账号类型	建议权限
只读集成账号	只授予数据查询接口，不授予变量写入、调试写入和重启类接口。
控制集成账号	仅授予指定写入链路需要的变量写入或 MQTT/调试接口权限。
运维账号	可授予变量写入、设备调试、日志查询和日志导出权限。
管理员账号	才授予角色授权、菜单维护、系统设置和重启权限。

菜单按钮授权只控制 Web 页面可见入口；API 授权控制接口调用能力。生产环境应同时检查两类权限。

常见问题

现象	处理建议
Web API 返回无权限	检查当前用户角色是否拥有变量写入 API 权限，并重新登录或刷新权限。
写入按钮不可见	检查菜单按钮授权、变量读写权限和页面按钮权限。
写入失败但接口已调用	检查变量数据类型、写入值格式、设备在线状态和设备日志；开启写入检查时，确认回读值是否能立即等于写入值。
MQTT 无响应	检查 RPC 写入 Topic、订阅 Topic、Broker 认证、QoS、TLS 和消息日志。
特殊方法没有执行	检查变量是否选择了正确的特殊方法、读写权限是否为只写或可写、RPC 写入是否开启、设备是否暂停，并查看 RPC 日志中的参数或方法错误。
OPC UA 写入失败	检查证书信任、安全策略、用户名密码、目标级写入开关、变量级写入开关和节点可写状态。
Modbus 写入无效	检查站号、寄存器地址、功能码、数据类型、字节序、目标级写入开关、变量级写入开关和客户端权限列表。
写入后变量值又恢复	现场设备可能拒绝写入，或采集周期重新读回真实值；查看设备日志确认。

相关链接

• 采集配置
• 插件手册索引
• OPC UA 客户端
• 数据转发
• 角色管理
• 网关 API 文档