#Harbor 镜像同步至集群 Registry

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

#前提条件

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

#概述

Harbor 中的关键配置

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

流程概览

#配置步骤

#步骤 1：在 Harbor 中配置 Registry Endpoint

首先，使用 Harbor 的 Registry Endpoint 功能配置目标 Registry 信息。

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

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

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

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

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

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 配置的 Registry Endpoint
• Namespace：同步资源的命名空间名称，留空则使用源命名空间。本示例留空，使用源命名空间
• Flattening：复制镜像时是否扁平化嵌套仓库结构，留空则保留原有层级

附加设置

• Trigger Mode：选择同步触发方式，本示例选择 Event Based，在 Harbor 推送事件时触发同步
• 勾选“Delete remote resources when locally deleted”，可使 Harbor 删除时同步删除目标 Registry 中的资源
• 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 到集群 Registry 的自动镜像同步，保持镜像路径一致，支持跨基础设施的无缝部署流程。基于推送的复制确保镜像在推送到 Harbor 后能立即在目标 Registry 可用。

#常见问题

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

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

• 首先，需要故障切换机制，在主实例故障时自动切换域名解析到备实例，保证用户能继续拉取已同步的镜像。
• 其次，该功能依赖事件驱动的镜像同步，主要面向 Registry 之间的复制，不是专门针对灾备的成熟方案。

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

#可解决的问题

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

#不能解决的问题

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

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

2. 恢复点目标（RPO）：

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

3. 回切到主实例：

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

#完整灾备方案建议

要实现完善的灾备机制，应重点关注 PostgreSQL 数据库（PG）和存储层的同步。例如，实现 PostgreSQL 实时数据库复制，开启存储层同步（如 S3 跨区域复制），确保元数据和所有数据的全面一致性。

#参考资料

• Harbor Replication