Docker Hub 拉取使用情况和限制

目录

未经身份验证的用户和 Docker Personal 用户在 Docker Hub 上受到 6 小时拉取速率限制。相比之下，Docker Pro、Team 和 Business 用户享有无限制的拉取速率。

根据您的订阅，以下拉取使用情况和限制适用，但需遵守合理使用原则

用户类型每 6 小时的拉取速率限制
Business (已验证)无限制
Team (已验证)无限制
Pro (已验证)无限制
Personal (已验证)200
未经身份验证的用户每个 IPv4 地址或 IPv6 /64 子网 100 次

拉取定义

拉取的定义如下

  • Docker 拉取包括版本检查和因拉取而发生的任何下载。根据客户端的不同，docker pull 命令可以通过执行版本检查来验证镜像或标签是否存在，而无需下载它。
  • 版本检查不计入使用量费用。
  • 正常镜像的一次拉取算作一个单一 Manifest的一次拉取。
  • 多架构镜像的一次拉取将对每个不同架构计为一次拉取。

拉取归因

已验证用户的拉取可以归因于个人或组织命名空间。

归因基于以下规则

  • 私有拉取：对私有仓库的拉取归因于仓库的命名空间所有者。
  • 公共拉取：当从公共仓库拉取镜像时，归因根据域名关联和组织成员身份确定。
  • 验证域名所有权：当从链接到已验证域名的账户拉取镜像时，归因设置为该域的所有者。
  • 单一组织成员身份
    • 如果已验证域名的所有者是一家公司，并且用户仅是该公司内一个组织的成员，则拉取归因于该特定组织。
    • 如果用户仅属于一个组织，则拉取归因于该特定组织。
  • 多组织成员身份：如果用户属于公司下的多个组织，则拉取归因于用户的个人命名空间。

身份验证

为确保正确归因您的拉取，您必须使用 Docker Hub 进行身份验证。以下部分提供了关于如何登录 Docker Hub 以验证您的拉取的信息。

Docker Desktop

如果您使用 Docker Desktop，可以从 Docker Desktop 菜单登录 Docker Hub。

从 Docker Desktop 菜单中选择 登录 / 创建 Docker ID，并按照屏幕上的说明完成登录过程。

Docker Engine

如果您使用独立版 Docker Engine，请从终端运行 docker login 命令以向 Docker Hub 进行身份验证。有关如何使用该命令的信息，请参阅docker login。

Docker Swarm

如果您正在运行 Docker Swarm，必须使用 --with-registry-auth 标志向 Docker Hub 进行身份验证。更多信息，请参阅创建服务。如果您使用 Docker Compose 文件部署应用堆栈，请参阅docker stack deploy。

GitHub Actions

如果您使用 GitHub Actions 构建 Docker 镜像并推送到 Docker Hub，请参阅登录操作。如果您使用其他 Action，必须以类似方式添加您的用户名和访问令牌进行身份验证。

Kubernetes

如果您正在运行 Kubernetes，请遵循从私有 Registry 拉取镜像 中的说明进行身份验证。

第三方平台

如果您使用任何第三方平台，请遵循提供商关于使用 Registry 身份验证的说明。

注意

通过第三方平台拉取镜像时，该平台可能会使用相同的 IPv4 地址或 IPv6 /64 子网为多个用户拉取镜像。即使您已验证，归因于单个 IPv4 地址或 IPv6 /64 子网的拉取仍可能导致滥用速率限制。

查看每月拉取量和包含的使用情况

您可以在 Docker Hub 的使用情况页面上查看您的每月拉取量。

在该页面上，您还可以向您的电子邮件发送一份报告，其中包含一个逗号分隔的文件，其中包含以下详细信息。

CSV 列定义使用指南
datehour导致数据传输的拉取的日期和小时 (yyyy/mm/dd/hh)。这有助于识别峰值使用时间和模式。
user_name拉取镜像的用户 Docker ID这让组织所有者可以跟踪每个用户的数据消耗并有效管理资源。
repository拉取镜像的仓库名称。这让您可以识别哪些仓库被访问最频繁，并消耗大部分数据传输量。
access_token_name用于通过 Docker CLI 进行身份验证的访问令牌名称。generated 令牌是用户登录时由 Docker 客户端自动生成的。个人访问令牌通常用于验证自动化工具（Docker Desktop、CI/CD 工具等）。这有助于识别是哪个自动化系统发起了拉取。
ips用于拉取镜像的 IP 地址。此字段是聚合的，因此可能出现多个 IP 地址，代表在同一日期和小时内用于拉取镜像的所有 IP。这有助于您了解数据传输的来源，对于诊断和识别自动化或手动拉取中的模式非常有用。
repository_privacy拉取镜像仓库的隐私状态。可以是 public 或 private。这区分了公共仓库和私有仓库，以确定拉取影响哪个数据传输阈值。
tag镜像的标签。标签仅在拉取包含标签时可用。这有助于识别镜像。标签通常用于识别镜像的特定版本或变体。
digest镜像的唯一镜像 Digest。这有助于识别镜像。
version_checks每个镜像仓库在指定日期和小时累积的版本检查次数。根据客户端的不同，拉取可以进行版本检查以验证镜像或标签是否存在，而无需下载它。这有助于识别版本检查的频率，可用于分析使用趋势和潜在的意外行为。
pulls每个镜像仓库在指定日期和小时累积的拉取次数。这有助于识别仓库拉取的频率，可用于分析使用趋势和潜在的意外行为。

查看拉取速率和限制

拉取速率限制以 6 小时为基础计算。付费订阅的用户或自动化系统没有拉取速率限制。未经身份验证的用户和使用 Docker Hub 的 Docker Personal 用户将受到镜像拉取速率限制。

当您发起拉取且超出限制时，当请求 Manifest 时，Docker Hub 会返回带有以下正文的 429 响应码

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://dockerd.com.cn/increase-rate-limits

此错误消息会出现在 Docker CLI 或 Docker Engine 日志中。

查看您当前的拉取速率和限制

注意

要检查您的限制，需要安装 curl、grep 和 jq。

  1. 获取令牌。

    • 匿名获取令牌，如果您正在匿名拉取

      $ TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)

    • 使用用户帐户获取令牌，如果已认证，请在以下命令中插入您的用户名和密码

      $ TOKEN=$(curl --user 'username:password' "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)

  2. 获取包含您的限制的标头。这些标头在 GET 和 HEAD 请求中都会返回。使用 GET 模拟真实拉取并计入限制。使用 HEAD 则不会。

    $ curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest

  3. 检查标头。您应该会看到以下标头。

    ratelimit-limit: 100;w=21600
ratelimit-remaining: 20;w=21600
docker-ratelimit-source: 192.0.2.1

    在前面的示例中，拉取限制为每 21600 秒（6 小时）拉取 100 次，并且剩余 20 次拉取。

    如果您没有看到任何 ratelimit 标头，可能是因为该镜像或您的 IP 地址与发布商、提供商或开源组织合作而没有限制。这也可能意味着您用来拉取镜像的用户是付费 Docker 计划的一部分。如果您没有看到这些标头，拉取该镜像将不计入拉取速率限制。

页面选项