反向 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 调试发布。 |
变量写入弹窗可用于现场快速验证变量本身是否支持写入。
权限配置建议
| 账号类型 | 建议权限 |
|---|---|
| 只读集成账号 | 只授予数据查询接口，不授予变量写入、调试写入和重启类接口。 |
| 控制集成账号 | 仅授予指定写入链路需要的变量写入或 MQTT/调试接口权限。 |
| 运维账号 | 可授予变量写入、设备调试、日志查询和日志导出权限。 |
| 管理员账号 | 才授予角色授权、菜单维护、系统设置和重启权限。 |
菜单按钮授权只控制 Web 页面可见入口；API 授权控制接口调用能力。生产环境应同时检查两类权限。
选择写入接口
Web API 写入
Web API 写入适合上位系统、MES、SCADA、运维平台或自研程序直接调用 TGateway。
| 步骤 | 操作 |
|---|---|
| 登录 | 调用认证接口获取 Bearer Token，或在 Web 已登录状态下调试。 |
| 授权 | 在“系统管理 → 角色管理 → 授权”中为集成账号角色分配变量写入 API 权限。 |
| 写入 | 调用当前 API 文档中的变量写入接口：/api/gatewaywritevariablecontroller/setvariablevalue。 |
| 验证 | 在变量列表、变量详情、设备日志或 RPC 日志中确认写入结果。 |
API 权限可在角色授权抽屉中搜索变量写入相关权限。
请求体通常按“设备名称 → 变量名称 → 写入值”的结构组织。接口路径、认证方式和返回结构请按 网关 API 文档 中的接口说明调用。
请求体及每个设备对应的变量对象不能为 null。出现这种结构错误时，整批请求会在写入前被拒绝，并记录一条失败 RPC 日志。空设备对象 {} 不执行写入；变量值本身为 null 时，仍按插件的写入合同处理。
通过变量绑定采集插件特殊方法
变量配置了“特殊方法（其他方法）”后，同一个变量写入接口会执行插件方法，而不是普通点位写入。方法变量仍需满足可写、允许 RPC 写入、设备未暂停和角色授权等前置条件。
例如，OPC UA 客户端的方法变量选择 CallMethodByNodeIdAsync，变量地址填写对象节点与方法节点，外部请求把方法输入参数作为变量值：
{
"OPC设备": {
"启动方法": [123, "start"]
}
}
参数的最外层数组表示方法参数列表。方法只有一个数组参数时应提交双层数组，例如 [[1, 2, 3]]。具体变量配置和 OPC UA 参数转换规则见 OPC UA 客户端。MQTT RPC 脚本解析出相同的设备名称、变量名称和 JSON 值后，也会进入同一方法调用链路。
不绑定变量，直接调用插件方法
在设备或转发目标的基本配置中开启“允许方法调用”，即可通过正式 Web API、MQTT 方法主题、OPC UA 原生 Method、调试页或规则特殊方法节点调用该实例公开的全部直接方法。默认关闭，不再单独配置方法或调用者白名单；变量 RPC 权限继续独立生效。
正式 Web API 为 POST /api/gatewayrpccontroller/invokepluginmethod，需要登录及 rpc:invoke_plugin_method API 权限。请求按实例类型、编号、方法名称和位置参数组织，无业务请求编号、去重或调用容量策略。MQTT 方法主题为固定请求主题，响应加 /Response，与下文变量 RPC 使用编号的格式不同。完整步骤、返回状态、超时和日志见插件方法调用。
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 | 接收 Source="TGateway" 和唯一 RequestId 的 JSON 请求，按目标配置上传快照，并在 请求Topic/Response/RequestId 返回完成标记。具体格式见MQTT 客户端转发。 |
| RPC 脚本 | RPC 消息脚本，用于自定义请求解析、写入目标选择、结果处理或响应结构。 |
| QoS 等级 | RPC 消息发布/订阅质量等级。关键写入建议结合 Broker 能力选择合适 QoS。 |
| 用户名 / 密码 | Broker 认证信息。 |
| 启用 SSL / TLS 证书配置 | TLS 场景下的证书、CA、目标主机和协议配置。 |
MQTT Client 调试页可用于验证发布和订阅链路。
| 调试项 | 说明 |
|---|---|
| 发布消息 | 填写 Topic、Payload、QoS、Retain 后发布测试消息。 |
| 状态与订阅 | 管理网关目标自身的主题订阅，新增或取消订阅 Topic。 |
| 目标日志与独立接收端 | 目标日志用于检查连接、订阅和处理错误；请求与响应正文在独立 MQTT 客户端中按 Topic 和请求编号核对。 |
先在独立客户端订阅响应 Topic，再发送一次带唯一编号的测试请求。逐变量检查响应结果，并用源设备或独立协议读取确认实际值；发布成功和 QoS 确认不能代替写入结果。完整请求示例见验证外部写入。
OPC UA Server 与 Modbus Slave
服务端类插件允许外部客户端主动连接网关，再通过协议写入节点或寄存器。
| 插件类型 | 写入方式 | 重点配置 |
|---|---|---|
| OPC UA Server | 外部 OPC UA 客户端写入网关暴露的节点。 | 服务地址、安全策略、用户名密码、服务端证书、目标级写入开关和变量级写入开关。 |
| Modbus Slave | 外部 Modbus 主站写入线圈或保持寄存器。 | 监听地址、站号、从站变量地址、变量数据类型、目标级写入开关、变量级写入开关、客户端权限列表。 |
OPC UA Server 关闭“安全策略”时发布 None 端点并允许匿名，单独填写用户名密码不会关闭匿名。开启后使用 SignAndEncrypt，不再发布 None 或匿名令牌；客户端需同时满足应用证书信任和所选用户身份。写入还必须通过目标配置及变量属性中的“允许RPC写入”，以及源变量的写权限。证书与用户身份配置见OPC UA 服务端。
Modbus Slave 的“客户端权限列表”只对 TCP 服务端模式接入的客户端 IP 生效。列表为空时不按 IP 限制；列表不为空时，未命中的 TCP 客户端不能访问该从站；命中的客户端再按“是否允许写入”决定能否写入。* 表示匹配所有客户端。只允许读取时，可配置 * 并关闭“是否允许写入”；只允许指定上位机写入时，按上位机 IP 分条配置。
Modbus Slave 写入还要通过目标级、变量级“允许RPC写入”和源变量写权限。“立即写入内存”控制协议写入成功后是否立即保留到从站内存；关闭它不会禁止已映射变量调用现场 RPC，采集反馈仍会更新服务值。未映射地址的内存读写也不能证明现场已写入。详细权限和验证见Modbus 服务端。
调试与验证
反向 RPC 上线前建议按以下顺序验证：
- 在“采集配置”中确认变量读写类型、数据类型、地址和写入检查。
- 使用变量列表的“写入”弹窗验证单变量能否成功写入。
- 在采集配置中选择设备，使用“更多功能 → 调试”验证协议地址读写能力。
- 如果走 MQTT，使用调试页检查连接与协议操作，再在独立客户端按 Topic 和请求编号核对请求、响应及源端回读。
- 如果走 Web API，使用角色授权抽屉确认 API 权限，再查看 RPC 日志和操作日志。
Foundation 调试页适合验证通用地址读写。
常见问题
| 现象 | 处理建议 |
|---|---|
| Web API 返回无权限 | 检查当前用户角色是否拥有变量写入 API 权限，并重新登录或刷新权限。 |
| 写入按钮不可见 | 检查菜单按钮授权、变量读写权限和页面按钮权限。 |
| 写入失败但接口已调用 | 检查变量数据类型、写入值格式、设备在线状态和设备日志；开启写入检查时，确认回读值是否能立即等于写入值。 |
| MQTT 无响应 | 检查 RPC 写入 Topic、订阅 Topic、Broker 认证、QoS、TLS 和消息日志。 |
| 变量绑定方法没有执行 | 检查变量选择的方法、变量写权限、RPC 写入开关和设备暂停状态。 |
| 直接方法没有执行 | 检查被调用设备或目标的“允许方法调用”、运行状态、方法目录和参数；查看 RPC 日志中的状态和消息。 |
| OPC UA 写入失败 | 检查证书信任、安全策略、用户名密码、目标级写入开关、变量级写入开关和节点可写状态。 |
| Modbus 写入无效 | 检查站号、寄存器地址、功能码、数据类型、字节序、目标级写入开关、变量级写入开关和客户端权限列表。 |
| 写入后变量值又恢复 | 现场设备可能拒绝写入，或采集周期重新读回真实值；查看设备日志确认。 |