反向 RPC 详解
反向 RPC 不是一个单独菜单，而是外部系统通过 Web API、MQTT、OPC UA Server、Modbus Slave 等入口向 GatewayRuntime 发起写入或控制请求的能力集合。使用前需要同时确认变量写入权限、角色授权和对应协议入口配置。
先看术语
| 术语 | 现场理解 |
|---|---|
| 反向 RPC | 外部系统主动调用网关。现场可理解为“上位系统反向下发写入、控制或查询请求”。 |
| RPC 写入 | 外部系统反写点位。只有控制类点位、且现场确认允许远程控制时才建议开启。 |
| RPC 写入 Topic | MQTT 场景下外部系统发送写入请求的主题前缀。请求和响应 Topic 必须按双方约定一致。 |
| 目标级写入开关 | 转发目标或服务端插件上的总开关，关闭后该目标下的变量不能被外部系统写入。 |
| 变量级写入开关 | 单个变量上的写入开关，只有目标级和变量级都允许时，外部系统才可写入该变量。 |
| Broker | MQTT 消息服务端，负责接收和分发 Topic 消息。 |
反向 RPC 的含义
在 GatewayRuntime 中，反向 RPC 可以理解为“外部系统反向调用网关写入能力”。外部系统不是只被动接收网关上传的数据，而是可以向网关发起写入、控制或查询请求；网关完成权限校验、变量校验和插件写入后，再返回执行结果。
| 链路 | 说明 |
|---|---|
| Web API 写入 | 外部系统登录后调用变量写入接口。 |
| MQTT RPC | 外部系统向约定 Topic 发布 RPC 请求，网关处理后发布响应。 |
| OPC UA Server | 外部 OPC UA 客户端写入网关暴露的节点。 |
| Modbus Slave | 外部 Modbus 主站写入网关映射的线圈或寄存器。 |
| 调试页写入 | 运维人员在 GatewayRuntime Web 中通过变量写入弹窗或设备调试页验证写入链路。 |
写入前置条件
反向 RPC 是否成功，不只取决于外部请求格式，还取决于变量、权限和插件能力。
| 检查项 | 说明 |
|---|---|
| 变量读写权限 | 变量应允许写入。只读变量不应执行写入。 |
| RPC 写入开关（允许外部系统反写点位） | 变量或插件属性中需要允许 RPC 写入时，应确认对应开关已开启。 |
| 写入检查 | 如果启用写入检查，写入成功后会再次读取变量并比较回读值。只写变量、写入后延迟生效、存在比例换算或回写取整的点位不宜随意开启。 |
| 插件写入能力 | 采集插件或服务端插件必须支持对应写入方式。 |
| 设备在线状态 | 写入真实设备时，通道和设备应处于可通信状态。 |
| 角色 API 权限 | Web 用户或集成账号需要拥有对应 API 权限，例如变量写入、调试写入或 MQTT 调试发布。 |
变量写入弹窗可用于现场快速验证变量本身是否支持写入。
Web API 写入
Web API 写入适合上位系统、MES、SCADA、运维平台或自研程序直接调用 GatewayRuntime。
| 步骤 | 操作 |
|---|---|
| 登录 | 调用认证接口获取 Bearer Token，或在 Web 已登录状态下调试。 |
| 授权 | 在“系统管理 → 角色管理 → 授权”中为集成账号角色分配变量写入 API 权限。 |
| 写入 | 调用当前 API 文档中的变量写入接口：/api/gatewaywritevariablecontroller/setvariablevalue。 |
| 验证 | 在变量列表、变量详情、设备日志或 RPC 日志中确认写入结果。 |
API 权限可在角色授权抽屉中搜索变量写入相关权限。
请求体通常按“设备名称 → 变量名称 → 写入值”的结构组织。接口路径、认证方式和返回结构请按 网关 API 文档 中的接口说明调用。
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 上线前建议按以下顺序验证：
- 在“采集配置”中确认变量读写类型、数据类型、地址和写入检查。
- 使用变量列表的“写入”弹窗验证单变量能否成功写入。
- 使用“设备显示 → 设备详情 → 调试”验证协议地址读写能力。
- 如果走 MQTT，使用 MQTT Client 或 MQTT Server 调试页验证 Topic、QoS 和消息日志。
- 如果走 Web API，使用角色授权抽屉确认 API 权限，再查看 RPC 日志和操作日志。
Foundation 调试页适合验证通用地址读写。
权限配置建议
| 账号类型 | 建议权限 |
|---|---|
| 只读集成账号 | 只授予数据查询接口，不授予变量写入、调试写入和重启类接口。 |
| 控制集成账号 | 仅授予指定写入链路需要的变量写入或 MQTT/调试接口权限。 |
| 运维账号 | 可授予变量写入、设备调试、日志查询和日志导出权限。 |
| 管理员账号 | 才授予角色授权、菜单维护、系统设置和重启权限。 |
菜单按钮授权只控制 Web 页面可见入口；API 授权控制接口调用能力。生产环境应同时检查两类权限。
常见问题
| 现象 | 处理建议 |
|---|---|
| Web API 返回无权限 | 检查当前用户角色是否拥有变量写入 API 权限，并重新登录或刷新权限。 |
| 写入按钮不可见 | 检查菜单按钮授权、变量读写权限和页面按钮权限。 |
| 写入失败但接口已调用 | 检查变量数据类型、写入值格式、设备在线状态和设备日志；开启写入检查时，确认回读值是否能立即等于写入值。 |
| MQTT 无响应 | 检查 RPC 写入 Topic、订阅 Topic、Broker 认证、QoS、TLS 和消息日志。 |
| OPC UA 写入失败 | 检查证书信任、安全策略、用户名密码、目标级写入开关、变量级写入开关和节点可写状态。 |
| Modbus 写入无效 | 检查站号、寄存器地址、功能码、数据类型、字节序、目标级写入开关、变量级写入开关和客户端权限列表。 |
| 写入后变量值又恢复 | 现场设备可能拒绝写入，或采集周期重新读回真实值；查看设备日志确认。 |