巧用supervisorctl，让Spring Boot项目部署So Easy！

一、引言

在当今快速迭代的软件开发领域，Spring Boot 凭借其强大的功能和便捷的开发体验，成为了众多开发者构建 Java 应用的首选框架。当我们历经艰辛，完成了 Spring Boot 项目的开发，满心欢喜地准备将其推向生产环境时，会发现部署环节至关重要。

传统的部署方式，如直接使用 Java 命令运行 JAR 包，虽然简单直接，但在实际生产中，却存在诸多不便。比如，当应用程序意外崩溃时，需要手动重新启动；而且，在多进程管理和日志监控方面，也显得力不从心。这就好比驾驶一辆没有仪表盘和自动修复功能的汽车，行驶在崎岖的道路上，随时可能陷入困境。

而 supervisorctl 就像是一位专业的汽车管家，为 Spring Boot 项目的部署和管理带来了极大的便利。它不仅可以帮助我们轻松管理 Spring Boot 项目的进程，确保应用程序在后台稳定运行，还能在应用程序出现异常时自动重启，就像汽车的自动修复系统一样，让我们的应用始终保持在线状态。同时，supervisorctl 还提供了丰富的命令行操作，方便我们对项目进行实时监控和管理，就像汽车仪表盘上的各种仪表，让我们对车辆的状态一目了然。

接下来，让我们一起深入探索如何使用 supervisorctl 部署 Spring Boot 项目，开启高效部署的新篇章。

二、supervisorctl 与 Spring Boot 简介

（一）supervisorctl 是什么

supervisorctl 是进程管理工具 supervisor 的命令行客户端，而 supervisor 是一个用 Python 开发的 client/server 服务，主要用于在类 Unix 操作系统上监视和控制多个进程 。它就像是一个专业的进程管家，能够帮助开发者轻松管理服务器上的各种进程。

通过 supervisorctl，我们可以方便地对由 supervisor 管理的进程执行启动、停止、重启等操作，还能实时查看进程的运行状态。比如，当我们在服务器上部署了多个应用程序，每个应用程序都有对应的进程，使用 supervisorctl，我们可以在一个统一的命令行界面下对这些进程进行集中管理，而不需要逐个去查找和操作每个进程的启动脚本。这就好比在一个大型停车场中，我们可以通过一个统一的管理系统来控制所有车辆的进出和停放，而不是分别对每辆车进行单独管理，大大提高了管理效率。

（二）Spring Boot 的特点

Spring Boot 是一个基于 Spring 框架的开源项目，它的出现极大地简化了 Spring 应用的初始搭建和开发过程，就像为 Java 开发者提供了一把神奇的 “瑞士军刀”，在 Java 开发领域得到了广泛的应用。

Spring Boot 具有 “约定优于配置” 的特性，这意味着它提供了许多默认配置，开发者在大多数情况下可以直接使用这些默认配置，快速开始开发应用程序，而无需花费大量时间进行繁琐的配置工作。比如在搭建一个 Web 项目时，Spring Boot 默认集成了 Tomcat 服务器，我们不需要手动去配置 Tomcat 的各种参数，只需要简单的设置，就能快速搭建起一个可用的 Web 服务。

它还支持将应用打包成一个可执行的 jar 或 war 文件，使得应用可以独立运行，无需部署在外部的 servlet 容器中。这就像把一个完整的小型工厂装进了一个集装箱里，这个集装箱可以在任何合适的地方独立运行，不受外部环境的过多限制，大大提高了应用的可移植性和部署的便捷性。

另外，Spring Boot 的自动配置功能也非常强大，它可以根据项目中引入的依赖和环境信息，自动配置项目的各种组件，如数据源、缓存、日志、安全性等，这大大减少了手动配置的工作量，让开发者能够更加专注于业务逻辑的实现。

三、部署前的准备工作

（一）环境要求

在开始部署之前，我们需要确保服务器环境满足以下条件：

1. Linux 系统：supervisorctl 主要运行在类 Unix 系统上，如常见的 CentOS、Ubuntu 等。本文以 CentOS 7 为例进行讲解，它具有良好的稳定性和广泛的应用场景，在企业级服务器中被大量使用 。

1. Java 环境：由于我们要部署 Spring Boot 项目，所以服务器必须安装 Java 运行时环境（JRE）或 Java 开发工具包（JDK）。Spring Boot 2.x 版本推荐使用 JDK 1.8 及以上版本。我们可以通过以下命令检查服务器上是否已安装 Java 以及 Java 的版本：

java -version

如果未安装 Java，可以从 Oracle 官方网站下载对应版本的 JDK 安装包，然后按照安装向导进行安装，并配置好环境变量。例如，在 CentOS 系统中，安装 JDK 后，需要编辑/etc/profile文件，添加以下内容：

export JAVA_HOME=/usr/local/jdk1.8.0_361 # 根据实际安装路径修改

export PATH=$JAVA_HOME/bin:$PATH

export CLASSPATH=.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar

保存文件后，执行source /etc/profile使配置生效。

3. supervisor 安装：安装 supervisor 的方式有多种，在 CentOS 系统中，可以使用 yum 命令进行安装，执行以下命令：

sudo yum install supervisor

安装完成后，supervisor 服务会自动启动。我们可以使用以下命令检查其状态：

sudo systemctl status supervisor

如果看到active (running)字样，说明 supervisor 安装并启动成功。

（二）获取 Spring Boot 项目

在部署之前，我们需要先获取 Spring Boot 项目的可执行文件。获取项目的方式主要有以下两种：

1. 本地项目打包：如果项目是在本地开发的，我们可以使用构建工具（如 Maven 或 Gradle）将项目打包成可执行的 JAR 文件。

• • Maven 打包：在项目的根目录下，打开命令行终端，执行以下命令：

mvn clean package

执行该命令后，Maven 会自动下载项目所需的依赖，并进行编译、测试和打包。打包完成后，在项目的target目录下会生成一个以项目名称命名的 JAR 文件，例如my - spring - boot - app.jar。

• Gradle 打包：如果项目使用 Gradle 构建，在项目根目录下执行以下命令：

./gradlew build

Gradle 执行完成后，在build/libs目录下会生成可执行的 JAR 文件。

2. 从代码仓库拉取项目：如果项目存储在代码仓库（如 GitLab、GitHub 等）中，我们需要先在服务器上安装 Git 工具，然后使用 Git 命令将项目克隆到服务器上。

• 安装 Git：在 CentOS 系统中，可以使用 yum 命令安装 Git：

sudo yum install git

• 克隆项目：假设项目的 Git 仓库地址为https://github.com/username/my - spring - boot - project.git，在服务器上选择一个合适的目录，执行以下命令克隆项目：

git clone https://github.com/username/my - spring - boot - project.git

克隆完成后，进入项目目录，使用构建工具进行打包，得到可执行的 JAR 文件。

通过以上步骤，我们完成了部署前的准备工作，确保了服务器环境满足要求，并获取了待部署的 Spring Boot 项目。接下来，就可以正式开始使用 supervisorctl 部署 Spring Boot 项目了。

四、使用 supervisorctl 部署 Spring Boot 项目的详细步骤

（一）安装 supervisor

在不同的 Linux 发行版上，安装 supervisor 的方式略有不同：

• CentOS 系统：使用 yum 命令进行安装，在终端中执行以下命令：

sudo yum install supervisor

• Ubuntu 系统：使用 apt - get 命令安装，执行以下命令：

sudo apt - get update

sudo apt - get install supervisor

安装完成后，supervisor 服务会自动启动。我们可以使用以下命令检查其状态：

sudo systemctl status supervisor

如果看到active (running)字样，说明 supervisor 安装并启动成功。

（二）配置 supervisor

1. 找到配置文件

supervisor 的配置文件通常位于/etc/supervisor/supervisord.conf 。这个文件包含了 supervisor 的全局配置信息，以及可以包含其他配置文件的路径。我们可以使用文本编辑器打开该文件进行查看和编辑，例如使用vim编辑器：

sudo vim /etc/supervisor/supervisord.conf

2. 编辑配置文件

在/etc/supervisor/supervisord.conf文件的末尾，找到[include]部分，确保其内容为：

[include]

files = /etc/supervisor/conf.d/*.conf

这表示 supervisor 会读取/etc/supervisor/conf.d/目录下所有以.conf结尾的配置文件。接下来，我们为 Spring Boot 项目创建一个单独的配置文件，假设项目名为my - spring - boot - project，在/etc/supervisor/conf.d/目录下创建my - spring - boot - project.conf文件：

sudo vim /etc/supervisor/conf.d/my - spring - boot - project.conf

在这个文件中，添加以下内容来配置 Spring Boot 项目：

[program:my - spring - boot - project]

; 项目目录，根据实际情况修改

directory=/home/yourusername/my - spring - boot - project

; 执行命令，假设项目打包后的jar文件名为my - spring - boot - app.jar

command=java -jar /home/yourusername/my - spring - boot - project/my - spring - boot - app.jar

; 启动参数，这里设置为后台运行，也可根据需要添加其他参数

autostart=true

autorestart=true

stderr_logfile=/var/log/my - spring - boot - project.err.log

stdout_logfile=/var/log/my - spring - boot - project.out.log

上述配置中：

• [program:my - spring - boot - project]：定义了一个名为my - spring - boot - project的程序，这个名称可以自定义，用于在 supervisorctl 中标识该项目。

• directory：指定项目所在的目录。

• command：指定启动项目的命令，这里使用java -jar命令来运行 Spring Boot 项目的 jar 包。

• autostart：设置为true，表示 supervisor 启动时自动启动该项目。

• autorestart：设置为true，表示当项目进程意外终止时，supervisor 会自动重启该项目。

• stderr_logfile和stdout_logfile：分别指定项目错误日志和标准输出日志的文件路径，方便我们查看项目运行过程中的错误信息和输出内容。

（三）上传 Spring Boot 项目

将本地打包好的 Spring Boot 项目的 jar 包上传到服务器的指定目录。我们可以使用scp命令进行上传，假设本地 jar 包路径为/Users/yourusername/Desktop/my - spring - boot - app.jar，服务器的用户名是yourusername，服务器 IP 为192.168.1.100，上传到服务器的/home/yourusername/my - spring - boot - project/目录下，执行以下命令：

scp /Users/yourusername/Desktop/my - spring - boot - app.jar yourusername@192.168.1.100:/home/yourusername/my - spring - boot - project/

执行命令后，系统会提示输入服务器的密码，输入正确密码后，jar 包就会开始上传。上传完成后，我们可以登录服务器，进入/home/yourusername/my - spring - boot - project/目录，查看 jar 包是否上传成功。

（四）启动项目

完成上述配置和上传步骤后，我们就可以使用 supervisorctl 来启动 Spring Boot 项目了。首先，重新加载 supervisor 的配置文件，使新的配置生效，在终端中执行以下命令：

sudo supervisorctl reread

sudo supervisorctl update

reread命令用于读取新的或修改后的配置文件，update命令用于使配置生效并启动新配置的程序。然后，启动 Spring Boot 项目，执行以下命令：

sudo supervisorctl start my - spring - boot - project

这里的my - spring - boot - project是我们在配置文件中定义的程序名称。如果启动成功，不会有任何输出；如果启动失败，可以通过查看日志文件（/var/log/my - spring - boot - project.err.log和/var/log/my - spring - boot - project.out.log）来查找原因。我们还可以使用以下命令查看项目的运行状态：

sudo supervisorctl status my - spring - boot - project

如果看到RUNNING字样，说明项目已经成功启动并正在运行；如果看到STOPPED字样，说明项目未启动或已停止，可以进一步检查配置和日志来排查问题。

五、部署过程中的常见问题及解决方法

（一）配置文件错误

在使用 supervisorctl 部署 Spring Boot 项目时，配置文件的正确性至关重要。一旦配置文件出现错误，可能会导致项目无法正常启动或运行。常见的配置文件错误主要包括语法错误和参数设置不当这两个方面。

1. 语法错误：supervisor 的配置文件采用特定的格式，对语法的要求较为严格。例如，在配置文件中，每个节（section）都必须以方括号[]括起来，节内的参数采用key = value的形式，并且等号两边不能有多余的空格。如果在编写配置文件时，不小心遗漏了方括号、等号，或者使用了错误的缩进，都会导致语法错误。比如，将[program:my - spring - boot - project]写成program:my - spring - boot - project，或者将command = java -jar /path/to/my - spring - boot - app.jar写成command:java -jar /path/to/my - spring - boot - app.jar，这些错误都会使 supervisor 在读取配置文件时无法正确解析，从而报错。

排查这类语法错误时，我们可以使用文本编辑器的语法检查功能，如果编辑器没有自带该功能，也可以将配置文件内容复制到在线的语法检查工具中进行检查。同时，仔细检查配置文件中的每一行，确保格式符合规范。

1. 参数设置不当：除了语法错误，参数设置不当也是一个常见问题。比如，directory参数指定的项目目录不存在，或者command参数中的启动命令错误，都会导致项目无法启动。假设我们将directory参数设置为/home/non - existent - directory/my - spring - boot - project，而实际上该目录并不存在，那么 supervisor 在启动项目时就会找不到项目文件，从而报错。又比如，command参数中指定的 jar 包路径错误，或者没有添加必要的启动参数，也会导致项目启动失败。

对于参数设置不当的问题，我们需要仔细核对每个参数的设置。可以先在本地测试启动命令是否正确，确保java -jar命令能够成功运行 Spring Boot 项目的 jar 包。同时，检查directory参数指定的目录是否存在，并且项目文件是否位于该目录下。此外，还可以参考 supervisor 的官方文档，了解每个参数的含义和正确用法，避免因参数设置错误而导致的问题。

（二）启动失败

在部署过程中，Spring Boot 项目启动失败也是一个常见的问题，其原因可能是多方面的。下面我们来分析一下项目依赖缺失和端口冲突这两个常见的导致启动失败的原因及相应的解决办法。

1. 项目依赖缺失：Spring Boot 项目通常依赖大量的第三方库，如果在部署过程中，这些依赖没有正确引入，就会导致项目启动失败。比如，项目中使用了 MySQL 数据库，依赖mysql - connector - java库，如果在服务器上部署时，没有将该库添加到项目的类路径中，那么项目在启动时就会抛出ClassNotFoundException异常，提示找不到相关的类。又比如，项目依赖某个特定版本的 Spring 框架，但在部署环境中引入的版本不兼容，也可能导致启动失败。

解决项目依赖缺失的问题，我们可以首先检查项目的pom.xml（如果使用 Maven 构建）或build.gradle（如果使用 Gradle 构建）文件，确保所有依赖都已正确声明。然后，在服务器上部署项目时，可以使用构建工具重新下载依赖。如果是从本地打包上传的项目，可以在本地执行mvn clean install（Maven）或./gradlew build（Gradle）命令，确保依赖都被正确打包进 jar 包中。另外，还可以查看项目启动时的日志，根据日志中的错误信息，确定具体缺失的依赖，然后手动添加。

1. 端口冲突：Spring Boot 项目默认使用 8080 端口启动，如果服务器上的 8080 端口已经被其他进程占用，那么项目启动时就会失败，并抛出Address already in use异常。比如，服务器上已经运行了一个 Tomcat 服务，占用了 8080 端口，此时再启动 Spring Boot 项目就会出现端口冲突。

为了解决端口冲突问题，我们可以采取以下两种方法。第一种方法是查找占用端口的进程，并将其停止。在 Linux 系统中，可以使用lsof -i :8080命令查看占用 8080 端口的进程信息，然后使用kill -9 [PID]命令（其中[PID]是进程 ID）终止该进程。在 Windows 系统中，可以使用netstat -ano | findstr :8080命令查找占用端口的进程 ID，然后在任务管理器中结束该进程。第二种方法是修改 Spring Boot 项目的启动端口。我们可以在项目的application.properties或application.yml配置文件中添加或修改server.port属性，将端口号改为一个未被占用的端口，例如server.port = 8081 。修改端口后，重新启动项目，就可以避免端口冲突问题。

六、supervisorctl 的常用管理命令

（一）停止与重启项目

在项目的运行过程中，我们常常需要对项目进行停止或重启操作，比如在进行项目更新、配置调整时，就需要先停止正在运行的项目，待操作完成后再重新启动。supervisorctl 为我们提供了简单便捷的命令来实现这些操作。

1. 停止项目：使用supervisorctl stop命令可以停止由 supervisor 管理的 Spring Boot 项目。例如，我们之前配置的项目名称为my - spring - boot - project，那么停止该项目的命令为：

sudo supervisorctl stop my - spring - boot - project

执行该命令后，supervisor 会向项目进程发送停止信号，项目进程会按照正常的关闭流程进行关闭。如果项目停止成功，再次使用supervisorctl status命令查看项目状态时，会显示STOPPED。

2. 重启项目：当我们需要对项目进行一些更新，如代码更新、配置文件修改后，就需要重启项目使新的更改生效。使用supervisorctl restart命令可以轻松实现项目的重启。对于my - spring - boot - project项目，重启命令如下：

sudo supervisorctl restart my - spring - boot - project

执行该命令后，supervisor 会先停止项目进程，然后再重新启动它。重启过程中，我们可以通过查看日志文件（/var/log/my - spring - boot - project.out.log和/var/log/my - spring - boot - project.err.log）来了解项目重启的进度和是否存在异常情况。如果项目重启成功，使用supervisorctl status命令查看项目状态时，会显示RUNNING。

（二）查看日志

在项目的开发和运维过程中，查看日志是了解项目运行情况、排查问题的重要手段。supervisorctl 提供了方便的命令来查看由其管理的 Spring Boot 项目的日志。

我们可以使用supervisorctl tail命令来查看项目的日志。该命令有不同的参数选项，可以满足我们不同的查看需求。

• 查看最新日志：要查看项目的最新日志内容，可以使用以下命令：

sudo supervisorctl tail my - spring - boot - project

这个命令会输出项目日志文件的最后 10 行内容（默认情况下），让我们能够快速了解项目最近的运行情况。如果项目出现了异常，通过查看最新日志，我们可以第一时间发现错误信息。

• 实时跟踪日志：如果我们想要实时跟踪项目的日志输出，以便及时发现问题，可以使用-f参数，命令如下：

sudo supervisorctl tail -f my - spring - boot - project

执行该命令后，日志会实时输出到终端，就像使用tail -f命令查看普通日志文件一样。当项目在运行过程中产生新的日志时，我们可以在终端中立即看到，这对于调试和监控项目的实时运行状态非常有帮助。例如，当项目在处理一些实时请求时，我们可以通过实时跟踪日志，查看请求的处理过程和结果，及时发现潜在的问题。

• 指定日志行数：如果我们想要查看更多或更少的日志行数，可以使用-n参数来指定行数。例如，要查看项目日志的最后 50 行内容，可以使用以下命令：

sudo supervisorctl tail -n 50 my - spring - boot - project

通过灵活使用这些参数，我们可以根据实际需求，方便地查看项目的日志信息，从而更好地对项目进行调试和维护。

七、总结与展望

通过以上步骤，我们详细了解了如何使用 supervisorctl 部署 Spring Boot 项目。这种部署方式具有诸多优势，它极大地简化了 Spring Boot 项目在生产环境中的部署和管理流程，让我们能够更加高效地将项目推向线上。

supervisorctl 提供的自动重启功能，就像为项目配备了一位不知疲倦的守护者，时刻监控着项目进程，一旦出现异常，能迅速做出反应，自动重启项目，确保项目的高可用性，这在实际生产环境中是至关重要的，大大减少了因进程意外终止而导致的服务中断时间，提升了用户体验。

同时，其方便的日志管理功能，让我们可以轻松查看项目的运行日志，为项目的调试和维护提供了有力支持。当项目出现问题时，我们可以通过查看日志，快速定位问题所在，从而及时解决问题，提高了项目的可维护性。

展望未来，随着微服务架构的普及和应用场景的不断拓展，supervisorctl 在多服务管理和容器编排等场景中有着更广阔的应用前景。在微服务架构中，一个应用往往由多个微服务组成，每个微服务都需要独立的进程管理，supervisorctl 可以对这些微服务的进程进行统一管理，确保整个微服务架构的稳定运行。

在容器编排领域，虽然目前有 Kubernetes 等强大的工具，但 supervisorctl 也可以作为一种轻量级的解决方案，在一些小型项目或对资源消耗要求较高的场景中发挥作用。它可以与容器技术相结合，实现对容器内进程的有效管理，为容器化应用的部署和运维提供更多的选择。

希望通过本文的介绍，能帮助更多开发者掌握使用 supervisorctl 部署 Spring Boot 项目的方法，在项目部署和管理的道路上更加得心应手，提升开发和运维效率，让技术更好地服务于业务。