此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Boot 3.4.0！spring-doc.cn

打包 OCI 映像

该插件可以使用 Cloud Native Buildpacks （CNB） 从 jar 或 war 文件创建 OCI 映像。 可以使用该任务构建图像。bootBuildImagespring-doc.cn

出于安全原因，映像以非 root 用户身份构建和运行。 有关更多详细信息，请参阅 CNB 规范。

该任务是在应用 or 插件时自动创建的，并且是 BootBuildImage 的一个实例。javawarspring-doc.cn

Docker 守护程序

该任务需要访问 Docker 守护程序。 该任务将检查本地 Docker CLI 配置文件以确定当前上下文，并使用上下文连接信息与 Docker 守护程序通信。 如果无法确定当前上下文或上下文没有连接信息，则任务将使用默认的本地连接。 这适用于所有受支持的平台上的 Docker Engine，无需配置。bootBuildImagespring-doc.cn

可以设置环境变量以将任务配置为使用备用本地或远程连接。 下表显示了环境变量及其值：bootBuildImagespring-doc.cn

环境变量 描述

DOCKER_CONFIGspring-doc.cn

用于确定当前上下文的 Docker CLI 配置文件的位置（默认为$HOME/.docker)spring-doc.cn

DOCKER_CONTEXTspring-doc.cn

应该用于从 Docker CLI 配置文件中检索主机信息的上下文的名称（覆盖DOCKER_HOST)spring-doc.cn

DOCKER_HOSTspring-doc.cn

包含 Docker 守护程序的主机和端口的 URL - 例如tcp://192.168.99.100:2376spring-doc.cn

DOCKER_TLS_VERIFYspring-doc.cn

当设置为 （optional） 时启用安全 HTTPS 协议1spring-doc.cn

DOCKER_CERT_PATHspring-doc.cn

HTTPS 的证书和密钥文件的路径（如果为 ，则为 required，否则为 ignored）DOCKER_TLS_VERIFY=1spring-doc.cn

还可以使用插件配置中的 properties 提供 Docker 守护程序连接信息。 下表总结了可用的属性：dockerspring-doc.cn

财产 描述

contextspring-doc.cn

应用于从 Docker CLI 配置文件中检索主机信息的上下文的名称spring-doc.cn

hostspring-doc.cn

包含 Docker 守护程序的主机和端口的 URL - 例如tcp://192.168.99.100:2376spring-doc.cn

tlsVerifyspring-doc.cn

当设置为 （optional） 时启用安全 HTTPS 协议truespring-doc.cn

certPathspring-doc.cn

HTTPS 的证书和密钥文件的路径（如果为 is ，则为必需，否则为忽略）tlsVerifytruespring-doc.cn

bindHostToBuilderspring-doc.cn

当 时，将向为 CNB 生成器创建的容器提供该属性的值（可选）truehostspring-doc.cn

有关更多详细信息，另请参阅示例。spring-doc.cn

Docker 注册表

如果 or 属性指定的 Docker 镜像存储在需要身份验证的私有 Docker 镜像注册表中，则可以使用 properties 提供身份验证凭证。builderrunImagedocker.builderRegistryspring-doc.cn

如果要将生成的 Docker 镜像发布到 Docker 镜像注册表，则可以使用 properties 提供身份验证凭证。docker.publishRegistryspring-doc.cn

提供了用于用户身份验证或身份令牌身份验证的属性。 有关支持的身份验证方法的更多信息，请参阅用于存储映像的 Docker 注册表的文档。spring-doc.cn

下表总结了 和 的可用属性：docker.builderRegistrydocker.publishRegistryspring-doc.cn

财产 描述

usernamespring-doc.cn

Docker 镜像注册表用户的用户名。用户身份验证是必需的。spring-doc.cn

passwordspring-doc.cn

Docker 镜像注册表用户的密码。用户身份验证是必需的。spring-doc.cn

urlspring-doc.cn

Docker 镜像注册表的地址。对于用户身份验证，可选。spring-doc.cn

emailspring-doc.cn

Docker 镜像注册表用户的电子邮件地址。对于用户身份验证，可选。spring-doc.cn

tokenspring-doc.cn

Docker 镜像注册表用户的身份令牌。令牌身份验证是必需的。spring-doc.cn

有关更多详细信息，另请参阅示例。spring-doc.cn

图像自定义

该插件调用构建器来编排映像的生成。 构建器包含多个 buildpack，这些 buildpack 可以检查应用程序以影响生成的映像。 默认情况下，插件会选择一个构建器镜像。 生成的映像的名称是从项目属性中推导出来的。spring-doc.cn

任务属性可用于配置生成器应如何操作项目。 下表总结了可用属性及其默认值：spring-doc.cn

财产 命令行选项 描述 默认值

builderspring-doc.cn

--builderspring-doc.cn

要使用的 Builder 映像的名称。spring-doc.cn

paketobuildpacks/builder-jammy-base:latest或应用 GraalVM Native Image 插件时。paketobuildpacks/builder-jammy-tiny:latestspring-doc.cn

runImagespring-doc.cn

--runImagespring-doc.cn

要使用的运行映像的名称。spring-doc.cn

无默认值，指示应使用生成器元数据中指定的运行映像。spring-doc.cn

imageNamespring-doc.cn

--imageNamespring-doc.cn

生成的镜像的镜像名称。spring-doc.cn

docker.io/library/${project.name}:${project.version}spring-doc.cn

pullPolicyspring-doc.cn

--pullPolicyspring-doc.cn

用于确定何时从注册表中提取生成器和运行镜像的策略。 可接受的值为 、 和 。ALWAYSNEVERIF_NOT_PRESENTspring-doc.cn

ALWAYSspring-doc.cn

environmentspring-doc.cn

应传递给生成器的环境变量。spring-doc.cn

为空或应用 GraalVM Native Image 插件时。['BP_NATIVE_IMAGE': 'true']spring-doc.cn

buildpacksspring-doc.cn

构建者在构建镜像时应使用的 Buildpack。 将仅使用指定的 buildpack，覆盖构建器中包含的默认 buildpack。 Buildpack 引用必须采用以下形式之一：spring-doc.cn

  • 构建器中的 buildpack -[urn:cnb:builder:]<buildpack ID>[@<version>]spring-doc.cn

  • Buildpack 位于文件系统上的目录中 -[file://]<path>spring-doc.cn

  • 文件系统上 gzip 压缩的 tar （.tgz） 文件中的 buildpack -[file://]<path>/<file name>spring-doc.cn

  • OCI 映像中的 Buildpack -[docker://]<host>/<repo>[:<tag>][@<digest>]spring-doc.cn

None，表示构建器应使用其中包含的 buildpack。spring-doc.cn

bindingsspring-doc.cn

在构建镜像时应挂载到构建器容器的卷绑定挂载。 在创建构建器容器时，绑定将未经解析和验证地传递给 Docker。 绑定必须采用以下形式之一：spring-doc.cn

  • <host source path>:<container destination path>[:<options>]spring-doc.cn

  • <host volume name>:<container destination path>[:<options>]spring-doc.cn

位置 可以包含：<options>spring-doc.cn

networkspring-doc.cn

--networkspring-doc.cn

生成器容器将配置为使用的网络驱动程序。 在创建构建器容器时，提供的值将在未经验证的情况下传递给 Docker。spring-doc.cn

cleanCachespring-doc.cn

--cleanCachespring-doc.cn

是否在构建前清理缓存。spring-doc.cn

falsespring-doc.cn

verboseLoggingspring-doc.cn

启用生成器操作的详细日志记录。spring-doc.cn

falsespring-doc.cn

publishspring-doc.cn

--publishImagespring-doc.cn

是否将生成的镜像发布到 Docker 注册表。spring-doc.cn

falsespring-doc.cn

tagsspring-doc.cn

要应用于生成的图像的一个或多个其他标记的列表。 提供给选项的值应为 full image references。 有关更多详细信息，请参阅 tags 部分。tagsspring-doc.cn

buildWorkspacespring-doc.cn

一个临时工作区，构建器和 buildpack 将使用它来在映像构建期间存储文件。 该值可以是命名卷或绑定挂载位置。spring-doc.cn

Docker 守护程序中的命名卷，其名称派生自映像名称。spring-doc.cn

buildCachespring-doc.cn

包含由 buildpack 创建并由映像构建过程使用的层的缓存。 该值可以是命名卷或绑定挂载位置。spring-doc.cn

Docker 守护程序中的命名卷，其名称派生自映像名称。spring-doc.cn

launchCachespring-doc.cn

包含由 buildpack 创建并由映像启动进程使用的层的缓存。 该值可以是命名卷或绑定挂载位置。spring-doc.cn

Docker 守护程序中的命名卷，其名称派生自映像名称。spring-doc.cn

createdDatespring-doc.cn

--createdDatespring-doc.cn

将用于在生成的图像元数据中设置字段的日期。 该值必须是 ISO 8601 即时格式的字符串，或者要使用当前日期和时间。Creatednowspring-doc.cn

启用构建可重现性的固定日期。spring-doc.cn

applicationDirectoryspring-doc.cn

--applicationDirectoryspring-doc.cn

应用程序内容将在生成器映像中上传到的目录的路径。 应用程序内容也将位于生成的映像中的此位置。spring-doc.cn

/workspacespring-doc.cn

securityOptionsspring-doc.cn

--securityOptionsspring-doc.cn

将应用于生成器容器的安全选项，以字符串值数组的形式提供spring-doc.cn

["label=disable"]在 Linux 和 macOS 上， 在 Windows 上[]spring-doc.cn
该插件使用 JavaPlugin 的属性检测项目的目标 Java 兼容性。 当使用默认的 Paketo 构建器和 buildpack 时，该插件会指示 buildpack 安装相同的 Java 版本。 您可以覆盖此行为，如 builder 配置示例所示。targetCompatibility

标签格式

提供给选项的值应为 full image references。 接受的格式为 .tags[domainHost:port/][path/]name[:tag][@digest]spring-doc.cn

如果缺少域，则默认为 。 如果缺少路径，则默认为 。 如果缺少标记，则默认为 .docker.iolibrarylatestspring-doc.cn

一些例子：spring-doc.cn

  • my-image指向图像引用docker.io/library/my-image:latestspring-doc.cn

  • my-repository/my-image导致docker.io/my-repository/my-image:latestspring-doc.cn

  • example.com/my-repository/my-image:1.0.0将按原样使用spring-doc.cn

例子

自定义映像生成器和运行映像

如果您需要自定义用于创建映像的生成器或用于启动构建映像的运行映像，请配置任务，如以下示例所示：spring-doc.cn

tasks.named("bootBuildImage") {
	builder = "mine/java-cnb-builder"
	runImage = "mine/java-cnb-run"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	builder.set("mine/java-cnb-builder")
	runImage.set("mine/java-cnb-run")
}

此配置将使用具有 name 和 tag 的生成器映像，以及名为 和 tag 的运行映像。mine/java-cnb-builderlatestmine/java-cnb-runlatestspring-doc.cn

也可以在命令行上指定 builder 和 run image，如以下示例所示：spring-doc.cn

$ gradle bootBuildImage --builder=mine/java-cnb-builder --runImage=mine/java-cnb-run

Builder 配置

如果生成器公开了配置选项，则可以使用 property 设置这些选项。environmentspring-doc.cn

以下是在构建时配置 Paketo Java buildpack 使用的 JVM 版本的示例：spring-doc.cn

tasks.named("bootBuildImage") {
	environment["BP_JVM_VERSION"] = "17"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	environment.put("BP_JVM_VERSION", "17")
}

如果构建器运行的 Docker 守护进程与 buildpack 下载工件的网络位置之间存在网络代理，则需要将构建器配置为使用该代理。 使用 Paketo 构建器时，可以通过设置 and/or 环境变量来实现，如以下示例所示：HTTPS_PROXYHTTP_PROXYspring-doc.cn

tasks.named("bootBuildImage") {
	environment["HTTP_PROXY"] = "http://proxy.example.com"
	environment["HTTPS_PROXY"] = "https://proxy.example.com"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	environment.putAll(mapOf("HTTP_PROXY" to "http://proxy.example.com",
						"HTTPS_PROXY" to "https://proxy.example.com"))
}

运行时 JVM 配置

Paketo Java buildpack 通过设置环境变量来配置 JVM 运行时环境。 可以修改 buildpack-provided 值，以自定义在容器中启动应用程序映像时的 JVM 运行时行为。JAVA_TOOL_OPTIONSJAVA_TOOL_OPTIONSspring-doc.cn

应存储在映像中并应用于每个部署的环境变量修改可以按照 Paketo 文档中所述进行设置，如以下示例所示：spring-doc.cn

tasks.named("bootBuildImage") {
	environment["BPE_DELIM_JAVA_TOOL_OPTIONS"] = " "
	environment["BPE_APPEND_JAVA_TOOL_OPTIONS"] = "-XX:+HeapDumpOnOutOfMemoryError"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	environment.putAll(mapOf(
		"BPE_DELIM_JAVA_TOOL_OPTIONS" to " ",
		"BPE_APPEND_JAVA_TOOL_OPTIONS" to "-XX:+HeapDumpOnOutOfMemoryError"
	))
}

自定义镜像名称

默认情况下，映像名称是从项目的 和 中推断出来的，类似于 . 您可以通过设置任务属性来控制名称，如以下示例所示：nameversiondocker.io/library/${project.name}:${project.version}spring-doc.cn

tasks.named("bootBuildImage") {
	imageName = "example.com/library/${project.name}"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	imageName.set("example.com/library/${project.name}")
}

请注意，此配置不提供显式标记，因此使用。 也可以使用内部版本或硬编码版本中的任何可用属性指定标记。latest${project.version}spring-doc.cn

也可以在命令行上指定映像名称，如以下示例所示：spring-doc.cn

$ gradle bootBuildImage --imageName=example.com/library/my-app:v1

构建包

默认情况下，构建器将使用构建器镜像中包含的 buildpack，并按预定义的顺序应用它们。 可以提供一组替代的 buildpack 来应用未包含在构建器中的 buildpack，或更改包含的 buildpack 的顺序。 当提供一个或多个 buildpack 时，将仅应用指定的 buildpack。spring-doc.cn

以下示例指示构建器使用打包在文件中的自定义 buildpack，后跟构建器中包含的 buildpack。.tgzspring-doc.cn

tasks.named("bootBuildImage") {
	buildpacks = ["file:///path/to/example-buildpack.tgz", "urn:cnb:builder:paketo-buildpacks/java"]
}
tasks.named<BootBuildImage>("bootBuildImage") {
	buildpacks.set(listOf("file:///path/to/example-buildpack.tgz", "urn:cnb:builder:paketo-buildpacks/java"))
}

Buildpack 可以采用下面显示的任何形式指定。spring-doc.cn

位于 CNB Builder 中的 buildpack（如果构建器中只有一个 buildpack 与 ）：buildpack-idspring-doc.cn

包含 buildpack 内容的目录的路径（在 Windows 上不受支持）：spring-doc.cn

包含 buildpack 内容的 gzip 压缩 tar 文件的路径：spring-doc.cn

包含打包的 buildpack 的 OCI 映像：spring-doc.cn

图像发布

通过启用选项，可以将生成的映像发布到 Docker 注册表。publishspring-doc.cn

如果 Docker 注册表需要身份验证，则可以使用 properties 配置凭证。 如果 Docker 注册表不需要身份验证，则可以省略配置。docker.publishRegistrydocker.publishRegistryspring-doc.cn

映像将发布到的注册表由映像名称的注册表部分确定（在这些示例中为 ）。 如果配置了凭据并包含属性，则此值将传递给注册表，但不用于确定发布注册表位置。docker.example.comdocker.publishRegistryurl 
tasks.named("bootBuildImage") {
	imageName.set("docker.example.com/library/${project.name}")
	publish = true
	docker {
		publishRegistry {
			username = "user"
			password = "secret"
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	imageName.set("docker.example.com/library/${project.name}")
	publish.set(true)
	docker {
		publishRegistry {
			username.set("user")
			password.set("secret")
		}
	}
}

也可以在命令行上指定 publish 选项，如以下示例所示：spring-doc.cn

$ gradle bootBuildImage --imageName=docker.example.com/library/my-app:v1 --publishImage

Builder 缓存和工作区配置

CNB 构建器缓存构建和启动映像时使用的层。 默认情况下，这些缓存作为命名卷存储在 Docker 守护程序中，其名称派生自目标映像的全名。 如果映像名称频繁更改，例如，当项目版本用作映像名称中的标记时，则缓存可能会频繁失效。spring-doc.cn

缓存卷可以配置为使用备用名称，以便更好地控制缓存生命周期，如以下示例所示：spring-doc.cn

tasks.named("bootBuildImage") {
	buildCache {
		volume {
			name = "cache-${rootProject.name}.build"
		}
	}
	launchCache {
		volume {
			name = "cache-${rootProject.name}.launch"
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	buildCache {
		volume {
			name.set("cache-${rootProject.name}.build")
		}
	}
	launchCache {
		volume {
			name.set("cache-${rootProject.name}.launch")
		}
	}
}

在映像构建期间，构建器和 buildpack 需要一个位置来存储临时文件。 默认情况下，此临时构建工作区存储在命名卷中。spring-doc.cn

缓存和构建工作区可以配置为使用绑定挂载而不是命名卷，如以下示例所示：spring-doc.cn

tasks.named("bootBuildImage") {
	buildWorkspace {
		bind {
			source = "/tmp/cache-${rootProject.name}.work"
		}
	}
	buildCache {
		bind {
			source = "/tmp/cache-${rootProject.name}.build"
		}
	}
	launchCache {
		bind {
			source = "/tmp/cache-${rootProject.name}.launch"
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	buildWorkspace {
		bind {
			source.set("/tmp/cache-${rootProject.name}.work")
		}
	}
	buildCache {
		bind {
			source.set("/tmp/cache-${rootProject.name}.build")
		}
	}
	launchCache {
		bind {
			source.set("/tmp/cache-${rootProject.name}.launch")
		}
	}
}

Docker 配置

minikube 的 Docker 配置

该插件可以与 minikube 提供的 Docker 守护进程通信，而不是默认的本地连接。spring-doc.cn

在 Linux 和 macOS 上，可以在 minikube 启动后使用命令设置环境变量。eval $(minikube docker-env)spring-doc.cn

还可以通过提供类似于以下示例中所示的连接详细信息，将插件配置为使用 minikube 守护进程：spring-doc.cn

tasks.named("bootBuildImage") {
	docker {
		host = "tcp://192.168.99.100:2376"
		tlsVerify = true
		certPath = "/home/user/.minikube/certs"
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		host.set("tcp://192.168.99.100:2376")
		tlsVerify.set(true)
		certPath.set("/home/user/.minikube/certs")
	}
}

podman 的 Docker 配置

该插件可以与 podman 容器引擎通信。spring-doc.cn

通过提供类似于以下示例中所示的连接详细信息，可以将插件配置为使用 podman 本地连接：spring-doc.cn

tasks.named("bootBuildImage") {
	docker {
		host = "unix:///run/user/1000/podman/podman.sock"
		bindHostToBuilder = true
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		host.set("unix:///run/user/1000/podman/podman.sock")
		bindHostToBuilder.set(true)
	}
}
安装 CLI 后，该命令可用于获取本示例所示的 configuration 属性的值。podmanpodman info --format='{{.Host.RemoteSocket.Path}}'docker.host

Colima 的 Docker 配置

该插件可以与 Colima 提供的 Docker 守护程序通信。 可以使用以下命令设置环境变量：DOCKER_HOSTspring-doc.cn

$ export DOCKER_HOST=$(docker context inspect colima -f '{{.Endpoints.docker.Host}}')

还可以通过提供类似于以下示例中所示的连接详细信息，将插件配置为使用 Colima 守护程序：spring-doc.cn

tasks.named("bootBuildImage") {
	docker {
		host = "unix://${System.properties['user.home']}/.colima/docker.sock"
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		host.set("unix://${System.getProperty("user.home")}/.colima/docker.sock")
	}
}

用于身份验证的 Docker 配置

如果生成器或运行映像存储在支持用户身份验证的私有 Docker 注册表中，则可以使用属性提供身份验证详细信息，如以下示例所示：docker.builderRegistryspring-doc.cn

tasks.named("bootBuildImage") {
	docker {
		builderRegistry {
			username = "user"
			password = "secret"
			url = "https://docker.example.com/v1/"
			email = "[email protected]"
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		builderRegistry {
			username.set("user")
			password.set("secret")
			url.set("https://docker.example.com/v1/")
			email.set("[email protected]")
		}
	}
}

如果生成器或运行映像存储在支持令牌身份验证的私有 Docker 注册表中，则可以使用以下示例所示提供令牌值：docker.builderRegistryspring-doc.cn

tasks.named("bootBuildImage") {
	docker {
		builderRegistry {
			token = "9cbaf023786cd7..."
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		builderRegistry {
			token.set("9cbaf023786cd7...")
		}
	}
}