harbor replication rule 卡在“pending”主因是事件驱动机制：仅新 push 的 artifact 触发任务，非定时扫描。老镜像需手动改 rule 为 * 后 trigger 才能同步。
replication rule 为什么总卡在 “pending” 状态
规则创建后长期不触发同步，界面显示 pending，不是延迟高，而是根本没被调度。Harbor 的 replication controller 默认只每 5 分钟轮询一次任务队列，且仅当源项目有新 artifact（镜像或 Helm chart）被 push 后才生成待执行任务——不是“定时轮询源仓库”，而是“事件驱动 + 延迟检查”。
常见错误现象：replication rule 启用后，已有镜像不自动同步；手动 trigger 失败并报 no eligible artifacts found；日志里反复出现 skip replication task: no new artifacts。
- 确认源项目是否真有新 push：老镜像不会被补同步，
replication rule不是“全量扫描同步”，它只管增量 - 检查目标 Harbor 的
project是否已存在且权限正确：目标项目名必须与 rule 中配置完全一致（区分大小写），且 robot account 必须有pull/push权限 - 验证 endpoint 配置：如果目标 Harbor 启用了 HTTPS 但证书非 CA 签发，需在源 Harbor 的 endpoint 配置中勾选
insecure，否则任务直接静默失败
跨数据中心同步时 tag 过滤器失效
用 **/latest 或 release-* 这类通配符在多 DC 场景下常不生效，根本原因是 Harbor 的 tag 过滤器只作用于 artifact 的 manifest 层级 tag，而不同数据中心的 Harbor 实例若未开启 clair 或 trivy 扫描，tag 元数据可能未完整索引，导致过滤逻辑跳过匹配。
使用场景：A 数据中心推送了 app:v1.2.3 和 app:latest，rule 设了 latest，但只有 v1.2.3 被同步过去。
- 优先改用正则模式：
^latest$比latest更可靠；避免用*开头，Harbor 对前导通配符支持弱 - 确保源 Harbor 的
job_service正常运行，且core日志中无tag filter not applied due to missing metadata类报错 - 如果必须同步历史 tag，临时改 rule 为
*，再手动 trigger 一次，完成后立刻切回精确模式——这是唯一绕过“仅增量”的办法
replication rule 与 robot account 权限不匹配的典型报错
最常遇到的是 401 unauthorized 或 403 forbidden，但日志里往往只显示 failed to pull artifact from source，掩盖了真实权限问题。robot account 是 Harbor 内部服务账号，它的 scope（作用域）必须显式包含目标项目，不能靠“project admin”角色继承。
错误示例：failed to create replication task: failed to get project info: 403 Forbidden，说明 robot account 在目标 Harbor 上连 GET /projects/{id} 都被拒了。
- robot account 的
access列表里，target project必须用 ID（数字）而非名称填写；填错成项目名会导致 403 - 如果目标 Harbor 启用了 LDAP/AD 认证，robot account 无法跨认证源复用——必须在目标实例单独创建同名 robot，并赋予对应权限
- 不要复用
admin用户 token：replication service 不接受 UI 用户 token，只认 robot account 的robot$xxx格式密钥
大镜像同步失败：timeout 与 chunked upload 问题
同步超过 2GB 的镜像时，经常卡在 uploading layer 阶段然后超时，错误信息类似 context deadline exceeded 或 failed to upload blob: read tcp: i/o timeout。这不是网络断开，而是 Harbor 默认的 HTTP client timeout（30s）和 backend reverse proxy（如 Nginx）的 proxy_read_timeout 不匹配。
性能影响：单个大 layer 同步失败会导致整个 artifact 失败重试，且重试不带断点续传，重复传输已成功部分。
- 调高源 Harbor 的
harbor.yml中jobservice的max_job_workers和worker_pool超时值，重点改replicationjob 的timeout（单位秒） - 目标 Harbor 前置的 Nginx 必须设置：
proxy_read_timeout 3600、proxy_send_timeout 3600，否则上传中途会被 proxy 主动断连 - 避免在 rule 中启用
override：它会强制覆盖目标层，触发完整 re-upload，对大镜像雪上加霜；只在确实需要覆盖时才打开
跨数据中心同步不是“配好 rule 就一劳永逸”，真正麻烦的是元数据一致性、权限链路断裂和超时阈值错配——这些地方一旦漏查，就会陷入“能看到任务、但永远不动”的死循环。
