镜像同步基础：Harbor复制（Replication）机制原理、基于规则的同步策略、推拉模式对比
2.1 Harbor复制机制核心原理
Harbor的复制（Replication）模块是实现跨实例镜像分发与同步的核心引擎。其本质是一个异步任务调度系统，通过监听规则触发条件，将源Registry中的镜像元数据和Blob层数据迁移至目标Registry。
核心工作流： 规则匹配 → 任务分片 → 元数据同步 → Blob流式传输 → 状态回写
复制过程涉及以下关键组件：
- Replication Controller： 常驻后台的调度器，负责轮询规则、拆分任务、管理并发。
- Task Worker Pool： 可配置的并发工作线程池，每个Worker独立处理一个镜像的同步。
- Transfer Manager： 负责实际的HTTP/HTTPS数据传输，支持Chunked传输与断点续传。
- Status Recorder： 将每个任务的状态（成功/失败/进行中）持久化到数据库，供API和UI查询。
关键设计点： Harbor复制采用“拉模式”作为默认传输方向——由目标实例主动向源实例发起请求。这种设计能有效避免源实例因推送压力过大导致性能抖动，同时便于在目标侧控制同步节奏。
2.2 基于规则的同步策略
Harbor通过复制规则（Replication Policy）实现高度灵活的同步策略。规则定义了“什么镜像”、“从哪里”、“到哪里”、“何时触发”以及“如何同步”五个维度。
2.2.1 规则核心属性
| 属性维度 | 配置项 | 说明 |
|---|---|---|
| 源 | 源Registry / 项目 / 仓库 / Tag过滤 | 支持正则表达式匹配仓库名和Tag，例如 nginx:1\.\d+ |
| 目标 | 目标Registry / 项目 / 仓库名重写 | 支持 {project}、{repository} 等占位符动态映射 |
| 触发模式 | 手动 / 事件驱动 / 定时 | 事件驱动依赖Webhook，定时依赖Cron表达式 |
| 同步模式 | 推模式 / 拉模式 | 决定由源主动推还是目标主动拉 |
| 覆盖策略 | 覆盖 / 跳过 / 保留 | 当目标已存在同名Tag时的处理方式 |
| 删除策略 | 同步删除 / 不同步删除 | 源端删除镜像后，是否同步删除目标端对应镜像 |
2.2.2 典型同步策略场景
- 全量同步： 源项目下所有仓库和Tag全部复制到目标，适用于灾备场景。
- 增量同步： 仅同步新推送或更新的镜像，通过事件驱动触发，降低带宽消耗。
- 过滤同步： 使用正则匹配特定版本（如
release-.*或v[0-9]+\.[0-9]+），仅同步生产版本。 - 多级分发： 从中心Registry同步到多个边缘站点，每个站点使用独立的拉规则。
2.3 推模式 vs 拉模式对比
Harbor支持两种数据传输方向模式，理解其差异对架构设计和故障排查至关重要。
| 对比维度 | 推模式（Push） | 拉模式（Pull） |
|---|---|---|
| 发起方 | 源Registry主动向目标发送数据 | 目标Registry主动从源拉取数据 |
| 网络方向 | 源 → 目标（出站流量在源侧） | 目标 → 源（入站流量在源侧） |
| 防火墙要求 | 目标需开放端口供源连接 | 源需开放端口供目标连接 |
| 适用场景 | 中心化分发，源控制同步节奏 | 边缘站点主动同步，目标控制节奏 |
| 负载分布 | 源侧承担扫描和传输负载 | 目标侧承担扫描和传输负载 |
| 断点续传 | 支持（基于HTTP Range） | 支持（基于HTTP Range） |
| 多目标场景 | 源需维护多个连接，可能成为瓶颈 | 各目标独立拉取，源仅需被动响应 |
常见误区： 推模式并不比拉模式“快”。实际传输速度取决于网络带宽、并发数以及Blob大小。在跨机房或跨云场景中，拉模式通常更稳定，因为目标侧可以更好地控制重试和并发策略。
2.3.1 模式选择决策树
- 源侧网络出口带宽有限？ → 优先使用拉模式，让目标侧主动拉取，避免源侧出站被打满。
- 目标侧防火墙策略严格？ → 优先使用推模式，由源侧主动连接目标，减少目标侧入站规则配置。
- 需要中心化管控同步进度？ → 优先使用推模式，源侧统一调度所有分发任务。
- 边缘站点数量多且网络不稳定？ → 优先使用拉模式，每个边缘站点独立重试，互不影响。
2.4 复制任务生命周期
每个复制任务从创建到完成经历以下状态转换：
| 状态 | 说明 | 常见停留原因 |
|---|---|---|
| Pending | 任务已创建，等待Worker调度 | Worker池满载，等待空闲Worker |
| In Progress | 正在传输Blob层或元数据 | 大镜像传输中，或网络延迟 |
| Succeeded | 所有Blob和Manifest同步完成 | — |
| Failed | 传输过程中发生不可恢复错误 | 认证失败、磁盘空间不足、网络超时 |
| Stopped | 用户手动取消或系统强制终止 | 规则被禁用或超时策略触发 |
排查提示： 当大量任务卡在 Pending 状态时，应检查
replication.worker.count 配置是否过小。默认值为 10，可根据硬件资源适当调大，但需注意不要超过CPU核心数的2倍。