打包 OCI 镜像

DeepSeek V3 中英对照 Packaging OCI Images

打包 OCI 镜像

• Docker 守护进程
• Docker 仓库
• 镜像定制
• 标签格式
• spring-boot:build-image
• 必填参数
• 可选参数
• 参数详情
• spring-boot:build-image-no-fork
• 必填参数
• 可选参数
• 参数详情
• 示例
• 自定义镜像构建器
• 构建器配置
• 运行时 JVM 配置
• 自定义镜像名称
• Buildpacks
• 镜像发布
• 构建器缓存和工作区配置
• Docker 配置

该插件可以使用 Cloud Native Buildpacks (CNB) 从 jar 或 war 文件创建一个 OCI 镜像。可以通过命令行使用 build-image 目标来构建镜像。这确保了在创建镜像之前，包的构建生命周期已经运行。

备注

出于安全考虑，镜像构建和运行时会以非 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>

xml

备注

在将目标绑定到包生命周期时，请使用 build-image-no-fork。该目标与 build-image 类似，但不会 fork 生命周期以确保 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 配置文件 的位置，用于确定当前上下文（默认为 $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 守护进程的连接信息也可以通过插件配置中的 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 注册表

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

如果要生成的 Docker 镜像发布到 Docker 镜像注册表，可以使用 docker.publishRegistry 参数提供认证凭据。

提供了用户身份验证或身份令牌验证的参数。有关支持的认证方法的更多信息，请查阅用于存储镜像的 Docker 注册表的文档。

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

参数	描述
username	Docker 镜像仓库用户的用户名。用于用户身份验证，必填。
password	Docker 镜像仓库用户的密码。用于用户身份验证，必填。
url	Docker 镜像仓库的地址。用于用户身份验证，选填。
email	Docker 镜像仓库用户的电子邮件地址。用于用户身份验证，选填。
token	Docker 镜像仓库用户的身份令牌。用于令牌身份验证，必填。

更多详情，请参见 示例。

图片自定义

该插件调用一个 builder 来协调生成镜像的过程。构建器包含多个 buildpacks，这些构建包可以检查应用程序以影响生成的镜像。默认情况下，插件会选择构建器镜像。生成的镜像名称是从项目属性中推断出来的。

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

参数 / （用户属性）	描述	默认值
builder (spring-boot.build-image.builder)	要使用的构建器镜像的名称。	paketobuildpacks/builder-jammy-java-tiny:latest
trustBuilder (spring-boot.build-image.trustBuilder)	是否将构建器视为受信任的构建器。	true if the builder is one of paketobuildpacks/builder-jammy-java-tiny, paketobuildpacks/builder-noble-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)	所拉取的任何构建器、运行和构建包镜像的平台（操作系统和架构）。必须以 OS[/architecture[/variant]] 的形式表示，例如 linux/amd64、linux/arm64 或 linux/arm/v5。请参考所使用的构建器文档，以确定可用的镜像操作系统和架构选项。	无默认值，表示应使用宿主机的平台。
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)	策略用于确定何时从注册表中拉取构建器和运行镜像。可接受的值为 ALWAYS、NEVER 和 IF_NOT_PRESENT。	ALWAYS
env	应传递给构建器的环境变量。
buildpacks	构建镜像时，构建器应使用的 Buildpacks。仅会使用指定的 Buildpacks，覆盖构建器中默认包含的 Buildpacks。Buildpack 引用必须采用以下形式之一：

• 构建器中的 Buildpack - [urn:cnb:builder:]<buildpack ID>[@<version>]
  例如：urn:cnb:builder:example-buildpack@1.0.0

• 文件系统中目录中的 Buildpack - [file://]<path>
  例如：file:///path/to/buildpack

• 文件系统中 gzip 压缩的 tar 文件 (.tgz) 中的 Buildpack - [file://]<path>/<file name>
  例如：file:///path/to/buildpack.tgz

• OCI 镜像中的 Buildpack - [docker://]<host>/<repo>[:<tag>][@<digest>]
  例如：docker://example.com/repo:latest 或 docker://example.com/repo@sha256:abc123...| 无，表示构建器应使用其中包含的构建包。 |
  | bindings| 在构建镜像时，应该挂载到构建器容器的卷绑定挂载。这些绑定在创建构建器容器时将未经解析和验证直接传递给 Docker。绑定必须符合以下形式之一：

• <主机源路径>:<容器目标路径>[:<选项>]

• <主机卷名称>:<容器目标路径>[:<选项>]

其中 <选项> 可以包含：

• 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 仓库。| false |
  | tags| 要应用于生成图像的一个或多个附加标签。提供给 tags 选项的值应为完整的图像引用。有关更多详细信息，请参见标签部分。| |
  | buildWorkspace| 构建器和构建包在镜像构建过程中用于存储文件的临时工作区。该值可以是一个命名卷或绑定挂载位置。| 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 构建器和构建包时，插件会指示构建包安装相同的 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.4.2

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

必填参数

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

可选参数

名称	类型	默认值
classifier	String
docker	[Docker](https://docs.spring.io/spring-boot/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/maven-plugin/api/java/org/springframework/boot/maven/Image.html)
includeSystemScope	boolean	false
includeTools	boolean	true
includes	List
layers	[Layers](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)
layout	[LayoutType](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)
layoutFactory	[LayoutFactory](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)
loaderImplementation	[LoaderImplementation](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/loader/tools/LoaderImplementation.html)
mainClass	String
skip	boolean	false

参数详情

classifier

查找源存档时使用的分类器。

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

docker

Docker 配置选项。

名称	docker
类型	[org.springframework.boot.maven.Docker](https://docs.spring.io/spring-boot/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/maven-plugin/api/java/org/springframework/boot/maven/Image.html)
默认值
用户属性
自版本	2.3.0

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/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/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/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)
默认值
用户属性
自版本	2.3.11

loaderImplementation

应该使用的加载器实现。

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

mainClass

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

名称	mainClass
类型	java.lang.String
默认值
用户属性
自版本	1.0.0

skip

跳过执行。

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

sourceDirectory

包含源存档的目录。

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

spring-boot:build-image-no-fork

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

使用构建包将应用程序打包成 OCI 镜像，但不分叉生命周期。在配置构建中的目标 execution 时应使用此目标。要在命令行中调用该目标，请使用 build-image 替代。

必需参数

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

可选参数

名称	类型	默认值
classifier	String
docker	[Docker](https://docs.spring.io/spring-boot/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/maven-plugin/api/java/org/springframework/boot/maven/Image.html)
includeSystemScope	boolean	false
includeTools	boolean	true
includes	List
layers	[Layers](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)
layout	[LayoutType](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)
layoutFactory	[LayoutFactory](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)
loaderImplementation	[LoaderImplementation](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/loader/tools/LoaderImplementation.html)
mainClass	String
skip	boolean	false

参数详情

classifier

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

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

docker

Docker 配置选项。

名称	docker
类型	[org.springframework.boot.maven.Docker](https://docs.spring.io/spring-boot/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

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

名称	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/maven-plugin/api/java/org/springframework/boot/maven/Image.html)
默认值
用户属性
起始版本	2.3.0

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/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/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/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)
默认值
用户属性
自版本	2.3.11

loaderImplementation

应使用的加载器实现。

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

mainClass

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

名称	mainClass
类型	java.lang.String
默认值
用户属性
自版本	1.0.0

skip

跳过执行。

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

sourceDirectory

包含源归档文件的目录。

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

示例

自定义镜像构建

如果需要自定义用于创建镜像的构建器或用于启动构建镜像的运行镜像，请按以下示例配置插件：

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

xml

此配置将使用构建器镜像 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

shell

Builder 配置

如果构建器使用环境变量来暴露配置选项，那么可以使用 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>

xml

如果 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>

xml

运行时 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>

xml

自定义镜像名称

默认情况下，镜像名称是从项目的 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>

xml

备注

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

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

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

shell

Buildpacks 构建包

默认情况下，构建器将使用构建器镜像中包含的构建包，并按照预定义的顺序应用它们。可以提供一个替代的构建包集，以应用未包含在构建器中的构建包，或者更改包含的构建包的顺序。当提供一个或多个构建包时，仅会应用指定的构建包。

以下示例指示构建器使用打包在 .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>

xml

Buildpacks 可以以下面所示的任何形式进行指定。

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

• urn:cnb:builder:buildpack-id

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

• buildpack-id

• buildpack-id@0.0.1

一个包含构建包内容的目录路径（Windows 上不支持）：

• file:///路径/到/buildpack/

• /路径/到/buildpack/

一个包含构建包内容的 gzip 压缩 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>

xml

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

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

shell

在使用命令行中的 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

shell

并在 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>

xml

构建器缓存与工作区配置

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>

xml

构建器和构建包需要一个位置来存储镜像构建过程中的临时文件。默认情况下，这个临时的构建工作空间存储在一个命名卷中。

缓存和构建工作区可以配置为使用绑定挂载（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>

xml

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>

xml

Docker 配置用于 podman

该插件可以与 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>

xml

提示

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

Colima 的 Docker 配置

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

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

shell

该插件也可以通过提供类似于以下示例中的连接细节来配置使用 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>

xml

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>user@example.com</email>
                        </builderRegistry>
                    </docker>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

xml

如果构建器或运行镜像存储在支持令牌认证的私有 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>

xml