#Harbor 镜像同步到集群镜像仓库

本指南介绍如何配置 Harbor 复制规则，实现当有新镜像推送时，自动将镜像从 Harbor 同步到集群中的镜像仓库。

#前提条件

• 已运行的 Harbor 服务
• 本地安装了 podman 客户端或其他镜像管理工具，用于向 Harbor 推送镜像
• 部署了镜像仓库的 Kubernetes 集群
• 本地安装并配置了 kubectl，可访问 Kubernetes 集群

#概述

Harbor 中的关键配置

• 镜像仓库端点：向 Harbor 添加目标镜像仓库信息
• 复制规则：定义同步哪些镜像及同步路径

流程概览

#配置步骤

#步骤 1：在 Harbor 中配置镜像仓库端点

首先，使用 Harbor 的“镜像仓库端点”功能配置目标镜像仓库信息。

1. 登录 Harbor，进入 Administration > Registries
2. 点击 NEW ENDPOINT，并配置以下内容：

• Provider：选择你的镜像仓库类型，本示例选择 Harbor
• Name：为目标镜像仓库提供描述性名称，建议使用 <cluster-name>-registry 格式，便于识别
• Endpoint URL：输入镜像仓库 URL（例如 https://cluster1-registry.example.com）
• Access ID：具有目标镜像仓库 Push/Delete 权限的用户名
• Access Secret：上述用户的密码
• Verify Remote Cert：是否验证远程仓库证书。自签名或不受信任证书请取消勾选

3. 点击 TEST CONNECTION 验证配置及网络连通性
4. 点击 OK 保存配置

#步骤 2：在 Harbor 中配置复制规则

接下来，配置复制规则，定义 Harbor 如何将镜像同步到目标镜像仓库。

1. 进入 Administration > Replications
2. 点击 NEW REPLICATION RULE，并配置：

基本设置

• Name：使用描述性名称，如 <cluster-name>-registry-replication
• Replication mode：选择 Push-based，即在镜像推送到 Harbor 时触发同步

源资源过滤器

配置过滤条件以确定同步哪些制品：

• Name：按资源名称过滤，留空或使用 ** 表示匹配所有，本示例留空同步所有仓库
• Tag：按标签/版本过滤，留空或使用 ** 表示匹配所有标签，本示例留空同步所有标签
• Label：按制品标签过滤，留空表示匹配所有制品，本示例留空同步所有制品
• Resource：过滤资源类型，本示例选择 ALL 同步所有制品类型

目标

定义同步目标及路径结构：

• Destination registry：选择步骤 1 配置的镜像仓库端点
• Namespace：指定同步资源的命名空间，留空则使用源命名空间，本示例留空
• Flattening：复制镜像时是否扁平化嵌套仓库结构，留空则保留原有层级

附加设置

• Trigger Mode：选择同步触发方式，本示例选择 Event Based，即基于 Harbor 推送事件触发同步
  • 若希望 Harbor 删除时同步删除目标资源，勾选“Delete remote resources when locally deleted”
• Bandwidth：设置每个复制工作线程的最大网络带宽（-1 表示不限）
• Options：
  • 勾选 Override 以覆盖目标已有资源
  • 勾选 Enable rule 激活复制规则

#步骤 3：验证镜像同步

向 Harbor 推送镜像

推送镜像以触发同步：

podman pull alpine:latest
podman tag alpine:latest <your-harbor-address>/library/alpine:latest
podman push <your-harbor-address>/library/alpine:latest

监控 Harbor 中的同步任务

1. 在 Harbor 中进入 Administration > Replications
2. 选择新建的复制规则，查看自动触发的同步任务
3. 点击执行记录查看详细信息

验证同步结果

在目标集群创建一个 Pod，测试镜像是否同步成功：

kubectl run alpine-test --image=<your-cluster-registry-address>/library/alpine:latest -- sleep 3600

如果 Pod 启动成功，说明同步正常。

#总结

本配置实现了 Harbor 到集群镜像仓库的自动镜像同步，保持镜像路径一致，支持跨基础设施的无缝部署流程。基于推送的复制确保镜像在推送到 Harbor 后能立即在目标仓库可用。

#常见问题

#复制功能能否用于 Harbor 灾备？

Harbor 的复制功能只能提供初步的灾备方案，存在一定局限性。

• 首先，需要有故障切换机制，在主实例故障时自动切换域名解析到备实例，使用户能继续拉取已同步的镜像。
• 其次，该功能依赖事件驱动的镜像同步，主要用于仓库间复制，非专门针对灾备设计的成熟方案。

以下内容分析该方案能解决和不能解决的问题。

#可解决的问题

• 镜像数据自动同步：主实例的容器镜像和 Helm Chart 可自动同步到备实例，启用“同步删除”选项时，主实例删除的镜像也会自动从备实例删除。
• 自动故障切换：主实例故障时，外部域名解析自动切换到备实例，用户可拉取已同步镜像（恢复时间目标 RTO 主要取决于故障切换机制）。

#不能解决的问题

1. 非镜像数据的自动同步（关键！）：

• 问题描述：Harbor 复制功能不同步用户账号、权限配置（如 OIDC 设置）、项目成员组、审计日志等元数据。
• 影响：元数据不同步导致故障切换后用户无法访问 Harbor，严重影响灾备目标。

2. 恢复点目标（RPO）：

• 问题描述：复制功能非专为灾备设计，镜像复制依赖后台任务执行，无法保证故障时主仓库所有镜像均已同步至备仓库。
• 影响：主仓库故障时，用户无法拉取尚未同步的镜像。

3. 回切到主实例：

• 问题描述：当前方案仅支持自动切换到备实例，回切主实例需手动操作。
• 影响：回切前需将备实例增量数据同步回主实例，否则数据丢失。

#完整灾备方案建议

建议从 PostgreSQL 数据库和存储层面实现同步，例如对 PostgreSQL 实现实时数据库复制，存储层启用跨区域复制（如 S3 跨区域复制），确保元数据和所有数据的全面一致性。

#参考资料

• Harbor Replication