📚 课程目录第3章镜像仓库认证基础

3、镜像仓库认证基础：Docker Registry、Harbor、ACR、ECR等仓库的认证方式

容器镜像拉取加速的前提是客户端能够安全、高效地通过仓库认证。不同镜像仓库的认证机制在协议、凭证格式、生命周期管理上存在显著差异。理解这些差异，是设计 Secrets 加密传输方案的基础。

3.1 认证协议与凭证模型

所有符合 OCI Distribution Spec 的仓库均采用 Bearer 或 Basic Auth 作为核心认证协议。客户端首先向仓库的 /v2/ 端点发起匿名请求，若返回 401 Unauthorized，则根据 Www-Authenticate 响应头中的 realm、service、scope 参数，向认证服务获取，随后在后续请求的 Authorization: Bearer <> 头中携带该。

  关键流程： 客户端 → 仓库 API（401 + challenge）→ 认证服务（凭证交换）→ Bearer  → 仓库 API（200 OK）

仓库类型	认证协议	凭证载体	生命周期
Docker Registry (v2)	Bearer / Basic Auth	用户名+密码或	由认证服务决定，通常 1~24h
Harbor	Bearer + OIDC / LDAP	用户名+密码 / Robot Account	可配置，支持短生命周期
ACR (Azure Container Registry)	OAuth2 + Azure AD	Service Principal / Managed Identity	默认 1h，可 refresh
ECR (AWS)	AWS Signature V4 + IAM	Access Key + Secret Key / IAM Role	12h（通过 `GetAuthorizationToken` 获取）

3.2 各仓库认证方式详解

3.2.1 Docker Registry (v2)

自建 Docker Registry 通常使用 htpasswd 文件或 Authentication。客户端将用户名和密码 Base64 编码后放入 Authorization: Basic 头，或通过 docker login 写入 ~/.docker/config.json。该文件中的 auths 字段存储 Base64 编码的凭证，是 Secrets 加密传输的主要目标。

# ~/.docker/config.json 示例
{
  "auths": {
    "myregistry.example.com": {
      "auth": "dXNlcjpwYXNzd29yZA=="  # Base64(user:password)
    }
  }
}

3.2.2 Harbor

Harbor 在 Docker Registry 基础上增加了 RBAC、Robot Account 和 OIDC 支持。Robot Account 是专为 CI/CD 设计的长期凭证，支持细粒度权限（如只读、只写）。Harbor 的认证服务会校验用户权限并返回 scope 限定的 Bearer 。

用户密码认证： 适用于管理员和开发者，支持 LDAP/AD 集成。
Robot Account： 生成固定，适合自动化拉取场景，可设置过期时间。
OIDC： 通过外部身份提供商（如 Keycloak、Okta）获取。

3.2.3 ACR (Azure Container Registry)

ACR 深度集成 Azure AD。推荐使用 Managed Identity（Pod 或 VM 身份）或 Service Principal 进行认证。客户端通过 az acr login 命令获取 ACR 的 Refresh ，该有效期为 3 小时，可自动刷新。

最佳实践： 在 Kubernetes 中使用 ACR 时，优先使用 Workload Identity 或 Managed Identity，避免在集群中存储长期 Service Principal 密码。

3.2.4 ECR (AWS)

ECR 使用 AWS IAM 进行认证。客户端必须调用 GetAuthorizationToken API（或通过 aws ecr get-login-password）获取一个 Base64 编码的密码，该密码有效期为 12 小时。ECR 的认证与 AWS 区域绑定，且需要 ecr:GetAuthorizationToken 权限。

# 获取 ECR 登录密码
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com

3.3 认证流程对比图

下图展示了 Docker Registry、Harbor、ACR、ECR 四种仓库在客户端拉取镜像时的认证流程差异，重点突出凭证获取与交换环节。

3.4 凭证类型与 Secrets 映射

在 Kubernetes 中，镜像拉取凭证以 docker-registry 类型的 Secret 存储。不同仓库的凭证字段映射如下：

仓库	Secret 类型	关键字段	注意事项
Docker Registry	`kubernetes.io/dockerconfigjson`	`.dockerconfigjson` 中的 `auth`	Base64 编码的 user:password
Harbor	`kubernetes.io/dockerconfigjson`	`.dockerconfigjson` 中的 `auth`	Robot Account 的直接作为 password
ACR	`kubernetes.io/dockerconfigjson`	`.dockerconfigjson` 中的 `auth`	使用 `00000000-0000-0000-0000-000000000000` 作为用户名
ECR	`kubernetes.io/dockerconfigjson`	`.dockerconfigjson` 中的 `auth`	用户名固定为 `AWS`，密码为 12h 有效

安全风险提示： 所有仓库的凭证在 ~/.docker/config.json 或 Kubernetes Secret 中均以 Base64 编码 存储，并非加密。Base64 仅是可逆编码，任何具有 Secret 读取权限的实体都能解码出明文凭证。因此，必须对 Secrets 进行额外的加密传输和存储保护。

3.5 认证方式选择建议

自建环境（Docker Registry / Harbor）： 优先使用 Robot Account 或短生命周期，避免使用长期用户密码。
公有云（ACR / ECR）： 优先使用云厂商提供的托管身份（Managed Identity / IAM Role），避免在集群中存储静态凭证。
多集群场景： 使用外部 Secrets 管理工具（如 External Secrets Operator、Vault）自动同步和轮换凭证。