OPC UA协议接入

约 2237 字大约 7 分钟

设备接入第三方协议OPC UA工业协议

2026-08-24

简介

OPC UA（OPC Unified Architecture）是工业自动化领域最通用的设备通信协议，联犀平台通过 opcua 协议网关接入各类 OPC UA 服务（PLC、SCADA、DCS 等）。

与其他"从站轮询"协议不同，OPC UA 接入平台同时支持两种角色：

Client（采集 + 反向写）：平台作为 OPC UA Client 主动连接下游 PLC/SCADA/DCS 的 UA Server，按配置周期轮询节点数据上报；支持平台下行控制写外部 UA Server 节点（反向写）。
Server（双向：读 + 写控制）：平台作为 OPC UA Server，把平台设备/物模型属性映射为 UA 地址空间节点，供外部 SCADA/MES 等 UA Client 订阅读取；允许外部 UA Client 写节点触发平台下行控制。

核心能力：平台提供产品级「节点映射表」与设备级「连接参数配置」，将 UA 节点（NodeID）与物模型属性一一对应，无需编写任何代码即可完成 OPC UA 设备接入、数据采集与下行控制。

应用场景

工业设备采集：PLC/SCADA/DCS 的 OPC UA Server 节点数据采集（Client 角色）
对外数据暴露：平台设备/物模型属性映射为 UA 节点，供外部 SCADA/MES 订阅读取（Server 角色）
双向控制：平台下行控制写外部 UA Server 节点；外部 UA Client 写平台节点触发平台下行控制
安全：SecurityPolicy 首版支持 None，Client 认证支持匿名与 UserName/Password

前置条件

协议容器已部署：protocol-opcua 容器运行正常
设备可达：目标 OPC UA Server（Client 角色）或外部 UA Client（Server 角色）网络可达
产品已创建：产品传输协议选择 其他，协议类型选择 opcua

产品配置

1. 创建产品

创建产品时选择协议 opcua（传输协议其他），创建后进入产品详情配置物模型属性。

2. 物模型配置

配置产品的物模型属性（如温度、开关、电压等），每个属性对应一个 OPC UA 节点（NodeID）。

3. 节点映射（重点）

进入产品详情「设备接入」Tab，打开节点映射表，以物模型属性为准，逐行配置 OPC UA 节点参数：

字段	说明
`identifier`	物模型属性标识符（只读，来自物模型）
`nodeID`	UA 节点标识，支持 `ns=<idx>;s=<string>` 与 `ns=<idx>;i=<num>` 两种格式
`dataType`	数据类型，用于读写转换（bool/int32/int64/float32/float64/string）
`writable`	是否允许外部写（仅 Server 角色：外部 UA Client 写该节点触发平台下行控制）

NodeID 格式：

格式	示例	说明
字符串节点	`ns=2;s=sensor1;t=temp`	字符串标识节点
数字节点	`ns=2;i=1001`	数字标识节点

保存节点映射时写入产品协议配置 protocolConf.points；未配置的点位走旧版物模型扩展配置（extendConfig）回退读取。

设备接入

1. 创建设备

在产品下创建设备，进入设备详情「设备接入」Tab。配置页会自动读取设备信息并填充连接参数，可直接编辑或使用默认值：

2. 连接参数

参数	说明	默认值
`mode`	角色：`client`（采集外部 UA Server）/ `server`（对外暴露平台数据）	`client`
`endpoint`	UA 地址（client 填外部服务如 `opc.tcp://127.0.0.1:4840`；server 填监听地址如 `opc.tcp://0.0.0.0:4841`）	必填
`securityPolicy`	安全策略（首版 `None`）	`None`
`auth`	认证方式：`anonymous` / `userPass`（仅 client 角色）	`anonymous`
`username` / `password`	userPass 认证时必填	-
`duration`	采集周期（毫秒，仅 client 角色）	`10000`
`timeout`	请求超时（毫秒）	`3000`

3. 连通测试

配置页提供「连通测试」按钮，以当前表单参数对目标 UA Server 发起连接，验证可达性。测试通过后提示「连接成功」及耗时。

连通测试走协议自有接口（__action=ping），需协议容器已部署且目标可达。

数据验证

真实链路验证结论

联犀平台接入 opcua 协议后，验证流程与结果如下：

mock UA Server 启动：OPC UA 模拟服务监听 4840 端口，含 ns=1;i=1001（int32=42）与 ns=1;s=temp（float64=25.6）节点
协议服务连接：Client 角色设备连接 mock，设备显示在线，周期采集上报
属性上报：物模型属性出现实时数据（switch=1、temperature=25.6）
Server 模式读：外部 UA Client 读平台 Server 节点，读回调返回平台最新值（temperature=33.3）
Server 模式写：外部 UA Client 写平台节点（值 88），触发平台下行控制指令

测试项	状态	详情
Client 采集	✅ 成功	周期轮询 mock 节点，上报 `switch=1 / temperature=25.6`
Client 反向写	✅ 成功	平台下行 control → 写外部节点，节点值变化并回读确认
Server 读	✅ 成功	外部 UA Client 读平台 Server 节点返回平台真实值
Server 写控制	✅ 成功	外部 UA Client 写节点 → 触发平台下行控制
配置页	✅ 可用	设备连接参数表单 + 产品节点映射表 + 连通测试

技术方案

接入架构

外部 UA Server ──opc.tcp──> protocol-opcua(Client) ──FastEvent──> 联犀平台
(PLC/SCADA)     周期轮询/写    - 节点读取解析        DevPubMsg      dmsvr
                              - 下行 control → Write  ◄──下行订阅──  物模型/属性/状态

外部 UA Client ──opc.tcp──> protocol-opcua(Server) ──读回调/写回调──> 联犀平台
(SCADA/MES)     读/写节点    - 节点读回调返回平台值    ◄──平台数据──    设备物模型
                            - 写节点触发平台下行控制

协议服务按 ProtocolCode 拉取设备列表，Client 角色逐设备建立 UA Client 连接
周期轮询（duration）读取映射节点 → 按节点映射组装 map[identifier]value → DevPubMsg 上报
平台下行 control → 按节点映射 Write 外部 UA Server 节点 → 回 controlReply
Server 角色为每个配置了 server 模式的产品构建 UA Server（监听配置端口的地址空间），节点读回调返回平台设备最新属性值；外部 UA Client 写节点触发平台下行控制

数据流

上行（采集）：UA Client 轮询节点 → 节点映射解析 → 属性上报（Client 角色）
下行（控制）：平台控制指令 → 映射到节点 → UA Client Write 外部节点（Client 角色反向写）
Server 读：外部 UA Client 读平台节点 → 读回调取平台设备最新值返回
Server 写：外部 UA Client 写平台节点 → 写回调触发平台下行控制

部署说明

OPC UA 协议默认不预装，由 scripts/add-protocol.sh opcua 按需加载/下线。部署片段为 deploy/compose/parts/protocol/opcua.yml：

# 协议片段：opcua（默认不预装，由 scripts/add-protocol.sh 按需加载/下线）
# 额外暴露 opc.tcp://4841 端口用于 server 模式对外暴露平台数据
services:
  protocol-opcua:
    image: docker.unitedrhino.com/proto/opcua:${PROTO_IMAGE_TAG}
    container_name: protocol-opcua
    hostname: protocol-opcua
    restart: unless-stopped
    environment:
      confSuffix: Docker
    ports:
      - "9358:9358"
      - "4841:4841"
    networks:
      - saas_prod

镜像：docker.unitedrhino.com/proto/opcua
协议服务端口：9358（配置页 Web 服务，平台以 iframe 渲染）+ 4841（Server 角色 opc.tcp）
协议代码：opcua，实现位于 backend/protocol/opcua/（CoreProtocol 设备直连类型）

注意事项

Server 端认证限制：gopcua 在 SecurityPolicy=None 下默认不注册 UserName token，故 Server 首版用「匿名 + None」；UserName/Password 需证书加密策略（后续迭代）。Client 端 userPass 可用。
节点 namespace 一致性：Server 模式节点的 NodeID namespace 需与 UA Server 实际命名空间 ID 匹配。
订阅 vs 轮询：Client 采集首版用轮询（duration 周期），订阅（monitor）作为后续优化。
NodeID 解析需正确（ns=<idx>;s=<str> 或 ns=<idx>;i=<num>），非法节点会被跳过并在协议日志记录。
关联任务：TASK-114（docs/物联网/任务/进行中/中-26-8-24-TASK-114-opcua协议网关/）

参考链接

属性质量映射（saas 新版支持）

适用版本：saas 新版。

Client 采集按 OPC UA StatusCode 的严重级别映射为平台质量：

OPC UA 严重级别	平台质量	页面显示
Good	GOOD	良好
Uncertain	UNCERTAIN	不确定
Bad	BAD	异常

非零状态码也可能属于 Good，不能只用“是否等于 0”判断。具体采集点失败、无有效值时记录 null + BAD，不以零值代替。平台只保留三个质量等级，不提供原始细分状态码的无损往返；细节参考 OPC UA StatusCode。

Server 对外返回属性时，将平台质量映射到对应的 OPC UA Good/Uncertain/Bad，不能把异常值自动标成 Good；无数据返回 BadNoData。

有源时间时将其作为数据时间。平台统计和数值告警只使用 GOOD；历史保留三种质量，最新状态不回退到旧 GOOD。联犀 JSON 报文格式见物模型协议。

更新日志

2026/9/16 22:54

查看所有更新日志

5b100-Merge #40 into master from codex/task-124-quality-protocol于 2026/9/16
08554-Merge #30 into master from docs/third-party-protocols于 2026/8/24

平台认知

基本概念

物模型

架构与开源

定价与更新

联犀协议

AI交互

第三方协议

网关接入

音视频

物联卡

组态大屏