宝塔面板部署 Spring Boot 3.2从 jar 到 HTTPS 的常见坑清单把 Spring Boot 3.2 的 jar 部署到宝塔并配好 HTTPS失败通常落在三个位置。jar 直接起不来日志第一行写着 UnsupportedClassVersionErrorclass file version 61.0。jar 起来得很干净浏览器一访问却在 https 和 http 之间来回跳或者上传稍大的文件就报 413。前面都通了证书到期的某一天整站突然打不开。这三类失败各自堵着一个接口。第一类卡在 JDK 与字节码之间第二类卡在 nginx 与应用的转发约定上第三类卡在证书续期与 nginx 重载的衔接上。报错出现在哪一层就先查哪一层。每条坑下面都给报错特征、原因、修法和一个本地自查命令方便照着跑。清单里的版本事实按 Spring Boot 3.2 这一代的公开文档口径nginx 部分按官方模块的默认值命令都可以在你的服务器上直接执行。宝塔面板各版本的界面和生成的配置有差别写到面板的地方以你手里的版本为准。下面是整份清单的排错总览。失败按启动层、反代层、证书层三层展开报错出现在哪一层就先查哪一层jar 起不来起来了但访问不对能访问但会自己断部署后访问失败报错出现在哪一层?启动层反代层证书层UnsupportedClassVersionErrorclass file version 61.0堆栈类名以 javax 开头nohup 挂进程终端一断就没了HTTPS 和 HTTP 之间来回跳上传稍大文件就 413WebSocket 握手失败curl -v 分层排查证书到期后整站打不开修法换 JDK 17 绝对路径修法javax 依赖升级导入改 jakarta修法宝塔项目管理或 systemd 托管修法Nginx 传转发头应用声明信任转发头修法放大 client_max_body_size与 multipart 上限修法透传 Upgrade 与 Connection 头按 curl 返回码定位refused / 502 / 504修法续期后执行 Nginx reload启动层jar 起不来1. UnsupportedClassVersionErrorclass file version 61.0报错java.lang.UnsupportedClassVersionError: com/example/App has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0机制Spring Boot 3.x 要求 Java 17 起步编译出的 class 文件版本号是 61.0。低版本 JVM 只认得更低的版本号加载时直接拒绝。报错里写着只认到 55.0对应的是 Java 11说明启动脚本实际用的 JVM 是 JDK 11。机器上装着多个 JDK 时宝塔生成的启动脚本或 systemd 服务没有写死 JDK 路径就会用到默认那个。修法把启动命令里的 java 换成 JDK 17 以上版本的绝对路径例如/usr/lib/jvm/jdk-17/bin/java -jar app.jar。用 systemd 托管时把绝对路径写进 unit 文件的 ExecStart。自查在启动脚本实际使用的环境里跑java -version确认版本是 17 或更高。class 文件版本号按 JVM 规范核对61 对应 Java 1755 对应 Java 1152 对应 Java 8。2. 堆栈里的类名以 javax 开头报错java.lang.ClassNotFoundException: javax.servlet.Filter或者同类的NoClassDefFoundError出错的类名以javax开头。机制Spring Boot 3 基于 Jakarta EE 10Servlet 系列的包名从javax换成了jakarta内嵌的 Tomcat 10.1 只带jakarta的类。还引用javax的老依赖在 Boot 3 上找不到类。老版本的过滤器、鉴权库以及自己写的Filter、Servlet、监听器是常见的出错点。修法升级还挂在javax上的依赖把自己代码里的javax.servlet导入改成jakarta.servlet。自查先看堆栈里的类名前缀。类名以javax开头的是这层问题类名已经是jakarta开头就往别处查。启动这层还有一个不报错的问题。用nohup把进程挂在 SSH 会话里终端一断进程就没了日志还会无限涨。用宝塔的项目管理或systemd托管把启动命令、自动拉起和日志路径固定下来。前者省事后者离开面板还能带走按这台机器以后归谁维护来选。反代层起来了但访问不对3. 在 HTTPS 和 HTTP 之间来回跳机制Nginx 在 443 终结 TLS转发给应用的请求是 HTTP。应用按请求的 scheme 生成跳转地址时看到的是 HTTP一跳就掉出 HTTPS。浏览器里表现为重定向被拦截或者页面混着 HTTP 资源被拦掉样式丢失。修法Nginx 侧传转发头应用侧声明信任转发头。location / { 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; }server:forward-headers-strategy:native自查curl -I https://你的域名/某个会触发跳转的地址看 Location 头里的协议是 HTTPS 还是 HTTP。4. 上传稍大的文件就 413报错413 Request Entity Too Large。机制Nginx 的 client_max_body_size 默认值是 1mSpring 的 multipart 也有自己的上限。请求要连过两道门槛哪一道先拦住都算数只放行其中一处没有用。修法在反代配置的 server 或 location 里设client_max_body_size 50m;同步放大应用侧的 spring.servlet.multipart.max-file-size 和 max-request-size。自查nginx -T | grep client_max_body_size看生效值。两处限制谁小谁说了算改完再看一次。5. WebSocket 握手失败报错特征浏览器开发者工具的网络面板里WebSocket 请求握手返回 400 或 502。只看页面会以为功能坏了状态码藏在开发者工具里。机制WebSocket 握手带 Upgrade 和 Connection 两个头Nginx 默认按普通请求转发不透传它们握手到不了应用。修法在 Nginx 的 http 段定义 map在反代的 location 里透传这两个头。map $http_upgrade $connection_upgrade { default upgrade; close; } location /ws { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; }自查面板生成的反代配置里如果没有这两行 proxy_set_header补上再 reload。6. 不通的时候先分清谁拒绝了你改完配置还是不通curl -v是分层的第一件工具。返回 connection refused说明 443 或 80 没有人监听去查防火墙和安全组。宝塔的安全页管一层云厂商的安全组管另一层两层都要放行 80 和 443。返回 502 Bad Gateway说明 nginx 活着转发的上游不通对比反代的 proxy_pass 端口和应用实际监听的 server.port。返回 504 Gateway Time-out说明上游太慢去反代的读超时设置里找。把curl -v的返回码和对应排查方向画成一张图方便对照connection refused502 Bad Gateway504 Gateway Time-outcurl -v 访问不通返回什么?443 / 80 无人监听查宝塔安全页放行 80 / 443查云厂商安全组放行 80 / 443Nginx 活着上游不通对比 proxy_pass 端口与应用 server.port上游响应太慢调反代读超时设置证书层能访问但会自己断7. 证书到期后整站突然打不开机制HTTPS 证书有效期有限到期后浏览器直接拒绝连接。自动续期任务跑完还要让 Nginx 重新加载配置否则服务用的还是内存里的旧证书。修法用面板的证书自动续期或 Certbot 的定时任务确认续期后的动作里有 Nginx reload 这一步。自查echo | openssl s_client -connect 你的域名:443 -servername 你的域名 2/dev/null | openssl x509 -noout -dates看 notAfter 离现在还有多久。具体有效期以签发方公布为准这些年行业里的方向是越来越短别按某一篇教程记死天数。适用边界清单里的版本事实固定在 Spring Boot 3.2 这一代换到 4.x 或者更老的 2.x要重新对一遍要求。面板的界面、生成的配置和证书功能随版本变化写到面板的地方以你的版本为准。这份清单整理自公开文档和常见报错没有在宝塔上实机跑完一整条流程每条都留了自查命令方便你逐条对照。应用本身的业务异常、性能和安全加固不在这份清单里报错落不到上面几层时问题多半在应用自己身上。