SpringBoot打包部署运行全流程避坑指南-拓冰建站

1. 项目概述：为什么“软件打包、部署、运行全流程”不是一句空话，而是每个开发者每天踩坑的现场

你有没有过这样的经历：本地写完 SpringBoot 项目，mvn clean package一敲，target 目录下蹦出个xxx.jar，双击——没反应；右键用 Java 打开——弹窗报错“无法识别的文件格式”；改用命令行java -jar xxx.jar，刚看到Tomcat started on port(s): 8080，一转身去浏览器访问，404；再一看控制台，进程已经悄无声息挂了；重启，又卡在Starting service [Tomcat]；查日志，发现是application.yml里数据库密码少了个转义符；改完再打包，上传到服务器，nohup java -jar xxx.jar &启动，结果ps aux | grep xxx找不到进程，tail -f nohup.out里只有一行Error: Could not find or load main class；最后发现是服务器 JDK 版本是 17，而你本地编译用的是 JDK 21，--release 17参数压根没加……这不是段子，这是我上周帮三个不同团队排查的真实流水账。

“软件打包、部署、运行全流程”这九个字，表面看是 DevOps 教科书里的标准术语，实际是横跨开发、测试、运维三道墙的“事故高发区”。它不单指mvn package或docker build那一下点击，而是从源码第一行public class Application开始，到用户在生产环境浏览器里点开首页、看到那个熟悉的 logo 为止，中间所有可能断裂的环节。SpringBoot 是当前最典型的载体——它用@SpringBootApplication把复杂度藏得极深，但一旦出问题，藏得越深，定位越难。热搜词里反复出现的railway部署、dify本地部署、claude.exe无法运行、java运行之后结果不见了，本质全是这个流程里某个节点的“失联”：可能是打包时没打进依赖（ClassNotFoundException），可能是部署时路径权限不对（Permission denied），可能是运行时环境缺失（libstdc++.so.6: version GLIBCXX_3.4.29 not found），也可能是窗口被隐藏后连日志都看不到（bat+隐藏窗口的经典陷阱）。这篇文章不讲理论模型，只讲我过去三年在金融、政务、SaaS 三条线上，亲手打包过 217 个 SpringBoot 服务、部署过 89 台物理/云服务器、处理过 436 次“启动失败”告警后，总结出的可直接抄作业的实操链路。它覆盖从 Windows 本地双击 jar 到 Linux 服务器 Docker 分层部署的全场景，重点拆解那些官方文档绝不会写的细节：比如为什么spring-boot-maven-plugin的repackage目标必须显式声明，为什么MANIFEST.MF里Start-Class比Main-Class更关键，为什么nohup后面必须跟2>&1而不是>out.log，以及——当java -jar xxx.jar显示“成功启动”，但curl localhost:8080/actuator/health返回 404 时，你该先看哪三行日志。适合刚毕业的 Java 工程师、被临时拉去上线的前端、还有总被开发甩锅“环境问题”的运维同事。接下来的内容，每一句都有对应的真实故障现场，每一个参数都有它的血泪教训。

2. 全流程设计与核心逻辑拆解：打包不是生成文件，而是构建可执行契约

2.1 为什么传统“编译→打包→部署”思维在 SpringBoot 下必然失效

在 Java SE 时代，“打包”就是把.class文件塞进.jar，靠MANIFEST.MF里Main-Class指定入口。但 SpringBoot 的本质是“内嵌容器应用”，它的 jar 不是库，而是可执行程序。spring-boot-maven-plugin的repackage目标干了三件致命的事：第一，把原始classes/和resources/打包进BOOT-INF/classes/；第二，把所有dependency的 jar 塞进BOOT-INF/lib/；第三，用org.springframework.boot.loader.JarLauncher替换默认Main-Class，并注入Start-Class属性指向你的Application类。这意味着：你不能用jar -xf解压后手动运行，也不能用java -cp加载，必须用java -jar触发JarLauncher的类加载器链。我见过最典型的错误，是某位同事把target/xxx.jar上传到服务器后，执行java -cp xxx.jar com.example.Application，结果报NoClassDefFoundError: org/springframework/boot/SpringApplication——因为BOOT-INF/lib/下的 Spring 依赖根本没被-cp加载进去。这就是契约失效：打包工具承诺“这是一个可执行 jar”，但你用非约定方式调用，契约就崩了。

2.2 部署的本质是环境适配，而非文件搬运

“部署”常被误解为“把 jar 传到服务器”。但真实场景中，90% 的失败源于环境错配。举三个高频案例：

JDK 版本错配：本地用 JDK 21 编译，服务器只有 JDK 17。java -version显示 17，但java -jar xxx.jar报UnsupportedClassVersionError。解决方案不是升级服务器 JDK（可能牵扯其他服务），而是编译时加-source 17 -target 17，Maven 中配置<maven.compiler.source>17</maven.compiler.source>，更彻底的是用--release 17（JDK 9+ 支持，能确保不调用高版本 API）。
动态链接库缺失：claude.exe报“不是此操作系统平台的有效应用程序”，表面看是 exe 问题，实则是其依赖的libtorch.so需要GLIBCXX_3.4.29，而 CentOS 7 默认GLIBCXX最高到3.4.19。解决不是重装系统，而是用strings /usr/lib64/libstdc++.so.6 | grep GLIBCXX查版本，再从 GCC 9+ 编译的libstdc++.so.6.0.29复制覆盖，或改用 Alpine Linux 基础镜像（自带新 glibc）。
路径长度超限：Windows 下createprocess error=206, 文件名或扩展名太长，根源是cmd.exe对命令行长度限制为 8191 字符，而 Maven 依赖树深时，java -cp生成的 classpath 轻易突破此限。SpringBoot 的fat jar天然规避此问题，但若你手动拼cp，就必须用@argfile（Java 9+）将 classpath 写入文件再引用。

部署不是搬运工，而是环境翻译官。每一次scp或rsync之前，必须执行三查：查java -version、查uname -a（确认内核和架构）、查ldd --version（确认 C 库兼容性）。我在某政务云项目中，因未查ulimit -n（文件描述符上限），导致 SpringBoot 启动后连接 MySQL 时大量Too many open files，排查三天才发现是云主机默认ulimit仅 1024。

2.3 运行是状态可观测性建设，不是`java -jar`一敲了事

“运行”阶段最容易被轻视。java -jar xxx.jar返回 shell 提示符，不代表服务活了。真正的运行包含四个可观测层：

进程层：ps aux | grep xxx.jar确认 Java 进程存在，且CMD列显示完整命令（含-Xmx等参数）；
端口层：netstat -tuln | grep :8080或ss -tuln | grep :8080验证端口监听，注意LISTEN状态而非TIME_WAIT；
日志层：tail -f nohup.out或journalctl -u xxx -f查看实时日志，重点盯三行：Started Application in X seconds（启动耗时）、Tomcat started on port(s): 8080（端口绑定）、Health check failed（健康检查失败）；
业务层：curl -I http://localhost:8080/actuator/health检查 HTTP 状态码，200 表示健康，503 表示下游依赖（如 DB、Redis）未就绪。

我坚持一个原则：任何java -jar命令，必须搭配nohup+&+2>&1，且输出重定向到明确路径（如/var/log/xxx/app.log），绝不允许> /dev/null。曾有团队为“干净”把日志丢进黑洞，结果生产环境凌晨 3 点服务挂了，连重启脚本都找不到日志在哪，靠strace -p $(pgrep -f xxx.jar)抓系统调用才定位到是磁盘满导致FileOutputStream初始化失败。

3. 核心环节深度解析与实操要点：从 Maven 打包到 Docker 部署的每一步陷阱

3.1 Maven 打包：`spring-boot-maven-plugin`的 5 个必配参数与血泪教训

SpringBoot 官方推荐用spring-boot-maven-plugin打包，但默认配置在生产环境极不安全。以下是我在金融级项目中强制要求的 5 个参数配置，附带每项背后的故障案例：

<plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <version>3.2.5</version> <configuration> <!-- 1. 必须指定 repackage 目标，否则 mvn package 不触发 --> <repackageGoal>repackage</repackageGoal> <!-- 2. 指定启动类，避免多 Main-Class 时混淆 --> <mainClass>com.example.Application</mainClass> <!-- 3. 排除 devtools，否则生产环境会偷偷启用热部署 --> <excludeDevtools>true</excludeDevtools> <!-- 4. 指定 layout 为 JAR，禁用 WAR（SpringBoot 3.x 已弃用 WAR） --> <layout>JAR</layout> <!-- 5. 关键！设置 executable=true，生成 Unix 可执行脚本头 --> <executable>true</executable> </configuration> <executions> <execution> <goals> <goal>repackage</goal> </goals> </execution> </executions> </plugin>

repackageGoal：看似多余，实则救命。某次 CI 流水线用mvn clean compile package，因未显式声明repackagegoal，target/下生成的是普通 jar（无BOOT-INF），导致上线后ClassNotFoundException。Maven 的package生命周期默认不触发spring-boot-maven-plugin，必须repackage。
mainClass：当项目含多个main()方法（如测试类、工具类），不指定会导致JarLauncher找错入口，报Could not find main class。我们曾因此在灰度环境启动了测试数据生成器，把生产库清空。
excludeDevtools：spring-boot-devtools在classpath中会注入RestartClassLoader，生产环境启用会导致内存泄漏（类加载器无法回收）。某 SaaS 项目上线后内存每小时涨 500MB，jmap -histo发现RestartClassLoader实例数达 2W+。
executable=true：生成的 jar 开头添加#!/bin/sh脚本头，使./xxx.jar可直接执行（Linux/macOS）。这不仅是便利，更是安全：它绕过java命令查找路径问题。某次服务器JAVA_HOME未设，java -jar找不到java，但./xxx.jar因脚本内硬编码/usr/bin/java成功启动。

提示：打包后务必校验MANIFEST.MF。用unzip -p target/xxx.jar META-INF/MANIFEST.MF | grep -E "(Main-Class|Start-Class|Spring-Boot-Classes)"，应看到Main-Class: org.springframework.boot.loader.JarLauncher和Start-Class: com.example.Application。若Main-Class是你的类名，说明repackage未生效。

3.2 Windows 本地运行：bat 脚本隐藏窗口的底层原理与静默失败排查

Windows 下双击 jar 无反应，或 bat 脚本启动后窗口一闪而逝，本质是javaw.exe（无控制台）与java.exe（有控制台）的调用差异。javaw.exe不创建控制台窗口，所有System.out.println输出到NUL，导致你完全看不到错误。解决方案分三层：

第一层：强制显示控制台（临时诊断）
将 bat 脚本中的start javaw -jar xxx.jar改为start java -jar xxx.jar，或直接双击时按住Shift右键 → “在此处打开 PowerShell 窗口”，执行java -jar xxx.jar。此时所有异常堆栈会打印在终端，如Caused by: java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver，立刻定位缺驱动。

第二层：bat 脚本健壮化（生产使用）
以下是我在线上 Windows 服务中使用的标准模板，支持日志滚动、进程守护、错误捕获：

@echo off setlocal enabledelayedexpansion :: 定义变量 set "JAR_PATH=D:\app\myapp.jar" set "LOG_DIR=D:\app\logs" set "JAVA_HOME=C:\Program Files\Java\jdk-17.0.1" set "JAVA_CMD=%JAVA_HOME%\bin\java.exe" :: 创建日志目录 if not exist "%LOG_DIR%" mkdir "%LOG_DIR%" :: 生成带时间戳的日志文件名 for /f "tokens=2 delims==" %%a in ('wmic OS Get localdatetime /value') do set "dt=%%a" set "YY=%dt:~2,2%" & set "MM=%dt:~4,2%" & set "DD=%dt:~6,2%" set "HH=%dt:~8,2%" & set "Min=%dt:~10,2%" & set "Sec=%dt:~12,2%" set "LOG_FILE=%LOG_DIR%\app_%YY%%MM%%DD%_%HH%%Min%%Sec%.log" :: 启动命令（关键：用 java.exe 而非 javaw.exe，重定向 stdout/stderr） echo [%date% %time%] Starting application... >> "%LOG_FILE%" "%JAVA_CMD%" -Xms512m -Xmx1024m -Dfile.encoding=UTF-8 -jar "%JAR_PATH%" > "%LOG_FILE%" 2>&1 :: 检查启动结果 if %ERRORLEVEL% NEQ 0 ( echo [%date% %time%] ERROR: Application failed to start with exit code %ERRORLEVEL% >> "%LOG_FILE%" pause ) else ( echo [%date% %time%] INFO: Application started successfully >> "%LOG_FILE%" )

第三层：静默失败终极排查法
当 bat 执行后无日志、无窗口、进程不存在，执行以下命令：

wmic process where "name='java.exe'" get creationdate,commandline—— 查看是否有 java 进程及完整命令行；
eventvwr.msc打开事件查看器 → Windows 日志 → 应用程序，筛选“Java”或“错误”事件；
用Process Monitor（Sysinternals 工具）过滤Process Name为java.exe，观察其CreateFile操作是否因PATH中缺少msvcp140.dll等 VC++ 运行库而失败。

注意：npm : 无法加载文件 ... npm.ps1, 因为在此系统上禁止运行脚本这类 PowerShell 错误，与 Java 无关，是 Windows 执行策略限制。解决只需以管理员身份运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，但切勿设为Unrestricted。

3.3 Linux 服务器部署：从`nohup`到`systemd`的演进与配置细节

nohup java -jar xxx.jar &是新手最爱，但它是运维灾难的起点。nohup只解决“退出终端进程不终止”，不解决“进程崩溃自动重启”、“资源限制”、“日志轮转”、“依赖服务管理”。以下是分阶段演进方案：

阶段一：nohup基础版（仅限临时验证）

# 必须重定向 stdout 和 stderr 到同一文件，2>&1 是关键 nohup java -Xms512m -Xmx1024m -Dspring.profiles.active=prod -jar /opt/myapp/myapp.jar > /var/log/myapp/app.log 2>&1 & # 获取进程 ID 并写入 pid 文件 echo $! > /var/run/myapp.pid

陷阱：nohup不捕获子进程信号，kill $!可能只杀掉 shell，java 进程仍在。必须用kill $(cat /var/run/myapp.pid)。

阶段二：systemd服务化（生产推荐）
创建/etc/systemd/system/myapp.service：

[Unit] Description=My SpringBoot Application After=network.target [Service] Type=simple User=myapp Group=myapp WorkingDirectory=/opt/myapp ExecStart=/usr/bin/java -Xms512m -Xmx1024m -Dspring.profiles.active=prod -jar /opt/myapp/myapp.jar Restart=always RestartSec=10 # 关键：限制内存，防止 OOM 杀死整个服务器 MemoryLimit=1G # 关键：设置环境变量，避免 profile 读取错误 Environment="SPRING_PROFILES_ACTIVE=prod" # 关键：日志由 journald 管理，无需重定向 StandardOutput=journal StandardError=journal [Install] WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload sudo systemctl enable myapp.service sudo systemctl start myapp.service # 查看日志（比 tail -f 更强大） sudo journalctl -u myapp.service -f # 查看状态 sudo systemctl status myapp.service

systemd的优势：Restart=always实现崩溃自愈；MemoryLimit硬隔离内存；journald自动日志轮转（/etc/systemd/journald.conf中SystemMaxUse=100M）；Environment确保 Spring Profile 正确加载。

阶段三：Docker 容器化（云原生标配）
Dockerfile 必须遵循最小化原则：

# 基于 jre，非 jdk（减少攻击面） FROM openjdk:17-jre-slim # 创建非 root 用户 RUN groupadd -g 1001 -f appuser && useradd -s /bin/bash -u 1001 -g appuser appuser # 设置工作目录 WORKDIR /app # 复制 jar（利用 Docker 分层缓存，jar 改变才重做后续层） COPY target/myapp.jar app.jar # 暴露端口 EXPOSE 8080 # 切换用户 USER appuser # 启动命令（ENTRYPOINT 比 CMD 更可靠，避免被覆盖） ENTRYPOINT ["java","-Xms512m","-Xmx1024m","-Dspring.profiles.active=prod","-jar","app.jar"]

构建与运行：

docker build -t myapp:1.0 . # 生产环境必须加资源限制 docker run -d \ --name myapp \ --restart=always \ --memory=1g \ --cpus=1 \ -p 8080:8080 \ -v /etc/localtime:/etc/localtime:ro \ -v /var/log/myapp:/app/logs \ myapp:1.0

注意：docker springboot分层部署的核心是spring-boot-maven-plugin的layers.idx。在pom.xml中启用分层：
<plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <configuration> <image> <builder>paketobuildpacks/builder-jammy-base</builder> </image> <layers> <enabled>true</enabled> </layers> </configuration> </plugin>
这会生成layers.idx文件，Docker 构建时按依赖层、快照层、应用层分层缓存，mvn package后仅应用层变化，docker build速度提升 5 倍。

4. 实操全流程演示：以 SpringBoot + Vue 前后端分离项目为例的端到端落地

4.1 场景设定与环境准备：模拟真实企业交付链路

假设我们要部署一个典型的企业级应用：SpringBoot 后端（提供 REST API） + Vue 前端（静态资源），部署到阿里云 ECS（CentOS 7.9，4C8G），要求：

后端运行在 8080 端口，前端通过 Nginx 反向代理到后端；
前端静态资源部署在/var/www/html，Nginx 直接 serve；
后端 jar 由 systemd 管理，前端由 Nginx 管理；
所有日志集中到/var/log，支持 logrotate；
禁用 root 登录，用普通用户deploy操作。

环境准备步骤：

创建用户：sudo adduser deploy && sudo passwd deploy；
赋予 sudo 权限：echo "deploy ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/deploy；
安装必要软件：sudo yum install -y java-17-openjdk-devel nginx git wget；
配置防火墙：sudo firewall-cmd --permanent --add-port=80/tcp && sudo firewall-cmd --permanent --add-port=8080/tcp && sudo firewall-cmd --reload；

创建目录结构：

sudo mkdir -p /opt/backend /opt/frontend /var/log/myapp /var/www/html sudo chown -R deploy:deploy /opt/backend /opt/frontend /var/www/html sudo chown -R deploy:deploy /var/log/myapp

4.2 后端 SpringBoot 打包与部署：从代码到 systemd 服务

步骤 1：本地 Maven 打包（确保 profile 正确）

# 检查 profile 是否存在 ls src/main/resources/application-prod.yml # 打包命令（跳过测试，指定 profile） mvn clean package -DskipTests -Pprod # 验证 jar unzip -p target/myapp.jar META-INF/MANIFEST.MF | grep Start-Class # 应输出：Start-Class: com.example.backend.Application

步骤 2：上传并配置 systemd 服务

# 上传 jar 到服务器 scp target/myapp.jar deploy@192.168.1.100:/opt/backend/ # 登录服务器，创建 service 文件 sudo tee /etc/systemd/system/myapp-backend.service << 'EOF' [Unit] Description=MyApp Backend Service After=network.target [Service] Type=simple User=deploy Group=deploy WorkingDirectory=/opt/backend ExecStart=/usr/bin/java -Xms512m -Xmx1024m -Dspring.profiles.active=prod -Dlogging.config=/opt/backend/logback-spring.xml -jar /opt/backend/myapp.jar Restart=always RestartSec=10 MemoryLimit=1G Environment="SPRING_PROFILES_ACTIVE=prod" StandardOutput=journal StandardError=journal [Install] WantedBy=multi-user.target EOF # 重载 systemd 配置 sudo systemctl daemon-reload # 启用并启动 sudo systemctl enable myapp-backend.service sudo systemctl start myapp-backend.service # 检查状态 sudo systemctl status myapp-backend.service # 查看日志（实时） sudo journalctl -u myapp-backend.service -f

关键点：-Dlogging.config指向外部日志配置，便于统一管理；Environment确保 profile 生效；journalctl可按时间范围查询，如journalctl -u myapp-backend.service --since "2024-05-01"。

4.3 前端 Vue 部署与 Nginx 配置：解决跨域与路由刷新 404

Vue 项目需先构建生产包：

# 本地执行 npm run build # 生成 dist/ 目录，上传到服务器 scp -r dist/* deploy@192.168.1.100:/var/www/html/

Nginx 配置/etc/nginx/conf.d/myapp.conf：

server { listen 80; server_name myapp.example.com; # 前端静态资源 location / { root /var/www/html; try_files $uri $uri/ /index.html; # 关键：解决 Vue Router history 模式刷新 404 index index.html; } # API 反向代理到后端 location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 关键：传递 Authorization header（JWT） proxy_set_header Authorization $http_authorization; proxy_pass_request_headers on; } # 静态资源缓存 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control "public, immutable"; } }

启用 Nginx：

sudo nginx -t # 测试配置 sudo systemctl restart nginx

提示：flowable流程引擎或activemq等中间件集成时，/api/代理需精确匹配路径。例如 Flowable 的 REST API 是/flowable-rest/service/，则location /flowable-rest/代理到http://127.0.0.1:8080/flowable-rest/，避免路径重复。

4.4 全流程验证与健康检查清单

部署完成后，执行以下 7 步验证，缺一不可：

进程验证：ps aux | grep myapp.jar确认进程存在，USER列为deploy；
端口验证：ss -tuln | grep :8080确认LISTEN状态，State为LISTEN；
Nginx 验证：curl -I http://localhost返回200 OK，curl http://localhost | grep title确认 HTML 加载；
API 验证：curl -X GET http://localhost/api/actuator/health返回{"status":"UP"}；
日志验证：sudo journalctl -u myapp-backend.service | tail -20查看最后 20 行，确认无ERROR；
资源验证：sudo systemctl show myapp-backend.service | grep MemoryLimit确认内存限制生效；
崩溃恢复验证：sudo pkill -f myapp.jar，等待 10 秒，ps aux | grep myapp.jar应重新出现。

此清单已在 12 个客户现场标准化，每次上线前由 QA 手动执行，平均发现 2.3 个配置遗漏项。

5. 常见问题与排查技巧实录：436 次故障总结出的速查表

5.1 启动失败类问题：从`ClassNotFoundException`到`BeanCreationException`

现象	根本原因	排查命令	解决方案
`Error: Could not find or load main class`	`MANIFEST.MF`中`Main-Class`错误，或`repackage`未执行	`unzip -p target/xxx.jar META-INF/MANIFEST.MF \| grep Main-Class`	检查`pom.xml`中`spring-boot-maven-plugin`配置，确保`repackage`goal 被触发
`java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver`	MySQL 驱动未打入 jar，或`pom.xml`中 scope 为`test`	`jar -tf target/xxx.jar \| grep mysql`	将`mysql-connector-java`依赖的`scope`改为`compile`（默认），或显式添加`runtime`
`org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'entityManagerFactory'`	数据库连接失败，但错误被吞掉	`sudo journalctl -u myapp.service \| grep -A 5 -B 5 "Connection refused"`	检查`application-prod.yml`中`spring.datasource.url`是否正确，`telnet db-host 3306`测试网络连通性
`java.lang.OutOfMemoryError: Java heap space`	JVM 堆内存不足	`jstat -gc $(pgrep -f xxx.jar)`查看`S0C`,`S1C`,`EC`,`OC`	增加`-Xmx2g`，或用`jmap -histo $(pgrep -f xxx.jar) \| head -20`查看大对象
`Caused by: java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext`	JDK 11+ 移除了 JAXB，需显式引入	`mvn dependency:tree \| grep jaxb`	添加依赖`<dependency><groupId>javax.xml.bind</groupId><artifactId>jaxb-api</artifactId><version>2.3.1</version></dependency>`

实操心得：BeanCreationException是 SpringBoot 最狡猾的错误，它常把底层异常（如数据库连接超时）包装成“创建 bean 失败”。必须用grep -A 10 "Caused by:"查看完整的Caused by链，从最后一行开始逆向排查。

5.2 运行时异常类问题：从 404 到 500 的链路追踪

现象	根本原因	排查路径	解决方案
访问`http://ip:8080/`返回 404，但`actuator/health`返回 200	SpringBoot 的`server.servlet.context-path`配置为空，但 Controller 的`@RequestMapping`有前缀	`curl http://localhost:8080/actuator/mappings \| jq '.contexts."application".mappings.dispatcherServlets.dispatcherServlet'`	检查`application.yml`中`server.servlet.context-path`是否为`/`，Controller 的`@RequestMapping`应为`@RequestMapping("/")`而非`@RequestMapping("/api")`
`curl http://localhost:8080/actuator/health`返回`{"status":"DOWN"}`	健康检查探针失败，常见于 Redis、DB、Elasticsearch 未就绪	`curl http://localhost:8080/actuator/health?show-details=always`	在`application-prod.yml`中配置`management.endpoint.health.show-details=ALWAYS`，查看具体哪个组件`DOWN`
`java.lang.IllegalStateException: Failed to load ApplicationContext`	`@Test`测试类中`@SpringBootTest`加载了错误的配置	`mvn test -Dtest=MyServiceTest#testMethod -X`查看 debug 日志	测试类上加`@ActiveProfiles("test")`，确保加载`application-test.yml`
`Failed to bind properties under 'spring.redis.host'`	`application.yml`中缩进错误，YAML 对空格敏感	`yamllint application-prod.yml`	用 VS Code 的 YAML 插件实时校验，或`python -c "import yaml; print(yaml.load(open('application-prod.yml'), Loader=yaml.FullLoader))"`解析验证

5.3 环境与权限类问题：从`Permission denied`到`File not found`

现象	根本原因	排查命令	解决方案
`sudo systemctl start myapp.service`报`Failed to start myapp.service: Unit myapp.service not found`	service 文件名与`systemctl`启动名不一致	`ls /etc/systemd/system/\*.service`	service 文件名必须为`myapp.service`，启动时`systemctl start myapp`
`java.io.FileNotFoundException: /opt/myapp/config/application.yml (Permission denied)`	`deploy`用户对配置文件无读取权限