Skip to content

Latest commit

 

History

History
878 lines (749 loc) · 48.7 KB

README.md

File metadata and controls

878 lines (749 loc) · 48.7 KB

jpack-maven-plugin

HitCount Build Status GitHub license codecov Java Version Maven Central Javadocs

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

一、特性

  • 专为 SpringBoot 服务和各个主流平台而设计的自动化 Maven 打包插件,基于约定优于配置的思想来构建各平台的部署包
  • 支持打包为 WindowsLinuxDocker 下的发布部署包,也可单独选择打某些平台下的部署包
  • 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.xmlbuild -> plugins 节点中加入 jpack-maven-plugin 的插件配置:

<build>
    <plugins>
        <!-- 引入 jpack-maven-plugin 插件 -->
        <plugin>
            <groupId>com.blinkfox</groupId>
            <artifactId>jpack-maven-plugin</artifactId>
            <version>1.5.5</version>
        </plugin>
    </plugins>
</build>

然后,执行如下 jpack 命令:

mvn clean package jpack:build

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

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

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

[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>
        <!-- 引入 jpack-maven-plugin 插件 -->
        <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> 标签即可,阶段必须是 packagepackage 之后的 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>
        <!-- 引入 jpack-maven-plugin 插件 -->
        <plugin>
            <groupId>com.blinkfox</groupId>
            <artifactId>jpack-maven-plugin</artifactId>
            <!-- 此处内容省略. -->
            <configuration>
                <docker>
                    <extraGoals>
                        <!-- 构建 docker 镜像之外的额外目标,可以填写 save 值.
                            save 表示导出镜像的离线包. -->
                        <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 中;
  • Dockerfilejpack-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>
            <!-- helm chart 源文件的目录位置,目前仅支持本地文件的绝对或相对路径. -->
            <location>jpack-chart</location>
            <!-- 要推送 helm chart 所在仓库的 API URL 地址. -->
            <chartRepoUrl>http://registry.yourcompany.com:5000/api/chartrepo/blinkfox/charts</chartRepoUrl>
            <!-- 该值表示 save 导出时,是否使用本插件 Docker 构建的镜像,将其也导出到最终的镜像包中,默认为 false. -->
            <useDockerImage>true</useDockerImage>
            <!-- 构建目标,这里设置了 chart 打包、推送和导出. -->
            <goals>
                <param>package</param>
                <param>push</param>
                <param>save</param>
            </goals>
            <!-- 推送 Chart 到 Harbor 中的 registry 用户密码信息,可以进行 AES 加密. -->
            <registryUser>
                <username>your-username</username>
                <password>your-password</password>
            </registryUser>
        </helmChart>
    </configuration>
</plugin>
  • Helm Chart 的构建支持打包为 tgz 包,便于上传到 Harbor Registry 仓库中;
  • 你也可以通过配置 chartRepoUrlregistryUser 来将 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>
        <!-- 打包哪些平台的包,不填写则代表所有平台. 目前支持 Windows、Linux 和 Dokcer 三个平台(大小写均可).
            这里作为示例,注释 Docker 的方式,就表明只打包 Windows 和 Linux 平台下的包。 -->
        <platforms>
            <param>Windows</param>
            <param>Linux</param>
            <!-- <param>Docker</param> -->
        </platforms>
    </configuration>
</plugin>

2. vmOptions

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

示例如下:

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    <!-- 此处内容省略. -->
    <configuration>
        <!-- JVM 运行所需的选项参数. -->
        <vmOptions>-Xms1024m -Xmx2048m</vmOptions>
    </configuration>
</plugin>

3. programArgs

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

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

示例如下:

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    <!-- 此处内容省略. -->
    <configuration>
        <!-- 所集成的 SpringBoot 服务程序运行所需的参数. -->
        <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>
        <!-- 需要复制到部署包中 config 目录下的 yml 或者 .properties 文件的配置文件路径,
            它的值可以配置多个,可以是相对路径、绝对路径具体的目录或文件,也可以是网络资源. -->
        <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>
        <!-- 遇到错误时是否跳过错误,目前仅Docker 下有用到此配置。默认是不填写或者 default,程序会自动处理,不需要你额外关注;
            true的话,会忽略所有异常;false的话,遇到错误就直接报错。 -->
        <skipError>default</skipError>
    </configuration>
</plugin>

6. cleanPackDir

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

7. generateBinDir

表示是否生成 Windows、Linux 下默认的 bin 目录及相关的可执行脚本文件,默认 true,即表示生成 jpack 自带 bin目录和文件。如果你配置为 false,将不会生成 jpack 自带的 bin 目录和相关的可执行文件,便于你自定义自己的可执行文件。

8. copyResources

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

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

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

示例如下:

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    <!-- 此处内容省略. -->
    <configuration>
        <!-- 需要copy 哪些资源(from 的值可以是目录或者具体的相对、绝对或网络资源路径)到部署包中的某个目录;
            to 的值只能是目录,为空或者 '.' 或者 '/' 符号则表示复制到各平台包的根目录中,否则就复制到具体的目录下 -->
        <copyResources>
            <!-- 复制本项目根目录的 README.md 到各平台包的根目录中. -->
            <copyResource>
                <from>README.md</from>
                <to>.</to>
            </copyResource>
            <!-- 复制本项目 docs 文件夾到各平台包的 docs 目录中. -->
            <copyResource>
                <from>docs</from>
                <to>docs</to>
            </copyResource>
            <!-- 复制本项目上层目录的 hello.pdf 文件到各平台包的 abc/def 目录中(会自动创建此目录). -->
            <copyResource>
                <from>../test-dir/hello.pdf</from>
                <to>abc/def</to>
            </copyResource>
            <!-- 复制网络资源 http://xxx.com/image.png 文件到各平台包的根目录中. -->
            <copyResource>
                <from>http://xxx.com/image.png</from>
                <to>/</to>
            </copyResource>
        </copyResources>
    </configuration>
</plugin>

9. excludeFiles

也需生成的可部署包中,某些文件资源对你而已,显得有些多余,你想排除它们。此时你可以使用 excludeFiles 来配置需要排除的文件或目录不会打包的部署包中,可以配置多个。

示例如下:

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    <!-- 此处内容省略. -->
    <configuration>
        <!-- 排除哪些文件或目录不需要打包进压缩包中,输入文件的相对路径即可. -->
        <excludeFiles>
            <param>logs</param>
            <param>README.md</param>
            <param>xxxxx.abc</param>
        </excludeFiles>
    </configuration>
</plugin>

10. windows

这是用于专门对 Windows 平台生效的配置项,主要包括前面提到的如下几个子配置项,用法同前面类似,不再赘述:

  • vmOptions: 针对 Windows 平台的 JVM 选项参数配置。如果你配置了这个值,那么在 Windows 下将会覆盖通用的 vmOptions 的值。
  • programArgs: 针对 Windows 平台的程序参数配置。如果你配置了这个值,那么在 Windows 下将会覆盖通用的 programArgs 的值。
  • generateBinDir: 针对 Windows 平台的是否生成 bin 目录及其下文件的配置。v1.5.4 版本新增,如果你配置了这个值,那么在 Windows 下将会覆盖通用的 generateBinDir 的值。
  • configFiles: 针对 Windows 平台的配置文件配置。如果你配置了这个值,那么在 Windows 下将会覆盖通用的 configFiles 的值。
  • copyResources: 针对 Windows 平台的资源复制。如果你配置了这个值,那么会额外复制这些资源到 Windows 平台的包中。
  • excludeFiles: 针对 Windows 平台的资源排除。如果你配置了这个值,那么会额外从 Windows 平台的包中排除这些资源。

示例如下:

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    <!-- 此处内容省略. -->
    <configuration>
        <!-- 以下是仅对 Windows 平台下生效的配置项。 -->
        <windows>
            <vmOptions>-Xms1024m -Xmx2048m</vmOptions>
            <programArgs>--server.port=7070</programArgs>
            <generateBinDir>true</generateBinDir>
            <configFiles>
                <param>src/test/resources/application.yml</param>
                <param>src/test/resources/application-dev.yml</param>
            </configFiles>
            <copyResources>
                <copyResource>
                    <from>README.pdf</from>
                    <to>.</to>
                </copyResource>
            </copyResources>
            <excludeFiles>
                <param>logs</param>
            </excludeFiles>
        </windows>
    </configuration>
</plugin>

11. linux

这是用于专门对 Linux 平台生效的配置项,主要包括前面提到的如下几个子配置项,用法同前面类似,不再赘述:

  • vmOptions: 针对 Linux 平台的 JVM 选项参数配置。如果你配置了这个值,那么在 Linux 下将会覆盖通用的 vmOptions 的值。
  • programArgs: 针对 Linux 平台的程序参数配置。如果你配置了这个值,那么在 Linux 下将会覆盖通用的 programArgs 的值。
  • generateBinDir: 针对 Linux 平台的是否生成 bin 目录及其下文件的配置。v1.5.4 版本新增,如果你配置了这个值,那么在 Linux 下将会覆盖通用的 generateBinDir 的值。
  • configFiles: 针对 Linux 平台的配置文件配置。如果你配置了这个值,那么在 Linux 下将会覆盖通用的 configFiles 的值。
  • copyResources: 针对 Linux 平台的资源复制。如果你配置了这个值,那么会额外复制这些资源到 Linux 平台的包中。
  • excludeFiles: 针对 Linux 平台的资源排除。如果你配置了这个值,那么会额外从 Linux 平台的包中排除这些资源。

示例同 Windows 下的类似。

12. docker

这是用于专门对 Docker 平台生效的配置项,主要包括前面提到的如下几个子配置项及Docker 平台下特有的一些配置项,用法同前面类似,不再赘述:

  • dockerfile: 构建 Docker 镜像的 Dockerfile 文件的相对路径,没有此配置项或者不填写,则使用 jpack 默认的 Dockerfile 文件.
  • registry: 远程仓库地址,不填写则默认为 Dockerhub。
  • repo: 构建镜像的仓库名,类似于 groupId,不填写则默认使用 groupId
  • name: 构建镜像的名称,类似于 artifactId,不填写则默认使用 artifactId
  • tag: 构建镜像的版本标签,不填写则默认使用 version
  • fromImage: Dockerfile 文件中 FROM 引用的基础镜像,如果没有配置该值,将默认使用 openjdk:8-jdk-alpine
  • expose: 对外暴露的端口,不配置该值,将不会在 Dockerfile 中生成 EXPOSE 指令。
  • volumes: 挂载的数据卷,不填写则默认挂载 "/tmp" 和 "/logs" 目录。
  • customCommands: 自定义的 Dockerfile 指令选项,可以填写多个值,每个值在 Dockerfile 中占一行,充当Dockerfile 中的一条指令。
  • extraGoals: 额外的构建目标,默认只是构建镜像,如果你需要配置导出镜像包可以再填写 save,推送到 Dockerhub 可以再填写 push
  • vmOptions: 针对 Docker 平台的 JVM 选项参数配置。如果你配置了这个值,那么在 Docker 下将会覆盖通用的 vmOptions 的值。
  • programArgs: 针对 Docker 平台的程序参数配置。如果你配置了这个值,那么在 Docker 下将会覆盖通用的 programArgs 的值。
  • configFiles: 针对 Docker 平台的配置文件配置。如果你配置了这个值,那么在 Docker 下将会覆盖通用的 configFiles 的值。
  • copyResources: 针对 Docker 平台的资源复制。如果你配置了这个值,那么会额外复制这些资源到 Docker 平台的包中。
  • excludeFiles: 针对 Docker 平台的资源排除。如果你配置了这个值,那么会额外从 Docker 平台的包中排除这些资源。
  • registryUserv1.4.0 版本新增,当镜像推送到私有权限限制的镜像仓库中时,可以填写如下用户权限认证信息。通常,至少需要填写用户名和密码。
    • username:registry 仓库的用户名。可以对用户名进行加密,只要将用户名以 ENCRYPT# 开头就表示是加过密的用户名,否则说明直接使用原文。
    • password:registry 仓库的密码。可以对密码进行加密,只要将文本内容以 ENCRYPT# 开头就表示是加过密的密码,否则说明直接使用原文密码。
    • email:用户的邮箱信息,非必填。
    • serverAddress:registry 仓库的服务地址,如果不填写就默认使用上面的 registry 地址,通常你不需要填写。
    • identityToken:Token 标识,通常你可以不用填写。

注:关于 registryUser 中的用户名或密码加密,你可以使用 jpack 中的 AesKit.encrypt("your-username"); 方法进行加密。该种加密并不安全,意在防君子,防不了小人。

示例如下:

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    <!-- 此处内容省略. -->
    <configuration>
        <!-- 以下是仅对 Docker 平台下生效的配置项。 -->
        <docker>
            <!-- 构建 Docker 镜像的 Dockerfile 文件的相对路径,没有此配置项或者不填写,则使用 jpack 默认的 Dockerfile 文件. -->
            <dockerfile>Dockerfile</dockerfile>
            <!-- 构建镜像的几个基础参数, registry远程仓库地址,不填写默认视为 Dockerhub 的地址;
                repo不填写则默认为 groupId,name 不填写则默认为 artifactId,tag不填写则默认为 version.-->
            <registry></registry>
            <repo>blinkfox</repo>
            <name>jpack-test</name>
            <tag>1.0.0-SNAPSHOT</tag>
            <!-- FROM 的镜像,如果没有配置该值,将默认是 openjdk:8-jdk-alpine. -->
            <fromImage>openjdk:8-jdk-alpine</fromImage>
            <!-- 对外暴露的端口,不配置该值,将不会在 Dockerfile 中生成 EXPOSE 指令. -->
            <expose>8080</expose>
            <!-- 挂载的数据卷,不填写则默认挂载 "/tmp" 和 "/logs" 目录. -->
            <volumes>
                <param>/tmp</param>
                <param>/logs</param>
            </volumes>
            <!-- 自定义的 Dockerfile 指令选项,可以填写多个值,每个值在 Dockerfile 中占一行,充当Dockerfile中的一条指令,例如:下面设置时区的一个指令. -->
            <customCommands>
                <param>RUN echo 'Asia/Shanghai' >/etc/timezone</param>
            </customCommands>
            <!-- jpack 的 Docker 构建的默认目标是构建镜像,如果你需要其他目标的话,可以在此配置).
                目前这里只支持导出镜像为 .tar 包(save). -->
            <!-- jpack 的 Docker 构建的默认目标是构建镜像,如果你需要其他目标的话,可以再此配置(可配多个).
                目前这里支持导出镜像为 .tar 包(save)和 推送镜像到远程仓库(push) 两种. -->
            <extraGoals>
                <param>save</param>
                <param>push</param>
            </extraGoals>
            <!-- jpack 推送到远程私有镜像仓库的用户权限认证信息,通常至少需要填写用户名和密码两项信息,
                serverAddress 不填写就默认使用 registry. -->
            <registryUser>
                <username>blinkfox</username>
                <password>123456</password>
                <!-- 可以对用户名或密码进行加密,可同时加密,也可只加密用户名或密码,只要将用户名或密码以 'ENCRYPT#' 开头就表示是加过密的信息. -->
                <!-- <password>ENCRYPT#xrrHHzgJsGUQrfkEasF6WahbGnMXTg==</password>-->
                <email>[email protected]</email>
                <serverAddress></serverAddress> <!-- registry 服务地址,不填写则使用上面 registry 的值. -->
                <identityToken></identityToken> <!-- 该 token 值通常不需要填写. -->
            </registryUser>
            <vmOptions>-Xms1024m -Xmx2048m</vmOptions>
            <programArgs>--server.port=7070</programArgs>
            <configFiles>
                <param>src/test/resources/application.yml</param>
                <param>src/test/resources/application-dev.yml</param>
            </configFiles>
            <copyResources>
                <copyResource>
                    <from>README.pdf</from>
                    <to>.</to>
                </copyResource>
            </copyResources>
            <excludeFiles>
                <param>logs</param>
            </excludeFiles>
        </docker>
    </configuration>
</plugin>

13. helmChart

这是用于专门对 Helm Chart 平台进行构建的配置项,v1.5.0 版本新增,主要包括前面提到的如下几个子配置项及 Helm Chart 平台下特有的一些配置项,用法同前面类似,不再赘述:

  • location: helm chart 源文件的目录位置,目前仅支持本地文件的绝对路径或相对 pom.xml 的相对路径。
  • chartRepoUrl: 要推送 Helm Chart 包所在 Harbor Registry 仓库的 API URL 地址,如果不填写将默认使用上面 docker 配置中的 registryrepo 的值去拼接。示例如:http://registry.yourcompany.com:5000/api/chartrepo/blinkfox/charts,将 yourcompanyblinkfox 替换成你自己的公司仓库和项目名称。
  • useDockerImage: 导出离线应用包(save)时,是后也导出使用 jpack 当前构建的镜像,仅设置为 true 时为真。
  • saveImages: 导出离线应用包(save)时,需要一起导出的离线镜像包,值为一个数组,可以配置多个镜像,也可以同时和 useDockerImage 参数一起生效。
  • saveImageFileName: 表示导出镜像时的镜像文件名称,不填写则默认是 images.tgz
  • goals: Helm Chart 相关的构建目标,如果不填写任何目标,则不会作任何构建任务。目前最多可以填写三个目标:打包 Chart(package)、推送 Chart(push)和导出应用包(save)。
  • configFiles: 针对 Helm Chart 可以一起打包的 Spring Boot 应用的配置文件配置。如果你配置了这个值,那么在 helmChart 下将会覆盖通用的 configFiles 的值。
  • copyResources: 针对 Helm Chart 的资源复制。如果你配置了这个值,那么在导出应用包时会额外复制这些资源到离线应用包中。
  • excludeFiles: 针对 Helm Chart 的资源排除。如果你配置了这个值,那么会额外从离线应用包中排除这些资源。
  • registryUser:当推送 Chart 到私有权限限制的镜像仓库中时,可以填写如下用户权限认证信息。通常,至少需要填写用户名和密码。该值和 Docker 平台中的 registryUser 可以相互使用,如果两个平台的配置都存在的话,那么你只需要在某一个平台中配置一次即可。
    • username:registry 仓库的用户名。可以对用户名进行加密,只要将用户名以 ENCRYPT# 开头就表示是加过密的用户名,否则说明直接使用原文。
    • password:registry 仓库的密码。可以对密码进行加密,只要将文本内容以 ENCRYPT# 开头就表示是加过密的密码,否则说明直接使用原文密码。

注:关于 registryUser 中的用户名或密码加密,你可以使用 jpack 中的 AesKit.encrypt("your-username"); 方法进行加密。该种加密并不安全,意在防君子,防不了小人。Docker 和 Helm Chart 平台中的 registryUser 可以相互使用,如果两个平台的配置都存在的话,那么你只需要在某一个平台中配置一次即可。

示例如下:

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    <!-- 此处内容省略. -->
    <configuration>
        <helmChart>
            <!-- helm chart 源文件的目录位置,支持本地文件的绝对路径或相对 pom.xml 的相对路径. -->
            <location>hello-helm</location>
            <!-- 要推送 helm chart 所在仓库的 API URL 地址,不填写,将使用 docker 配置中的 registry 和 repo. -->
            <chartRepoUrl>http://registry.yourcompany.com:5000/api/chartrepo/blinkfox/charts</chartRepoUrl>
            <!-- 该值表示 save 导出时,是否使用本插件 Docker 构建的镜像,将其也导出到最终的镜像包中,默认为 false. -->
            <useDockerImage>false</useDockerImage>
            <!-- goals 中有 save 时,需要导出的镜像名称或有标签的镜像名称,不填写会默认从上面 Docker 导出的镜像中获取. -->
            <saveImages>
                <param>registry.yourcompany.com:5000/blinkfox/jpack-test:1.0.0-SNAPSHOT</param>
            </saveImages>
            <!-- 表示导出镜像时的镜像文件名称,不填写,则默认是 'images.tgz'. -->
            <saveImageFileName></saveImageFileName>
            <goals>
                <param>package</param>
                <param>push</param>
                <param>save</param>
            </goals>
            <registryUser>
                <username>ENCRYPT#leSdRWZZesst0PRxA2uMYqWgmcBOuzQx</username>
                <password>ENCRYPT#xrrHHzgJsGUQrfkEasF6WahbGnMXTg==</password>
            </registryUser>
        </helmChart>
    </configuration>
</plugin>

五、更全的配置示例及说明

jpack 的所有配置参数都非必填或者有默认值。下面是 jpack Maven 插件的所有配置项配置示例和配置含义的说明如下:

<plugin>
    <groupId>com.blinkfox</groupId>
    <artifactId>jpack-maven-plugin</artifactId>
    <version>1.5.5</version>
    <executions>
        <execution>
            <goals>
                <!-- 只能是 build. -->
                <goal>build</goal>
            </goals>
            <!-- 默认执行阶段是 package,你可以根据情况写为 install 或 deploy 等. -->
            <phase>package</phase>
        </execution>
    </executions>
    <configuration>
        <!-- 打包哪些平台的包,不填写则代表所有平台. 目前支持 Windows、Linux 和 Dokcer 三种(大小写均可). -->
        <platforms>
            <param>Windows</param>
            <param>Linux</param>
            <param>Docker</param>
        </platforms>
        <!-- JVM 运行所需的参数选项. -->
        <vmOptions>-Xms1024m -Xmx2048m</vmOptions>
        <!-- 所集成的 SpringBoot 服务程序运行所需的参数. -->
        <programArgs>--server.port=7070</programArgs>
        <!-- 遇到错误时是否跳过错误,目前仅Docker 下有用到此配置。默认是不填写或者 default,程序会自动处理,不需要你额外关注;
            true的话,会忽略所有异常;false的话,遇到错误就直接报错。 -->
        <skipError>default</skipError>
        <cleanPackDir>true</cleanPackDir>
        <!-- 是否生成 Windows、Linux 下默认的 bin 目录,默认 true,即生成 jpack 自带 bin 目录和文件. -->
        <generateBinDir>true</generateBinDir>
        <windows>
            ...
        </windows>
        <linux>
            ...
        </linux>
        <docker>
            <!-- 构建 Docker 镜像的 Dockerfile 文件的相对路径,没有此配置项或者不填写则使用 jpack 默认的 Dockerfile 文件. -->
            <dockerfile>Dockerfile</dockerfile>
            <!-- 构建镜像的几个基础参数, registry远程仓库地址,不填写默认视为 Dockerhub 的地址;
                repo 不填写则默认为 groupId,name 不填写则默认为 artifactId,tag不填写则默认为 version.-->
            <registry></registry>
            <repo>blinkfox</repo>
            <name>jpack-demo</name>
            <tag>1.0.0</tag>
            <!-- FROM 的镜像,如果没有配置该值,将默认是 openjdk:8-jdk-alpine. -->
            <fromImage>openjdk:8-jdk-alpine</fromImage>
            <!-- 对外暴露的端口,不配置该值,将不会在 Dockerfile 中生成 EXPOSE 指令. -->
            <expose>8080</expose>
            <!-- 挂载的数据卷,不填写则默认挂载 "/tmp" 和 "/logs" 目录. -->
            <volumes>
                <param>/tmp</param>
                <param>/logs</param>
            </volumes>
            <!-- 自定义的 Dockerfile 指令选项,可以填写多个值,每个值在 Dockerfile 中占一行,充当Dockerfile中的一条指令,例如:下面设置时区的一个指令. -->
            <customCommands>
                <param>RUN echo 'Asia/Shanghai' >/etc/timezone</param>
            </customCommands>
            <!-- jpack 的 Docker 构建的默认目标是构建镜像,如果你需要其他目标的话,可以在此配置).
                目前这里只支持导出镜像为 .tar 包(save). -->
            <!-- jpack 的 Docker 构建的默认目标是构建镜像,如果你需要其他目标的话,可以再此配置(可配多个).
                目前这里支持导出镜像为 .tar 包(save)和 推送镜像到远程仓库(push) 两种. -->
            <extraGoals>
                <param>save</param>
                <param>push</param>
            </extraGoals>
            <!-- jpack 推送到远程私有镜像仓库的用户权限认证信息,通常至少需要填写用户名和密码两项信息,
                serverAddress 不填写就默认使用 registry. -->
            <registryUser>
                <username>ENCRYPT#leSdRWZZesst0PRxA2uMYqWgmcBOuzQx</username>
                <password>ENCRYPT#xrrHHzgJsGUQrfkEasF6WahbGnMXTg==</password>
                <!-- 可以对用户名或密码进行加密,可同时加密,也可只加密用户名或密码,只要将用户名或密码以 'ENCRYPT#' 开头就表示是加过密的信息. -->
                <!-- <password>ENCRYPT#xrrHHzgJsGUQrfkEasF6WahbGnMXTg==</password>-->
                <email>[email protected]</email>
                <serverAddress></serverAddress> <!-- registry 服务地址,不填写则使用上面 registry 的值. -->
                <identityToken></identityToken> <!-- 该 token 值通常不需要填写. -->
            </registryUser>
            ...
        </docker>
        <helmChart>
            <!-- helm chart 源文件的目录位置,目前仅支持本地文件的绝对路径或相对 pom.xml 的相对路径. -->
            <location>src/test/resources/hello-helm</location>
            <!-- 要推送 helm chart 所在仓库的 API URL 地址. -->
            <chartRepoUrl>http://registry.yourcompany.com:5000/api/chartrepo/blinkfox/charts</chartRepoUrl>
            <!-- 该值表示 save 导出时,是否使用本插件 Docker 构建的镜像,将其也导出到最终的镜像包中,默认为 false. -->
            <useDockerImage>false</useDockerImage>
            <!-- goals 中有 save 时,需要导出的镜像名称或有标签的镜像名称,不填写会默认从上面 Docker 导出的镜像中获取. -->
            <saveImages>
                <param>registry.yourcompany.com:5000/blinkfox/jpack-test:1.0.0-SNAPSHOT</param>
            </saveImages>
            <!-- 表示导出镜像时的镜像文件名称,不填写,则默认是 'images.tgz'. -->
            <saveImageFileName></saveImageFileName>
            <goals>
                <param>package</param>
                <param>push</param>
                <param>save</param>
            </goals>
            <registryUser>
                <username>ENCRYPT#leSdRWZZesst0PRxA2uMYqWgmcBOuzQx</username>
                <password>ENCRYPT#xrrHHzgJsGUQrfkEasF6WahbGnMXTg==</password>
            </registryUser>
        </helmChart>
        <!-- 需要copy 哪些资源(from 的值可以是目录或者具体的相对、绝对或网络资源路径)到部署包中的某个目录;
            to 的值只能是目录,为空或者 '.' 或者 '/' 符号则表示复制到各平台包的根目录中,否则就复制到具体的目录下 -->
        <copyResources>
            <!-- 复制本项目根目录的 README.md 到各平台包的根目录中. -->
            <copyResource>
                <from>README.md</from>
                <to>.</to>
            </copyResource>
            <!-- 复制本项目 docs 文件夾到各平台包的 docs 目录中. -->
            <copyResource>
                <from>docs</from>
                <to>docs</to>
            </copyResource>
            <!-- 复制本项目上层目录的 hello.pdf 文件到各平台包的 abc/def 目录中(会自动创建此目录). -->
            <copyResource>
                <from>../test-dir/hello.pdf</from>
                <to>abc/def</to>
            </copyResource>
            <!-- 复制网络资源 http://xxx.com/image.png 文件到各平台包的根目录中. -->
            <copyResource>
                <from>http://xxx.com/image.png</from>
                <to>/</to>
            </copyResource>
        </copyResources>
        <!-- 排除哪些文件或目录不需要打包进压缩包中,输入文件的相对路径即可. -->
        <excludeFiles>
            <param>logs</param>
            <param>README.md</param>
            <param>xxxxx.abc</param>
        </excludeFiles>
    </configuration>
</plugin>

六、许可证

jpack-maven-plugin Maven 插件 遵守 Apache License 2.0 许可证。

七、版本记录

  • v1.5.5 (2021-05-11)
    • 修改了Linux 中的几个脚本,使重启时也能支持优雅停机重启;
    • 一些依赖版本升级;
  • v1.5.4 (2020-07-18)
    • 新增了不生成默认 bin 目录和文件的配置项,便于自定义 bin 目录中的文件;
    • 修改了 Windows 下 logs 目录在 bin 目录中的问题;
    • 修改了 Linux 下的 Shell 脚本,将 kill -9 改为 kill -15,脚本中均添加了 exit 的退出指令;
    • 重构使用了 okhttp 库来完成 chart 包推送的功能;
  • v1.5.3 (2020-07-06)
    • 新增了不配置 chartRepoUrl 时,将自动从 docker 配置的 registryrepo 中读取拼接;
    • 修改回了 Docker 镜像包的文件格式为 tar;
    • 修复了导出 Docker 完整离线部署包时包名不对的问题;
  • v1.5.2 (2020-06-24)
    • 修改了无 Docker 环境但却配置了使用 Docker 镜像时导出 Chart 包时一直循环等待构建的问题;
  • v1.5.1 (2020-06-23)
    • 修复了未配置 Helm Chart 时的空指针问题;
  • v1.5.0 (2020-06-23)
    • 新增了 Helm Chart 的相关构建;
    • 修改了一些日志格式的显示;
  • v1.4.0 (2020-06-03)
    • 新增了推送到远程私有镜像仓库时,可以配置 registry 的用户权限认证信息;
    • 修改了一些日志格式的显示;
  • v1.3.4 (2019-11-18)
    • 新增了是否清除之前的打包目录的配置项;
    • 新增了在 start.sh 脚本中对是否已经启动了本服务的判断;
  • v1.3.3 (2019-10-12)
    • 升级了相关包的依赖;
  • v1.3.2 (2019-09-08)
    • 新增了 Windows 和 Linux 下查看服务运行状态(status)的脚本;
    • 修改了 Linux 发布包脚本中的 shell 声明为 bash
  • v1.3.1 (2019-08-21)
    • 修改了默认构建的 Dockerfiletarget 目录下读取 jar 包;
  • v1.3.0 (2019-06-04)
    • 修改了 jpack 默认的 Dockerfile 的一些指令为从配置文件读取;
    • 新增了 fromImage, expose, volumes, customCommands 4项 jpack 默认提供的 Dockerfile 的指令配置;
  • v1.2.1 (2019-06-01)
    • 修改了 configFile 改为了 configFiles,支持配置多个配置文件地址;
    • 新增了推送到自定义仓库时的打标签功能;
  • v1.2.0 (2019-05-22)
    • 修复了 Windows 下的 SpringBoot 配置文件不生效的问题;
    • 新增了 configFile 的配置支持;
    • 新增了自定义 Windows、Linux、Docker 下的一些通用配置为平台专属配置;
    • 修复了默认 Dockerfile 构建的镜像容器时间不对的问题;
  • v1.1.0 (2019-05-18)
    • 新增了 Docker 平台下的构建、部署包导出、推送镜像等;
    • 新增了一些配置参数;
    • 完善文档说明;
  • v1.0.0 (2019-05-07)
    • 基础功能完成;
    • 支持打包为 Windows 和 Linux 下的部署包;