Linux harbor 的 replication rule 与多数据中心镜像同步

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 超时值，重点改 replication job 的 timeout（单位秒）
• 目标 Harbor 前置的 Nginx 必须设置：proxy_read_timeout 3600、proxy_send_timeout 3600，否则上传中途会被 proxy 主动断连
• 避免在 rule 中启用 override：它会强制覆盖目标层，触发完整 re-upload，对大镜像雪上加霜；只在确实需要覆盖时才打开

跨数据中心同步不是“配好 rule 就一劳永逸”，真正麻烦的是元数据一致性、权限链路断裂和超时阈值错配——这些地方一旦漏查，就会陷入“能看到任务、但永远不动”的死循环。