{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

要与容器镜像仓库进行身份验证，您可以使用：

对于基于令牌的身份验证方法，最低要求范围：

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

{{< alert type=”note” >}}

管理员模式在与容器镜像仓库进行身份验证时不适用。如果您是一位启用了管理员模式的管理员，并且创建了一个没有 admin_mode 范围的个人访问令牌， 即使启用了管理员模式，该令牌也能正常工作。

{{< /alert >}}

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

您可以使用极狐 GitLab 用户名和密码与容器镜像仓库进行身份验证：

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

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

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

{{< alert type=”warning” >}} 如果您启用了双因素身份验证（2FA），则无法使用用户名和密码进行身份验证。在这种情况下，您必须使用基于令牌的身份验证方法。 {{< /alert >}}

使用令牌进行身份验证

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

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

身份验证后，客户端会缓存凭据。后续操作会发出授权请求并返回 JWT 令牌，仅授权执行指定操作。令牌默认有效期为 5 分钟，在 JihuLab.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

容器镜像仓库返回极狐 GitLab API URL 给 Docker 客户端 以验证凭据。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 私有化部署实例的容器镜像仓库令牌在五分钟后过期。 在 JihuLab.com 上，令牌过期时间为 15 分钟。