采集配置
采集配置用于维护通道、设备和变量，是 GatewayRuntime 连接现场设备、采集点位数据、配置报警和写入控制的主要入口。
私有协议接入
没有现成采集插件，但协议可以用固定请求、分帧规则和数据偏移描述时，请参见完全自定义报文采集。
先看术语
| 术语 | 现场含义 |
|---|---|
| 通道 | 网关到设备的通讯链路，例如一条 TCP 连接、一组 UDP 通讯或一个串口。 |
| 设备 | 一台 PLC、仪表、采集模块，或一个由插件管理的逻辑设备。 |
| 变量 | 点表中的一个点位，例如温度、压力、运行状态、故障状态或控制写入点。 |
Other 通道类型 | 无普通通讯通道插件。插件不需要普通 TCP、UDP、串口通道，连接由插件自己处理或不需要外部连接。 |
| Cron 表达式 | 定时表达式。现场常规周期建议优先填写毫秒数，例如 1000 表示 1 秒。 |
| RPC 写入 | 外部系统或页面反写点位。控制类点位才需要开启，监测点一般保持关闭。 |
| StreamAsync | 串口异步读写方式。串口通讯稳定时保持默认；遇到阻塞、读取不及时等问题时再调整。 |
| DtuId / DTU 编号 | DTU 或透传终端编号，用于区分哪台远端设备正在接入。 |
| Topic | MQTT 或 Kafka 等消息系统中的主题/路径，现场可理解为外部系统约定的数据通道名称。 |
功能入口
登录 GatewayRuntime Web 后，点击左侧菜单“开发配置 → 采集配置”。
现场配置前先确认
本页参数表很多，现场不要先从字段逐个看起。先把通讯链路和点表边界确认清楚，再按“通道、设备、变量”的顺序配置。
| 先确认什么 | 现场要拿到的信息 |
|---|---|
| 通讯方式 | TCP 客户端、TCP 服务端、UDP、串口、OPC UA、OPC DA、MQTT，或插件自管理连接。 |
| 连接参数 | IP、端口、串口号、波特率、校验位、停止位、账号密码、证书、防火墙策略。 |
| 设备身份 | PLC 型号、站号、从站地址、机架槽号、DTU 编号、OPC 节点空间或 MQTT Topic。 |
| 点表 | 变量名称、地址、数据类型、单位、量程、读写权限、报警阈值。 |
| 验证方法 | 用 PLC 软件、仪表面板、上位机页面或现场校验值确认读取结果。 |
| 安全边界 | 哪些点只读，哪些点允许写入，写入前需要谁确认。 |
现场推荐顺序
现场接入设备时，建议按“少量验证、再批量扩展”的方式配置。不要一开始就导入整站点表，否则通讯参数、站号、地址和数据类型问题会混在一起，排查成本很高。
| 顺序 | 操作 | 通过标准 |
|---|---|---|
| 1 | 新建通道，填写 IP、端口或串口参数。 | 通道能连接，通道日志没有持续超时或连接失败。 |
| 2 | 新建设备，选择采集插件并填写站号、超时、字节序等插件属性。 | 设备显示在线，设备日志没有持续读写错误。 |
| 3 | 先建立 3 到 5 个典型变量。 | 当前值与 PLC 软件、仪表显示或现场校验值一致。 |
| 4 | 确认数据类型、单位、量程、读写权限和报警阈值。 | 点表与现场最终确认版本一致。 |
| 5 | 再批量导入或复制完整点表。 | 导入结果无失败行，抽查关键点位正确。 |
| 6 | 导出采集配置留档。 | 交付包中包含最终 Excel 配置和点表。 |
配置层级
| 层级 | 说明 |
|---|---|
| 通道 | 通讯链路，例如 TCP 客户端、TCP 服务端、UDP、串口等。先让通道连通，再继续建设备。 |
| 设备 | 采集对象，选择具体采集插件。大多数设备需要归属于通道；只支持 Other 的插件可不选择普通通道。 |
| 变量 | 设备下的点位，定义地址、数据类型、读写权限、报警、值过滤和表达式。先建少量变量验证，再导入完整点表。 |
页面结构
| 区域 | 说明 |
|---|---|
| 左侧资源面板 | 按通道分组展示设备，通道标题显示在线设备数量和通道摘要；未绑定普通通道的 Other 类型设备以平铺分组显示。面板支持按设备名称、通道名称、设备状态和插件名称筛选。 |
| 变量显示 | 查看和维护变量列表，范围会随左侧选中的通道或设备变化。 |
| 设备显示 | 查看所选设备的设备信息、通道日志、设备日志和调试页签。 |
| 顶部操作 | 刷新、通道管理、设备管理，以及“显示更多”菜单中的导入导出和测试数据。 |
选择左侧通道或设备后，右侧变量列表会按所选范围过滤；再次点击当前设备可回到全部采集变量范围。设备行会显示在线状态、冗余角色和采集插件名称，便于在同一通道下区分不同协议设备。
资源面板操作
| 操作 | 说明 |
|---|---|
| 搜索设备名称 | 按设备名称过滤资源面板。 |
| 搜索通道名称 | 按设备所属通道名称过滤。 |
| 设备状态筛选 | 只显示在线或离线设备。 |
| 插件名称筛选 | 只显示指定采集插件下的设备。 |
| 选择通道分组 | 查看该通道下设备和变量。 |
| 选择未分组设备 | 查看不需要普通通讯通道的 Other 类型设备和变量。 |
| 选择设备 | 查看该设备变量，或在“设备显示”页签查看设备详情。 |
通道管理
点击“通道管理”，打开通道管理抽屉。
| 操作 | 说明 |
|---|---|
| 搜索 | 按通道名称或启用状态筛选通道。 |
| 新增 | 打开通道配置弹窗，创建通道。 |
| 编辑 | 修改通道基础信息和通信参数。 |
| 删除 | 删除单个通道。删除前确认通道下设备不再使用。 |
| 批量编辑 | 批量调整选中通道的部分配置。 |
| 批量删除 | 删除选中的多个通道。 |
| 刷新 | 重新读取通道列表。 |
通道配置
点击“新增”或“编辑”，打开通道配置弹窗。
| 配置项 | 说明 |
|---|---|
| 通道名称 | 通道显示名称，建议按协议、现场链路或设备组命名。名称不要使用 Memory，该名称保留给内存变量。 |
| 描述 | 通道用途、连接对象或现场位置说明。 |
| 通道类型 | 选择通信方式。网络通道会显示远程地址、绑定地址和 SSL 配置；串口通道会显示串口参数。 |
| 启用 | 控制通道是否参与运行。关闭后，该通道下设备无法通过此通道采集。 |
| 远程地址 | 客户端模式连接的对端地址，常用格式为 IP:端口 或 域名:端口，例如 192.168.1.10:502。TCP 客户端必须填写远程地址；UDP 会话至少填写远程地址或绑定地址其中一项。现场提供带协议的地址时，可按对方要求填写 tcp://、ssl:// 或 http(s):// 前缀。 |
| 备用远程地址 | TCP 客户端通道的备用对端地址。主远程地址连接失败、连接断开或通讯超时后，通道会在同一设备和同一通道内尝试切换到该地址。只要主、备任一链路可用，设备不会因为单条 TCP 链路故障立即进入主备设备切换。留空表示不启用 TCP 客户端网络冗余；备用地址不要与远程地址相同。 |
| 绑定地址 | 服务端模式在网关本机监听的地址，常用 0.0.0.0:端口 表示允许其它主机连接，127.0.0.1:端口 只允许本机连接。TCP 服务端必须填写绑定地址；UDP 会话至少填写远程地址或绑定地址其中一项。需要带协议监听时，可按现场约定填写 tcp://0.0.0.0:端口 或 ssl://0.0.0.0:端口。 |
| 使用 SSL | 网络通道的 TLS 开关。对端要求加密通信、双向证书或证书校验时开启；普通内网明文协议保持关闭。TCP 服务端启用 SSL 时必须选择服务端证书，否则客户端无法完成 TLS 握手。 |
| SSL 目标主机 | TCP 客户端启用 SSL 时用于校验证书主机名。用 IP 连接但证书签发给域名时，填写证书中的域名。 |
| SSL 客户端证书 / 服务端证书 / CA 证书 | 客户端证书用于网关向对端证明身份；服务端证书用于网关作为服务端监听时提供给客户端；CA 证书用于校验对端证书。证书需先在“证书管理”中维护。 |
| 允许不受信任证书 | 调试自签名证书时可临时开启。生产环境建议关闭，并配置正确的 CA 证书。 |
| SSL 协议 / 检查证书吊销 | 握手失败或现场安全策略有要求时再指定 TLS 版本、开启吊销检查；没有明确要求时保持默认。 |
| 端口名称 | 串口通道使用的串口名，例如 COM1 或 /dev/ttyS0。串口通道必须填写端口名称，并确保运行主机能识别该串口。 |
| 波特率、数据位、校验位、停止位 | 串口通信参数，必须与现场设备保持一致。 |
| DTR / RTS / 握手方式 | 串口硬件流控参数。现场串口服务器、RS485 转换器或仪表手册要求启用时再调整。 |
| StreamAsync | 串口异步读写方式。现场可理解为串口驱动的读写模式；串口通讯稳定时保持默认，遇到阻塞、读取不及时等问题时再结合现场驱动要求调整。 |
| 串口读写缓冲区 | 串口通信使用的读缓冲和写缓冲大小。大量连续报文或长报文场景可适当增大。 |
| 连接超时 | 建立 TCP 连接或等待对端响应的最长时间。网络慢时可增大；设置过大时离线判断会变慢。 |
| 缓存超时 | 数据读取缓存的有效期，单位毫秒。在有效期内重复读取同一地址时会优先返回缓存值；希望每次都访问设备时设为 0，希望降低重复读压力时可适当增大。 |
| 最大并发数 | 同一通道允许同时处理的请求数量。现场设备要求请求顺序严格时保持 1；确认对端支持并发后再增大。 |
| 心跳内容 / 心跳时间 | TCP 客户端保持连接时使用。对端要求固定心跳报文时填写；“心跳是否 Hex”开启后按十六进制字节解析。 |
| 最大连接数 / 客户端清理时间 | TCP 服务端通道用于限制客户端数量并清理空闲连接。上位机或 DTU 数量较多时确认最大连接数足够。 |
| DtuId / DtuId 是否 Hex / Dtu 服务类型 | DTU 或透传终端编号，用于识别哪台远端设备正在接入。DTU 上报的是文本编号时直接填写；上报的是十六进制字节时开启 Hex。 |
TCP 客户端配置了备用远程地址后，网关启动或通道重启时仍优先连接“远程地址”。运行中切换到备用地址后会保持使用当前可用链路；只有当前链路再次失败时才尝试另一条链路。该配置只作用于采集侧 TCP 客户端通道，不影响 TCP 服务端、UDP、串口或设备主备冗余配置。
批量编辑通道时，只会修改批量弹窗中实际调整过的字段。用于统一启停、日志级别、超时、心跳、SSL 等公共配置；不同类型通道的地址、串口名和证书仍应逐个核对。
设备管理
点击“设备管理”，打开设备管理抽屉。
| 操作 | 说明 |
|---|---|
| 搜索 | 按设备名称搜索。 |
| 状态筛选 | 按在线或离线状态筛选。 |
| 插件筛选 | 按采集插件筛选。 |
| 启用状态筛选 | 按启用或禁用筛选。 |
| 新增 | 打开设备配置弹窗，创建设备。 |
| 编辑 | 修改设备基础信息、插件属性和冗余配置。 |
| 删除 | 删除设备。删除前确认设备下变量不再需要。 |
| 批量编辑 | 批量调整选中设备的部分配置。 |
| 批量删除 | 删除选中的多个设备。 |
| 刷新 | 重新读取设备列表。 |
设备配置
点击“新增”或“编辑”，打开设备配置弹窗。
| 配置项 | 说明 |
|---|---|
| 设备名称 | 设备显示名称，建议与现场设备编号一致。名称不要包含英文句点 .，也不要使用 Memory。Memory 是系统内存变量使用的设备名称。 |
| 设备插件 | 选择采集插件。选择后会显示该插件的设备属性。 |
| 所属通道 | 选择设备使用的通道。页面会根据所选插件支持的通道类型决定该项是否必填；普通 TCP、UDP、串口等采集插件通常必须选择通道，只支持 Other（无普通通讯通道）的插件可留空。字段旁可直接新增、编辑或删除通道。 |
| 执行间隔 | 设备采集执行间隔，可填写毫秒数或 Cron 定时表达式，例如 1000 表示 1 秒，*/5 * * * * * 表示每 5 秒。现场常规周期优先填毫秒数；间隔越小实时性越高，但会增加设备和网关负载。 |
| 启用 | 控制设备是否参与采集。 |
| 日志级别 | 控制设备运行日志详细程度。排查问题时可临时提高日志级别。 |
| 描述 | 设备用途、现场编号或安装位置。 |
| 备注1 至 备注5 | 项目自定义扩展字段。 |
| 启用冗余 | 为关键设备配置备用设备。 |
| 冗余设备 | 启用冗余后选择备用设备。备用设备应使用相同采集插件并已配置好通道、插件属性和变量；已经作为其它设备备用的设备不能再被重复选择。 |
| 冗余模式 | 可按离线状态切换，或通过脚本判断是否切换。离线切换适合主设备不可达时自动切换；脚本切换适合按质量、业务状态或外部条件判断。 |
| 扫描间隔 | 冗余状态检查间隔，单位毫秒，最小 10000。间隔越小切换越快，但会增加检查频率。 |
| 切换脚本 | 冗余模式为脚本切换时选择。脚本应返回是否切换的判断结果，适合按业务条件决定主备。选择脚本切换时必须选择脚本。 |
| 插件属性 | 由所选采集插件提供，例如站号、超时、字节序、认证、订阅参数等。每个采集插件显示哪些字段、字段如何填写，请参考 插件属性详表。地址格式请参考 插件参考。 |
设备插件会提供可用通道类型。新增或编辑设备时，先选择插件，再选择匹配的通道；如果插件只支持 Other（无普通通讯通道）类型，页面允许保存无通道设备，并在左侧资源面板的未分组区域展示。
冗余设备不要互相重复套娃配置：作为备用设备的对象不要再启用自己的冗余。上线前可先停用主设备或断开主链路，观察是否按预期切换到备用设备。
变量列表
“变量显示”页签用于查看、筛选和维护变量。
| 工具 | 说明 |
|---|---|
| 搜索变量名称 | 按变量名称搜索。 |
| 搜索地址 | 按寄存器地址或协议地址搜索。 |
| 资源范围筛选 | 通过左侧通道或设备选择变量范围。 |
| 状态筛选 | 按正常或异常状态筛选。 |
| 刷新 | 手动刷新变量列表。 |
| 自动刷新 | 开启后按页面设置自动刷新变量值。 |
| 新增变量 | 打开变量配置弹窗。 |
| 批量编辑 | 批量修改选中变量。 |
| 批量删除 | 删除选中变量。 |
| 列设置 | 自定义变量表格显示列。 |
常用列包括设备名称、变量名称、描述、寄存器地址、当前值、原始值、最后设定值、数据类型、单位、采集组、业务组、在线状态、启用状态、采集时间、变化时间和错误信息。
内存变量在“内存计算”页面维护。该页面只显示 Memory 设备下的变量，适合保存脚本、规则或内部计算结果；采集配置页主要维护连接现场设备的通道、设备和变量。
变量配置
点击变量列表中的“新增”或“编辑”，打开变量配置弹窗。
| 配置项 | 说明 |
|---|---|
| 变量名称 | 点位名称，建议与设备点表保持一致。 |
| 所属设备 | 变量归属设备。选择设备后，地址提示和可选数据类型会按插件刷新。 |
| 单位 | 变量显示单位。 |
| 启用 | 控制变量是否参与采集。 |
| 描述 | 点位用途说明。 |
| 变量地址 | 设备内寄存器、节点、Topic 字段或协议地址。地址格式由插件决定，例如 Modbus 使用寄存器地址，OPC UA 使用节点标识，MQTT 使用 Topic 和 Payload 字段。 |
| 数据类型 | 采集值的数据类型。必须与设备实际数据一致；数值显示颠倒、精度异常或布尔状态不对时，应同时检查数据类型、变量地址、数组长度和插件字节序。内存变量按对象值保存，不填写现场设备地址。 |
| 读写权限 | 选择只读、读写或只写。写入前应确认现场设备允许下发。 |
| 数组长度 | 数组型变量或批量读取场景的长度。普通单点变量保持 0 或默认值；读取连续数组时按实际元素数量填写。内存变量不需要填写数组长度。 |
| 特殊方法 | 插件提供的特殊读写方法。选择后，变量地址通常作为该方法的参数使用，不再按普通寄存器地址打包采集；只有现场协议、插件说明或调试要求明确需要时再选择。 |
| 执行间隔 | 变量级采集间隔。留空或保持默认时按设备间隔执行；需要独立周期时可填写毫秒数或 Cron 定时表达式，例如 500 或 */10 * * * * *。 |
| 保存初始值 / 初始值 | 开启保存初始值后，变量启动时会使用配置的初始值。适合内存变量、状态保持或脚本计算的初始状态。 |
| 触发模式 | 内存变量可配置按变化、按间隔或间隔/变化触发。按变化适合联动计算；按间隔适合周期计算；间隔/变化适合两者都需要的场景。普通采集变量按设备或变量执行间隔采集，不需要维护该项。 |
| 读表达式 / 写表达式 | 读表达式用于把采集原始值转换为业务值；写表达式用于把页面或外部写入值转换成设备需要的值。普通采集变量选择数据转换脚本；内存变量的读表达式用于计算内存值。选择带参数的表达式后，需要填写表达式参数。 |
| 读表达式参数 / 写表达式参数 | 表达式要求的输入参数。页面会显示参数名和数据类型；缺少必填参数时无法保存变量。 |
| 采集组 | 给变量设置业务分组名称。支持打包采集的插件会尽量把同组变量合并读取；数据转发也可按采集组筛选或分批。 |
| RPC 写入 | 控制该变量是否允许外部系统通过 RPC、MQTT、OPC UA、Modbus 从站等方式反写点位。涉及设备控制的变量应谨慎开启。 |
| 写入检查 | 写入成功后再次读取同一变量，并比较回读值与写入值。适合需要确认写入确实生效的点位；只写变量、写入后延迟生效的设备、存在比例换算或回写取整的点位不宜随意开启。 |
| 备注1 至 备注5 | 项目自定义扩展字段。 |
批量编辑变量时，只会保存批量弹窗中被修改的字段。批量修改数据类型、地址、读写权限、表达式或报警前，应先筛选出同一设备、同一协议或同一数据类型的变量，避免把不兼容配置套到其它点位上。
报警配置
| 配置项 | 说明 |
|---|---|
| 布尔开报警 / 布尔关报警 | 布尔变量可分别配置打开和关闭状态报警。开报警用于值为真时报警，关报警用于值为假时报警。 |
| 高、高高、低、低低报警 | 数值变量可配置上下限报警。启用多个限值时，阈值应满足“高高 > 高 > 低 > 低低”，否则保存时会提示错误。 |
| 自定义报警 | 通过自定义条件配置报警。适合设备状态码、质量码、组合条件等不能只用上下限描述的报警。 |
| 报警代码 / 报警文本 | 报警代码用于区分报警类型，报警文本是值班人员看到的说明。建议写清楚对象、条件和处理方向。 |
| 报警等级 | 报警严重程度，范围为 0 到 10，数值越大越严重。 |
| 报警延迟 | 报警条件持续达到设定时间后才触发，单位毫秒。用于过滤瞬时抖动；设为 0 表示条件满足后立即报警。 |
| 抑制表达式 | 条件满足时抑制对应报警，适合检修、联锁或特定工况下暂不报警的场景。抑制表达式只影响报警触发，不改变变量采集值。 |
值过滤
| 配置项 | 说明 |
|---|---|
| 范围过滤 | 按最小值和最大值过滤异常值。适合传感器偶发越界、断线极值等场景。启用后必须填写最小值和最大值，并保证最大值不小于最小值。 |
| 幅度过滤 | 按最大变化幅度或最大变化百分比过滤突变值。适合温度、压力、流量等不应瞬间大幅跳变的模拟量。最大变化百分比按 0 到 100 填写。 |
| 连续过滤 | 按连续异常次数处理重复或异常连续值。适合需要等异常持续多次后再接受或丢弃的场景。最大连续次数从 1 开始填写。 |
值过滤只用于数值类变量；字符串和布尔变量不显示该页签。过滤参数设置过紧会导致真实变化被过滤，设置前应根据现场量程、采样周期和允许波动范围确认。
变量详情与写入
点击变量行的“详情”，打开变量详情抽屉。
| 分区 | 说明 |
|---|---|
| 基本信息 | 显示变量 ID、名称、设备、描述、状态和启用状态。 |
| 地址配置 | 显示寄存器地址、数组长度、特殊方法和来源信息。 |
| 数据信息 | 显示当前值、原始值、最后设置值、数据类型、单位和间隔。 |
| 表达式配置 | 显示读写表达式及参数。 |
| 报警信息 | 变量启用报警后显示报警配置和运行时报警状态。 |
| 值过滤 | 变量配置了值过滤时显示过滤参数。 |
| 历史数据 / 历史报警 | 在详情抽屉中查询当前变量的历史数据；历史报警在变量启用报警时显示。 |
点击变量行的“写入”，打开写入弹窗。
| 配置项 | 说明 |
|---|---|
| 设备名称 | 当前变量所属设备，只读显示。 |
| 变量名称 | 当前写入变量，只读显示。 |
| 当前值 | 写入前页面读取到的变量值。 |
| 写入值 | 要下发的值，格式应与变量数据类型匹配。 |
注意
变量写入会影响现场设备。执行写入前，请确认变量读写权限、写入值范围和现场安全条件。
设备详情与调试
切换到“设备显示”，在左侧选择设备，右侧会显示设备详情。
| 页签 | 说明 |
|---|---|
| 设备信息 | 查看设备基础信息、通道配置、运行状态、插件属性和冗余配置。 |
| 通道日志 | 查看该设备所属通道的通信日志。 |
| 设备日志 | 查看当前设备运行日志和错误信息。 |
| 调试 | 打开插件对应调试工具，例如地址读写、节点浏览、MQTT 发布订阅。 |
详细调试步骤请参考 设备调试。
测试数据
点击“显示更多 → 测试数据”，打开测试数据生成弹窗。该功能用于生成演示或压测配置。
| 配置项 | 说明 |
|---|---|
| 数据类型 | 选择普通测试数据或 DTU 测试数据。 |
| 变量数量 | 普通测试数据下生成的变量数量。 |
| 设备数量 | 要生成的测试设备数量。 |
| 从站地址 | 生成设备时使用的从站地址或连接信息。 |
| 启用数据转发 | 普通测试数据下是否同步生成数据转发配置。 |
| 生成 | 按弹窗中填写的数量和选项生成测试配置。 |
生产环境使用测试数据前，应确认名称和数量不会与正式配置混淆。
导入导出
采集配置导入导出位于变量列表右上角“显示更多”菜单中。
| 操作 | 说明 |
|---|---|
| 导入采集配置 | 从 Excel 导入通道、设备、变量等采集配置。 |
| 导出当前采集配置 | 按页面筛选条件和资源范围导出。 |
| 导出全部采集配置 | 导出全部采集配置。 |
导入完成后会显示导入结果。现场导入时应重点检查失败行、字段名和错误详情，再根据提示修正 Excel 后重新导入。
使用注意
| 场景 | 建议 |
|---|---|
| 新建采集链路 | 先建通道，再建设备，最后建变量。 |
| 设备离线 | 检查通道参数、设备插件属性、网络或串口连接。 |
| 变量异常 | 检查变量地址、数据类型、设备在线状态和设备日志。 |
| 批量导入 | 先在测试环境导入验证，再导入生产环境。 |
| 删除通道或设备 | 先确认下级设备、变量和数据转发配置不再使用。 |