尧图网站建设 
Harbor 内容信任实战Docker 客户端拉取已签名镜像DB 模式完整指南【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor导读本文以 Harbor 官方内容信任Content Trust测试用例 9-03-DB-user-pull-signed-images.md 为骨架系统讲解在本地数据库DB 模式认证环境下普通用户如何通过 Docker 客户端启用 Docker Content TrustDCT并成功拉取已签名镜像的完整流程。读者将掌握DOCKER_CONTENT_TRUST与DOCKER_CONTENT_TRUST_SERVER环境变量的正确配置、自签名证书环境下 Notary 服务的信任配置、签名镜像在 Harbor Web 界面的识别方法以及 Harbor 服务端在拉取链路上执行内容信任校验的底层原理。背景为什么需要内容信任与 NotaryHarbor 是一个开源的云原生制品仓库支持制品的存储、签名与扫描。内容信任Content Trust基于 Docker 的 Notary 项目实现当客户端启用 DCT 后推送镜像时会同时生成签名元数据并上传至 Notary 服务Harbor 中该服务默认监听4443端口拉取镜像时Docker 客户端会先向 Notary 校验镜像的签名与信任链再决定是否拉取对应镜像内容。在 Harbor 中内容信任的落地分为两个层面客户端层面由 Docker CLI 通过环境变量控制是否签名、是否校验签名服务端层面当项目开启了内容信任策略后Harbor 的 Registry 路由会在拉取镜像的请求链路上插入校验中间件强制要求镜像存在有效签名否则拒绝拉取。本文聚焦第一个层面——用户主动开启 DCT 并成功拉取已签名镜像对应测试用例 9-03。环境准备依据测试用例的Environment一节执行本流程需要满足一个正在运行且可访问的 Harbor 实例本地数据库认证模式即 DB 模式一台安装了 Docker CLIDocker 客户端的 Linux 机器一个已经存在的 Harbor 项目文中以 project X 代指。补充说明DB 模式意味着用户数据存放在 Harbor 内置的本地数据库中与之相对的是 LDAP/AD 等外部认证模式。本测试用例 9-03 针对 DB 模式设计对应的 LDAP 版本见 9-13-LDAP-user-pull-signed-images.md管理员版本见 9-23-admin-pull-signed-images.md。测试步骤详解第 1 步登录 Harbor Web UI在浏览器中访问 Harbor 门户使用具有目标项目访问权限的普通用户账号登录 UI。确保目标项目 X 已存在可通过 9-01-DB-user-push-signed-images.md 中的流程创建项目并推送已签名镜像作为前置准备。第 2 步在 Docker 客户端启用内容信任并登录在 Docker 客户端主机上执行以下环境变量设置export DOCKER_CONTENT_TRUST1 export DOCKER_CONTENT_TRUST_SERVERhttps://harbor_ip:4443DOCKER_CONTENT_TRUST1通知 Docker CLI 启用内容信任模式。此模式下docker pull在拉取镜像前会先向信任服务器查询该镜像的签名元数据只有签名有效时才继续拉取镜像内容。DOCKER_CONTENT_TRUST_SERVERhttps://harbor_ip:4443显式指定信任服务器地址。Harbor 部署的 Notary 服务默认暴露在 4443 端口HTTPS。不设置此变量时Docker 会按https://registry_host:4443的默认约定推断但在 Harbor 场景下显式指定更稳妥。设置完成后登录 Harbordocker login harbor_ip按提示输入用户名与密码。若目标 Harbor 使用了非默认端口需在harbor_ip后附带端口号。自签名证书注意事项如果 Harbor 使用自签名证书Docker 客户端默认不会信任该证书必须将 CA 根证书复制到以下两个位置来自测试用例的 NOTE 说明# Registry 访问信任 /etc/docker/certs.d/harbor_ip/ # Notary 信任服务器访问信任端口 4443 $HOME/.docker/tls/harbor_ip:4443/完成证书放置后重启 Docker 守护进程使其生效。这一步骤缺失时docker login或后续的信任校验会因 TLS 证书不受信任而失败。第 3 步拉取已签名镜像从项目 X 中拉取一个已签名镜像docker pull harbor_ip/project_x/signed-image:tag其中project_x应替换为实际项目名signed-image:tag替换为实际镜像名与标签。预期结果根据测试用例Expected Outcome镜像可以被成功拉取。即docker pull命令成功完成本地出现该镜像。这表明在DOCKER_CONTENT_TRUST1下Docker 客户端成功向 Harbor 的 Notary 服务4443 端口验证了镜像签名随后从 Registry 拉取了镜像内容。服务端原理Harbor 如何配合签名拉取虽然测试用例 9-03 主要验证客户端开启 DCT 后能拉到签名镜像但理解 Harbor 服务端的处理逻辑有助于排查问题。从源码看Harbor 在 Registry 的 manifest 拉取链路上挂了内容信任中间件。在 src/server/registry/route.go 中GET与HEAD两种/*/manifests/:reference请求都挂载了contenttrust.ContentTrust()中间件root.NewRoute(). Method(http.MethodGet). Path(/*/manifests/:reference). Middleware(metric.InjectOpIDMiddleware(metric.ManifestOperationID)). Middleware(repoproxy.ManifestMiddleware()). Middleware(contenttrust.ContentTrust()). Middleware(vulnerable.Middleware()). HandlerFunc(getManifest)中间件实现位于 src/server/middleware/contenttrust/contentrust.go它根据请求中的ArtifactInfo找到对应项目若项目开启了内容信任策略ContentTrustEnabled()或ContentTrustCosignEnabled()则进一步调用signatureChecking检查制品是否带有对应类型的签名 accessory若无签名则返回PROJECTPOLICYVIOLATION错误拒绝拉取。项目级策略通过项目元数据metadata实现键定义在 src/pkg/project/models/pro_meta.goenable_content_trust对应ProMetaEnableContentTrust是否要求镜像具备 Notation 签名enable_content_trust_cosign对应ProMetaEnableContentTrustCosign是否要求镜像具备 Cosign 签名。对应的布尔判断实现在 src/pkg/project/models/project.go。需要强调的是9-03 场景下项目未必开启了上述项目级策略拉取成功的关键在于 Docker 客户端自身开启 DCT 并成功完成签名校验。项目级策略是另一道服务端强制门禁对应测试 9-30-Project-level-content-trust.md启用策略后未签名镜像将无法拉取而签名镜像可以拉取。关联场景签名镜像的完整生命周期9-03 属于 Group9-Content-trust 测试组中DB 模式普通用户的子集将其放入整个测试矩阵可以更清楚地理解内容信任的完整闭环测试用例操作关键预期9-01开启 DCT 后推送镜像镜像被签名并推送成功UI 显示绿色对勾9-02关闭 DCT 推送镜像推送成功但无签名9-03开启 DCT 拉取已签名镜像拉取成功9-04开启 DCT 拉取未签名镜像拉取被拒绝9-05删除已签名镜像删除成功从 9-01 的Expected Outcome可以看到签名镜像在 Harbor UI 中会以绿色对勾标识呈现这是确认镜像已被签名的最直观方式。在 9-04 中当DOCKER_CONTENT_TRUST1时拉取未签名镜像会失败——这正是 Docker 客户端侧 DCT 校验拦截的结果与 9-03 形成对照。常见问题与排查思路测试用例中Possible Problems为 None但在真实环境中仍可能遇到以下情况TLS 证书错误x509: certificate signed by unknown authority自签名证书未按上文复制到/etc/docker/certs.d/harbor_ip/与$HOME/.docker/tls/harbor_ip:4443/或复制后未重启 Docker 守护进程。拉取被拒could not find signed tag/no valid trust data目标镜像本身未签名未在 DCT 开启状态下推送请先通过 9-01 流程准备签名镜像或在 UI 中确认镜像带绿色对勾标识。项目级内容信任策略拦截若项目在配置页面开启了内容信任或Cosign 内容信任未签名镜像即使客户端开启 DCT 也会被 Harbor 服务端中间件拒绝返回PROJECTPOLICYVIOLATION错误信息为 The image is not signed by notation/cosign。此时需使用签名镜像或按 9-30 的流程验证策略行为。信任服务器端口不通确认 Harbor 的 Notary 服务4443 端口对外可达且DOCKER_CONTENT_TRUST_SERVER中的 IP/FQDN 与证书中的主机名匹配。小结本测试用例验证了 Harbor 内容信任体系中最基础也最关键的一环DB 模式下的普通用户能够在启用DOCKER_CONTENT_TRUST后成功拉取已签名镜像。整个过程同时涉及 Docker 客户端侧环境变量、信任服务器、TLS 证书与 Harbor 服务端侧Notary 4443 端口、manifest 拉取链路中间件、项目元数据策略。掌握 9-03 的操作流程再配合 9-01签名推送、9-04未签名拦截与 9-30项目级强制策略等关联用例即可完整落地 Harbor 的镜像签名信任体系。相关文件索引测试用例9-03-DB-user-pull-signed-images.md、9-01-DB-user-push-signed-images.md、9-04-DB-user-pull-unsigned-images.md、9-30-Project-level-content-trust.md服务端中间件src/server/middleware/contenttrust/contentrust.go路由挂载点src/server/registry/route.go项目元数据键定义src/pkg/project/models/pro_meta.go项目策略判断src/pkg/project/models/project.go【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Harbor 内容信任实战：Docker 客户端拉取已签名镜像（DB 模式）完整指南
Harbor 内容信任实战Docker 客户端拉取已签名镜像DB 模式完整指南【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor导读本文以 Harbor 官方内容信任Content Trust测试用例 9-03-DB-user-pull-signed-images.md 为骨架系统讲解在本地数据库DB 模式认证环境下普通用户如何通过 Docker 客户端启用 Docker Content TrustDCT并成功拉取已签名镜像的完整流程。读者将掌握DOCKER_CONTENT_TRUST与DOCKER_CONTENT_TRUST_SERVER环境变量的正确配置、自签名证书环境下 Notary 服务的信任配置、签名镜像在 Harbor Web 界面的识别方法以及 Harbor 服务端在拉取链路上执行内容信任校验的底层原理。背景为什么需要内容信任与 NotaryHarbor 是一个开源的云原生制品仓库支持制品的存储、签名与扫描。内容信任Content Trust基于 Docker 的 Notary 项目实现当客户端启用 DCT 后推送镜像时会同时生成签名元数据并上传至 Notary 服务Harbor 中该服务默认监听4443端口拉取镜像时Docker 客户端会先向 Notary 校验镜像的签名与信任链再决定是否拉取对应镜像内容。在 Harbor 中内容信任的落地分为两个层面客户端层面由 Docker CLI 通过环境变量控制是否签名、是否校验签名服务端层面当项目开启了内容信任策略后Harbor 的 Registry 路由会在拉取镜像的请求链路上插入校验中间件强制要求镜像存在有效签名否则拒绝拉取。本文聚焦第一个层面——用户主动开启 DCT 并成功拉取已签名镜像对应测试用例 9-03。环境准备依据测试用例的Environment一节执行本流程需要满足一个正在运行且可访问的 Harbor 实例本地数据库认证模式即 DB 模式一台安装了 Docker CLIDocker 客户端的 Linux 机器一个已经存在的 Harbor 项目文中以 project X 代指。补充说明DB 模式意味着用户数据存放在 Harbor 内置的本地数据库中与之相对的是 LDAP/AD 等外部认证模式。本测试用例 9-03 针对 DB 模式设计对应的 LDAP 版本见 9-13-LDAP-user-pull-signed-images.md管理员版本见 9-23-admin-pull-signed-images.md。测试步骤详解第 1 步登录 Harbor Web UI在浏览器中访问 Harbor 门户使用具有目标项目访问权限的普通用户账号登录 UI。确保目标项目 X 已存在可通过 9-01-DB-user-push-signed-images.md 中的流程创建项目并推送已签名镜像作为前置准备。第 2 步在 Docker 客户端启用内容信任并登录在 Docker 客户端主机上执行以下环境变量设置export DOCKER_CONTENT_TRUST1 export DOCKER_CONTENT_TRUST_SERVERhttps://harbor_ip:4443DOCKER_CONTENT_TRUST1通知 Docker CLI 启用内容信任模式。此模式下docker pull在拉取镜像前会先向信任服务器查询该镜像的签名元数据只有签名有效时才继续拉取镜像内容。DOCKER_CONTENT_TRUST_SERVERhttps://harbor_ip:4443显式指定信任服务器地址。Harbor 部署的 Notary 服务默认暴露在 4443 端口HTTPS。不设置此变量时Docker 会按https://registry_host:4443的默认约定推断但在 Harbor 场景下显式指定更稳妥。设置完成后登录 Harbordocker login harbor_ip按提示输入用户名与密码。若目标 Harbor 使用了非默认端口需在harbor_ip后附带端口号。自签名证书注意事项如果 Harbor 使用自签名证书Docker 客户端默认不会信任该证书必须将 CA 根证书复制到以下两个位置来自测试用例的 NOTE 说明# Registry 访问信任 /etc/docker/certs.d/harbor_ip/ # Notary 信任服务器访问信任端口 4443 $HOME/.docker/tls/harbor_ip:4443/完成证书放置后重启 Docker 守护进程使其生效。这一步骤缺失时docker login或后续的信任校验会因 TLS 证书不受信任而失败。第 3 步拉取已签名镜像从项目 X 中拉取一个已签名镜像docker pull harbor_ip/project_x/signed-image:tag其中project_x应替换为实际项目名signed-image:tag替换为实际镜像名与标签。预期结果根据测试用例Expected Outcome镜像可以被成功拉取。即docker pull命令成功完成本地出现该镜像。这表明在DOCKER_CONTENT_TRUST1下Docker 客户端成功向 Harbor 的 Notary 服务4443 端口验证了镜像签名随后从 Registry 拉取了镜像内容。服务端原理Harbor 如何配合签名拉取虽然测试用例 9-03 主要验证客户端开启 DCT 后能拉到签名镜像但理解 Harbor 服务端的处理逻辑有助于排查问题。从源码看Harbor 在 Registry 的 manifest 拉取链路上挂了内容信任中间件。在 src/server/registry/route.go 中GET与HEAD两种/*/manifests/:reference请求都挂载了contenttrust.ContentTrust()中间件root.NewRoute(). Method(http.MethodGet). Path(/*/manifests/:reference). Middleware(metric.InjectOpIDMiddleware(metric.ManifestOperationID)). Middleware(repoproxy.ManifestMiddleware()). Middleware(contenttrust.ContentTrust()). Middleware(vulnerable.Middleware()). HandlerFunc(getManifest)中间件实现位于 src/server/middleware/contenttrust/contentrust.go它根据请求中的ArtifactInfo找到对应项目若项目开启了内容信任策略ContentTrustEnabled()或ContentTrustCosignEnabled()则进一步调用signatureChecking检查制品是否带有对应类型的签名 accessory若无签名则返回PROJECTPOLICYVIOLATION错误拒绝拉取。项目级策略通过项目元数据metadata实现键定义在 src/pkg/project/models/pro_meta.goenable_content_trust对应ProMetaEnableContentTrust是否要求镜像具备 Notation 签名enable_content_trust_cosign对应ProMetaEnableContentTrustCosign是否要求镜像具备 Cosign 签名。对应的布尔判断实现在 src/pkg/project/models/project.go。需要强调的是9-03 场景下项目未必开启了上述项目级策略拉取成功的关键在于 Docker 客户端自身开启 DCT 并成功完成签名校验。项目级策略是另一道服务端强制门禁对应测试 9-30-Project-level-content-trust.md启用策略后未签名镜像将无法拉取而签名镜像可以拉取。关联场景签名镜像的完整生命周期9-03 属于 Group9-Content-trust 测试组中DB 模式普通用户的子集将其放入整个测试矩阵可以更清楚地理解内容信任的完整闭环测试用例操作关键预期9-01开启 DCT 后推送镜像镜像被签名并推送成功UI 显示绿色对勾9-02关闭 DCT 推送镜像推送成功但无签名9-03开启 DCT 拉取已签名镜像拉取成功9-04开启 DCT 拉取未签名镜像拉取被拒绝9-05删除已签名镜像删除成功从 9-01 的Expected Outcome可以看到签名镜像在 Harbor UI 中会以绿色对勾标识呈现这是确认镜像已被签名的最直观方式。在 9-04 中当DOCKER_CONTENT_TRUST1时拉取未签名镜像会失败——这正是 Docker 客户端侧 DCT 校验拦截的结果与 9-03 形成对照。常见问题与排查思路测试用例中Possible Problems为 None但在真实环境中仍可能遇到以下情况TLS 证书错误x509: certificate signed by unknown authority自签名证书未按上文复制到/etc/docker/certs.d/harbor_ip/与$HOME/.docker/tls/harbor_ip:4443/或复制后未重启 Docker 守护进程。拉取被拒could not find signed tag/no valid trust data目标镜像本身未签名未在 DCT 开启状态下推送请先通过 9-01 流程准备签名镜像或在 UI 中确认镜像带绿色对勾标识。项目级内容信任策略拦截若项目在配置页面开启了内容信任或Cosign 内容信任未签名镜像即使客户端开启 DCT 也会被 Harbor 服务端中间件拒绝返回PROJECTPOLICYVIOLATION错误信息为 The image is not signed by notation/cosign。此时需使用签名镜像或按 9-30 的流程验证策略行为。信任服务器端口不通确认 Harbor 的 Notary 服务4443 端口对外可达且DOCKER_CONTENT_TRUST_SERVER中的 IP/FQDN 与证书中的主机名匹配。小结本测试用例验证了 Harbor 内容信任体系中最基础也最关键的一环DB 模式下的普通用户能够在启用DOCKER_CONTENT_TRUST后成功拉取已签名镜像。整个过程同时涉及 Docker 客户端侧环境变量、信任服务器、TLS 证书与 Harbor 服务端侧Notary 4443 端口、manifest 拉取链路中间件、项目元数据策略。掌握 9-03 的操作流程再配合 9-01签名推送、9-04未签名拦截与 9-30项目级强制策略等关联用例即可完整落地 Harbor 的镜像签名信任体系。相关文件索引测试用例9-03-DB-user-pull-signed-images.md、9-01-DB-user-push-signed-images.md、9-04-DB-user-pull-unsigned-images.md、9-30-Project-level-content-trust.md服务端中间件src/server/middleware/contenttrust/contentrust.go路由挂载点src/server/registry/route.go项目元数据键定义src/pkg/project/models/pro_meta.go项目策略判断src/pkg/project/models/project.go【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考