OPC UA 客户端
连接 OPC UA 服务端的采集驱动
选择入口
进入“开发配置 → 采集配置”，创建设备并在“采集插件”中选择“OPC UA 客户端”。
支持的通道和数据类型
| 通道类型 | 配置前检查 |
|---|---|
| 插件内置连接 | 连接参数在设备动态属性中配置，不使用公共 TCP、UDP 或串口通道参数。 |
变量类型按当前编辑器选择。Object 可保留节点返回的对象值；数值、布尔、字符串、数组和结构节点应结合服务端声明及实际返回值核对。选择变量类型不会改变服务端的节点类型。
插件参数
OPC UA 客户端在设备属性中直接维护会话，不使用普通 TCP、UDP 或串口通道字段；失败重试、写优先等采集公共属性仍按采集配置配置。
连接配置
| 参数 | 说明 |
|---|---|
| 连接Url | 默认：opc.tcp://127.0.0.1:49320；填写：文本输入。设置建立连接时使用的连接Url。 |
连接 URL 必须是服务端实际发布的 OPC UA Endpoint（包括协议、主机、端口和必要路径），不能只填写主机或浏览器 URL。
安全认证
| 参数 | 说明 |
|---|---|
| 登录账号 | 填写：文本输入。设置身份校验或安全连接使用的登录账号。 |
| 登录密码 | 填写：文本输入。设置身份校验或安全连接使用的登录密码。 |
| 安全策略 | 默认：否；填写：开关。控制“安全策略”功能是否启用。 |
| 接受不受信任证书 | 默认：否；填写：开关。控制“接受不受信任证书”功能是否启用。 |
| 证书 | 填写：证书选择。设置身份校验或安全连接使用的证书。 |
启用“安全策略”后，客户端按服务端 Endpoint 的安全策略建立加密会话；“接受不受信任证书”仅适用于首次联调，生产环境应改为在证书管理/服务端信任列表中建立信任链。
订阅配置
| 参数 | 说明 |
|---|---|
| 数据变化触发条件 | 默认：1；填写：下拉选择。设置当前插件使用的数据变化触发条件。 |
| 激活订阅 | 默认：是；填写：开关。控制“激活订阅”功能是否启用。 |
协议参数
| 参数 | 说明 |
|---|---|
| 名称标识 | 默认：TGateway_OPC_UA_Master；填写：文本输入。设置协议通信使用的名称标识。 |
| 加载服务端数据类型 | 默认：是；填写：开关。控制“加载服务端数据类型”功能是否启用。 |
数据格式
| 参数 | 说明 |
|---|---|
| 是否使用SourceTime | 默认：是；填写：开关。控制“是否使用SourceTime”功能是否启用。 |
运行参数
| 参数 | 说明 |
|---|---|
| 更新频率 | 默认 1000 毫秒。订阅模式下作为监视项请求的采样间隔，服务端可修正；关闭订阅后用于组织轮询计划。它不等同于订阅发布周期，实际轮询耗时还受请求和组数影响。 |
| 心跳频率 | 默认 3000 毫秒，控制会话 KeepAlive；填 0 使用 5000 毫秒默认值，不表示关闭心跳。它与变量采样、订阅发布分别设置。 |
变量配置
| 参数 | 说明 |
|---|---|
| 死区 | 默认 0。非零时请求绝对数值死区，抑制较小数值变化的订阅通知，不是百分比，也不改变服务端当前值。 |
打包规则
| 参数 | 说明 |
|---|---|
| 最大组大小 | 默认 500。在采集组内分块组织读取或自动订阅；同组同 NodeId 可以去重。缩小后会增加组数及会话工作量。 |
“数据变化触发条件”可选 Status、StatusValue、StatusValueTimestamp：分别在状态变化、状态或值变化、状态/值/时间戳变化时触发订阅回调。需要时间戳变化也触发时选择最后一项。
当前客户端在死区非零时才提交包含该触发条件的过滤器；死区为零时不提交自定义过滤器。订阅发布周期由服务端协商，不能把“更新频率”当作固定发布频率。
用直接读取对照订阅
- 选择一个正常数值节点，先直接读取并建立订阅。
- 使用
StatusValue和死区10，把源值从1234改为1239。直接读取能看到新值，订阅可能仍保持原值；再改为1250，确认超过死区后通知更新。 - 选择
Status、保持非零死区，只改变数值而不改变质量，确认不会把值变化当作状态变化。普通数值订阅通常使用StatusValue。 - 需要来源时间时开启“是否使用SourceTime”，核对服务端时间与网关采集时间；同时确认两端时钟正确。
写优先和读写占空比是公共运行字段，当前 OPC UA 写入使用其专用路径，不能根据这两个开关推导每次写后必定插入一次读取。写入验收仍应重新读取源节点并检查质量。
建立第一条有效采集
- 填写实际 Endpoint，保存启用设备。OPC UA 客户端自行管理连接，不需新建普通 TCP 通道。
- 打开设备“调试 → 协议调试”，展开地址空间，选择可读取的变量节点。复制详情中的完整 NodeId，例如
ns=2;s=Channel1.Temperature。 - 点击刷新读取，核对值、Good 状态和时间戳。目录节点、显示名称和浏览路径不能代替 NodeId。
- 创建业务变量，填写完整 NodeId，并按服务端声明选择类型。先接一个标量，再扩展数组或结构对象。
- 在源端改变测试值，确认业务变量产生新的有效数据；分别检查连接在线、点位质量和数值，旧值仍在不能说明采集恢复。
“激活订阅”关闭后改为轮询，自动订阅列表可为空，设备仍能采集；调试手工订阅也不受此开关禁止。开启后检查自动组和实际监视项。四个业务变量指向同一个 NodeId 时，可能只产生一个监视项，并不表示丢失变量。
“加载服务端数据类型”主要用于自定义结构和 ExtensionObject 的声明解析；关闭后内置 Int16 等简单类型仍可读取。复杂类型须核对实际声明及结果，不能用开关替代变量类型选择。
应用证书与用户身份
| 检查项 | 操作要求 |
|---|---|
| 名称标识 | 未选证书时用于客户端应用名称和 urn: 应用 URI。修改后会重建会话，不改变远端 NodeId。 |
| 客户端应用证书 | 在证书管理中准备带私钥、有效期和 OPC UA 应用 URI 的客户端证书。选用证书时，其名称用于应用身份，应与证书 SAN 中的 URI 对应。 |
| 接受不受信任证书 | 只放行 BadCertificateUntrusted；过期、主机名或应用 URI 不匹配仍会失败。先辨认具体错误，再维护信任。 |
| 登录账号、密码 | 用于用户令牌认证，必须被所选 Endpoint 接受。应用证书不能代替用户的节点权限。 |
| 清空证书选择 | 恢复按名称标识自动创建的应用身份；不会删除证书资源，也不表示安全会话不再使用应用证书。 |
安全参数修改后需确认新会话已连接，再读取同一个节点。TCP 连通、证书通过和用户身份通过分别检查，避免把密码错误误判为网络问题。
地址规则
普通变量
普通采集变量的地址填写 OPC UA NodeId，例如 ns=2;s=Channel1.Temperature。建议先在设备调试页浏览并读取节点，再复制完整的命名空间和标识符。
OPC UA 方法变量
需要让外部系统调用 OPC UA 服务端方法时，先在当前设备下创建一个专用变量，再按下表配置。
| 配置项 | 填写要求 |
|---|---|
| 变量名称 | 使用能表达控制动作的名称，例如“启动方法”或“配方切换方法”。外部 RPC 使用该名称定位方法变量。 |
| 其他方法 | 选择 CallMethodByNodeIdAsync，页面显示名称为“调用 OPC UA 方法”。 |
| 变量地址 | 填写 ["对象节点Id","方法节点Id"] 格式的标准 JSON 数组，例如 ["ns=2;s=Machine1","ns=2;s=Machine1.Start"]。第一个元素必须是提供方法的对象节点，第二个元素必须是方法节点。 |
| 读写权限 | 选择“只写”。控制方法不应进入周期采集，否则可能被重复触发。 |
| RPC写使能 | 开启。关闭后，Web API、MQTT 等外部入口会拒绝调用。 |
| 写入检查 | 关闭。方法调用不是可回读点位，应通过 RPC 返回结果和设备状态确认执行结果。 |
保存变量后，外部 RPC 的变量值按 OPC UA 方法 InputArguments 的顺序填写。最外层数组表示“参数列表”：
| 方法输入 | RPC 变量值 |
|---|---|
| 无输入参数 | [] |
| 一个标量参数 | [123] |
| 两个参数 | [123, "start"] |
| 一个数组参数 | [[1, 2, 3]] |
客户端会读取服务端方法的标准 InputArguments 元数据，并把 JSON 值转换为声明的数据类型。服务端返回的所有输出参数按顺序组成 JSON 数组；没有输出参数时返回空数组。
方法变量应只绑定已经过现场确认的控制方法。为集成账号仅授予必要的变量写入权限，并在联调阶段使用不会影响生产的对象和参数。
外部 RPC 调用
Web API
调用变量写入接口 /api/gatewaywritevariablecontroller/setvariablevalue，请求体按“设备名称 → 方法变量名称 → 输入参数数组”组织：
{
"OPC设备": {
"启动方法": [123, "start"]
}
}
接口会先检查变量是否存在、是否为只写或可写、是否允许 RPC 写入以及设备是否暂停，再调用 OPC UA 方法。响应中该变量的 Content 是服务端输出参数数组；失败时查看 ErrorMessage、RPC 日志和设备日志。
MQTT 等入口
MQTT RPC 和其它已经接入变量 RPC 服务的入口使用同一个方法变量。外部消息经过目标的 RPC Topic 或脚本解析后，只要最终得到相同的“设备名称、变量名称、JSON 参数数组”，就会执行同一个 OPC UA 方法。Topic、认证和响应规则见反向 RPC 详解。
设备调试
进入“开发配置 → 采集配置”，选择当前设备后点击“更多功能”并打开“调试”。
协议调试 · OpcUaClient
| 功能 | 作用 |
|---|---|
| 浏览节点 | 展开 OPC UA 地址空间，查看 NodeId、显示名称、数据类型、值、状态码和时间戳。 |
| 读取/写入节点 | 单独读取选中节点；写入会修改服务端点值。 |
| 导出 Excel | 把勾选节点导出为变量配置文件。 |
| 导入变量 | 把勾选节点直接导入当前设备变量。 |
| 订阅管理 | 按 NodeId 列表创建、查看或取消订阅组。 |
调试要点
先浏览节点并读取值，再建立订阅；导入变量后复核 NodeId、数据类型和采集周期，写入只在点位允许时执行。
| 节点详情 | 如何使用 |
|---|---|
| NodeClass、BrowseName、DisplayName | 区分变量、对象和方法；名称用于浏览，地址仍使用完整 NodeId。 |
| Value、状态码、SourceTimestamp | 同时判断当前数据和质量。SourceTime 开启时使用来源时间，关闭时使用网关接收处理时间。 |
| DataType、ValueRank、ArrayDimensions | 核对声明类型及标量/数组维度。DataType 属性自身是 NodeId，不能因此把变量值当成 NodeId。 |
| AccessLevel、UserAccessLevel | 分别看节点开放权限和当前用户实际权限。WriteMask 与 UserWriteMask 是节点属性写掩码，不能代替数值写权限。 |
| Historizing、MinimumSamplingInterval | 历史能力与最小采样声明；能读取当前值不等于已启用历史，间隔 0 也不承诺无限速度。 |
需要临时观察节点时，在订阅管理中填写组名和每行一个 NodeId，再创建订阅。同名手工组会先释放再建立；取消指定手工组不会删除业务变量或自动组。直接写入后点击刷新读取，并回到现场源核对新值。
勾选节点后，“导出 Excel”只下载映射文件；“导入数据库”才向当前设备新增变量。先勾选少量变量节点，避免对整个目录递归导入过多点位。导入后核对实际新增数量、名称、完整地址和类型；默认 Object 应按业务需要复核，再等待新变量上线。
验证重点
- 浏览到一个已知 NodeId，读取当前值并确认状态码正常。
- 在服务端改变该测试节点，确认调试页读取结果或订阅值同步更新。
- 导入少量测试节点后，核对 NodeId、数据类型、当前值和时间戳。
- 启用订阅时，确认更新频率、死区和最大组大小符合现场要求；需要服务端时间时核对 SourceTime。
- 节点写入只在服务端明确允许的测试节点上执行，写入后重新读取确认结果。
- 方法调用先使用无生产影响的测试方法，确认对象节点、方法节点和输入参数数量正确。
- 分别通过变量写入弹窗和目标外部 RPC 入口调用一次，核对输出参数、RPC 日志和服务端执行结果。
排障差异
- 无法连接或浏览节点：检查连接 URL、账号密码、安全策略、应用证书和服务端信任列表。
- 提示证书不受信任：先确认拒绝发生在哪一端。客户端拒绝远端时检查服务端证书及本端信任；服务端拒绝客户端时，把正确的客户端应用证书加入服务端信任列表。两端都要核对有效期和应用 URI，不要长期依赖“接受不受信任证书”。
- 能浏览但读取状态码异常：核对 NodeId、服务端节点权限和数据质量。
- 订阅没有更新：检查“激活订阅”、更新频率、数据变化触发条件、死区和订阅组节点数量。
- 导入后类型不正确：开启“加载服务端数据类型”，重新浏览并核对自定义类型映射后再导入。
- 特殊方法列表中没有“调用 OPC UA 方法”：确认设备使用当前版本的 OPC UA 客户端插件，并在更新程序后重启 TGateway。
- 提示输入参数数量不正确：确认 RPC 值的最外层是参数列表；方法只有一个数组参数时必须使用双层数组，例如
[[1, 2, 3]]。 - 提示参数类型不匹配：核对服务端方法的
InputArguments数据类型和值阶，并确认服务端公开了标准输入参数元数据。 - 提示方法无效或不可执行：核对对象节点与方法节点是否属于同一对象、当前用户是否有执行权限，以及服务端方法的 Executable 状态。
- 方法被周期性重复触发：把方法变量的读写权限改为“只写”，不要将控制方法配置为可读变量。
- 外部 RPC 被拒绝：检查方法变量是否允许 RPC 写入、设备是否暂停、集成账号是否有变量写入权限。