Harbor镜像复制失败时，最常见的误判是反复点击重试，却没有确认失败发生在“任务未触发、鉴权失败、镜像拉取失败、目标推送失败”还是 jobservice 执行异常。镜像复制链路跨越 Harbor 策略、源仓库、目标仓库、证书、网络和后台任务，排查必须先定位断点。
如果团队还在梳理镜像和发布基础，可先从容器化开发中的镜像构建与制品流转建立上下文，再把本文作为 Harbor 同步排障清单。
图1：从复制策略、任务状态到目标仓库推送失败的排查决策树
检查点一：复制任务是否真的被策略触发
先确认失败是不是任务没有创建。很多“复制失败”其实是策略匹配不到目标镜像、触发方式选择错误或项目过滤条件过窄。
优先检查：
- 策略方向是 push 还是 pull。
- 源项目、仓库名、tag 过滤规则是否匹配。
- 手动触发和事件触发结果是否一致。
- 任务列表是否生成 execution 和 task。
- Harbor 版本是否支持当前复制目标类型。
Harbor Replication 官方文档[1]说明，复制策略会根据 endpoint、触发方式和资源过滤规则执行；因此排查时要先看策略是否覆盖实际镜像，而不是直接怀疑网络。
检查点二：目标仓库凭据和项目权限是否有效
当任务已经创建但很快失败，最常见原因是目标仓库凭据不具备推送权限。尤其是使用 robot account 时，要检查它是否有目标项目的 push 权限，以及 token 是否过期；Harbor Robot Accounts 官方文档[3]也将机器人账号作为自动化访问仓库资源的专用身份。
图2：Harbor 复制任务中源仓库、凭据、TLS 证书和目标
| 失败信号 | 可能原因 | 处理方向 |
|---|---|---|
| 401 / unauthorized | 用户名、密码或 robot token 错误 | 重新验证 endpoint 凭据 |
| 403 / denied | 有登录权限但无项目推送权限 | 检查项目角色和仓库路径 |
| repository not found | 目标项目不存在或路径不一致 | 创建项目或修正命名规则 |
| token expired | robot account 过期 | 轮换 token 并记录到凭据管理 |
目标仓库结果才是最终验证点
凭据修复后不要只看任务状态变成成功，还要到目标仓库确认镜像 digest 是否一致。
检查点三：TLS 证书和代理配置是否阻断传输
证书问题经常在跨地域、内网仓库或自签名证书环境中出现。不要把“跳过证书校验”作为默认方案，生产环境更推荐把可信 CA 正确配置到 Harbor 组件和运行环境中。
常见证书与网络问题包括：
- 目标 endpoint 使用自签名证书，但 Harbor 不信任该 CA。
- 证书域名与 endpoint 地址不匹配。
- 出口代理只允许部分域名或端口。
- 中间网络设备重置大镜像层传输连接。
- DNS 解析到旧地址或不可达地址。
如果团队同时维护 Kubernetes 镜像拉取链路，也可以把镜像可信、仓库权限和准入策略一起设计，避免复制成功后在下游拉取或准入阶段再次失败。
检查点四：jobservice 队列和日志是否出现积压
Harbor 复制任务由后台任务执行。任务状态卡住、长时间 pending 或大量 retry，可能不是单个策略问题，而是 jobservice 或 registry 组件压力问题。
建议查看：
- jobservice 日志中的 task id 和错误堆栈。
- Harbor UI 中 execution 和 task 的失败详情。
- registry 存储后端是否有空间、权限或延迟异常。
- 同一时间是否有大量扫描、垃圾回收或复制任务并发。
Harbor Troubleshooting 官方文档[2]建议排障时结合组件日志、任务状态和系统配置，而不是只看 UI 顶层状态。
检查点五：修复后做端到端验证
修复 Harbor 复制失败后，必须验证完整链路，而不是只看某一次任务成功。
图3：从策略修复、任务重试到目标仓库 digest 校验和发布
验证顺序建议：
- 选择一个小镜像手动触发复制。
- 确认 execution、task 和日志均成功。
- 在目标仓库检查项目、仓库、tag 和 digest。
- 在测试集群拉取目标仓库镜像。
- 恢复事件触发策略并观察一段时间。
关键结论：Harbor 复制排障的终点不是任务成功，而是目标仓库镜像可被下游发布链路稳定使用。
小结
Harbor镜像复制失败通常可以从 5 个检查点收敛：策略是否触发、凭据是否有效、证书和代理是否通、jobservice 是否正常、目标镜像是否可用。排查时先定位失败阶段，再处理对应组件，避免用重试掩盖权限或网络问题。
参考资料
常见问题
1. Harbor镜像复制失败后可以直接重建策略吗？
不建议先重建。应先导出或记录原策略的 endpoint、过滤规则和触发方式，再判断是否是策略匹配、权限或网络问题。直接重建可能掩盖根因，也可能引入重复复制。
2. 复制任务成功但目标仓库拉取失败怎么办？
先检查目标仓库的项目权限、镜像 digest、tag 是否一致，再验证下游集群的 imagePullSecret、网络和证书信任。复制成功只说明 Harbor 侧写入成功，不代表所有集群都能拉取。
3. 自签名证书环境能不能关闭 TLS 校验？
测试环境可短期验证问题，但生产环境不建议作为常态。更稳妥的做法是让 Harbor 和下游运行时信任企业 CA，并记录证书轮换流程。
4. 多个复制任务同时失败应该先看哪里？
如果多个目标或多个项目同时失败，优先看 Harbor jobservice、registry 存储、网络出口和证书配置；如果只有单个目标失败，再聚焦 endpoint 凭据、目标项目权限和路径规则。
