jpack-maven-plugin

这是一个用于对 SpringBoot 服务打包为 Windows、Linux 和 Docker 下可发布部署包的 Maven 插件。参考示例项目（jpack-demo）。

一、特性

• 简单易用，基于约定优于配置的思想来构建部署包
• 支持打包为 Windows、 Linux 和 Docker 下的发布部署包，也可单独选择打某些平台下的部署包
• Windows部署包可以安装为服务，从 Windows 的服务界面中来启动和停止应用服务，且默认为开机自启动
• 支持 Docker 的镜像构建、导出镜像 tgz 包和推送镜像到远程仓库或远程私有仓库等功能
• 支持 Helm Chart 的打包、推送和连带镜像一起导出 tgz 包的功能
• jpack 内部默认提供了一个简单通用的 Dockerfile 来构建 SpringBoot 服务的镜像，也支持自定义 Dockerfile 来构建镜像
• 可自定义复制文件资源到部署包中，例如通常发布时需要的：数据库脚本、文档说明等
• 可自定义排除不需要的文件资源被打包到部署包中，例如默认生成的文件目录资源你可以选择性排除掉

二、集成本插件

我将以一个新建的 SpringBoot 2.3.1.RELEASE 的 web 项目 jpack-demo，版本 1.0.0 作为示例，来做介绍。

1. 最简示例

首先，在项目的 Maven pom.xml 的 build -> plugins 节点中加入 jpack-maven-plugin 的插件配置：

<build>
    <plugins>

        <plugin>
            <groupId>com.blinkfox</groupId>
            <artifactId>jpack-maven-plugin</artifactId>
            <version>1.5.1</version>
        </plugin>
    </plugins>
</build>

然后，执行如下 jpack 命令：

mvn clean package jpack:build

注：jpack 须要有 Maven 打包的 jar 包，才能来生成用于发布的各平台的部署包，所以至少须要执行 package 阶段的命令。

然后，执行成功之后，你将在 Maven 控制台看到如下输出：

[INFO] ---------------------------------- jpack start packing... ---------------------------------
                                   __                          __
                                  |__|______  _____     ____  |  | __
                                  |  |\____ \ \__  \  _/ ___\ |  |/ /
                                  |  ||  |_> > / __ \_\  \___ |    <
                              /\__|  ||   __/ (____  / \___  >|__|_ \
                              \______||__|         \/      \/      \/ v1.5.1

[INFO] 【Chart构建 -> 跳过】没有配置【<helmChart>】的构建目标【<goals>】，将跳过 HelmChart 相关的构建.
[INFO] 【构建打包 -> 成功】制作 linux 下的部署压缩包完成.
[INFO] 【构建打包 -> 成功】制作 windows 下的部署压缩包完成.
[INFO] 【构建镜像 -> 默认】将使用 jpack 默认提供的 Dockerfile 文件来构建镜像.
[INFO] 【构建镜像 -> 进行】正在构建【com.blinkfox/jpack-demo:1.0.0】镜像...

[INFO] 【构建镜像 -> 成功】构建【com.blinkfox/jpack-demo:1.0.0】镜像完毕，镜像ID: d761303ae702
[INFO] --------------------- jpack has been packaged to end. [costs: 6.57 s] ---------------------

成功之后就可以在 target 目录中看到 jpack 的文件夹，jpack 文件夹中就包含了对应各个平台下的可部署服务包, Docker 下的包除外，因为 Docker 构建不做额外配置的话，默认只是构建镜像，想要推送镜像到远程仓库或者可导入的离线镜像部署包，可以参看下面的介绍。

• jpack-demo-1.0.0.zip: Windows 下的服务部署包
• jpack-demo-1.0.0.tar.gz: Linux 下的服务部署包
• jpack-demo-1.0.0-docker.tar.gz: Docker 下的可离线导入的部署包（此时应该没有这个包）
• jpack-demo-1.0.0-helmChart.tgz: HelmChart 下的可离线导入的应用包，包括了 Chart 包和 Docker 镜像包（此时应该没有这个包）

注：如果你的执行环境中没有安装 Docker、没有开启 Docker 或者 Docker 无根执行权限，将默认跳过 Docker 的构建环节。如果有 Docker 环境，且不做额外配置的话，将默认构建 docker 镜像，不会导出和推送 Docker 镜像。如果检测到没有 Helm 环境或者没有配置 HelmChart 的相关信息，默认也会跳过，不做任何构建。

构建成功之后，可以在 docker 中键入 docker images 命令，将看到构建的 docker 镜像：

REPOSITORY                     TAG                 IMAGE ID            CREATED               SIZE
com.blinkfox/jpack-demo        1.0.0               c8f91718f286        About a minute ago    123MB
openjdk                        8-jdk-alpine        a3562aa0b991        6 days ago            105MB
...

2. 另一种简单配置

你也可以在 jpack 的插件中配置执行的阶段，就不用再手动输入 jpack:build 的命令了，配置如下：

<build>
    <plugins>

        <plugin>
            <groupId>com.blinkfox</groupId>
            <artifactId>jpack-maven-plugin</artifactId>
            ...
            <executions>
                <execution>
                    <goals>
                        <goal>build</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

然后只需输入 mvn package 命令，jpack 就可以构建执行了。

3. 自定义构建阶段

只需要在 <execution> 中写上 <phase> 标签即可，阶段必须是 package 或 package 之后的 Maven 构建阶段，以下以 install 阶段为例：

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    ...
    <executions>
        <execution>
            <goals>
                <goal>build</goal>
            </goals>
            <phase>install</phase>
        </execution>
    </executions>
</plugin>

然后，只需输入 mvn install 命令，jpack 就可以构建执行了。

三、各平台包结构介绍

1. Windows

生成的 Windows 下的 jpack-demo-1.0.0.zip 包，解压之后的文件结构说明：

• bin: 存放可执行脚本的目录
• install.bat: 安装为 windows 服务的可执行脚本
• uninstall.bat: 卸载本 windows 服务的可执行脚本
• start.bat: 启动服务的可执行脚本
• stop.bat: 停止服务的可执行脚本
• restart.bat: 重启服务的可执行脚本
• status.bat: 查看服务运行状态的可执行脚本
• jpack-demo-1.0.0.exe: 可执行的二进制文件，可不用管
• jpack-demo-1.0.0.exe.config: 也可不用管
• jpack-demo-1.0.0.xml: 服务执行相关的配置文件，一般情况下不需要修改
• config: 存放 application.yml 等配置文件的目录（可自定义复制配置文件到此目录，方便部署时按需修改，SpringBoot 启动时会自动读取）
• docs: 存放文档的目录（可自定义复制文档到此目录，方便部署时查阅文档）
• logs: 存放日志的目录（建议 SpringBoot 的日志存放到 jar 包同级的 logs 目录中）
• jpack-demo-1.0.0.jar: 可执行的 jar 文件
• README.md: 主入口说明文件

注意事项：

• 6 个 .bat 可执行脚本，请以管理员的身份运行；
• 请先执行 install.bat 来安装为 windows 服务，安装服务只需要执行一次即可，以后就可以通过 Windows 服务界面来启动了，且默认是开机自启动；
• bin 目录下的文件不要移动，各文件的文件名无特殊情况也不要修改；
• 命令运行时，可能会提示安装 .NET, 安装完成就可运行命令了，不过现在大部分的 Windows 服务器或者个人电脑都会默认安装了 .NET, 没有的话启用一下就好了;

2. Linux

生成的 Linux 下的 jpack-demo-1.0.0.tar.gz 包，解压之后的文件结构说明：

• bin: 存放可执行脚本的目录
• start.sh: 启动服务的 shell 脚本
• stop.sh: 停止服务的 shell 脚本
• restart.sh: 重启服务的 shell 脚本
• status.sh: 查看服务运行状态的 shell 脚本
• config: 存放 application.yml 等配置文件的目录（可自定义复制配置文件到此目录，方便部署时按需修改，SpringBoot 启动时会自动读取）
• docs: 存放文档的目录（可自定义复制文档到此目录，方便部署时查阅文档）
• logs: 存放日志的目录（建议 SpringBoot 的日志存放到 jar 包同级的 logs 目录中）
• jpack-demo-1.0.0.jar: 可执行的 jar 文件
• README.md: 主入口说明文件

注意事项：

• 各个可执行脚本请以 bash 命令来执行，如：bash start.sh，或者对 bin 目录添加可执行权限（chmod -R 755 bin），然后执行 ./start.sh 即可。

3. Docker

如果不做任何配置的话，默认只是构建最新的 Docker 镜像，而不会生成部署需要的 .tgz 包和相关资源文件。你需要做下 docker 的额外导出 (save) 配置即可在执行 mvn package 之后生成 docker 的 .tar.gz 包，该包中包含了可导入Docker 的离线镜像 .tgz 包和其他你配置的资源。

<build>
    <plugins>

        <plugin>
            <groupId>com.blinkfox</groupId>
            <artifactId>jpack-maven-plugin</artifactId>
            <version>1.5.1</version>
            <executions>
                <execution>
                    <goals>
                        <goal>build</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <docker>
                    <extraGoals>

                        <param>save</param>
                    </extraGoals>
                </docker>
            </configuration>
        </plugin>
    </plugins>
</build>

Maven 构建成功之后，就可以在 jpack 目录中看到一个 jpack-demo-1.0.0-docker.tar.gz 的压缩包，即为 docker 的离线导入相关的资源包。该包解压之后的文件结构说明：

• config: 存放 application.yml 等配置文件的目录（可自定义复制配置文件到此目录，生成该目录与 Windows 或 Linux 下的目的不同，主要是为了方便部署时查阅配置信息，了解系统环境和参数配置，辅助运维人员配置 Docker 的环境变量等，让配置有据可查。）
• docs: 存放文档的目录（可自定义复制文档到此目录，方便部署时查阅文档）
• jpack-demo-1.0.0.tgz: 可导入 Docker 的离线镜像包，主要使用此包来导入到 Docker 中
• Dockerfile: 用于构建镜像的源 Dockerfile 文件（可以再自定义修改，用于二次构建）
• jpack-demo-1.0.0.jar: 用于构建镜像的源 jar 包（可以用于二次构建）
• README.md: 主入口说明文件

注意事项：

• 使用 docker load < jpack-demo-1.0.0.tar 命令来将本离线镜像包导入到 Docker 中；
• Dockerfile 和 jpack-demo-1.0.0.jar 让开发者或部署人员，可以根据自己的需要再做自定义修改，构建出符合自己需要的新镜像；

命令参考：

使用以下命令是用来启动镜像的，仅供参考：

简单的方式：

docker run -d -p 8080:8080 com.blinkfox/jpack-demo:1.0.0

稍等一会儿，访问 http://127.0.0.1:8080 即可访问服务。

带参数的方式：

以下以修改服务端口的示例来演示，修改 SpringBoot 的参数示例，实际上，你可以再 PROGRAM_ARGS 中写更多的参数，这些参数以 -- 开头即可，每个参数用空格隔开。

docker run -d -p 7070:7070 -e JVM_OPTS="-Xms512m -Xmx1024m" -e PROGRAM_ARGS="--server.port=7070" com.blinkfox/jpack-demo:1.0.0

稍等一会儿，访问 http://127.0.0.1:7070 即可访问服务。

4. Helm Chart

v1.5.0 版本开始新增了 Helm Chart 配置文件打包、推送和导出离线可部署包的功能。如果不做任何 Helm Chart 配置的话，默认会跳过这块儿的构建。要构建 Helm Chart，需要到这里下载安装 Helm 环境，类似于 Docker 环境。配置示例如下：

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    <configuration>
        <helmChart>

            <location>jpack-chart</location>

            <chartRepoUrl>http://registry.yourcompany.com:5000/api/chartrepo/blinkfox/charts</chartRepoUrl>

            <useDockerImage>true</useDockerImage>

            <goals>
                <param>package</param>
                <param>push</param>
                <param>save</param>
            </goals>

            <registryUser>
                <username>your-username</username>
                <password>your-password</password>
            </registryUser>
        </helmChart>
    </configuration>
</plugin>

• Helm Chart 的构建支持打包为 tgz 包，便于上传到 Harbor Registry 仓库中；
• 你也可以通过配置 chartRepoUrl 和 registryUser 来将 Chart 直接推送到 Harbor 远程仓库中；
• 也可以将 Chart 包和所需的镜像包一起打包，共通导出成离线应用包。

离线应用包内容结果如下：

• config: 存放 application.yml 等配置文件的目录，便于部署时参考和设置配置项；
• docs: 存放文档的目录（可自定义复制文档到此目录，方便部署和应用使用时查阅相关文档）
• jpack-demo-1.0.0.tgz: 打包后的 Chart 包。
• images.tgz: Chart 所需的离线镜像包，可以自定义导出多个镜像包为一个镜像包，也可以默认使用 jpack 自身构建的 Docker 镜像包。
• README.md: 主入口说明文件

四、jpack configuration 配置详解

jpack 的所有配置参数都非必填或者有默认值。以下是关于 jpack Maven 插件 configuration 下的配置信息介绍，供你参考。

1. platforms

用于配置打包时可以打包哪些平台的包。默认为 Windows、Linux 和 Dokcer 三个平台，如果打包的环境没有或没开启 Docker，则会自动忽略 Docker 下的构建及后续的打包等操作。这三个平台的值大小写均可。

示例如下：

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
        ...
    <configuration>

        <platforms>
            <param>Windows</param>
            <param>Linux</param>

        </platforms>
    </configuration>
</plugin>

2. vmOptions

用于配置 JVM 运行所需的参数选项，作用于各个平台下。默认为空，如果配置了对应的值，生成的部署包命令行中将会追加这些 JVM 选项参数。

示例如下：

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
        ...
    <configuration>

        <vmOptions>-Xms1024m -Xmx2048m</vmOptions>
    </configuration>
</plugin>

3. programArgs

用于配置 SpringBoot 运行所需的参数，作用于各个平台下。默认为空，如果配置了对应的值，生成的部署包命令行中将会追加这些程序运行参数。

注：不太建议使用此配置项来使参数生效，这是命令行级别的生效，不便于运维人员修改，容易出错，建议使用 configFiles 配置文件的方式。

示例如下：

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
       ...
    <configuration>

        <programArgs>--server.port=7070</programArgs>
    </configuration>
</plugin>

4. configFiles

用来复制诸如 application.yml 等类似的配置文件到部署包的 config 目录中。针对所有平台生效。默认为空，如果配置了对应的值，生成的部署包的 config 目录中将会有你复制的配置文件。该值只能配置一个，可以是相对于 pom.xml 的相对路径或绝对路径的目录或文件，也可以是网络资源。

注：强烈建议配置该值用来替代 programArgs，以便于在 Windows 或 Linux 下，直接让运维人员来修改配置文件的方式来使配置生效，而不是通过命令行参数的方式来修改配置。

示例如下：

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
       ...
    <configuration>

        <configFiles>
            <param>src/test/resources/application.yml</param>
            <param>src/test/resources/application-local.yml</param>
        </configFiles>
    </configuration>
</plugin>

5. skipError

遇到错误时是否跳过错误。默认是不填写或者 default，程序会自动处理，不需要你额外关注；true 的话，会忽略所有异常；false 的话，遇到错误就直接报错。

注：目前仅 Docker 下有用到此配置。

示例如下：

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
       ...
    <configuration>

        <skipError>default</skipError>
    </configuration>
</plugin>

6. cleanPackDir

表示执行打包命令是否清除之前生成的发布包数据，默认清除（true），可配置为 false。

7. copyResources

系统发布时，发布包中必然会有很多除了 xxx.jar 之外的其他文件，如：数据库脚本、配置文件、文档手册等等，这些也需要集成到发布包中。为了统一管理和维护，所以通过 copyResources 配置项，可以复制你项目中几乎所有你想要的目录、文件或者网络资源等到发布包及发布包里的自定义的目录中。

copyResources 可以包含多个 copyResource 子节点配置项，copyResource 中有 from 和 to 两个参数。用于表示从哪里复制到哪里。

• from: 复制的源。可以是相对于 pom.xml 的相对路径或绝对路径的本地资源，也可以是网络资源文件路径。from如果是本地路径时可以是目录也可以是文件。
• to: 需要复制到哪里。不填写或者填写.、/ 时表示的是复制到各平台包的根目录中。如果要填写就只能是目录，可以嵌套多级。如：abc/def，表示复制到abc目录下的 def 目录中，目录会自动创建。

示例如下：

```xml com.blinkfox jpack-maven-plugin ... <!-- 需要copy 哪些资源(from 的值可以是目录或者具体的相对、绝对或网络资源路径)到部署包中的某个目录;