Harbor如何将镜像自动复制到远程仓库？

Question

**常见技术问题：** 在Harbor中配置了基于事件触发的镜像复制策略（如“push”事件），但新推送的镜像始终未自动同步至远程Harbor仓库，日志显示“replication task skipped: no matching resources”。可能原因包括：① 源项目未启用“可复制”（Repliable）属性；② 复制过滤器（Filter）设置过于严格（如正则表达式不匹配镜像名或标签）；③ 目标端项目不存在或权限不足（目标Harbor需预先创建同名项目且源Harbor账户具备pull权限）；④ 复制策略状态为“Disabled”或未关联到正确的目标Endpoint；⑤ Harbor版本差异导致事件监听机制异常（v2.5+默认启用异步事件总线，旧版需确认`core`服务是否正常消费`redis`队列）。排查建议：检查`/api/v2.0/replication/policies` API返回策略状态，结合`core.log`中`replication`模块日志定位跳过原因。

Answer 1

```html

一、现象层：典型错误日志与表象特征

运维人员在 Harbor UI 中配置了“Event-based”复制策略（触发条件为 push），但新镜像推送后目标仓库无任何同步动作；core.log 中高频出现关键错误：

replication task skipped: no matching resources

该日志并非表示网络失败或认证错误，而是策略引擎主动跳过执行——说明事件已捕获，但资源匹配阶段即终止。此为典型的“策略逻辑未命中”问题，需穿透五层配置栈定位断点。

二、配置层：五大核心配置项的合规性校验清单

以下为必须逐项验证的配置矩阵，任一缺失或错配均导致资源匹配失败：

序号	配置项	检查方式	合规示例	高危陷阱
①	源项目 Repliable 属性	UI：项目设置 → 勾选“Enable Replication”；或 API：GET /api/v2.0/projects/{id} 查 metadata.enable_content_trust 非关联字段，实际查 metadata.enable_replication	"enable_replication": "true"	新建项目默认为 false，且 UI 翻页后易被忽略
②	Filter 正则表达式	策略编辑页 → Filters → Name/Tag 字段；验证工具：echo "nginx:1.25.3" | grep -E 'nginx.*'	Name: ^nginx$；Tag: ^1\.[0-9]+\.[0-9]+$	未转义点号（.）、未锚定行首行尾（^/$）、标签含特殊字符（如 latest）未显式声明

三、架构层：Harbor v2.5+ 异步事件总线机制深度解析

v2.5 起 Harbor 彻底重构事件分发模型：由原 core 同步轮询改为 event-scheduler → redis stream → event-controller 异步消费链路。若 event-controller Pod 崩溃或 Redis 连接中断，push 事件将滞留在 harbor_events stream 中，core 日志不报错但永不触发复制。

诊断命令：

kubectl exec -it harbor-harbor-core -- redis-cli \
  --no-auth-warning -h harbor-harbor-redis \
  XLEN harbor_events

若返回值持续增长 > 0，则证明事件积压 —— 此时 replication task skipped 实为“事件未送达策略引擎”。

四、权限层：跨 Harbor 项目级权限的隐式依赖关系

目标 Harbor 的项目不仅需存在，还必须满足双重权限契约：

1. 源 Harbor 账户对目标项目的 pull 权限：复制任务本质是源端发起 pull 操作，故需在目标 Harbor 的 Project → Members 中，将源 Harbor 的 robot account（如 robot$harbor-src）添加为 Developer 或更高角色；
2. 目标项目未启用内容信任（Content Trust）强制策略：若目标项目开启 Enable Content Trust，而源镜像无签名，则复制会静默失败（日志仍显示 no matching resources，因签名验证前置拦截）。

五、验证层：结构化排障流程图与 API 交叉验证法

采用“API 状态快照 + 日志上下文锚定”双轨验证：

graph TD
  A[调用 GET /api/v2.0/replication/policies] --> B{策略 status == enabled?}
  B -->|否| C[UI 启用策略或 PATCH /policies/{id}]
  B -->|是| D[检查 targets[].id 是否匹配目标 Endpoint ID]
  D --> E[调用 GET /api/v2.0/registries/{target_id} 验证连通性]
  E --> F[检索 core.log 中 'replication' + 'filter' 关键词上下文]
  F --> G[定位 filter.matchResources 输出的 actual name/tag]

六、实战案例：一次生产环境根因溯源纪实

某金融客户 Harbor v2.6.3 集群出现同步失效，经上述流程排查发现：

• Filter 设置为 Name: nginx.* —— 未加 ^ 导致匹配到 my-nginx-app 等非目标镜像，实际应为 ^nginx$；
• 目标 Harbor 项目启用了 Content Trust，而源镜像使用 docker build -t nginx:prod . 未签名；
• event-controller 因 Redis 内存满（maxmemory-policy noeviction）拒绝写入，stream 积压 172 条事件。

修复后 3 分钟内完成积压事件消费，新推送镜像秒级同步。

```