企业官网建设流程全解析

Harbor 复制（Replication）远程证书验证设置实战：对接自签名证书仓库的配置与验证

【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor

导读

当 Harbor 通过复制（Replication）功能与远端仓库（Registry Endpoint）同步镜像时，若对方站点使用自签名 HTTPS 证书，默认的证书校验会让握手失败、复制任务报错。本文以仓库中的功能测试用例 8-04-Replication-edit-verify-remote-certificate.md 为核心骨架，完整还原"关闭远程证书验证 → 添加自签名证书端点 → 建立并启用复制规则"的配置路径，并从 TLS 传输层、Registry 数据模型、复制传输器 等源码角度解释其底层原理。读完本文，你将掌握在 Harbor 中安全、正确地处理不可信/自签名远端证书的完整方案，并理解"全局开关"与"端点级配置"之间的真实关系。

一、问题背景：复制功能为什么会被证书卡住

Harbor 的复制功能用于在两个容器镜像仓库之间同步制品（Artifact）。执行复制任务时，Harbor 的后端（core 与 jobservice）会以 HTTP 客户端身份访问远端仓库的/v2/等 Registry API 端点。此时如果远端站点启用了 HTTPS 且证书由私有 CA 签发或属于自签名证书，标准 TLS 校验会因"证书不受信任"而失败，表现即为复制任务持续失败。

针对这类场景，Harbor 提供了一条配置路径，其验证逻辑正是由测试用例 8-04 覆盖的：管理员可以调整"验证远程证书"（Verify Remote Certificate）相关设置，使得 Harbor 在复制时不再强制校验远端证书，从而让复制任务能够正常完成。

二、"验证远程证书"设置：全局配置与端点级配置

2.1 全局配置项（UI 配置页）

在系统管理的配置页面（Configuration）中，"复制"（Replication）分类下存在一个"验证远程证书"（Verify Remote Certificate）开关。前端将其定义为配置项verify_remote_cert，类型为布尔值，见 config.ts；其默认值为false，见 config.ts：

// src/portal/src/app/base/left-side-nav/config/config.ts verify_remote_cert: BoolValueItem; // ... this.verify_remote_cert = new BoolValueItem(false, true);

说明：从源码结构看，verify_remote_cert是早期 Harbor 用于统一控制复制连接是否校验证书的全局布尔开关（前端仍保留该字段且默认可编辑）。在当前版本的复制引擎中，实际的证书校验行为已由端点（Endpoint）级别的insecure与ca_certificate字段决定（见下文 2.2），因此在较新版本中即使关闭该全局开关，仍建议在添加端点时同步配置端点的证书策略。

2.2 端点级配置（Registry 模型）

无论是源仓库还是目标仓库，每一个被添加的端点都会以Registry对象持久化。该结构体定义在 registry.go，其中与证书校验直接相关的字段有两个：

// src/pkg/reg/model/registry.go type Registry struct { ID int64 `json:"id"` Name string `json:"name"` Description string `json:"description"` Type string `json:"type"` URL string `json:"url"` // ... Credential *Credential `json:"credential"` Insecure bool `json:"insecure"` CACertificate string `json:"ca_certificate,omitempty"` Status string `json:"status"` // ... }

• Insecure（insecure）：true表示跳过对远端服务器证书的验证（对应 UI 中"不安全/验证证书"勾选框，见 create-edit-endpoint.component.html 中的destination_insecure复选框）；
• CACertificate（ca_certificate）：允许为端点指定自定义 CA 证书（支持证书链），用于信任由私有 CA 签发的证书，而无需完全关闭验证。

这两个字段通过 v2.0 API 在创建/更新端点时写入，参见 registry.go 与 registry.go。

三、源码级原理：TLS 传输层如何决定验证行为

复制执行期间，所有对远端仓库的 HTTP 请求都经由统一的传输层构造。核心逻辑集中在 transport.go 的GetHTTPTransport，其优先级规则如下：

1. 提供自定义 CA 证书（CACertificate非空）时，创建携带自定义 CA 的新 transport，自定义 CA 会被追加到系统 CA 池（WithCustomCACert，见 transport.go）；
2. 否则，若Insecure为true，返回跳过证书验证的共享 transport（insecureHTTPTransport，其构造为NewTransport(WithInsecureSkipVerify(true))，见 transport.go 与 transport.go）；
3. 否则返回使用系统 CA 池的标准安全 transport。

关键点在于：自定义 CA 优先于 insecure。也就是说，只要给端点配置了合法的自定义 CA 证书，即使insecure被误设为true，也会按自定义 CA 校验（WithCACert与WithInsecure的组合逻辑见 transport.go）。

复制任务在执行时，会为源/目标仓库分别创建客户端并记录insecure标志，见 transfer.go：

// src/controller/replication/transfer/image/transfer.go t.logger.Infof("client for source registry [type: %s, URL: %s, insecure: %v] created", src.Registry.Type, src.Registry.URL, src.Registry.Insecure) // ... t.logger.Infof("client for destination registry [type: %s, URL: %s, insecure: %v] created", dst.Registry.Type, dst.Registry.URL, dst.Registry.Insecure)

对 Harbor 类型的目标端点，adapter 同样依据registry.Insecure与registry.CACertificate构造 HTTP 客户端，见 adapter.go。还有一个值得注意的特殊分支：当目标端点指向本机 Harbor 实例（LOCAL Harbor）时，代码会强制使用 insecure transport 并忽略 CA 证书，以避免"127.0.0.1 与证书 IP SAN 不匹配"的校验错误，见 adapter.go。

四、测试用例全流程演练（8-04 实操还原）

以下步骤完整继承自测试用例 8-04-Replication-edit-verify-remote-certificate.md，并补充了界面与验证细节。

4.1 前置环境

• 一个正在运行且可访问的 Harbor 实例（含管理后台 UI）；
• 一台安装有 Docker CLI（Docker 客户端）的 Linux 主机；
• 一个使用了自签名证书的远端仓库站点（用于充当复制的目标/源端点）。

4.2 操作步骤

Step 1：以管理员身份登录 Harbor UI。使用具备系统管理权限的账号（admin）登录 Web 控制台，进入"系统管理 → 配置"。

Step 2：在配置页的"复制"（Replication）区域，取消勾选"验证远程证书"设置。找到"验证远程证书"（Verify Remote Certificate）开关并取消勾选。该操作即对应修改verify_remote_cert配置项。

Step 3：保存设置。点击页面底部的"保存"按钮。设置生效后，复制相关的连接策略将按新配置执行。

Step 4：添加一个使用自签名证书的端点（Endpoint）。在"系统管理 → 仓库管理（Registries）"中点击"新建目标"，填写：

• 名称与描述（可选）；
• 提供方类型：按远端仓库类型选择（如 Harbor、Docker Registry 等）；
• 端点 URL：填写远端仓库的 HTTPS 地址（如https://192.168.1.100:5000）；
• 访问凭证（Access Key / Access Secret）；
• 证书策略：为对接自签名证书，勾选"不安全"（跳过证书验证），或在"CA 证书"输入框中粘贴远端站点使用的 CA 证书内容（推荐做法）。

添加完成后可点击"测试连接"（Ping）验证连通性。该操作对应的后端实现见 registry.go 的PingRegistry，它会对 URL、insecure、ca_certificate等参数进行校验后向远端发起健康检查，只有远端健康（healthy）才会通过。

Step 5：为任意项目添加一条复制规则并启用。在"系统管理 → 复制管理（Replication）"中新建规则：

• 选择源仓库/目标仓库为步骤 4 添加的端点；
• 选择复制模式（Push / Pull）与资源过滤器（如按仓库名或标签过滤）；
• 选择触发方式（手动、定时或事件驱动）；
• 保存并启用该规则。

4.3 预期结果

根据测试用例的 Expected Outcome：在 Step 5 完成后，对应项目可以被成功复制（replicated）。也就是说，即使远端仓库使用自签名证书，只要正确关闭了证书验证（或配置了可信 CA），复制任务即可正常拉取/推送制品，而不会因 TLS 校验失败而中断。

五、验证与排错建议

1. 查看复制执行记录：进入"复制管理"页面查看规则最近的执行历史与任务日志。若出现x509: certificate signed by unknown authority之类的错误，说明证书验证仍然生效，请回头检查端点的insecure/ca_certificate配置是否已保存。
2. 确认传输层日志：复制任务的日志中会打印client for destination registry [type: ..., URL: ..., insecure: ...]（见 transfer.go），通过insecure值可确认实际采用的连接策略。
3. 使用"测试连接"：添加/编辑端点时的 Ping 测试能快速暴露证书与连通性问题，且对已保存的端点，Ping 会以其已保存的连接设置为准，避免被临时传入的 URL/证书参数误导（见 registry.go 的注释说明）。
4. 注意本地 Harbor 特例：当复制目标为本机 Harbor 时，adapter 会强制使用 insecure 连接，日志中会给出Using INSECURE transport - CA certificate will be IGNORED的警告，这属于预期行为，见 adapter.go。

六、安全建议：优先使用自定义 CA，而不是全局关闭验证

完全跳过证书验证会暴露于中间人（MITM）攻击风险，因此生产环境建议按以下优先级决策：

1. 首选：在端点配置中粘贴远端仓库的 CA 证书（ca_certificate），既保持 TLS 完整性校验，又能信任私有 CA 签发的证书；该证书会与系统 CA 池合并使用（见 transport.go）。
2. 次选：仅在自签名证书无法更换、且网络环境可信（如隔离的内网）时，才对特定端点启用 insecure 跳过验证。
3. 避免：不加区分地全局关闭证书验证，尤其当复制链路需要跨越不可信网络时。

另外，Harbor 安装配置模板 harbor.yml.tmpl 中也体现了同类策略——trivy扫描组件的insecure标志（# insecure The flag to skip verifying registry certificate）默认关闭，需要时再显式开启，这反映了 Harbor 整体上"默认验证、按需放宽"的安全取向。

七、相关资源

• 测试用例原文：8-04-Replication-edit-verify-remote-certificate.md
• Registry 数据模型（Insecure/CACertificate字段）：src/pkg/reg/model/registry.go
• TLS 传输层实现（自定义 CA / insecure 优先级）：src/common/http/transport.go
• 复制传输器（源/目标客户端创建）：src/controller/replication/transfer/image/transfer.go
• Harbor 类型端点 adapter：src/pkg/reg/adapter/harbor/base/adapter.go
• 端点 Ping/健康检查 API：src/server/v2.0/handler/registry.go
• 前端端点表单（insecure 复选框）：create-edit-endpoint.component.html
• 前端全局配置定义（verify_remote_cert）：src/portal/src/app/base/left-side-nav/config/config.ts

【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor