打包 OCI 镜像
| 出于安全原因，镜像构建和运行为非 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>
在将目标绑定到包生命周期时，使用build-image-no-fork。此目标类似于build-image，但不会分叉生命周期以确保package已运行。在本节的其余部分，build-image用于指代build-image或build-image-no-fork目标。
|
虽然构建包从可执行存档运行，但无需先执行repackage目标，因为可执行存档会在必要时自动创建。当build-image重新打包应用程序时，它会应用与repackage目标相同的设置，即可以使用其中一个排除选项来排除依赖项。默认情况下，spring-boot-devtools和spring-boot-docker-compose模块会自动排除（可以使用excludeDevtools和excludeDockerCompose属性控制此行为）。
|
Docker守护进程
build-image目标需要访问Docker守护进程。该目标将检查本地Docker CLI 配置文件以确定当前上下文，并使用上下文连接信息与Docker守护进程通信。如果无法确定当前上下文或上下文没有连接信息，则该目标将使用默认的本地连接。这适用于所有受支持平台上的Docker Engine，无需配置。
可以设置环境变量来配置build-image目标以使用备用本地或远程连接。下表显示了环境变量及其值
| 环境变量 | 描述 |
|---|---|
DOCKER_CONFIG |
用于确定当前上下文的Docker CLI 配置文件的位置（默认为 |
DOCKER_CONTEXT |
应使用以从Docker CLI配置文件中检索主机信息的上下文的名称（覆盖 |
DOCKER_HOST |
包含Docker守护进程的主机和端口的URL - 例如 |
DOCKER_TLS_VERIFY |
设置为 |
DOCKER_CERT_PATH |
HTTPS 证书和密钥文件路径（如果 |
Docker 守护进程连接信息也可以通过插件配置中的 docker 参数提供。下表总结了可用的参数
| 参数 | 描述 |
|---|---|
|
|
|
包含Docker守护进程的主机和端口的URL - 例如 |
|
设置为 |
|
HTTPS 证书和密钥文件路径（如果 |
|
当 |
有关更多详细信息，请参阅 示例。
Docker 仓库
如果 builder 或 runImage 参数指定的 Docker 镜像存储在需要身份验证的私有 Docker 镜像仓库中，则可以使用 docker.builderRegistry 参数提供身份验证凭据。
如果生成的 Docker 镜像要发布到 Docker 镜像仓库，则可以使用 docker.publishRegistry 参数提供身份验证凭据。
参数用于用户身份验证或身份令牌身份验证。请参阅用于存储镜像的 Docker 仓库的文档，以获取有关支持的身份验证方法的更多信息。
下表总结了 docker.builderRegistry 和 docker.publishRegistry 的可用参数
| 参数 | 描述 |
|---|---|
|
Docker 镜像仓库用户的用户名。用户身份验证需要。 |
|
Docker 镜像仓库用户的密码。用户身份验证需要。 |
|
Docker 镜像仓库的地址。用户身份验证可选。 |
|
Docker 镜像仓库用户的电子邮件地址。用户身份验证可选。 |
|
Docker 镜像仓库用户的身份令牌。令牌身份验证需要。 |
有关更多详细信息，请参阅 示例。
镜像自定义
image 参数允许配置构建器及其在项目上的操作方式。下表总结了可用参数及其默认值
| 参数 / (用户属性) | 描述 | 默认值 |
|---|---|---|
|
要使用的构建器镜像的名称。 |
|
|
要使用的运行镜像的名称。 |
没有默认值，表示应使用构建器元数据中指定的运行镜像。 |
|
|
|
|
策略 用于确定何时从注册表中拉取构建器和运行镜像。可接受的值为 |
|
|
应传递给构建器的环境变量。 |
|
|
构建器在构建镜像时应使用的构建包。只有指定的构建包将被使用，覆盖构建器中包含的默认构建包。构建包引用必须采用以下形式之一
|
无，表示构建器应使用其中包含的构建包。 |
|
卷绑定挂载 应在构建镜像时挂载到构建器容器。绑定将在创建构建器容器时未解析且未验证地传递给 Docker。绑定必须采用以下形式之一
其中
|
|
|
构建器容器将配置为使用的 网络驱动程序。提供的 value 将在创建构建器容器时未经验证地传递给 Docker。 |
|
|
是否在构建之前清理缓存。 |
|
|
启用构建器操作的详细日志记录。 |
|
|
是否将生成的镜像发布到 Docker 仓库。 |
|
|
要应用于生成的镜像的一个或多个附加标签。提供给 |
|
|
构建器和构建包将在镜像构建过程中使用此临时工作区来存储文件。该值可以是命名卷或绑定挂载位置。 |
Docker 守护程序中的命名卷，其名称源自镜像名称。 |
|
包含构建包创建的层并用于镜像构建过程的缓存。该值可以是命名卷或绑定挂载位置。 |
Docker 守护程序中的命名卷，其名称源自镜像名称。 |
|
包含构建包创建的层并用于镜像启动过程的缓存。该值可以是命名卷或绑定挂载位置。 |
Docker 守护程序中的命名卷，其名称源自镜像名称。 |
|
用于设置生成的镜像元数据中 |
一个固定日期，它可以实现 构建可重复性。 |
|
应用程序内容将被上传到构建器镜像中的目录的路径。应用程序内容也将位于生成的镜像中的此位置。 |
|
|
将应用于构建器容器的 安全选项，以字符串值数组的形式提供 |
在 Linux 和 macOS 上为 |
该插件使用编译器的插件配置或maven.compiler.target属性检测项目的目标 Java 兼容性。当使用默认的 Paketo 构建器和构建包时，该插件会指示构建包安装相同的 Java 版本。您可以覆盖此行为，如构建器配置示例所示。
|
有关更多详细信息，另请参阅示例。
标签格式
提供给tags选项的值应为完整的镜像引用。接受的格式为[domainHost:port/][path/]name[:tag][@digest]。
如果缺少域，则默认为docker.io。如果缺少路径，则默认为library。如果缺少标签，则默认为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.3.0
使用构建包将应用程序打包到 OCI 镜像中，分叉生命周期以确保package已运行。此目标适合命令行调用。如果您需要在构建中配置目标execution，请改用build-image-no-fork。
参数详细信息
excludeDevtools
从重新打包的归档文件中排除 Spring Boot devtools。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
excludeDockerCompose
从重新打包的归档文件中排除 Spring Boot 开发服务。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
excludeGroupIds
要排除的 groupId 名称的逗号分隔列表（精确匹配）。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
excludes
要排除的工件定义集合。Exclude 元素定义了必需的 groupId 和 artifactId 组件，以及可选的 classifier 组件。当配置为属性时，值应以逗号分隔，并以冒号分隔组件：groupId:artifactId,groupId:artifactId:classifier
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
image
图像配置，包括 builder、runImage、name、env、cleanCache、verboseLogging、pullPolicy 和 publish 选项。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
includes
要包含的工件定义集合。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.3.0
使用构建包将应用程序打包到 OCI 镜像中，但不分叉生命周期。此目标应在配置构建中的目标execution时使用。要在命令行上调用目标，请使用build-image。
参数详细信息
excludeDevtools
从重新打包的归档文件中排除 Spring Boot devtools。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
excludeDockerCompose
从重新打包的归档文件中排除 Spring Boot 开发服务。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
excludeGroupIds
要排除的 groupId 名称的逗号分隔列表（精确匹配）。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
excludes
要排除的工件定义集合。Exclude 元素定义了必需的 groupId 和 artifactId 组件，以及可选的 classifier 组件。当配置为属性时，值应以逗号分隔，并以冒号分隔组件：groupId:artifactId,groupId:artifactId:classifier
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
image
图像配置，包括 builder、runImage、name、env、cleanCache、verboseLogging、pullPolicy 和 publish 选项。
名称 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
自 |
|
includes
要包含的工件定义集合。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属性设置这些选项。
以下是如何在构建时配置 Paketo Java 构建包使用的 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>如果 Docker 守护程序与构建包下载工件的网络位置之间存在网络代理，则需要配置构建器以使用代理。当使用 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 构建包通过设置JAVA_TOOL_OPTIONS环境变量来配置 JVM 运行时环境。当应用程序镜像在容器中启动时，可以修改构建包提供的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 构建器中的构建包（如果构建器中只有一个与 `buildpack-id` 匹配的构建包，则可以省略版本）
-
urn:cnb:builder:buildpack-id -
urn:cnb:builder:[email protected] -
buildpack-id
指向包含构建包内容的目录的路径（在 Windows 上不支持）
-
file:///path/to/buildpack/ -
/path/to/buildpack/
指向包含构建包内容的压缩 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 守护程序中，其名称源自目标镜像的完整名称。如果镜像名称经常更改，例如当项目版本用作镜像名称中的标签时，则缓存可能会频繁失效。
可以配置缓存卷以使用备用名称，以便更好地控制缓存生命周期，如下例所示
<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 守护程序 通信，而不是默认的本地连接。
在 Linux 和 macOS 上，可以在 minikube 启动后使用命令 eval $(minikube docker-env) 设置环境变量。
该插件还可以配置为使用 minikube 守护程序，方法是提供类似于以下示例中所示的连接详细信息
<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 守护程序通信。可以使用命令 export DOCKER_HOST=$(docker context inspect colima -f '{{.Endpoints.docker.Host}}'). 设置 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 身份验证配置
如果构建器或运行镜像存储在支持用户身份验证的私有 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>
