Installing Spring Boot Applications

除了使用 java -jar 直接运行 Spring Boot 应用程序外，还可以将它们作为 systemd、init.d 或 Windows 服务运行。

In addition to running Spring Boot applications by using java -jar directly, it is also possible to run them as systemd, init.d or Windows services.

Installation as a systemd Service

systemd 是 System V 初始化系统的继任者，现在它被许多现代 Linux 发行版使用。Spring Boot 应用程序可以使用 systemd ``service’ 脚本启动。

systemd is the successor of the System V init system and is now being used by many modern Linux distributions. Spring Boot applications can be launched by using systemd '`service’ scripts.

假设你在 /var/myapp 中有一个打包成 uber jar 的 Spring Boot 应用程序，要以 systemd 服务的形式安装它，请创建一个名为 myapp.service 的脚本，并将其放在 /etc/systemd/system 目录中。以下脚本提供了一个示例：

Assuming that you have a Spring Boot application packaged as an uber jar in /var/myapp, to install it as a systemd service, create a script named myapp.service and place it in /etc/systemd/system directory. The following script offers an example:

[Unit]
Description=myapp
After=syslog.target network.target

[Service]
User=myapp
Group=myapp

Environment="JAVA_HOME=/path/to/java/home"

ExecStart=${JAVA_HOME}/bin/java -jar /var/myapp/myapp.jar
ExecStop=/bin/kill -15 $MAINPID
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

别忘了更改应用程序的 Description、User、Group、Environment 和 ExecStart 字段。

Remember to change the Description, User, Group, Environment and ExecStart fields for your application.

ExecStart 字段不声明脚本操作命令，这意味着 run 命令将被默认使用。

The ExecStart field does not declare the script action command, which means that the run command is used by default.

运行该应用程序的用户、PID 文件和控制台日志文件由 systemd 本身管理，因此必须使用 ``service’ 脚本中的适当字段对其进行配置。有关更多详细信息，请参阅 service unit configuration man page 。

The user that runs the application, the PID file, and the console log file are managed by systemd itself and therefore must be configured by using appropriate fields in the '`service’ script. Consult the service unit configuration man page for more details.

若要标记该应用程序在系统启动时自动启动，请使用以下命令：

To flag the application to start automatically on system boot, use the following command:

$ systemctl enable myapp.service

运行 man systemctl 以了解更多详细信息。

Run man systemctl for more details.

Installation as an init.d Service (System V)

若要以 init.d 服务的形式使用应用程序，请配置其构建以生成 fully executable jar 。

To use your application as init.d service, configure its build to produce a fully executable jar.

完全可执行 jar 文件通过在文件开头嵌入一个额外脚本工作的。目前，一些工具不接受此格式，因此你可能无法始终使用此技术。例如，jar -xf 可能静默失败提取一个已被制作成完全可执行的 jar 或 war。建议仅在你打算直接执行 jar 或 war 时，而不是在使用 java -jar 运行它或将其部署到 servlet 容器时，才使其完全可执行。

Fully executable jars work by embedding an extra script at the front of the file. Currently, some tools do not accept this format, so you may not always be able to use this technique. For example, jar -xf may silently fail to extract a jar or war that has been made fully executable. It is recommended that you make your jar or war fully executable only if you intend to execute it directly, rather than running it with java -jar or deploying it to a servlet container.

一个 zip64 格式的 jar 文件不能被制成完全可执行。试图这样做将导致当直接执行或使用 java -jar 执行时，将 jar 文件报告为已损坏。包含一个或多个 zip64 格式的嵌套 jar 文件的标准格式 jar 文件可以被完全执行。

A zip64-format jar file cannot be made fully executable. Attempting to do so will result in a jar file that is reported as corrupt when executed directly or with java -jar. A standard-format jar file that contains one or more zip64-format nested jars can be fully executable.

若要使用 Maven 创建 ``完全可执行’ jar，请使用以下插件配置：

To create a '`fully executable’ jar with Maven, use the following plugin configuration:

<plugin>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-maven-plugin</artifactId>
	<configuration>
		<executable>true</executable>
	</configuration>
</plugin>

以下示例显示等效的 Gradle 配置：

The following example shows the equivalent Gradle configuration:

tasks.named('bootJar') {
	launchScript()
}

然后可以将其符号链接到 init.d 以支持标准 start、stop、restart 和 status 命令。

It can then be symlinked to init.d to support the standard start, stop, restart, and status commands.

添加到一个完全可执行的 jar 文件中的默认启动脚本支持大多数 Linux 发行版，并在 CentOS 和 Ubuntu 上进行了测试。其他平台（如 OS X 和 FreeBSD）需要使用一个自定义脚本。默认脚本支持以下功能：

The default launch script that is added to a fully executable jar supports most Linux distributions and is tested on CentOS and Ubuntu. Other platforms, such as OS X and FreeBSD, require the use of a custom script. The default scripts supports the following features:

  • Starts the services as the user that owns the jar file

  • Tracks the application’s PID by using /var/run/<appname>/<appname>.pid

  • Writes console logs to /var/log/<appname>.log

假设您在 /var/myapp 安装了 Spring Boot 应用程序，要将 Spring Boot 应用程序安装为 init.d 服务，请按照如下所示创建一个符号链接：

Assuming that you have a Spring Boot application installed in /var/myapp, to install a Spring Boot application as an init.d service, create a symlink, as follows:

$ sudo ln -s /var/myapp/myapp.jar /etc/init.d/myapp

安装完成后，您可以用惯常的方式启动并停止服务。例如，在基于 Debian 的系统上，您可以使用以下命令启动：

Once installed, you can start and stop the service in the usual way. For example, on a Debian-based system, you could start it with the following command:

$ service myapp start

如果您的应用程序无法启动，请查看写入到 /var/log/<appname>.log 中的日志文件以获取错误。

If your application fails to start, check the log file written to /var/log/<appname>.log for errors.

您还可使用标准操作系统工具将应用程序标记为自动启动。例如，在 Debian 中，您可以使用以下命令：

You can also flag the application to start automatically by using your standard operating system tools. For example, on Debian, you could use the following command:

$ update-rc.d myapp defaults <priority>

Securing an init.d Service

以下是有关如何保护作为 init.d 服务运行的 Spring Boot 应用程序的指南。它不会罗列实现强化应用程序及其运行环境所需的所有事项。

The following is a set of guidelines on how to secure a Spring Boot application that runs as an init.d service. It is not intended to be an exhaustive list of everything that should be done to harden an application and the environment in which it runs.

当作为 root 执行时，比如在使用 root 启动 init.d 服务时，默认可执行脚本使用 RUN_AS_USER 环境变量中指定的用户运行应用程序。如果未设置环境变量，则该系统会改用拥有 jar 文件的用户。您绝不应将 Spring Boot 应用程序作为 root 运行，因此 RUN_AS_USER 不应为 root，并且您的应用程序的 jar 文件不应为 root 所有。相反，您可以创建一个特定用户来运行您的应用程序，并设置 RUN_AS_USER 环境变量或使用 chown 将其设为 jar 文件的所有者，如以下示例所示：

When executed as root, as is the case when root is being used to start an init.d service, the default executable script runs the application as the user specified in the RUN_AS_USER environment variable. When the environment variable is not set, the user who owns the jar file is used instead. You should never run a Spring Boot application as root, so RUN_AS_USER should never be root and your application’s jar file should never be owned by root. Instead, create a specific user to run your application and set the RUN_AS_USER environment variable or use chown to make it the owner of the jar file, as shown in the following example:

$ chown bootapp:bootapp your-app.jar

在这种情况下，默认可执行脚本将以 bootapp 用户身份运行应用程序。

In this case, the default executable script runs the application as the bootapp user.

为了减少应用程序用户帐户被入侵的可能性，您应该考虑阻止其使用登录 shell。例如，您可以将该帐户的 shell 设置为 /usr/sbin/nologin。

To reduce the chances of the application’s user account being compromised, you should consider preventing it from using a login shell. For example, you can set the account’s shell to /usr/sbin/nologin.

您还应采取措施来防止修改应用程序的 jar 文件。首先，配置其权限，使其不可写，并且只能由其所有者读取或执行，如以下示例所示：

You should also take steps to prevent the modification of your application’s jar file. Firstly, configure its permissions so that it cannot be written and can only be read or executed by its owner, as shown in the following example:

$ chmod 500 your-app.jar

其次，您还应采取措施以在您的应用程序或运行它的帐户被入侵时限制损失。如果攻击者确实获得访问权限，他们可以使 jar 文件可写并更改其内容。一种防范方法是使用 chattr 使其不可变，如以下示例所示：

Second, you should also take steps to limit the damage if your application or the account that is running it is compromised. If an attacker does gain access, they could make the jar file writable and change its contents. One way to protect against this is to make it immutable by using chattr, as shown in the following example:

$ sudo chattr +i your-app.jar

这将阻止包括 root 在内的任何用户修改 jar 文件。

This will prevent any user, including root, from modifying the jar.

如果 root 用于控制应用程序的服务，并且您 use a .conf file 以自定义其启动，则 .conf 文件由 root 用户读取和评估。应对其进行相应的保护。使用 chmod，使得该文件只能由所有者读取，并使用 chown 使 root 成为所有者，如以下示例所示：

If root is used to control the application’s service and you use a .conf file to customize its startup, the .conf file is read and evaluated by the root user. It should be secured accordingly. Use chmod so that the file can only be read by the owner and use chown to make root the owner, as shown in the following example:

$ chmod 400 your-app.conf
$ sudo chown root:root your-app.conf

Customizing the Startup Script

Maven 或 Gradle 插件编写的默认嵌入式启动脚本可以通过多种方式自定义。一般而言，使用带有少量自定义的默认脚本通常已足够。如果您发现无法自定义您需要的内容，请使用 embeddedLaunchScript 选项完全编写您自己的文件。

The default embedded startup script written by the Maven or Gradle plugin can be customized in a number of ways. For most people, using the default script along with a few customizations is usually enough. If you find you cannot customize something that you need to, use the embeddedLaunchScript option to write your own file entirely.

Customizing the Start Script When It Is Written

通常对写入 jar 文件的 start 脚本的元素进行自定义是有意义的。例如，init.d 脚本可以提供 “description”。由于您预先就知道了描述（并且它不必更改），因此您不妨在生成 jar 文件时提供该描述。

It often makes sense to customize elements of the start script as it is written into the jar file. For example, init.d scripts can provide a “description”. Since you know the description up front (and it need not change), you may as well provide it when the jar is generated.

要自定义书面元素，请使用 Spring Boot Maven 插件的 embeddedLaunchScriptProperties 选项或 properties property of the Spring Boot Gradle plugin’s launchScript。

To customize written elements, use the embeddedLaunchScriptProperties option of the Spring Boot Maven plugin or the properties property of the Spring Boot Gradle plugin’s launchScript.

使用默认脚本支持以下属性替换：

The following property substitutions are supported with the default script:

Name Description Gradle default Maven default

mode

The script mode.

auto

auto

initInfoProvides

The Provides section of “INIT INFO”

${task.baseName}

${project.artifactId}

initInfoRequiredStart

Required-Start section of “INIT INFO”.

$remote_fs $syslog $network

$remote_fs $syslog $network

initInfoRequiredStop

Required-Stop section of “INIT INFO”.

$remote_fs $syslog $network

$remote_fs $syslog $network

initInfoDefaultStart

Default-Start section of “INIT INFO”.

2 3 4 5

2 3 4 5

initInfoDefaultStop

Default-Stop section of “INIT INFO”.

0 1 6

0 1 6

initInfoShortDescription

Short-Description section of “INIT INFO”.

Single-line version of ${project.description} (falling back to ${task.baseName})

${project.name}

initInfoDescription

Description section of “INIT INFO”.

${project.description} (falling back to ${task.baseName})

${project.description} (falling back to ${project.name})

initInfoChkconfig

chkconfig section of “INIT INFO”

2345 99 01

2345 99 01

confFolder

The default value for CONF_FOLDER

Folder containing the jar

Folder containing the jar

inlinedConfScript

Reference to a file script that should be inlined in the default launch script. This can be used to set environmental variables such as JAVA_OPTS before any external config files are loaded

logFolder

Default value for LOG_FOLDER. Only valid for an init.d service

logFilename

Default value for LOG_FILENAME. Only valid for an init.d service

pidFolder

Default value for PID_FOLDER. Only valid for an init.d service

pidFilename

Default value for the name of the PID file in PID_FOLDER. Only valid for an init.d service

useStartStopDaemon

Whether the start-stop-daemon command, when it is available, should be used to control the process

true

true

stopWaitTime

Default value for STOP_WAIT_TIME in seconds. Only valid for an init.d service

60

60

Customizing a Script When It Runs

对于脚本中需要自定义的项 after jar 文件已写入，您可以使用环境变量或 config file.

For items of the script that need to be customized after the jar has been written, you can use environment variables or a config file.

默认脚本支持以下环境属性：

The following environment properties are supported with the default script:

Variable Description

MODE

The “mode” of operation. The default depends on the way the jar was built but is usually auto (meaning it tries to guess if it is an init script by checking if it is a symlink in a directory called init.d). You can explicitly set it to service so that the `stop

start

status

restart` commands work or to run if you want to run the script in the foreground.

RUN_AS_USER

The user that will be used to run the application. When not set, the user that owns the jar file will be used.

USE_START_STOP_DAEMON

Whether the start-stop-daemon command, when it is available, should be used to control the process. Defaults to true.

PID_FOLDER

The root name of the pid folder (/var/run by default).

LOG_FOLDER

The name of the folder in which to put log files (/var/log by default).

CONF_FOLDER

The name of the folder from which to read .conf files (same folder as jar-file by default).

LOG_FILENAME

The name of the log file in the LOG_FOLDER (<appname>.log by default).

APP_NAME

The name of the app. If the jar is run from a symlink, the script guesses the app name. If it is not a symlink or you want to explicitly set the app name, this can be useful.

RUN_ARGS

The arguments to pass to the program (the Spring Boot app).

JAVA_HOME

The location of the java executable is discovered by using the PATH by default, but you can set it explicitly if there is an executable file at $JAVA_HOME/bin/java.

JAVA_OPTS

Options that are passed to the JVM when it is launched.

JARFILE

The explicit location of the jar file, in case the script is being used to launch a jar that it is not actually embedded.

DEBUG

If not empty, sets the -x flag on the shell process, allowing you to see the logic in the script.

STOP_WAIT_TIME

PID_FOLDER、LOG_FOLDER`和`LOG_FILENAME`变量仅对`init.d`服务有效。对于`systemd，使用`service` 脚本进行等效自定义。有关详细信息，请参阅 service unit configuration man page。

The PID_FOLDER, LOG_FOLDER, and LOG_FILENAME variables are only valid for an init.d service. For systemd, the equivalent customizations are made by using the '`service’ script. See the service unit configuration man page for more details.
Using a Conf File

除了`JARFILE`和`APP_NAME`之外，前面部分列出的设置都可以使用 .conf`文件进行配置。该文件应位于 jar 文件旁边，并且具有相同名称，但后缀为 `.conf，而不是 .jar。例如，名为`/var/myapp/myapp.jar`的 jar 使用名为`/var/myapp/myapp.conf`的配置文件，如下面的示例所示：

With the exception of JARFILE and APP_NAME, the settings listed in the preceding section can be configured by using a .conf file. The file is expected to be next to the jar file and have the same name but suffixed with .conf rather than .jar. For example, a jar named /var/myapp/myapp.jar uses the configuration file named /var/myapp/myapp.conf, as shown in the following example:

myapp.conf
JAVA_OPTS=-Xmx1024M
LOG_FOLDER=/custom/log/folder

如果你不喜欢配置文件位于 jar 文件旁边，你可以设置一个`CONF_FOLDER`环境变量来自定义配置文件的位置。

If you do not like having the config file next to the jar file, you can set a CONF_FOLDER environment variable to customize the location of the config file.

要了解如何适当保护此文件，请参阅the guidelines for securing an init.d service。

To learn about securing this file appropriately, see the guidelines for securing an init.d service.

Microsoft Windows Services

Spring Boot 应用程序可以通过使用 winsw 作为 Windows 服务启动。

A Spring Boot application can be started as a Windows service by using winsw.

一个（ separately maintained sample）逐步描述了如何为你的 Spring Boot 应用程序创建一个 Windows 服务。

A (separately maintained sample) describes step-by-step how you can create a Windows service for your Spring Boot application.