Docker Hub 使用与速率限制
重要
Docker 正在推出增强型订阅计划。我们的新计划增加了更多功能，提高了使用限额，并简化了定价模式。新订阅计划将于您在 2024 年 12 月 10 日或之后的下一次续订日期起生效。在 2025 年 2 月 28 日之前，Docker Hub 的镜像拉取及存储服务将不产生任何费用。请参阅 《推出升级版 Docker 订阅计划》 ，了解详情，并查看您的使用情况如何适配此次更新。
Docker 可能会针对 Docker Hub 实施使用量和访问频率限制，以确保资源公平分配并维持服务质量。了解您的使用情况有助于您有效管理自身及所属组织的使用行为。
用法
Usage refers to both:
- Pulls: 从 Docker Hub 下载的数据量
- 存储：存储在 Docker Hub 上的数据量
合法使用
使用 Docker 平台时，用户需注意：过度的数据传输、拉取频率或数据存储可能导致限速或产生额外费用。为确保资源使用的公平性并维持服务质量，我们保留对存在过度数据和存储消耗行为的账户实施限制或收取额外费用的权利。
查看 Docker Hub 使用情况
登录到 Docker Hub。
若要下载某组织所有成员的使用情况，您必须使用该组织的**所有者账户**登录。否则，您只能查看自己的个人使用情况。
在 Docker Hub 中，从顶层导航菜单中选择 使用。
在下拉菜单中，选择您希望查看个人数据还是组织数据。
使用情况页面显示拉取次数和存储空间使用情况。
选择使用类型，并使用可用的筛选器查看使用情况。
下载 Docker Hub 使用情况
您可以下载您自己或您所在组织的 Docker Hub 使用情况的 CSV 文件。下载文件的方法如下：
登录到 Docker Hub。
若要下载某组织所有成员的使用情况，您必须使用该组织的**所有者账户**登录。否则，您只能查看自己的个人使用情况。
在 Docker Hub 中，从顶层导航菜单中选择 使用。
在下拉菜单中，选择您希望查看个人数据还是组织数据。
可选。使用按隐私设置筛选下拉菜单，选择公开或私有拉取。
使用 起始日期 和 结束日期 过滤器选择数据的日期范围。
选择 将报告发送至邮箱，Docker 将通过电子邮件向您发送数据文件的链接。请注意，邮件处理时间可能有所不同。
该文件包含以下以逗号分隔的值：
| 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 | 该镜像的唯一镜像摘要。 | 这有助于识别镜像。 |
version_checks | 每个镜像仓库在对应日期和小时累积的版本检查次数。根据客户端不同，拉取请求（pull request）可执行版本检查，以验证镜像或标签是否存在，而无需实际下载。 | 这有助于识别版本检查的频率，您可利用此信息分析使用趋势及潜在的意外行为。 |
pulls | 每个镜像仓库在指定日期和小时的累积拉取次数。 | 这有助于识别仓库拉取的频率，您可利用此数据来分析使用趋势及潜在的异常行为。 |
优化和管理 Docker Hub 使用
使用以下步骤帮助优化和管理您对 Docker Hub 的使用，适用于个人用户和组织。
使用 Docker Hub 使用数据，识别消耗数据最多的账户，确定峰值使用时段，并找出与数据使用量最多的镜像相关的信息。此外，还需关注使用趋势，例如以下情况：
- 拉取行为低效：识别频繁访问的镜像仓库，以评估是否可通过优化缓存策略或合并使用方式来减少拉取操作。
- 低效的自动化系统：检查哪些自动化工具（例如 CI/CD 管道）可能导致较高的镜像拉取频率，并对其进行配置以避免不必要的镜像拉取。
通过执行以下操作来优化镜像拉取：
- 使用缓存：通过镜像或在CI/CD流水线中实现本地镜像缓存，以减少重复拉取操作。
- 自动化手动工作流：通过配置自动化系统，仅在镜像有新版本可用时才拉取，避免不必要的拉取操作。
通过定期审计并删除未标记、未使用或过期的镜像，优化仓库的大小。
通过升级或购买附加组件来扩展您的限制。详情请参阅 Docker 定价。
对于组织而言，通过执行以下操作来监控并强制执行组织策略：
- 定期 查看 Docker Hub 使用情况 以监控使用情况。
- 强制登录，以确保您能够监控用户使用情况，同时用户可获得更高的使用配额。
拉取归属
拉取操作可归因于个人或组织 命名空间。
私有拉取
私有仓库的拉取操作将计入该仓库命名空间所有者的名下。
公共拉取
从公共仓库拉取镜像时，归属权（attribution）将根据域名归属和组织成员身份来确定。
已验证域名所有权
从与已验证域名关联的账户拉取镜像时，归属权将设置为该 域名 的所有者
单一组织成员资格
- 如果已验证域名的所有者是公司，且用户仅属于该公司内的一个组织， 则该拉取操作将归属于该特定组织。 公司
- 如果用户仅属于一个组织，则拉取操作将归因于该特定组织。
多个组织成员资格
如果用户隶属于公司下的多个组织，则拉取操作将归因于该用户的个人命名空间。
速率限制
速率限制适用于拉取（pull）使用量。用户的速率限制等于其个人账户或其所属的任何组织中最高的授权额度。要利用此功能，您必须以已认证用户身份登录 Docker Hub。有关更多信息，请参阅 如何对拉取请求进行身份验证。未经身份验证（匿名）用户将通过IP地址实施速率限制。
- 拉取操作计入执行拉取操作的用户，而非镜像的所有者。
- 拉取请求（pull request）定义为对注册表清单（registry manifest）URL的最多两次
GET次请求（/v2/*/manifests/*）。 - 常规的镜像拉取操作仅发起一次清单（manifest）请求。
- 对多架构镜像的拉取请求会发起两次清单请求。
HEAD个请求不会被计数。- 某些镜像通过 Docker 赞助开源 和 Docker 认证发布者 项目提供无限使用。
重要
Docker 正在推出增强型订阅计划。我们的新计划增加了更多功能，提高了使用限额，并简化了定价模式。新订阅计划将于您在 2024 年 12 月 10 日或之后的下一次续订日期起生效。在 2025 年 2 月 28 日之前，Docker Hub 的镜像拉取及存储服务将不产生任何费用。请参阅 《推出升级版 Docker 订阅计划》 ，了解详情，并查看您的使用情况如何适配此次更新。
请注意，当这些变更生效时，拉取请求和限制的以下新定义将生效：
- Docker 拉取请求既包括版本检查，也包括因拉取而发生的任何下载。根据客户端的不同，可以通过执行版本检查来验证镜像或标签是否存在，而无需下载，此时返回码为
docker pull。- 针对普通镜像的拉取请求只会拉取一个单一清单。
- 多架构镜像的拉取请求将按每种不同的架构分别计为一次拉取。
- 拉取操作计入执行拉取的用户，而非镜像的所有者。
Docker Hub 上的下载速率限制是多少？
重要
自2025年3月3日起，随着Docker增强订阅计划的推出，拥有付费订阅的用户或自动化系统将不再受镜像拉取速率限制。
匿名用户和使用 Docker Hub 的 Docker 个人版用户在拉取镜像请求时将受到速率限制。对于已认证用户，限制为每用户每小时 40 次拉取；对于未认证使用，限制为每 IP 地址每小时 10 次拉取。
Docker Hub 根据拉取镜像的用户账户类型，限制了 Docker 镜像下载（即拉取）的数量。拉取速率限制基于单个 IP 地址。下表反映了 Docker 当前的速率限制：
如果您需要更多的拉取次数，您也可以购买 增强版服务账户附加组件。
我如何知道我的 pull requests 正在被限制？
当您发起拉取请求且超过限制时，如果请求清单（manifest），Docker Hub 会返回一个
429 响应码，并附带以下主体内容：
You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits此错误消息出现在 Docker CLI 或 Docker Engine 日志中。
如何查看我当前的速率？
向 Hub 发出的有效 API 请求通常在响应中包含以下速率限制标头：
ratelimit-limit
ratelimit-remaining
docker-ratelimit-source这些头部信息会在 GET 和 HEAD 请求中返回。
注意
使用 GET 方法会模拟真实的拉取操作，并计入限额。使用 HEAD 方法则不会。 要检查您的限制，您需要安装
curl、grep和jq。
若要匿名获取令牌，如果您正在匿名拉取：
$ 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)
然后要获取显示您的限制的标头，请运行以下命令：
$ curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest
应返回以下标头：
ratelimit-limit: 100;w=21600
ratelimit-remaining: 76;w=21600
docker-ratelimit-source: 192.0.2.1在之前的示例中，拉取限制为每 21600 秒（6 小时）100 次拉取，剩余 76 次拉取。
我没有看到任何 RateLimit 头信息
如果您没有看到任何 RateLimit 标头，可能是因为该镜像或您的 IP 地址通过与发布者、提供商或开源组织的合作关系而不受限制。这也可能意味着您用于拉取的用户属于付费 Docker 计划。如果您没有看到这些标头，则拉取该镜像不会计入拉取限制。但是，每日拉取次数超过 5000 次的付费 Docker 订阅用户需要订阅 服务帐户。
尽管我已订阅了付费的 Docker 订阅，但仍被限制为较低的速率
若要利用付费 Docker 订阅中包含的更高限额，您必须通过用户账户 进行身份验证拉取。
Pro、Team 或 Business 套餐不会增加其他用户的镜像限制。请参阅 Docker 的 开源、 发布者 或 大型组织 产品。
其他限制
Docker Hub 也有总体速率限制，以保护应用程序和基础设施。此限制适用于对 Hub 属性的所有请求，包括网页、API 和镜像拉取。该限制按 IP 应用，虽然限制会随时间根据负载和其他因素变化，但大约为每分钟数千次请求。总体速率限制平等地适用于所有用户，无论账户级别如何。
您可以通过查看错误代码来区分这些限制。“总体限制”返回简单的 429 Too Many Requests 响应。拉取限制返回较长的错误消息，其中包含指向此页面的链接。
如何对拉取请求进行身份验证？
以下部分包含有关如何登录 Docker Hub 以验证拉取请求的信息。
Docker Desktop版
如果您使用的是 Docker Desktop，可以从 Docker Desktop 菜单登录 Docker Hub。
从 Docker Desktop 菜单中选择 登录 / 创建 Docker ID，并按照屏幕上的说明完成登录过程。
Docker 引擎
如果您使用的是独立版本的 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，请参阅 从私有注册表拉取镜像 以获取有关身份验证的信息。
第三方平台
如果您正在使用任何第三方平台，请遵循您的提供商关于使用注册表认证的说明。