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://docker.net.tw/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 計劃的一部分。如果您沒有看到這些標頭，拉取該映象將不計入拉取速率限制。

頁面選項