同步桥接
在一个公网 Hub 与一个或多个 Edge 节点之间同步转发范围内的配置和实时变量。Hub 负责监听并汇聚 Edge；Edge 主动连接 Hub 并发布本地镜像。
首次配置建议按中心与边缘部署全流程操作，优先使用 Studio 自动配置；本页用于维护插件参数。
转发组范围和目标启停见数据转发。本页完整说明同步桥接的角色、多 Hub 冗余地址、双向 TLS、同步策略和专用调试面板。
接入准备与角色选择
使用前准备
- 在 Hub 和每个 Edge 上分别创建同步桥接目标。
- 如需 TLS，为 Hub 准备服务端证书、为每个 Edge 准备带私钥的客户端证书，并让两端信任签发 CA。Edge 客户端证书的 DNS 名称或主题名称必须匹配该 Edge 的“本地Peer标识”；证书在“开发配置 → 证书管理”中维护。不启用 TLS 时无需配置证书。
- 两端使用相同的“连接校验令牌”，每个节点使用唯一的“本地Peer标识”。
- 确保 Edge 可以访问 Hub 监听地址和端口。
功能入口
进入“开发配置 → 数据转发”，按以下顺序配置：
- 在 Hub 和每个 Edge 上分别保存一个同步桥接目标。
- 在目标基本信息中选择转发组、填写名称和启动超时。
- 在目标属性中选择运行角色，再按角色填写监听或 Hub 冗余端点、身份和同步容量。需要加密时开启“启用双向TLS”，再选择证书。
- 保存并启用目标，先确认 Hub 与 Edge 已连接，再执行配置同步和实时值验证。
目标基本信息
| 参数 | 默认值 | 如何配置 |
|---|---|---|
| 所属转发组 | - | 必须选择已保存的转发组；Edge 只发布该组范围内的数据。 |
| 目标名称 | - | 必填，同一转发组内不能重复。 |
| 启用 | 开启 | 关闭时不会建立监听或远端连接。 |
| 日志级别 | Info | 排查 TLS、握手或同步问题时临时使用 Debug。 |
| 启动超时 | 60 秒 | 页面可填 1～3600 秒。 |
角色与连接
| 参数 | 默认值 | 说明 |
|---|---|---|
| 运行角色 | EdgePublisher | Hub 选择 HubServer，Edge 选择 EdgePublisher。角色决定监听还是主动连接。 |
| 本地Peer标识 | 空（必填） | 1～100 个字母、数字、点、下划线或短横线；每个节点必须唯一。 |
| 配置同步模式 | 变更和重连时同步 | 仅重连时同步 只在建立连接或 Hub 请求时比较；变更和重连时同步 还会在 Edge 转发范围变化时同步。 |
| 监听地址 | 0.0.0.0:7777 | Hub 使用的监听地址。 |
| Hub冗余端点 | 空（Edge必填） | Edge 按列表顺序尝试连接 Hub；每行填写唯一端点标识、Hub 地址和 TLS 目标主机，最多 16 行。Hub 角色不使用。 |
连接、故障切换与安全
多 Hub 故障切换
Edge 会保持当前活动 Hub 的连接。只要心跳、实时发送确认和配置同步都正常，连接会持续保持；普通空闲不会触发切换。
实际链路错误会触发重新连接，例如心跳失败或超时、实时批次发送/确认超时、配置同步失败或传输连接被关闭。每轮重新连接都从 HubEndpoints 第一项开始，某端点连接或握手失败后才在该轮继续尝试下一项；原端点仍可连接时可能继续使用它。连接成功后先校验配置，再恢复完整快照和实时增量。
主 Hub 恢复后不会被主动探测，也不会从当前备 Hub 自动回切。当前备 Hub 后续发生错误并进入重新连接流程时，才会再次按端点优先级从第一项开始尝试。调试页中的“当前 Hub”、切换次数、端点连接状态和最近错误可用于确认实际切换原因。
安全认证
| 参数 | 默认值 | 说明 |
|---|---|---|
| 连接校验令牌 | 空（必填） | 连接后的身份校验密钥，Hub 和 Edge 必须完全一致；TCP 和 TLS 均需填写。 |
| 启用双向TLS | 关闭 | 两端保持一致；开启后使用双向 TLS，关闭时使用 TCP 并隐藏证书配置。 |
| 传输证书 | 空（TLS 开启时必填） | 从下拉框选择。Hub 仅显示服务端证书，Edge 仅显示客户端证书。 |
| 传输CA证书 | 空（TLS 开启时必填） | 从下拉框选择用于验证对端证书链的 CA 证书。 |
| TLS目标主机 | 端点内配置 | TLS 开启时，Edge 每个端点填写与 Hub 服务端证书 DNS 名称或 SAN 一致的目标主机；Hub 监听角色不使用。 |
| TLS协议 | 系统默认 | 支持多选 TLS 1.2、TLS 1.3；选择“系统默认”时由操作系统协商，并取消显式协议选择。下拉框只提供这三项；SSL 2.0、SSL 3.0、TLS 1.0、TLS 1.1 和其他无效协议值均会被拒绝。 |
| 检查证书吊销 | 开启 | 按项目证书策略检查对端证书是否已撤销。 |
选择“运行角色”后再打开“传输证书”下拉框。找不到证书时，先到“证书管理”按当前角色生成或导入正确用途的证书，再重新展开下拉框。切换角色不会自动替换已填写的证书，需要重新确认所选用途。
Edge 客户端证书的名称用于绑定节点身份，与证书管理列表中的资源名称不同。例如，“本地Peer标识”为 edge-01 时，客户端证书的 DNS 名称或主题名称应为 edge-01。Hub 证书的名称则匹配端点中的“TLS目标主机”。仅有可信 CA 和正确证书用途仍不足以完成连接；修改 Peer 标识后也要重新选择匹配的证书。保存后核对新会话、配置修订和新来源值是否均已到达 Hub。
也可从 Studio“现场管理 → 数据同步”连接两端、选择现场转发组后直接配置并启用。此流程开启 TLS 时会自动生成并安装所需证书，无需导入同步配对包。
配置同步与补录
同步与容量
| 参数 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|
| 心跳间隔（毫秒） | 5000 | 1000～60000 | 连接健康检查周期。 |
| 实时合并窗口（毫秒） | 20 | 10～1000 | 控制发送循环的合并等待窗口；普通缓存仍可保留同一变量的多条来源记录。不是每次按钮操作固定增加的延时。 |
| 实时确认超时（毫秒） | 3000 | 500～60000 | 等待 Hub 确认实时批次的最长时间。 |
| 实时批次变量上限 | 2000 | 1～10000 | 单批变量记录数；同一变量的多条来源采样也各占一条。 |
| 恢复最新快照上限 | 200000 | 1～1000000 | 重连或手动恢复快照可容纳的最新变量身份数量；不足时会丢弃部分恢复值，不是历史缓存行数。 |
| 实时批次字节上限 | 262144 | 4096～1048576 | 单个实时批次的最大 UTF-8 字节数。 |
| 配置分块字节上限 | 524288 | 4096～1048576 | 单个配置分块的最大 UTF-8 字节数。 |
| 配置同步并发Peer数 | 4 | 1～32 | Hub 同时请求多个 Edge 配置时的并发数。 |
| 允许反向RPC | 关闭 | - | 允许 Hub 向 Edge 发起变量写入；变量自身也必须开启写入权限。仅在现场明确授权时开启。 |
实时字节上限计算完整 UTF-8 批次，包括 Peer、Epoch、序号、修订、时间、数组结构和中文编码，不能只累计 Value 长度。配置分块是另一份配置描述载荷，使用自己的上限；Begin、连续分块和 Commit 全部完成后才算配置已应用。
例如范围有 65 个变量，实时数量上限 16 会分成多批确认；恢复快照上限若只有 4，即使配置已完整提交，也不能恢复全部 65 个最新值。应将上限覆盖实际范围，并在调试中检查丢弃数及收到的来源身份。
“配置同步并发Peer数”只用于 Hub 对多个 Edge 的维护操作，不增加实时上传线程。Edge“并发上传数量”固定为 1，填写其他值会被拒绝。验收维护并发时，核对每个 Peer 的新描述、修订和提交结果，而不只看操作已创建。
离线缓存与中心历史补录
Edge 使用与 MQTT 上传相同的 CacheDB 缓存。转发组产生的变化记录和周期快照进入缓存；断线或发送失败时保留，Hub 确认成功后删除。已经落盘的记录可在目标重启后继续补发。Hub 角色不创建出站缓存。
| 参数 | 说明 |
|---|---|
| 启用失败重试缓存 | 默认开启；关闭后，断线或发送失败的数据不保留重试。 |
| 缓存文件最大行数 | 默认 262144，必须大于 0；每个队列超限后删除最旧记录，一行可能是一条变化或一组快照。 |
| 内存队列上限 | 默认 100000，必须大于 0；达到上限先落盘，失败时保留已接收记录并拒绝新记录，由上游重试。 |
| 上传分片大小 | 默认 2000，必须大于 0；同时受实时批次数量和字节上限约束。 |
| 并发上传数量 | 固定填写 1，保持单连接的序号顺序。 |
| 过滤离线数据 | 默认关闭；开启后跳过来源采样当时离线的变量。转发组中的在线过滤也会影响采样范围。 |
要在中心补入历史记录：
- 在 Edge 启用缓存，并在转发组中选择需要的变量和变化、定时触发方式。
- 在 Hub 的“开发配置 → 数据转发”中创建历史存储组，把对应镜像变量加入范围，再添加并启用“历史数据存储”目标，配置数据库和时区。
- 补发的旧值、同值采样会按来源记录进入历史目标；实时变量保持最新状态。历史补录保留边缘处理后的值，不重新执行中心读取表达式。
- 在“调试 → 缓存”查看积压，在中心历史查询中按断线期间的时间范围核对。具体时间列和各插件边界见离线缓存与历史补录。
补录遵循中心历史组的范围、启用状态和在线过滤，不受该组的变化判定、定时周期或批组最新快照合并影响。中心组另外配置的定时采样仍会生成中心本地快照；仅需来源记录时使用变化触发。
缓存仅包含转发组实际产生且尚未超限淘汰的记录。目标停用期间未产生的数据、已移出范围的变量不会补发。应用确认表示 Hub 接受并处理了批次，数据库目标随后按自身缓存和连接状态写入；这不是数据库提交确认。确认丢失或部分批次重试可能产生重复记录，多 Hub 切换也不会把已确认的数据再复制到其它 Hub。
最新恢复快照与旧采样补发分别验证。关闭失败保留时，重连仍可恢复当前最新状态，但该快照不会重建已丢弃的旧采样；普通暂存和在途记录另行核对。目标离线过滤用于普通缓存发送；最新恢复快照仍会同步来源质量，因此开启过滤也不能保证重连时完全没有离线状态记录。
确认超时可能发生在 Hub 已经应用、Edge 尚未收到响应之后，随后可能收到 Applied 或 Duplicate。保持同一变量和来源时间核对结果，不要把重复确认当成再次产生的新采样。确认失败会进入重新连接，但首选端点仍可连接时不保证立即切到备用 Hub。
配置和实时值规则
- Hub 可从专用调试页请求单个 Edge 或全部 Edge 同步配置。
- Hub 自动建立无通道的镜像设备及变量，无需为镜像新建或选择采集通道。设备编辑页显示“SyncBridge 镜像”及自动管理说明，插件身份不可手动替换；连接参数在所属同步桥接目标中维护。
- 镜像属于内部设备，由服务端管理，不能手动新增、复制或删除。设备管理显示“内部设备”；批量选中包含内部设备时不可删除，“清空设备”仅清理普通采集设备，保留镜像及其变量。设备离线或停用时同样受保护。
- 内部设备仍可编辑名称、描述、日志等级、启用状态和备注。保存这些本地设置不会改变内部设备身份，也不会解除删除保护。
- 配置通过修订、校验和、分块和单次提交应用；中途失败不会留下半批配置。
- 已有镜像变量只更新数据类型、单位和描述；名称、表达式、报警、历史和写权限保留 Hub 本地设置。
- Edge 删除变量或把变量移出转发范围后，Hub 保留本地镜像并标记来源缺失，不会自动删除。
- 实时值按 Epoch、Sequence 和配置修订校验；Hub 应用后返回确认，迟到旧值不会覆盖新状态。
- 断线重连后先校验配置，再恢复完整最新值并消费离线缓存，最后继续发送新采样。
目标变量属性
该插件没有目标变量级附加参数。变量必须先进入 Edge 目标所属转发组的范围。反向写入还要满足源变量写权限和现场安全要求。
调试与验收
目标调试
进入“开发配置 → 数据转发”，选择同步桥接目标，打开“调试 → 协议调试 · SyncBridge”。
| 功能 | 作用 |
|---|---|
| 状态与对等端 | 查看角色、本地节点、传输状态、当前 Hub、故障切换次数、各 Hub 端点连接统计、对等端连接、待发数量、延迟和最近错误。 |
| 同步配置 | Hub 向所选 Edge 请求全部或指定范围的配置同步。 |
| 发送完整快照 | Edge 立即向 Hub 发送当前转发范围的完整快照。 |
| 重新连接 | Edge 主动断开并重新建立到 Hub 的连接。 |
| 导出诊断 | 导出当前连接和同步统计，用于排查。 |
“传输就绪”表示本机监听或连接组件已启动；Hub 没有已连接 Edge 时，目标仍可能显示离线。
同步策略与写回验收
配置同步只包含转发范围内的必要设备与变量描述，不是复制整个工程。元数据修订和运行值更新应分别验证。
- 先选“仅重连时同步”，连接成功后修改 Edge 变量描述并保存。保持同一会话，Hub 可以继续收到新值，描述却仍可能保持原修订。
- 在 Hub 请求同步或让 Edge 重新连接，确认描述与配置修订更新。
- 改为“变更和重连时同步”，再次修改范围内变量的描述，等待自动同步，检查元数据和数值都正确。
- 对每个 Hub 分别核对配置提交、完整快照和新采样。多 Hub 切换不意味着各 Hub 的历史记录自动保持一致。
反向写回需要多层许可同时满足：Hub 镜像变量允许写和 RPC、Hub 目标允许反向 RPC、Edge 目标允许反向 RPC、Edge 来源变量允许写和 RPC，最后由现场协议及设备权限决定是否执行。新建镜像默认只读且关闭 RPC，开启总开关不会自动解除这些限制。
先在安全测试点关闭一层许可，确认写入被拒绝且源值未改变；再恢复许可，从 Hub 发出一个不同的新值，依次核对逐变量写入结果、独立源端、Edge 新采样和 Hub 镜像。结束后恢复业务规定的权限。
多 Hub 与历史补传验收
- 记录活动 Hub、配置修订、应用序号和源值，确保目标处于稳定连接。
- 在维护窗口实际断开当前 Hub 的链路，保持 Edge 采集及端点列表不变。确认切换计数增加、失败端点留下错误，备用 Hub 完成配置提交及最新值应用。
- 从源端产生不同的新值，核对备用 Hub 的来源时间与序号继续推进。恢复首选 Hub 后，检查当前可用连接仍保持。
- 需要验收逐条历史时，使用变化触发和“不分批”，断开全部 Hub 后产生多个不同值及时间，再恢复连接。先核对最新恢复快照，再查普通缓存批次和 Hub 的应用确认。
- 在 Hub 历史库逐条查询断线期间的样本，同时确认实时镜像保持最新值。快照容量、缓存容量、上传分片和实时批次上限分别约束不同阶段，不能互相替代。
完整队列参数及重复记录处理见离线缓存与补传。
验证方法
- 启用 Hub 与 Edge 目标，在 Hub 调试页确认出现 Edge 的 Peer 标识且状态为“已连接”。
- 在 Hub 请求一次单 Edge 配置同步，确认修订和校验和一致。
- 在 Edge 修改一个已纳入转发范围的测试变量。
- 在 Hub 核对变量值、更新时间和入站序号，并确认待发与确认中数量回落。
- 断开当前 Hub 的实际链路，确认 Edge 在错误后按端点优先级重新连接；首选仍不可达时使用备用 Hub。恢复主 Hub 后不应从健康备用连接自动回切。
- 断开当前备 Hub，确认重新连接时按
HubEndpoints优先级重新尝试，并继续完成配置和实时值同步。 - 在维护窗口断开全部 Hub 链路，在 Edge 产生多条测试记录，再恢复连接；确认缓存减少，中心历史库按原采集时间和记录时间保存这些值，实时值不回退。
常见问题
| 现象 | 检查方法 |
|---|---|
| Edge 无法连接 Hub | Hub 监听地址、Edge Hub 冗余端点、防火墙、令牌和两端日志；调试页可查看每个端点的失败次数和最近错误。 |
| TLS 握手或后续身份校验失败 | 传输证书及私钥、CA、证书用途与有效期、吊销检查；Edge 证书 DNS 名称或主题名称匹配本地 Peer 标识，Hub 证书名称匹配 TLS 目标主机。 |
| 已连接但没有变量 | Edge 转发组范围、配置同步模式、完整快照和待发送数量。 |
| 配置不同步 | Peer标识、配置修订、同步模式，并在 Hub 手动执行一次“同步配置”。 |
| 反向写入失败 | “允许反向RPC”、源变量写权限、目标变量类型和现场联锁。 |
| 未发生故障却切换 Hub | 检查心跳、实时发送确认和配置同步日志；正常空闲连接不会触发切换，只有实际错误或连接关闭才会切换。 |
| 主 Hub 恢复后没有回切 | 这是预期行为。系统不会主动探测已恢复的主 Hub；当前端点再次发生错误并重新连接时，才按优先级重新尝试。 |