切换语言

缓存存储后端

目录

为了确保快速构建，BuildKit 会自动将构建结果缓存在自己的 内部缓存。此外，BuildKit 还支持将构建缓存导出到 external 位置，从而可以在将来的构建中导入。

在 CI/CD 构建环境中，外部缓存几乎是必不可少的。这样 环境在运行之间通常几乎没有持久性，但它仍然如此 请务必将镜像构建的运行时间保持在尽可能低的时间内。

默认驱动程序支持 、 、 和 缓存后端，但前提是您启用了 containerd 镜像存储。 其他缓存后端要求您选择不同的驱动程序。dockerinlinelocalregistrygha

警告

如果您在构建过程中使用 secret 或凭证，请确保 使用专用的 --secret 选项操作它们。 使用或可能导致泄露的密钥 凭据。COPYARG

后端

Buildx 支持以下缓存存储后端：

  • inline：将构建缓存嵌入到镜像中。

    内联缓存被推送到与主输出结果相同的位置。 这仅适用于镜像导出器。

  • registry：将构建缓存嵌入到单独的镜像中，并推送到 专用位置与主输出分开。

  • local：将构建缓存写入文件系统上的本地目录。

  • gha：将构建缓存上传到 GitHub Actions 缓存（测试版）。

  • s3：将构建缓存上传到 AWS S3 存储桶（未发布）。

  • azblob：将构建缓存上传到 Azure Blob 存储（未发布）。

命令语法

要使用任何缓存后端，您首先需要在构建时使用 --cache-to 选项指定它，以将缓存导出到您选择的存储后端。然后，使用 --cache-from 选项将缓存从存储后端导入到当前构建中。与 本地 BuildKit 缓存（始终处于启用状态），所有缓存存储 backend 必须显式导出到 backend，并从 backend 显式导入。

使用后端、使用 import 和 export 的示例命令 缓存：buildxregistry

$ 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 目前仅支持单个缓存导出器。但是你 可以从任意数量的远程缓存中导入。例如，通用模式 是同时使用 Current Branch 和 main Branch 的缓存。这 以下示例显示了使用 注册表缓存后端：

$ 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 .

配置选项

本节介绍生成 缓存导出。此处描述的选项至少在两个或多个 backend 类型。此外，不同的后端类型支持特定的 参数。有关更多信息，请参阅有关每种后端类型的详细页面 有关哪些配置参数适用的信息。

此处描述的常见参数包括：

缓存模式

生成缓存输出时，该参数接受一个选项，用于定义导出的缓存中要包含的图层。这是 除 Cache 之外的所有 Cache 后端都支持。--cache-tomodeinline

Mode 可以设置为以下两个选项之一： 或 .例如 要使用注册表后端构建缓存：mode=minmode=maxmode=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

在缓存模式（默认）下，只有导出到 生成的镜像将被缓存，而在缓存模式下，所有图层都将被缓存， 即使是那些中间步骤的。minmax

虽然缓存通常较小（这会加快导入/导出时间，并且 降低存储成本），cache 更有可能获得更多的缓存命中。 根据构建的复杂性和位置，您应该进行试验 使用这两个参数来查找最适合您的结果。minmax

缓存压缩

缓存压缩选项与导出器压缩选项相同。这是 由 和 cache 后端支持。localregistry

例如，要使用压缩来压缩缓存：registryzstd

$ 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 选项相同。这些是 由 和 cache 后端支持。localregistry

例如，要导出 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> .

此属性仅对 flag 有意义。当 fetch cache 时，BuildKit 会自动检测要使用的正确媒体类型。--cache-to

默认情况下，OCI 媒体类型为高速缓存镜像生成镜像索引。 某些 OCI 注册表（例如 Amazon ECR）不支持镜像索引媒体 类型：。如果将缓存镜像导出到 ECR 或任何其他不支持镜像索引的注册表，将参数设置为 to 生成单个镜像清单 而不是缓存镜像的 image 索引：application/vnd.oci.image.index.v1+jsonimage-manifesttrue

$ 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> .