打包 OCI 镜像

QWen Max 中英对照 Packaging OCI Images

打包 OCI 镜像

• Docker Daemon
• Docker Registry
• Image Customizations
• Tags Format
• spring-boot:build-image
• Required parameters
• Optional parameters
• Parameter details
• spring-boot:build-image-no-fork
• Required parameters
• Optional parameters
• Parameter details
• Examples
• Custom Image Builder
• Builder Configuration
• Runtime JVM Configuration
• Custom Image Name
• Buildpacks
• Image Publishing
• Builder Cache and Workspace Configuration
• Docker Configuration

该插件可以使用 Cloud Native Buildpacks（CNB）从 jar 或 war 文件创建一个 OCI 镜像。可以通过命令行使用 build-image 目标来构建镜像。这可确保在创建镜像之前，package 生命周期阶段已经执行完毕。

备注

出于安全原因，镜像以非 root 用户身份构建和运行。更多详情请参见 CNB 规范。

最简单的入门方式是在项目上执行 mvn spring-boot:build-image。也可以在每次调用 package 阶段时自动创建镜像，如下例所示：

<build>
	<plugins>
		<plugin>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-maven-plugin</artifactId>
			<executions>
				<execution>
					<goals>
						<goal>build-image-no-fork</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
	</plugins>
</build>

备注

在将目标绑定到 package 生命周期时，请使用 build-image-no-fork。该目标与 build-image 类似，但不会 fork 生命周期以确保 package 已经执行。在本节其余部分中，build-image 用于指代 build-image 或 build-image-no-fork 目标。

提示

虽然 buildpack 是从一个可执行归档文件运行的，但无需先执行 repackage 目标，因为如果需要，可执行归档文件会自动生成。当 build-image 对应用进行重新打包时，它会应用与 repackage 目标相同的设置，也就是说，可以使用其中一种排除选项来排除依赖项。默认情况下，spring-boot-devtools 和 spring-boot-docker-compose 模块会被自动排除（你可以通过 excludeDevtools 和 excludeDockerCompose 属性来控制这一行为）。

Docker Daemon

build-image goal 需要访问 Docker daemon。该 goal 会检查本地 Docker CLI 的 配置文件，以确定当前的 context，并使用该 context 的连接信息与 Docker daemon 通信。如果无法确定当前 context，或者该 context 没有连接信息，则该 goal 将使用默认的本地连接。此方式在所有受支持的平台上无需额外配置即可与 Docker Engine 协同工作。

可以设置环境变量来配置 build-image 目标，以使用替代的本地或远程连接。下表列出了相关的环境变量及其值：

环境变量	说明
DOCKER_CONFIG	Docker CLI 配置文件 的位置，用于确定当前上下文（默认为 $HOME/.docker）
DOCKER_CONTEXT	应使用的 上下文 名称，用于从 Docker CLI 配置文件中获取主机信息（会覆盖 DOCKER_HOST）
DOCKER_HOST	包含 Docker 守护进程主机和端口的 URL —— 例如 tcp://192.168.99.100:2376
DOCKER_TLS_VERIFY	当设置为 1 时，启用安全的 HTTPS 协议（可选）
DOCKER_CERT_PATH	HTTPS 证书和密钥文件的路径（当 DOCKER_TLS_VERIFY=1 时必需，否则忽略）

Docker daemon 连接信息也可以通过插件配置中的 docker 参数提供。下表总结了可用的参数：

参数	描述
context	应用于从 Docker CLI 配置文件 中检索主机信息的 上下文 名称
host	包含 Docker 守护进程主机和端口的 URL，例如 tcp://192.168.99.100:2376
tlsVerify	当设置为 true 时，启用安全的 HTTPS 协议（可选）
certPath	HTTPS 证书和密钥文件的路径（当 tlsVerify 为 true 时必需，否则忽略）
bindHostToBuilder	当为 true 时，host 属性的值将提供给为 CNB builder 创建的容器（可选）

更多详情，请参见 示例。

Docker Registry

如果 builder 或 runImage 参数指定的 Docker 镜像存储在需要身份验证的私有 Docker 镜像仓库中，则可以使用 docker.builderRegistry 参数提供身份验证凭据。

如果要将生成的 Docker 镜像发布到 Docker 镜像仓库，可以使用 docker.publishRegistry 参数提供身份验证凭据。

参数用于用户认证或身份令牌（identity token）认证。有关所支持的认证方法的更多信息，请参阅用于存储镜像的 Docker registry 的相关文档。

下表总结了 docker.builderRegistry 和 docker.publishRegistry 的可用参数：

Parameter	Description
username	Docker 镜像仓库用户的用户名。用户认证时必需。
password	Docker 镜像仓库用户的密码。用户认证时必需。
url	Docker 镜像仓库的地址。用户认证时可选。
email	Docker 镜像仓库用户的电子邮件地址。用户认证时可选。
token	Docker 镜像仓库用户的身份令牌。令牌认证时必需。

更多详情，请参见 示例。

备注

如果未提供凭证，该插件会读取用户现有的 Docker 配置文件（通常位于 $HOME/. docker/config.json）以确定认证方法。插件将使用这些方法，尝试为所请求的镜像提供认证凭证。

该插件支持以下认证方法：

• Credential Helpers：在 Docker 配置文件中配置的外部工具，用于为特定的 registry 提供凭证。例如，osxkeychain 或 ecr-login 等工具可处理某些 registry 的认证。

• Credential Store：一种默认的后备机制，用于安全地存储和检索凭证（例如，Docker Desktop 使用的 desktop）。

• Static Credentials：直接存储在 Docker 配置文件 auths 部分中的凭证。

镜像定制

该插件调用一个 builder 来协调生成镜像。该 builder 包含多个 buildpacks，可以检查应用程序并影响所生成的镜像。默认情况下，插件会选择一个 builder 镜像。所生成镜像的名称由项目属性推断得出。

image 参数允许配置构建器（builder）及其在项目上的操作方式。下表总结了可用的参数及其默认值：

Parameter / (User Property)	描述	默认值
builder (spring-boot.build-image.builder)	要使用的构建器镜像的名称。	paketobuildpacks/builder-noble-java-tiny:latest
trustBuilder (spring-boot.build-image.trustBuilder)	是否将该 builder 视为受信任的。	true if the builder is one of paketobuildpacks/builder-noble-java-tiny, paketobuildpacks/builder-jammy-java-tiny, paketobuildpacks/builder-jammy-tiny, paketobuildpacks/builder-jammy-base, paketobuildpacks/builder-jammy-full, paketobuildpacks/builder-jammy-buildpackless-tiny, paketobuildpacks/builder-jammy-buildpackless-base, paketobuildpacks/builder-jammy-buildpackless-full, gcr.io/buildpacks/builder, heroku/builder; false otherwise.
imagePlatform (spring-boot.build-image.imagePlatform)	所拉取的任何 builder 镜像、运行镜像和 buildpack 镜像的平台（操作系统和架构）。格式必须为 OS[/architecture[/variant]]，例如 linux/amd64、linux/arm64 或 linux/arm/v5。请参考所使用 builder 的文档，以确定可用的镜像操作系统和架构选项。	无默认值，表示应使用主机平台。
runImage (spring-boot.build-image.runImage)	要使用的运行镜像的名称。	无默认值，表示应使用 Builder 元数据中指定的运行时镜像。
name (spring-boot.build-image.imageName)	生成镜像的 Image name。	docker.io/library/ ${project.artifactId}:${project.version}
pullPolicy (spring-boot.build-image.pullPolicy)	用于确定何时从注册表拉取 builder 和 run 镜像的策略。可接受的值为 ALWAYS、NEVER 和 IF_NOT_PRESENT。	ALWAYS
env	应传递给构建器的环境变量。
buildpacks	构建器在构建镜像时应使用的 Buildpack。仅会使用指定的 Buildpack，覆盖构建器中包含的默认 Buildpack。Buildpack 引用必须采用以下形式之一： - 构建器中的 Buildpack - [urn:cnb:builder:]<buildpack ID>[@<version>] - 文件系统目录中的 Buildpack - [file://]<path> - 文件系统中 gzipped tar（.tgz）文件内的 Buildpack - [file://]<path>/<file name> - OCI 镜像中的 Buildpack - [docker://]<host>/<repo>[:<tag>][@<digest>]	None，表示构建器应使用其中包含的 buildpacks。
bindings	卷绑定挂载（Volume bind mounts），在构建镜像时应挂载到构建器容器中。这些绑定将在创建构建器容器时以未经解析和验证的形式直接传递给 Docker。绑定必须采用以下形式之一： - <host source path>:<container destination path>[:<options>] - <host volume name>:<container destination path>[:<options>] 其中 <options> 可包含以下内容： - ro：将卷以只读方式挂载到容器中 - rw：将卷以可读写方式挂载到容器中 - volume-opt=key=value：指定由选项名称及其值组成的键值对
network + (spring-boot.build-image.network)	构建器容器将配置为使用的 网络驱动。所提供的值在创建构建器容器时将未经验证地传递给 Docker。
cleanCache + (spring-boot.build-image.cleanCache)	是否在构建前清理缓存。	false
verboseLogging	启用构建器操作的详细日志记录。	false
publish + (spring-boot.build-image.publish)	是否将生成的镜像发布到 Docker registry。	false
tags	一个或多个要应用于生成镜像的附加标签。提供给 tags 选项的值应为完整的镜像引用。更多详情请参见 标签部分。
buildWorkspace	一个临时工作区，将由 builder 和 buildpacks 在镜像构建过程中用于存储文件。该值可以是一个命名卷（named volume）或绑定挂载（bind mount）位置。	Docker 守护进程中一个命名卷，其名称源自镜像名称。
buildCache	一个包含由 buildpacks 创建的层并被镜像构建过程使用的缓存。该值可以是一个命名卷或一个绑定挂载位置。	Docker 守护进程中一个命名卷，其名称源自镜像名称。
launchCache	一个包含由 buildpacks 创建的层并被镜像启动过程使用的缓存。该值可以是一个命名卷或一个绑定挂载位置。	Docker 守护进程中一个命名卷，其名称源自镜像名称。
createdDate (spring-boot.build-image.createdDate)	一个用于设置生成镜像元数据中 Created 字段的日期。该值必须是 ISO 8601 即时格式的字符串，或者为 now 以使用当前日期和时间。	一个固定的日期，用于实现 构建可重现性。
applicationDirectory (spring-boot.build-image.applicationDirectory)	应用程序内容将被上传到构建器镜像中的目录路径。在生成的镜像中，应用程序内容也将位于此位置。	/workspace
securityOptions	将应用于构建器容器的安全选项，以字符串值数组的形式提供	["label=disable"] on Linux and macOS, [] on Windows

备注

该插件通过编译器的插件配置或 maven.compiler.target 属性来检测项目的目标 Java 兼容性。当使用默认的 Paketo builder 和 buildpacks 时，该插件会指示 buildpacks 安装相同的 Java 版本。你可以按照 builder 配置 示例中所示的方式覆盖此行为。

更多详情，请参见 examples。

标签格式

提供给 tags 选项的值应为完整的镜像引用。可接受的格式为 [domainHost:port/][path/]name[:tag][@digest]。

如果域（domain）缺失，则默认为 docker.io。如果路径（path）缺失，则默认为 library。如果标签（tag）缺失，则默认为 latest。

一些示例：

• my-image 对应的镜像引用为 docker.io/library/my-image:latest

• my-repository/my-image 对应的镜像引用为 docker.io/my-repository/my-image:latest

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

spring-boot:build-image

org.springframework.boot:spring-boot-maven-plugin:3.5.10

使用 buildpack 将应用程序打包为 OCI 镜像，并 fork 生命周期以确保 package 已执行。此目标适用于命令行调用。如果需要在构建中配置 goal execution，请改用 build-image-no-fork。

必需参数

名称	类型	默认值
sourceDirectory	File	${project.build.directory}

可选参数

名称	类型	默认值
applicationDirectory	String
classifier	String
cleanCache	Boolean
createdDate	String
docker	[Docker](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Docker.html)
excludeDevtools	boolean	true
excludeDockerCompose	boolean	true
excludeGroupIds	String
excludes	List
image	[Image](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Image.html)
imageBuilder	String
imageName	String
imagePlatform	String
includeOptional	boolean	true
includeSystemScope	boolean	false
includeTools	boolean	true
includes	List
layers	[Layers](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)
layout	[LayoutType](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)
layoutFactory	[LayoutFactory](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)
loaderImplementation	[LoaderImplementation](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/loader/tools/LoaderImplementation.html)
mainClass	String
network	String
publish	Boolean
pullPolicy	[PullPolicy](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/buildpack/platform/build/PullPolicy.html)
runImage	String
skip	boolean	false
trustBuilder	Boolean

参数详情

applicationDirectory

Image#applicationDirectory 的别名，用于支持通过命令行属性进行配置。

applicationDirectory
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.applicationDirectory
起始版本	3.1.0

classifier

查找源代码归档文件时使用的分类器。

classifier
类型	java.lang.String
默认值
用户属性
自	2.3.0

cleanCache

Image#cleanCache 的别名，用于支持通过命令行属性进行配置。

cleanCache
类型	java.lang.Boolean
默认值
用户属性	spring-boot.build-image.cleanCache
起始版本	2.4.0

createdDate

Image#createdDate 的别名，用于支持通过命令行属性进行配置。

createdDate
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.createdDate
起始版本	3.1.0

docker

Docker 配置选项。

docker
类型	[org.springframework.boot.maven.Docker](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Docker.html)
默认值
用户属性
自	2.4.0

excludeDevtools

从重新打包的归档文件中排除 Spring Boot devtools。

excludeDevtools
类型	boolean
默认值	true
用户属性	spring-boot.repackage.excludeDevtools
起始版本	1.3.0

excludeDockerCompose

将 Spring Boot 开发服务从重新打包的归档文件中排除。

excludeDockerCompose
类型	boolean
默认值	true
用户属性	spring-boot.repackage.excludeDockerCompose
自版本	3.1.0

excludeGroupIds

要排除的 groupId 名称的逗号分隔列表（精确匹配）。

excludeGroupIds
类型	java.lang.String
默认值
用户属性	spring-boot.excludeGroupIds
起始版本	1.1.0

excludes

要排除的构件定义集合。Exclude 元素定义了必需的 groupId 和 artifactId 组件，以及一个可选的 classifier 组件。当将其配置为属性时，值应以逗号分隔，各组件之间用冒号分隔：groupId:artifactId,groupId:artifactId:classifier

excludes
类型	java.util.List
默认值
用户属性	spring-boot.excludes
起始版本	1.1.0

image

镜像配置，包含 builder、runImage、name、env、cleanCache、verboseLogging、pullPolicy 和 publish 选项。

image
类型	[org.springframework.boot.maven.Image](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Image.html)
默认值
用户属性
起始版本	2.3.0

imageBuilder

Image#builder 的别名，用于支持通过命令行属性进行配置。

imageBuilder
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.builder
起始版本	2.3.0

imageName

Image#name 的别名，用于支持通过命令行属性进行配置。

imageName
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.imageName
起始版本	2.3.0

imagePlatform

Image#imagePlatform 的别名，用于支持通过命令行属性进行配置。

imagePlatform
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.imagePlatform
自	3.4.0

includeOptional

包含可选依赖项。

includeOptional
类型	boolean
默认值	true
用户属性
自	3.5.7

includeSystemScope

包含系统作用域的依赖项。

includeSystemScope
类型	boolean
默认值	false
用户属性
自版本	1.4.0

includeTools

包含 JAR 工具。

includeTools
类型	boolean
默认值	true
用户属性
自	3.3.0

includes

要包含的构件定义集合。Include 元素定义了必需的 groupId 和 artifactId 组件，以及一个可选的 classifier 组件。当配置为属性时，值应以逗号分隔，各组件之间用冒号分隔：groupId:artifactId,groupId:artifactId:classifier

includes
类型	java.util.List
默认值
用户属性	spring-boot.includes
起始版本	1.2.0

layers

层配置，包含禁用层创建、排除层工具 JAR 包，以及提供自定义层配置文件的选项。

layers
类型	[org.springframework.boot.maven.Layers](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)
默认值
用户属性
自	2.3.0

layout

归档文件的类型（对应于其中依赖项的布局方式）。可能的值有 JAR、WAR、ZIP、DIR、NONE。默认值根据归档文件类型进行猜测。

layout
类型	[org.springframework.boot.maven.AbstractPackagerMojo$LayoutType](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)
默认值
用户属性
自	2.3.11

layoutFactory

如果未显式设置布局，将使用此布局工厂来创建可执行归档文件。第三方可以提供替代的布局实现。

layoutFactory
类型	[org.springframework.boot.loader.tools.LayoutFactory](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)
默认值
用户属性
自	2.3.11

loaderImplementation

应使用的 loader 实现。

loaderImplementation
类型	[org.springframework.boot.loader.tools.LoaderImplementation](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/loader/tools/LoaderImplementation.html)
默认值
用户属性
起始版本	3.2.0

mainClass

主类的名称。如果未指定，则将使用找到的第一个包含 main 方法的已编译类。

mainClass
类型	java.lang.String
默认值
用户属性
起始版本	1.0.0

network

Image#network 的别名，用于支持通过命令行属性进行配置。

network
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.network
起始版本	2.6.0

publish

Image#publish 的别名，用于支持通过命令行属性进行配置。

publish
类型	java.lang.Boolean
默认值
用户属性	spring-boot.build-image.publish
起始版本

pullPolicy

Image#pullPolicy 的别名，用于支持通过命令行属性进行配置。

pullPolicy
类型	[org.springframework.boot.buildpack.platform.build.PullPolicy](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/buildpack/platform/build/PullPolicy.html)
默认值
用户属性	spring-boot.build-image.pullPolicy
起始版本

runImage

Image#runImage 的别名，用于支持通过命令行属性进行配置。

runImage
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.runImage
自	2.3.1

skip

跳过执行。

skip
类型	boolean
默认值	false
用户属性	spring-boot.build-image.skip
起始版本	2.3.0

sourceDirectory

包含源代码归档文件的目录。

sourceDirectory
类型	java.io.File
默认值	${project.build.directory}
用户属性
自	2.3.0

trustBuilder

Image#trustBuilder 的别名，用于支持通过命令行属性进行配置。

trustBuilder
类型	java.lang.Boolean
默认值
用户属性	spring-boot.build-image.trustBuilder
起始版本

spring-boot:build-image-no-fork

org.springframework.boot:spring-boot-maven-plugin:3.5.10

使用 buildpack 将应用程序打包为 OCI 镜像，但无需 fork 生命周期。在配置构建中的 execution 目标时应使用此目标。若要在命令行上调用该目标，请改用 build-image。

必需参数

名称	类型	默认值
sourceDirectory	File	${project.build.directory}

可选参数

名称	类型	Default
applicationDirectory	String
classifier	String
cleanCache	Boolean
createdDate	String
docker	[Docker](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Docker.html)
excludeDevtools	boolean	true
excludeDockerCompose	boolean	true
excludeGroupIds	String
excludes	List
image	[Image](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Image.html)
imageBuilder	String
imageName	String
imagePlatform	String
includeOptional	boolean	true
includeSystemScope	boolean	false
includeTools	boolean	true
includes	List
layers	[Layers](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)
layout	[LayoutType](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)
layoutFactory	[LayoutFactory](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)
loaderImplementation	[LoaderImplementation](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/loader/tools/LoaderImplementation.html)
mainClass	String
network	String
publish	Boolean
pullPolicy	[PullPolicy](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/buildpack/platform/build/PullPolicy.html)
runImage	String
skip	boolean	false
trustBuilder	Boolean

参数详情

applicationDirectory

Image#applicationDirectory 的别名，用于支持通过命令行属性进行配置。

applicationDirectory
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.applicationDirectory
起始版本	3.1.0

classifier

查找源代码归档文件时使用的分类器。

classifier
类型	java.lang.String
默认值
用户属性
自	2.3.0

cleanCache

Image#cleanCache 的别名，用于支持通过命令行属性进行配置。

cleanCache
类型	java.lang.Boolean
默认值
用户属性	spring-boot.build-image.cleanCache
起始版本	2.4.0

createdDate

Image#createdDate 的别名，用于支持通过命令行属性进行配置。

createdDate
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.createdDate
起始版本	3.1.0

docker

Docker 配置选项。

docker
类型	[org.springframework.boot.maven.Docker](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Docker.html)
默认值
用户属性
自	2.4.0

excludeDevtools

从重新打包的归档文件中排除 Spring Boot devtools。

excludeDevtools
类型	boolean
默认值	true
用户属性	spring-boot.repackage.excludeDevtools
起始版本	1.3.0

excludeDockerCompose

将 Spring Boot 开发服务从重新打包的归档文件中排除。

excludeDockerCompose
类型	boolean
默认值	true
用户属性	spring-boot.repackage.excludeDockerCompose
起始版本	3.1.0

excludeGroupIds

要排除的 groupId 名称的逗号分隔列表（精确匹配）。

excludeGroupIds
类型	java.lang.String
默认值
用户属性	spring-boot.excludeGroupIds
起始版本	1.1.0

excludes

要排除的构件定义集合。Exclude 元素定义了必需的 groupId 和 artifactId 组件，以及一个可选的 classifier 组件。当配置为属性时，值应以逗号分隔，各组件之间用冒号分隔：groupId:artifactId,groupId:artifactId:classifier

excludes
类型	java.util.List
默认值
用户属性	spring-boot.excludes
起始版本	1.1.0

image

镜像配置，包含 builder、runImage、name、env、cleanCache、verboseLogging、pullPolicy 和 publish 选项。

image
类型	[org.springframework.boot.maven.Image](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Image.html)
默认值
用户属性
自	2.3.0

imageBuilder

Image#builder 的别名，用于支持通过命令行属性进行配置。

imageBuilder
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.builder
起始版本	2.3.0

imageName

Image#name 的别名，用于支持通过命令行属性进行配置。

imageName
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.imageName
起始版本	2.3.0

imagePlatform

Image#imagePlatform 的别名，用于支持通过命令行属性进行配置。

imagePlatform
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.imagePlatform
自	3.4.0

includeOptional

包含可选依赖项。

includeOptional
类型	boolean
默认值	true
用户属性
自	3.5.7

includeSystemScope

包含系统作用域的依赖项。

includeSystemScope
类型	boolean
默认值	false
用户属性
自版本	1.4.0

includeTools

包含 JAR 工具。

includeTools
类型	boolean
默认值	true
用户属性
自版本	3.3.0

includes

要包含的构件定义集合。Include 元素定义了必需的 groupId 和 artifactId 组件，以及一个可选的 classifier 组件。当将其配置为属性时，值应以逗号分隔，各组件之间用冒号分隔：groupId:artifactId,groupId:artifactId:classifier

includes
类型	java.util.List
默认值
用户属性	spring-boot.includes
起始版本	1.2.0

layers

层配置，包含禁用层创建、排除层工具 JAR 包以及提供自定义层配置文件的选项。

layers
类型	[org.springframework.boot.maven.Layers](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)
默认值
用户属性
自	2.3.0

layout

归档文件的类型（对应于其内部依赖项的布局方式）。可能的值有 JAR、WAR、ZIP、DIR、NONE。默认值根据归档文件类型进行推测。

layout
类型	[org.springframework.boot.maven.AbstractPackagerMojo$LayoutType](https://docs.spring.io/spring-boot/3.5/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)
默认值
用户属性
自	2.3.11

layoutFactory

如果未显式设置布局，将用于创建可执行归档文件的布局工厂。第三方可以提供替代的布局实现。

layoutFactory
类型	[org.springframework.boot.loader.tools.LayoutFactory](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)
默认值
用户属性
自	2.3.11

loaderImplementation

应使用的 loader 实现。

loaderImplementation
类型	[org.springframework.boot.loader.tools.LoaderImplementation](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/loader/tools/LoaderImplementation.html)
默认值
用户属性
自	3.2.0

mainClass

主类的名称。如果未指定，则将使用找到的第一个包含 main 方法的已编译类。

mainClass
类型	java.lang.String
默认值
用户属性
起始版本	1.0.0

network

Image#network 的别名，用于支持通过命令行属性进行配置。

network
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.network
起始版本	2.6.0

publish

Image#publish 的别名，用于支持通过命令行属性进行配置。

publish
类型	java.lang.Boolean
默认值
用户属性	spring-boot.build-image.publish
起始版本

pullPolicy

Image#pullPolicy 的别名，用于支持通过命令行属性进行配置。

pullPolicy
类型	[org.springframework.boot.buildpack.platform.build.PullPolicy](https://docs.spring.io/spring-boot/3.5/api/java/org/springframework/boot/buildpack/platform/build/PullPolicy.html)
默认值
用户属性	spring-boot.build-image.pullPolicy
起始版本

runImage

Image#runImage 的别名，用于支持通过命令行属性进行配置。

runImage
类型	java.lang.String
默认值
用户属性	spring-boot.build-image.runImage
起始版本	2.3.1

skip

跳过执行。

skip
类型	boolean
默认值	false
用户属性	spring-boot.build-image.skip
起始版本	2.3.0

sourceDirectory

包含源代码归档文件的目录。

sourceDirectory
类型	java.io.File
默认值	${project.build.directory}
用户属性
自	2.3.0

trustBuilder

Image#trustBuilder 的别名，用于支持通过命令行属性进行配置。

trustBuilder
类型	java.lang.Boolean
默认值
用户属性	spring-boot.build-image.trustBuilder
起始版本

示例

Custom Image Builder

如果你需要自定义用于创建镜像的 builder，或用于启动构建后镜像的 run 镜像，请按以下示例配置该插件：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<builder>mine/java-cnb-builder</builder>
						<runImage>mine/java-cnb-run</runImage>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

此配置将使用名为 mine/java-cnb-builder、标签为 latest 的构建器镜像，以及名为 mine/java-cnb-run、标签为 latest 的运行镜像。

构建器镜像和运行镜像也可以在命令行中指定，如下例所示：

$ mvn spring-boot:build-image -Dspring-boot.build-image.builder=mine/java-cnb-builder -Dspring-boot.build-image.runImage=mine/java-cnb-run

Builder 配置

如果构建器使用环境变量暴露配置选项，则可以使用 env 属性进行设置。

以下是在构建时 配置 Paketo Java buildpacks 所使用的 JVM 版本 的一个示例：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<env>
							<BP_JVM_VERSION>17</BP_JVM_VERSION>
						</env>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

如果在运行 buildpack 构建器的 Docker daemon 与 buildpack 下载制品的网络位置之间存在网络代理，则需要配置构建器以使用该代理。使用 Paketo 构建器时，可以通过设置 HTTPS_PROXY 和/或 HTTP_PROXY 环境变量来实现，如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<env>
							<HTTP_PROXY>http://proxy.example.com</HTTP_PROXY>
							<HTTPS_PROXY>https://proxy.example.com</HTTPS_PROXY>
						</env>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

运行时 JVM 配置

Paketo Java buildpack 通过设置 JAVA_TOOL_OPTIONS 环境变量来配置 JVM 运行时环境。当应用镜像在容器中启动时，可以修改 buildpack 提供的 JAVA_TOOL_OPTIONS 值，以自定义 JVM 运行时行为。

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

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<env>
							<BPE_DELIM_JAVA_TOOL_OPTIONS xml:space="preserve"> </BPE_DELIM_JAVA_TOOL_OPTIONS>
							<BPE_APPEND_JAVA_TOOL_OPTIONS>-XX:+HeapDumpOnOutOfMemoryError</BPE_APPEND_JAVA_TOOL_OPTIONS>
						</env>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

自定义镜像名称

默认情况下，镜像名称是从项目的 artifactId 和 version 推断出来的，类似于 docker.io/library/${project.artifactId}:${project.version}。你可以像下面的例子一样自行控制镜像名称：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<name>example.com/library/${project.artifactId}</name>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

备注

此配置未提供显式的标签，因此使用 latest。也可以指定一个标签，可以使用 ${project.version}、构建中可用的任意属性，或者一个硬编码的版本。

镜像名称也可以在命令行中指定，如以下示例所示：

$ mvn spring-boot:build-image -Dspring-boot.build-image.imageName=example.com/library/my-app:v1

Buildpacks

默认情况下，builder 将使用 builder 镜像中包含的 buildpack，并按照预定义的顺序应用它们。也可以提供一组替代的 buildpack，以应用未包含在 builder 中的 buildpack，或更改已包含 buildpack 的顺序。当提供一个或多个 buildpack 时，将仅应用所指定的 buildpack。

以下示例指示 builder 使用一个打包在 .tgz 文件中的自定义 buildpack，然后使用 builder 中包含的 buildpack。

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<buildpacks>
							<buildpack>file:///path/to/example-buildpack.tgz</buildpack>
							<buildpack>urn:cnb:builder:paketo-buildpacks/java</buildpack>
						</buildpacks>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Buildpacks 可以以下面所示的任意一种形式指定。

位于 CNB Builder 中的 buildpack（如果 builder 中只有一个与 buildpack-id 匹配的 buildpack，则版本号可以省略）：

• urn:cnb:builder:buildpack-id

• urn:cnb:builder:buildpack-id@0.0.1

• buildpack-id

• buildpack-id@0.0.1

指向包含 buildpack 内容的目录的路径（在 Windows 上不受支持）：

• file:///path/to/buildpack/

• /path/to/buildpack/

一个指向包含 buildpack 内容的 gzip 压缩 tar 文件的路径：

• file:///path/to/buildpack.tgz

• /path/to/buildpack.tgz

一个包含 打包的 buildpack 的 OCI 镜像：

• docker://example/buildpack

• docker:///example/buildpack:latest

• docker:///example/buildpack@sha256:45b23dee08…​

• example/buildpack

• example/buildpack:latest

• example/buildpack@sha256:45b23dee08…​

镜像发布

通过启用 publish 选项，可以将生成的镜像发布到 Docker registry。

如果 Docker registry 需要身份验证，可以使用 docker.publishRegistry 参数配置凭据。如果 Docker registry 不需要身份验证，则可以省略 docker.publishRegistry 配置。

备注

镜像将被发布到的 registry 由镜像名称中的 registry 部分决定（在这些示例中为 docker.example.com）。如果配置了 docker.publishRegistry 凭据并包含 url 参数，该值会传递给 registry，但不会用于确定发布 registry 的位置。

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<name>docker.example.com/library/${project.artifactId}</name>
						<publish>true</publish>
					</image>
					<docker>
						<publishRegistry>
							<username>user</username>
							<password>secret</password>
						</publishRegistry>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

publish 选项也可以在命令行中指定，如以下示例所示：

$ mvn spring-boot:build-image -Dspring-boot.build-image.imageName=docker.example.com/library/my-app:v1 -Dspring-boot.build-image.publish=true

在命令行中使用 publish 选项并进行身份验证时，可以像下面这个示例一样，通过属性提供凭据：

$ mvn spring-boot:build-image \
      -Ddocker.publishRegistry.username=user \
      -Ddocker.publishRegistry.password=secret \
      -Ddocker.publishRegistry.url=docker.example.com \
      -Dspring-boot.build-image.publish=true \
      -Dspring-boot.build-image.imageName=docker.example.com/library/my-app:v1

并在 XML 配置中引用这些属性：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<publishRegistry>
							<url>${docker.publishRegistry.url}</url>
							<username>${docker.publishRegistry.username}</username>
							<password>${docker.publishRegistry.password}</password>
						</publishRegistry>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

构建器缓存与工作区配置

CNB 构建器会缓存构建和启动镜像时使用的层。默认情况下，这些缓存以命名卷的形式存储在 Docker 守护进程中，其名称由目标镜像的完整名称派生而来。如果镜像名称频繁更改（例如，当项目版本被用作镜像名称中的标签时），则缓存可能会频繁失效。

缓存卷可以配置为使用替代名称，以提供对缓存生命周期的更多控制，如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<buildCache>
							<volume>
								<name>cache-${project.artifactId}.build</name>
							</volume>
						</buildCache>
						<launchCache>
							<volume>
								<name>cache-${project.artifactId}.launch</name>
							</volume>
						</launchCache>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

构建器（Builders）和 buildpacks 在构建镜像时需要一个位置来存储临时文件。默认情况下，这个临时构建工作区存储在一个命名卷（named volume）中。

缓存和构建工作区可以配置为使用绑定挂载（bind mounts）而非命名卷（named volumes），如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<buildWorkspace>
							<bind>
								<source>/tmp/cache-${project.artifactId}.work</source>
							</bind>
						</buildWorkspace>
						<buildCache>
							<bind>
								<source>/tmp/cache-${project.artifactId}.build</source>
							</bind>
						</buildCache>
						<launchCache>
							<bind>
								<source>/tmp/cache-${project.artifactId}.launch</source>
							</bind>
						</launchCache>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Docker 配置

minikube 的 Docker 配置

该插件可以与 minikube 提供的 Docker daemon 通信，而不是使用默认的本地连接。

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

该插件也可以通过提供类似以下示例所示的连接详细信息，配置为使用 minikube daemon：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<host>tcp://192.168.99.100:2376</host>
						<tlsVerify>true</tlsVerify>
						<certPath>/home/user/.minikube/certs</certPath>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Podman 的 Docker 配置

该插件可以与 podman 容器引擎 通信。

该插件可以通过提供类似以下示例所示的连接详细信息，配置为使用 podman 本地连接：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<host>unix:///run/user/1000/podman/podman.sock</host>
						<bindHostToBuilder>true</bindHostToBuilder>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

提示

安装了 colima CLI 后，可以使用命令 podman info --format='{{.Host.RemoteSocket.Path}}' 来获取本示例中 docker.host 配置属性的值。

Colima 的 Docker 配置

该插件可以与 Colima 提供的 Docker daemon 通信。可以通过以下命令设置 DOCKER_HOST 环境变量：

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

该插件也可以通过提供类似以下示例所示的连接详细信息，配置为使用 Colima 守护进程：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<host>unix:///${user.home}/.colima/docker.sock</host>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

用于身份验证的 Docker 配置

如果 builder 镜像或 run 镜像存储在支持用户身份验证的私有 Docker registry 中，则可以使用 docker.builderRegistry 参数提供身份验证详细信息，如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<builderRegistry>
							<username>user</username>
							<password>secret</password>
							<url>https://docker.example.com/v1/</url>
							<email>user@example.com</email>
						</builderRegistry>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

如果构建器镜像或运行镜像存储在支持令牌认证的私有 Docker registry 中，则可以使用 docker.builderRegistry 参数提供令牌值，如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<builderRegistry>
							<token>9cbaf023786cd7...</token>
						</builderRegistry>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>