打包 OCI 镜像
该插件可以通过使用 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 目标相同的设置，即可以使用 exclude 选项之一排除依赖项。默认情况下会自动排除 spring-boot-devtools 和 spring-boot-docker-compose 模块（可以使用 excludeDevtools 和 excludeDockerCompose 属性控制此行为）。 |
Docker Daemon
build-image 目标需要访问 Docker daemon。该目标将检查本地 Docker CLI 配置文件 以确定当前的 context 并使用 context 连接信息与 Docker daemon 通信。如果无法确定当前的 context 或 context 没有连接信息，则该目标将使用默认的本地连接。这适用于所有受支持平台上的 Docker Engine 无需配置。
可以设置环境变量来配置 build-image 目标以使用替代的本地或远程连接。下表显示了环境变量及其值：
| 环境变量 | 描述 |
|---|---|
DOCKER_CONFIG |
Docker CLI 配置文件 的位置，用于确定当前的 context（默认为 |
DOCKER_CONTEXT |
context 的名称，应使用此名称从 Docker CLI 配置文件中检索主机信息（覆盖 |
DOCKER_HOST |
包含 Docker daemon 的主机和端口的 URL，例如 |
DOCKER_TLS_VERIFY |
当设置为 |
DOCKER_CERT_PATH |
HTTPS 的证书和密钥文件路径（如果 |
Docker daemon 连接信息也可以使用插件配置中的 docker 参数提供。下表总结了可用的参数：
| 参数 | 描述 |
|---|---|
|
|
|
包含 Docker daemon 的主机和端口的 URL，例如 |
|
当设置为 |
|
HTTPS 的证书和密钥文件路径（如果 |
|
当 |
更多详情，请参阅 示例。
Docker Registry
如果通过 builder 或 runImage 参数指定的 Docker 镜像存储在需要认证的私有 Docker 镜像 registry 中，则可以使用 docker.builderRegistry 参数提供认证凭据。
如果生成的 Docker 镜像要发布到 Docker 镜像 registry 中，则可以使用 docker.publishRegistry 参数提供认证凭据。
为用户认证或身份令牌认证提供了参数。有关支持的认证方法的更多信息，请查阅用于存储镜像的 Docker registry 文档。
下表总结了 docker.builderRegistry 和 docker.publishRegistry 可用的参数：
| 参数 | 描述 |
|---|---|
|
Docker 镜像 registry 用户的用户名。用户认证所需。 |
|
Docker 镜像 registry 用户的密码。用户认证所需。 |
|
Docker 镜像 registry 的地址。用户认证可选。 |
|
Docker 镜像 registry 用户的电子邮件地址。用户认证可选。 |
|
Docker 镜像 registry 用户的身份令牌。令牌认证所需。 |
更多详情，请参阅 示例。
镜像定制
该插件会调用一个 builder 来协调镜像的生成。builder 包含多个 buildpacks ，它们可以检查应用程序以影响生成的镜像。默认情况下，插件会选择一个 builder 镜像。生成镜像的名称是从项目属性推断出来的。
image 参数允许配置 builder 以及它应如何在项目上运行。下表总结了可用的参数及其默认值：
| 参数 / (用户属性) | 描述 | 默认值 |
|---|---|---|
|
要使用的 builder 镜像名称。 |
|
|
是否将 builder 视为 trusted。 |
如果 builder 是以下之一则为 |
|
拉取的任何 builder、run 和 buildpack 镜像的平台（操作系统和架构）。必须采用 |
没有默认值，表示应使用主机平台的配置。 |
|
要使用的 run 镜像名称。 |
没有默认值，表示应使用 Builder 元数据中指定的 run 镜像。 |
|
镜像名称，用于生成的镜像。 |
|
|
策略，用于确定何时从 registry 拉取 builder 和 run 镜像。可接受的值为 |
|
|
应传递给 builder 的环境变量。 |
|
|
builder 在构建镜像时应使用的 buildpack。将仅使用指定的 buildpack，覆盖 builder 中包含的默认 buildpack。Buildpack 引用必须采用以下形式之一：
|
无，表示 builder 应使用其中包含的 buildpack。 |
|
卷绑定挂载，构建镜像时应挂载到 builder 容器的。在创建 builder 容器时，这些绑定将未经解析和验证直接传递给 Docker。绑定必须采用以下形式之一：
其中
|
|
|
builder 容器将配置使用的 network driver。提供的值在创建 builder 容器时将未经验证传递给 Docker。 |
|
|
是否在构建前清理缓存。 |
|
|
启用 builder 操作的详细日志记录。 |
|
|
是否将生成的镜像发布到 Docker registry。 |
|
|
要应用于生成镜像的一个或多个附加标签。提供给 |
|
|
builder 和 buildpack 在镜像构建期间用于存储文件的临时工作空间。该值可以是命名卷或绑定挂载位置。 |
Docker daemon 中的命名卷，名称源自镜像名称。 |
|
包含 buildpack 创建的层并在镜像构建过程中使用的缓存。该值可以是命名卷或绑定挂载位置。 |
Docker daemon 中的命名卷，名称源自镜像名称。 |
|
包含 buildpack 创建的层并在镜像启动过程中使用的缓存。该值可以是命名卷或绑定挂载位置。 |
Docker daemon 中的命名卷，名称源自镜像名称。 |
|
一个日期，将用于设置生成的镜像元数据中的 |
启用 构建可重现性 的固定日期。 |
|
应用程序内容将上传到 builder 镜像中该目录的路径。在生成的镜像中，应用程序内容也将位于此位置。 |
|
|
安全选项，将应用于 builder 容器的，作为字符串值数组提供： |
在 Linux 和 macOS 上为 |
插件使用编译器的插件配置或 maven.compiler.target 属性检测项目的目标 Java 兼容性。使用默认的 Paketo builder 和 buildpack 时，插件会指示 buildpack 安装相同的 Java 版本。你可以覆盖此行为，如 builder 配置 示例所示。 |
更多详情，请参阅 示例。
标签格式
提供给 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.4.5
使用 buildpack 将应用程序打包到 OCI 镜像中，会 fork 生命周期以确保 package 已运行。此目标适合在命令行调用。如果你需要在构建中配置一个 goal execution，请改用 build-image-no-fork。
可选参数
| 名称 | 类型 | 默认值 |
|---|---|---|
|
||
|
|
|
|
|
|
|
||
|
||
|
|
|
|
|
|
|
||
|
||
|
|
参数详情
excludeDevtools
从重新打包的归档文件中排除 Spring Boot devtools。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
excludeDockerCompose
从重新打包的归档文件中排除 Spring Boot dev services。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
excludeGroupIds
逗号分隔的要排除的 groupId 名称列表（精确匹配）。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
excludes
要排除的 artifact 定义集合。Exclude 元素定义了必需的 groupId 和 artifactId 组件以及可选的 classifier 组件。当配置为属性时，值应是逗号分隔的，其中组件使用冒号分隔：groupId:artifactId,groupId:artifactId:classifier
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
image
镜像配置，包含 builder, runImage, name, env, cleanCache, verboseLogging, pullPolicy, 和 publish 等选项。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
includes
要包含的 artifact 定义集合。Include 元素定义了必需的 groupId 和 artifactId 组件以及可选的 classifier 组件。当配置为属性时，值应是逗号分隔的，其中组件使用冒号分隔：groupId:artifactId,groupId:artifactId:classifier
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
layout
归档文件的类型（对应于依赖项在其中布局的方式）。可能的值为 JAR, WAR, ZIP, DIR, NONE。默认根据归档文件类型猜测。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
spring-boot:build-image-no-fork
org.springframework.boot:spring-boot-maven-plugin:3.4.5
使用 buildpack 将应用程序打包成 OCI 镜像，但无需 fork 生命周期。此目标应在构建中配置目标 execution 时使用。要在命令行上调用此目标，请改用 build-image。
可选参数
| 名称 | 类型 | 默认值 |
|---|---|---|
|
||
|
|
|
|
|
|
|
||
|
||
|
|
|
|
|
|
|
||
|
||
|
|
参数详情
excludeDevtools
从重新打包的归档文件中排除 Spring Boot devtools。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
excludeDockerCompose
从重新打包的归档文件中排除 Spring Boot dev services。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
excludeGroupIds
逗号分隔的要排除的 groupId 名称列表（精确匹配）。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
excludes
要排除的 artifact 定义集合。Exclude 元素定义了必需的 groupId 和 artifactId 组件以及可选的 classifier 组件。当配置为属性时，值应是逗号分隔的，其中组件使用冒号分隔：groupId:artifactId,groupId:artifactId:classifier
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
image
镜像配置，包含 builder, runImage, name, env, cleanCache, verboseLogging, pullPolicy, 和 publish 等选项。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
includes
要包含的 artifact 定义集合。Include 元素定义了必需的 groupId 和 artifactId 组件以及可选的 classifier 组件。当配置为属性时，值应是逗号分隔的，其中组件使用冒号分隔：groupId:artifactId,groupId:artifactId:classifier
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
layout
归档文件的类型（对应于依赖项在其中布局的方式）。可能的值为 JAR, WAR, ZIP, DIR, NONE。默认根据归档文件类型猜测。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
始于 |
|
示例
自定义镜像构建器
如果需要自定义用于创建镜像的构建器或用于启动已构建镜像的运行镜像，请按照以下示例配置插件
<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构建器配置
如果构建器通过环境变量暴露配置选项，可以使用 env 属性进行设置。
以下是配置 JVM 版本的示例，该版本由 Paketo Java buildpacks 在构建时使用
<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>如果在构建器运行的 Docker daemon 与 buildpacks 下载工件的网络位置之间存在网络代理，您需要配置构建器使用该代理。使用 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 buildpacks 通过设置 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构建包
默认情况下，构建器将使用构建器镜像中包含的构建包，并按照预定义的顺序应用它们。可以提供一组替代的构建包，以应用不包含在构建器中的构建包，或更改包含的构建包的顺序。当提供一个或多个构建包时，仅应用指定的构建包。
以下示例指示构建器使用打包在 .tgz 文件中的自定义构建包，然后使用构建器中包含的构建包。
<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>可以通过以下任何一种形式指定构建包。
CNB Builder 中的构建包（如果构建器中只有一个与 buildpack-id 匹配的构建包，则可以省略版本）
包含构建包内容的目录路径（Windows 上不支持）
-
file:///path/to/buildpack/ -
/path/to/buildpack/
包含构建包内容的 gzipped tar 文件路径
-
file:///path/to/buildpack.tgz -
/path/to/buildpack.tgz
包含打包的构建包的 OCI 镜像
-
docker://example/buildpack -
docker:///example/buildpack:latest -
docker:///example/buildpack@sha256:45b23dee08… -
example/buildpack -
example/buildpack:latest -
example/buildpack@sha256:45b23dee08…
镜像发布
可以通过启用 publish 选项将生成的镜像发布到 Docker 注册表。
如果 Docker 注册表需要身份验证，可以使用 docker.publishRegistry 参数配置凭据。如果 Docker 注册表不需要身份验证，则可以省略 docker.publishRegistry 配置。
镜像将发布到的注册表由镜像名称的注册表部分确定（在本例中为 docker.example.com）。如果配置了 docker.publishRegistry 凭据并包含 url 参数，此值将传递给注册表，但不用于确定发布注册表的位置。 |
<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 daemon 中，其名称派生自目标镜像的完整名称。如果镜像名称经常更改，例如在镜像名称中使用项目版本作为标签时，则缓存可能会频繁失效。
可以配置缓存卷使用替代名称，以更好地控制缓存生命周期，如下例所示
<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>构建器和构建包在镜像构建期间需要一个存储临时文件的位置。默认情况下，此临时构建工作空间存储在命名卷中。
可以将缓存和构建工作空间配置为使用绑定挂载而非命名卷，如下例所示
<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 配置
可以使用以下命令设置 DOCKER_HOST 环境变量
$ export DOCKER_HOST=$(docker context inspect colima -f '{{.Endpoints.docker.Host}}')也可以通过提供与以下示例中类似的连接详情，将插件配置为使用 Colima daemon
<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 身份验证配置
如果构建器或运行镜像存储在支持用户身份验证的私有 Docker 注册表中，可以使用 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>[email protected]</email>
</builderRegistry>
</docker>
</configuration>
</plugin>
</plugins>
</build>
</project>如果构建器或运行镜像存储在支持令牌身份验证的私有 Docker 注册表中，可以使用 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>
