Harbor部署时镜像同步失败如何排查？

Question

在Harbor部署过程中，镜像同步失败的常见问题之一是目标项目不存在或未正确配置复制规则。当使用 Harbor 的镜像复制功能进行跨实例同步时，若目标端未预先创建对应项目或项目类型（如私有项目）不兼容，则会导致同步任务失败。该问题通常伴随“403 Forbidden”或“project not found”等错误日志。排查时应首先确认源和目标项目的名称、可见性及认证信息是否正确；其次检查复制策略中的端点配置与目标 Harbor 实例网络连通性；最后查看任务日志以定位具体失败阶段。确保目标项目已存在且具备写入权限，是解决此类同步问题的关键步骤。

Answer 1

一、Harbor镜像同步失败的常见现象与初步诊断

在使用 Harbor 的跨实例镜像复制功能时，最常见的失败场景之一是目标项目不存在或复制规则配置不当。当源 Harbor 实例尝试将镜像推送到目标 Harbor 时，若目标端未创建对应的项目，系统通常会返回 403 Forbidden 或 project not found 错误。

这类问题多发生在以下几种情况：

• 目标 Harbor 实例中未手动创建对应名称的项目
• 项目类型不匹配（如源为公开项目，目标为私有项目且权限受限）
• 复制策略中使用的机器人账户（Robot Account）或用户账户缺乏写入权限
• 网络隔离导致目标 Harbor 端点不可达

初步排查应从日志入手。可在 Harbor 的“Jobservice”或“Core”组件日志中搜索关键词 replication、failed、403 等，快速定位错误来源。

二、深入分析：复制机制与权限模型

Harbor 的镜像复制基于 Pull/Push 模型，依赖于复制策略（Replication Policy）和目标端点（Endpoint）配置。其核心流程如下：

1. 源 Harbor 根据策略触发复制任务
2. 通过 HTTP/HTTPS 调用目标 Harbor API 进行认证
3. 尝试在目标项目下创建仓库或推送镜像层
4. 若项目不存在或权限不足，则任务中断并记录错误

Harbor 的权限控制严格遵循项目级别的访问策略。即使认证成功，若目标项目不存在，API 将拒绝创建新项目（除非启用自动创建功能）。此外，私有项目的写入操作必须由具有 “Project Admin” 或 “Developer” 角色的账户执行。

错误码	可能原因	建议操作
403 Forbidden	账户无目标项目写入权限	检查角色权限或使用 Robot Account
404 Not Found	目标项目不存在	手动创建项目或启用自动创建
502 Bad Gateway	网络不通或目标 Harbor 不可达	检查 DNS、防火墙、TLS 配置

三、解决方案与最佳实践

解决此类问题需系统性地验证配置、权限与网络连通性。以下是推荐的操作流程：

# 示例：通过 curl 验证目标 Harbor 是否可访问项目
curl -u "admin:Harbor12345" \
  https://harbor-target.example.com/api/v2.0/projects/demo-project

# 若返回 404，则需创建项目
curl -X POST -u "admin:Harbor12345" \
  -H "Content-Type: application/json" \
  -d '{"project_name":"demo-project", "public": false}' \
  https://harbor-target.example.com/api/v2.0/projects

在 Web 控制台中，确保复制策略的配置包含以下关键字段：

• Target Endpoint：正确指向目标 Harbor 实例
• Project：源与目标项目名称一致
• Enable Sync：开启自动同步
• Override：允许覆盖已有镜像

四、自动化与流程可视化

为提升运维效率，可通过 CI/CD 流程预创建目标项目，或使用 Terraform 管理 Harbor 资源。以下为镜像同步失败的典型排查流程图：

graph TD A[启动复制任务] --> B{目标项目是否存在?} B -- 否 --> C[尝试创建项目] C --> D{是否有项目创建权限?} D -- 否 --> E[报错: 403 Forbidden] D -- 是 --> F[创建项目] F --> G[继续推送镜像] B -- 是 --> H{账户是否有写入权限?} H -- 否 --> I[报错: 403 Forbidden] H -- 是 --> J[成功同步镜像] G --> J

该流程清晰展示了权限校验与项目存在性检查的逻辑顺序，有助于开发和运维团队理解底层机制。