快取儲存後端

目錄

為了確保快速構建，BuildKit 會自動將其構建結果快取到其內部快取中。此外，BuildKit 還支援將構建快取匯出到外部位置，以便在未來的構建中匯入。

在 CI/CD 構建環境中，外部快取幾乎是必不可少的。這類環境在執行之間通常幾乎沒有永續性，但仍必須儘可能縮短映象構建的執行時。

預設的 docker 驅動程式支援 inline、local、registry 和 gha 快取後端，但前提是您已啟用 containerd 映象儲存。其他快取後端要求您選擇不同的 驅動程式。

警告

如果您在構建過程中使用機密或憑據，請務必使用專用的 --secret 選項對其進行操作。手動使用 COPY 或 ARG 管理機密可能會導致憑據洩露。

後端

Buildx 支援以下快取儲存後端

  • inline：將構建快取嵌入到映象中。

    內聯快取會被推送到與主輸出結果相同的位置。這僅適用於 image 匯出器。

  • registry：將構建快取嵌入到單獨的映象中，並推送到與主輸出分離的專用位置。

  • local：將構建快取寫入檔案系統上的本地目錄。

  • gha：將構建快取上傳到 GitHub Actions 快取（beta 版）。

  • s3：將構建快取上傳到 AWS S3 儲存桶（未釋出）。

  • azblob：將構建快取上傳到 Azure Blob 儲存（未釋出）。

命令語法

要使用任何快取後端，您首先需要在構建時使用 --cache-to 選項指定它，以便將快取匯出到您選擇的儲存後端。然後，使用 --cache-from 選項將快取從儲存後端匯入到當前構建中。與本地 BuildKit 快取（始終啟用）不同，所有快取儲存後端都必須顯式匯出到和顯式匯入自。

使用 registry 後端，利用匯入和匯出快取的 buildx 命令示例

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>[,parameters...] \
  --cache-from type=registry,ref=<registry>/<cache-image>[,parameters...] .
警告

通常，每個快取都會寫入某個位置。沒有任何位置可以寫入兩次而不會覆蓋之前快取的資料。如果您希望維護多個範圍快取（例如，每個 Git 分支一個快取），請確保對匯出的快取使用不同的位置。

多重快取

BuildKit 支援多個快取匯出器，允許您將快取推送到多個目的地。您還可以從任意數量的遠端快取匯入。例如，一個常見模式是使用當前分支和主分支的快取。以下示例展示了使用登錄檔快取後端從多個位置匯入快取

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>:<branch> \
  --cache-from type=registry,ref=<registry>/<cache-image>:<branch> \
  --cache-from type=registry,ref=<registry>/<cache-image>:main .

配置選項

本節介紹生成快取匯出時可用的一些配置選項。此處描述的選項對於至少兩種或更多後端型別是通用的。此外，不同的後端型別也支援特定的引數。有關哪些配置引數適用的更多資訊，請參閱每種後端型別的詳細頁面。

此處描述的通用引數是

快取模式

生成快取輸出時，--cache-to 引數接受一個 mode 選項，用於定義要包含在匯出快取中的層。所有快取後端都支援此功能，但 inline 快取除外。

模式可以設定為兩個選項之一：mode=min 或 mode=max。例如，要使用登錄檔後端以 mode=max 構建快取

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,mode=max \
  --cache-from type=registry,ref=<registry>/<cache-image> .

此選項僅在匯出快取時設定，使用 --cache-to。匯入快取時（--cache-from），相關引數會自動檢測。

在 min 快取模式（預設）下，只有匯出到結果映象的層才會被快取，而在 max 快取模式下，所有層都會被快取，即使是中間步驟的層。

雖然 min 快取通常更小（這會加快匯入/匯出時間，並降低儲存成本），但 max 快取更有可能獲得更多的快取命中。根據構建的複雜性和位置，您應該嘗試使用這兩個引數，以找到最適合您的結果。

快取壓縮

快取壓縮選項與 匯出器壓縮選項 相同。local 和 registry 快取後端支援此功能。

例如，要使用 zstd 壓縮來壓縮 registry 快取

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,compression=zstd \
  --cache-from type=registry,ref=<registry>/<cache-image> .

OCI 媒體型別

快取 OCI 選項與 匯出器 OCI 選項 相同。local 和 registry 快取後端支援這些功能。

例如，要匯出 OCI 媒體型別快取，請使用 oci-mediatypes 屬性

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true \
  --cache-from type=registry,ref=<registry>/<cache-image> .

此屬性僅對 --cache-to 標誌有意義。當獲取快取時，BuildKit 將自動檢測要使用的正確媒體型別。

預設情況下，OCI 媒體型別為快取映象生成一個映象索引。某些 OCI 登錄檔，例如 Amazon ECR，不支援映象索引媒體型別：application/vnd.oci.image.index.v1+json。如果您將快取映象匯出到 ECR 或任何其他不支援映象索引的登錄檔，請將 image-manifest 引數設定為 true，以便為快取映象生成單個映象清單而不是映象索引。

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true,image-manifest=true \
  --cache-from type=registry,ref=<registry>/<cache-image> .
注意

自 BuildKit v0.21 起，image-manifest 預設啟用。