使用容器注册表进行身份验证

要使用容器注册表进行身份验证，您可以使用：

• GitLab 用户名和密码（如果启用了 2FA 则不可用）
• 个人访问令牌
• 部署令牌
• 项目访问令牌
• 群组访问令牌
• GitLab CLI

对于基于令牌的身份验证方法，所需的最小权限范围：

• 用于读取（拉取）访问，必须为 read_registry
• 用于写入（推送）访问，必须为 write_registry 和 read_registry

使用用户名和密码进行身份验证

您可以使用 GitLab 用户名和密码对容器注册表进行身份验证：

docker login registry.example.com -u <username> -p <password>

出于安全考虑，建议使用 --password-stdin 标志而不是 -p：

echo "<password>" | docker login registry.example.com -u <username> --password-stdin

使用令牌进行身份验证

要使用令牌进行身份验证，请运行 docker login 命令：

TOKEN=<token>
echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin

身份验证后，客户端会缓存凭据。后续操作会发出授权请求，返回 JWT 令牌， 该令牌仅被授权执行指定的操作。令牌默认有效期为 5 分钟， 在 GitLab.com 上为 15 分钟。

使用 GitLab CI/CD 进行身份验证

要使用 CI/CD 对容器注册表进行身份验证，您可以使用：

• CI_REGISTRY_USER CI/CD 变量。

  此变量包含一个具有对容器注册表读写权限的每作业用户。 其密码也会自动创建，并在 CI_REGISTRY_PASSWORD 中可用。

  echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin

• CI 作业令牌。

  此令牌只能用于读取（拉取）访问。它具有 read_registry 权限范围，但不具有推送操作所需的 write_registry 权限范围。

  echo "$CI_JOB_TOKEN" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin

  您也可以使用 gitlab-ci-token 方案：

  echo "$CI_JOB_TOKEN" | docker login $CI_REGISTRY -u gitlab-ci-token --password-stdin

• 具有以下最小权限范围的 部署令牌：

  • 用于读取（拉取）访问，read_registry。
  • 用于写入（推送）访问，read_registry 和 write_registry。
  echo "$CI_DEPLOY_PASSWORD" | docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin

• 具有以下最小权限范围的 个人访问令牌：

  • 用于读取（拉取）访问，read_registry。
  • 用于写入（推送）访问，read_registry 和 write_registry。
  echo "<access_token>" | docker login $CI_REGISTRY -u <username> --password-stdin

故障排除

docker login 命令失败，显示 access forbidden

容器注册表 向 Docker 客户端返回 GitLab API URL 以验证凭据。Docker 客户端使用基本身份验证，因此请求包含 Authorization 标头。如果对注册表配置中 token_realm 配置的 /jwt/auth 端点的请求中缺少 Authorization 标头，您会收到 access forbidden 错误消息。

例如：

> docker login gitlab.example.com:4567

Username: user
Password:
Error response from daemon: Get "https://gitlab.company.com:4567/v2/": denied: access forbidden

为避免此错误，确保请求中的 Authorization 标头未被剥离。 例如，GitLab 前面的代理可能会重定向到 /jwt/auth 端点。

推送大镜像时出现 unauthorized: authentication required

推送大镜像时，您可能会看到如下身份验证错误：

docker push gitlab.example.com/myproject/docs:latest
The push refers to a repository [gitlab.example.com/myproject/docs]
630816f32edb: Preparing
530d5553aec8: Preparing
...
4b0bab9ff599: Waiting
d1c800db26c7: Waiting
42755cf4ee95: Waiting
unauthorized: authentication required

当您的身份验证令牌在镜像推送完成前过期时，会发生此错误。 默认情况下，GitLab 自托管实例上的容器注册表令牌在五分钟后过期。 在 GitLab.com 上，令牌过期时间为 15 分钟。