Spring Boot 项目里折腾 Tomcat如果你还停留在改个端口号就完事的阶段那这篇内容正好是给你准备的。Tomcat 作为 Spring Boot 默认内置的 Web 容器绝大多数开发者每天其实都在跟它打交道但真正把它配置明白的人并不多。别人线上接口高并发扛得住、重启快、日志清爽你的服务一压测就超时、莫名 404、CPU 飙高——这些差距往往就藏在 Tomcat 的细节配置里。我整理了一份从参数拆解到部署实战、从日常问题到性能调优的完整笔记覆盖application.yml里最常见的配置项、JAR 与 WAR 打包方式的取舍、Java 21 虚拟线程接入后的线程模型变化以及 Linux 环境下部署时容易踩的坑。无论你是刚把第一个 Spring Boot 程序跑起来的新手还是打算把项目部署到服务器的进阶选手这份内容应该都能帮你少走不少弯路。1. Spring Boot 默认选型与配置全景1.1 为什么 Spring Boot 默认选择 TomcatSpring Boot 的spring-boot-starter-web默认引入的就是内嵌 Tomcat这个选择背后有很实际的历史原因。在早期 SSM 或 SSH 时代开发者必须先装一个独立 Tomcat再把 WAR 包丢进 webapps 目录启动前还要配数据源、配日志框架环境稍微不一致就各种莫名其妙的问题。Spring Boot 把 Tomcat 打成内嵌依赖之后应用自带容器、一键启动部署成本断崖式下降这对开发和运维都是极大的解放。从技术角度看Tomcat 经过二十多年的迭代对 Servlet 规范、HTTP 协议、WebSocket 的支持都已经非常成熟生态里排查问题能搜到的资料也最多。虽然 Jetty 更轻、Undertow 高并发表现更激进但论稳定性和社区成熟度Tomcat 依然是绝大多数项目的稳妥起手式。1.2 项目里 Tomcat 配置通常涉及哪些层面我见过很多同事把 Tomcat 相关的配置只理解成server.port其实完整的配置至少分成四个层次第一层是基础参数比如端口号、上下文路径、编码格式第二层是连接器参数涉及线程池、最大连接数、超时时间第三层是 JVM 层面的参数比如堆内存设置、GC 策略、启动参数第四层是部署方式层面的抉择用内嵌 JAR 还是外置 WAR直接决定了你后面怎么管这台 Tomcat。这几层配置虽然隔着application.yml和catalina.sh两个不同的配置文件但最终都作用于同一个容器实例。理解这层关系你在排查线上问题时就能更准确地判断某个超时错误到底是连接器层面的并发不够还是 JVM 堆内存不足导致的 GC 停顿。2. 内嵌 Tomcat 核心配置参数逐项拆解2.1 端口、上下文与编码配置先看最基础的一块端口和上下文路径。server: port: 8080 servlet: context-path: /api encoding: charset: UTF-8 enabled: true force: trueserver.port决定应用监听端口这一点大家都会。context-path决定访问前缀如果你设置/api那么原来访问http://localhost:8080/hello的接口就变成http://localhost:8080/api/hello。这里有个我在项目里踩过的坑前端联调时如果接口地址写死了没有带前缀你改了 context-path 会导致大量 404。所以通常 context-path 在开发环境不加、在网关统一路由的环境里也不加而是把路由前缀交给网关处理避免多个服务之间上下文冲突。字符编码这块容易被忽略。server.servlet.encoding.force: true的意思是强制请求和响应都用 UTF-8而不管客户端有没有指定其他编码。这个配置在接口返回中文乱码时往往立竿见影建议默认就加上。2.2 线程池参数max-threads、min-spare-threads 与 accept-countTomcat 处理 HTTP 请求的核心模型是线程池参数都在server.tomcat.threads下面server: tomcat: threads: max: 200 min-spare: 20 accept-count: 200max-threads是工作线程的最大数量也就是同一时刻 Tomcat 能够并行处理的请求数。min-spare-threads是启动时预创建的线程数目的是减少请求到来时的线程创建开销。accept-count是请求等待队列的长度当所有工作线程都忙时新的请求会进入这个队列等待。我给一个实际的计算思路。假设线上机器是 4 核 8G接口平均响应时间是 100ms单接口 QPS 目标是 1000。Tomcat 处理能力粗略估算公式是最大 QPS 约等于 (1000ms / 平均响应时间) × max-threads代入上面数据1000 / 100 × 200 2000所以 QPS 目标 1000 的情况下 200 线程是够用的。但注意这只是理想值实际中锁竞争、GC、数据库连接等都会影响建议留出 30% 到 50% 的余量。线程数设置过大有问题吗有。线程只是执行载体真正撑不住的往往是数据库连接池。200 个线程同时去抢 10 个数据库连接大部分线程其实在阻塞等待。所以我现在的习惯是把高并发服务的 Tomcat max-threads 控制在 400 以内同时把数据库连接池最大连接数调到与线程数同一量级避免线程排队浪费。2.3 连接数、超时与 keep-alive 设置细节再往下是连接器层面的参数server: tomcat: max-connections: 10000 connection-timeout: 20000 keep-alive-timeout: 30s max-keep-alive-requests: 200max-connections是 Tomcat 能同时接收的最大 TCP 连接数默认 8192。注意它和 max-threads 不是一回事TCP 连接建立后不一定立即分配处理线程HTTP keep-alive 长连接会占用连接但不占用线程。connection-timeout是等待客户端发送请求的超时时间单位毫秒。keep-alive 这块很多人配置出错。HTTP/1.1 默认开启 keep-alive客户端复用同一个 TCP 连接发多个请求省去反复三次握手的开销。但如果客户端连接池没做限制大量空闲 keep-alive 连接会占满 max-connections新请求反而进不来。所以 keep-alive-timeout 设置成 30 秒比较合理既保证常规复用率又不会让无效长连接一直挂着。2.4 压缩、优雅停机与访问日志配置这几个配置属于体验和运维层面日常很容易被忽略。server: compression: enabled: true mime-types: application/json,application/xml,text/html,text/plain min-response-size: 1024 shutdown: graceful tomcat: accesslog: enabled: true directory: /data/logs/tomcat pattern: %h %l %u %t \%r\ %s %b %D压缩配置建议开尤其是纯 JSON 接口。开启 gzip 后大体积 JSON 响应体常常能压缩到原来的四分之一。min-response-size: 1024的意思是小于 1KB 的响应不压缩避免小响应浪费 CPU 做压缩运算。shutdown: graceful是 Spring Boot 2.3 之后提供的优雅停机开关。开启后应用收到 SIGTERM 信号时不会立刻关闭容器而是先停止接收新请求、等待已接收的请求处理完成再退出。配合spring.lifecycle.timeout-per-shutdown-phase单位秒设置最长等待时间。这个配置在发版时非常有用能明显减少滚动发布过程中的 502 错误。访问日志开启后%D记录请求处理耗时毫秒%F记录耗时秒%b是响应字节数。我一般会把 pattern 里的%D放进去统计慢请求非常方便比在业务代码里手动打耗时日志快得多。3. 部署形式选择与 Linux 环境实操3.1 JAR 内嵌模式与 WAR 外置模式怎么选Spring Boot 提供两种部署形态我根据自己的项目经历说说怎么选。JAR 内嵌模式是默认也是最推荐的。打包后一个可执行 JAR里面既包含代码也包含 Tomcat 运行时用java -jar app.jar直接启动。没有单独的 Tomcat 安装目录JDK 有就行。升级 Spring Boot 版本时容器也随之升级不会出现本地 Tomcat 和项目依赖的 Servlet API 版本错配的问题。适合大多数微服务场景、Docker 部署场景。WAR 外置模式是把项目打成 WAR 包丢进已有的 Tomcat 的 webapps 目录。这种模式适合两种情况一是公司运维明确要求用统一 Tomcat 管理多个应用二是项目依赖外部容器提供的 JNDI 数据源、JMX 监控等能力。代价是打包需要继承SpringBootServletInitializer启动方式也变成由外部 Tomcat 管理应用的启动日志、线程模型、类加载顺序都跟内嵌模式有差异。WAR 模式下有两处必须注意。第一pom.xml里打包方式改为 war 后内置 Tomcat 会被 scope 为 provided否则打出来的 WAR 里还带着 Tomcat部署到外部容器会造成类冲突和端口冲突。第二必须重写configure方法类似下面这样SpringBootApplication public class DemoApplication extends SpringBootServletInitializer { Override protected SpringApplicationBuilder configure(SpringApplicationBuilder application) { return application.sources(DemoApplication.class); } }这段代码的作用是让外部 Tomcat 在启动应用时能找到 Spring Boot 的入口配置类。漏了这一步最常见的错误就是Tomcat 启动后访问任何 URL 都返回 404因为应用根本没有被容器加载起来。3.2 内嵌 JAR 部署时的 JVM 参数设置内嵌 JAR 模式下Tomcat 本身跑在应用进程内部JVM 参数通过启动命令指定。这里列出我自己在 4 核 8G 服务器上常用的参数模板java -Xms2g -Xmx2g \ -XX:MetaspaceSize256m \ -XX:MaxMetaspaceSize512m \ -XX:UseG1GC \ -XX:MaxGCPauseMillis200 \ -XX:DisableExplicitGC \ -Djava.security.egdfile:/dev/./urandom \ -jar app.jarXms和Xmx我倾向于设置成相等避免运行期堆动态扩容导致的性能抖动。G1 GC 是 JDK 11 默认值MaxGCPauseMillis控制期望的 GC 停顿时间。DisableExplicitGC这个参数很多人没加作用是禁止代码里显式调用System.gc()防止某些框架强行触发 Full GC 造成长时间停顿。最后那个-Djava.security.egdfile:/dev/./urandom值得特别说明。Java 在生成安全随机数时默认会读取/dev/random而/dev/random在熵池不足时会阻塞等待导致 Tomcat 启动阶段卡住表现就是应用启动特别慢有时需要几分钟。切到/dev/urandom后启动速度明显提升。如果你遇到过同一个应用在一次环境里秒启、在另一次环境里启动卡半分钟的怪现象大概率就是这个原因。还有一个容易忽略的点不要手动设置-Xss线程栈大小。Tomcat 内部有工作线程池线程栈大小影响内存占用默认 1M 左右通常足够。强行调小虽然能省内存但在深度递归场景下容易导致 StackOverflowError排查起来非常痛苦。3.3 Linux 下部署与开机自启动设置Linux 部署场景分两种用 systemd 管理或者用 Docker。我先说 systemd 方式。首先准备一个部署目录比如/opt/apps/demo上传应用 JAR。然后创建 systemd 服务文件/etc/systemd/system/demo.service[Unit] DescriptionDemo Spring Boot App Afternetwork.target [Service] Typesimple Userappuser WorkingDirectory/opt/apps/demo ExecStart/usr/bin/java -Xms2g -Xmx2g -jar /opt/apps/demo/app.jar ExecStop/bin/kill -s TERM $MAINPID Restarton-failure RestartSec10 EnvironmentJAVA_HOME/usr/local/jdk-21 [Install] WantedBymulti-user.target几个关键点。Typesimple意味着 systemd 认为 ExecStart 进程本身就是主进程应用启动后就是前台运行。ExecStop发送 SIGTERM 信号配合前面说过的server.shutdown: graceful实现优雅停机。Restarton-failure让应用异常退出时自动拉起但注意如果应用是因为端口被占用启动失败会陷入反复重启的死循环所以重启前先确认端口真的没被别的进程占用。创建好之后的操作流程sudo systemctl daemon-reload sudo systemctl enable demo sudo systemctl start demo sudo systemctl status demoenable用于开机自启动daemon-reload每次修改 service 文件后都要执行否则 systemd 还拿着旧的配置。顺带说一句安全相关的经验如果服务器上还跑了 Nginx 做反向代理建议配置server.tomcat.remoteip.host-header相关的 RemoteIpValve让 Tomcat 能正确识别客户端的真实 IP。Spring Boot 2.x 之后可以用server.forward-headers-strategy: framework这样访问日志里记录的客户端 IP 就是真实访客 IP而不是 Nginx 的内网 IP。对于需要按 IP 做限流、封禁、日志分析的场景这个配置价值很大。4. 日常高频问题排查与性能调优实录4.1 端口占用导致启动失败端口占用恐怕是遇到次数最多的问题了。报错信息一般是Web server failed to start. Port 8080 was already in use.排查方法和处理步骤是固定的先用netstat或ss找到占用进程的 PIDnetstat -tlnp | grep 8080 ss -tlnp | grep 8080然后根据 PID 查进程信息ps -ef | grep PID确认是已废弃的旧进程就直接杀掉kill PID如果kill杀不掉可能是进程僵死状态再用kill -9这个命令会强制终止进程一般属于最后手段。如果是本机有多个服务要占用不同端口直接改server.port即可。4.2 外部 Tomcat 部署后页面 404 的排查外部 Tomcat 部署 WAR 后访问 404是部署问题里最常见的。我会按这个顺序排查第一步查看 Tomcat 的 catalina 日志确认应用到底有没有被加载。日志如果根本没提到你的应用名WAR 放置的目录有问题或者 Tomcat 没有被正确触发热部署。第二步确认 WAR 包解压后的目录结构是否包含WEB-INF/classesSpring Boot 打出来的 WAR 和普通 Web 项目的结构略有不同内部类加载机制也不一样。第三步确认项目是否继承了SpringBootServletInitializer并正确覆写了configure方法这个是部署到外部容器的入口缺失必 404。最后翻一下logs/localhost_access_log看请求是否到了 Tomcat 层。如果 Tomcat 层访问日志有记录但应用层 404问题在应用路由层如果访问日志里都没有你的请求说明请求根本进不了应用问题在部署或 INI 配置。4.3 高并发下的性能瓶颈与排查思路线上服务在高并发时出现响应变慢不一定直接跟 Tomcat 相关但排查路径往往从 Tomcat 开始。先用jstack抓线程快照看工作线程是不是大量卡在某个状态。如果线程 dump 里大量线程都在java.net.SocketInputStream.socketRead0等待读取客户端数据说明连接很多但实际请求没上来可能是长连接占满。如果大量线程卡在数据库 JDBC 驱动的socketRead或锁等待上说明瓶颈在数据库Tomcat 线程池数值再怎么调大也没有用。另一个验证手段是看 Tomcat 访问日志里的%D耗时字段。如果某个接口的耗时普遍从几十毫秒升到几百毫秒且持续不降优先看线程 dump 和数据库慢查询日志而不是急着把 Tomcat 线程数调上去。我曾经排查过一个案例接口偶发超时最后定位到是因为数据库连接池最大连接数不够请求排队等待数据库连接释放Tomcat 线程池设置成多大都没用。4.4 Java 21 Spring Boot 3.5 启用虚拟线程Java 21 发布后虚拟线程的场景非常适合 Tomcat 这种线程池 IO 模型。如果你用的 Spring Boot 3.5 JDK 21可以直接把 Tomcat 的工作线程切换到虚拟线程模式配置很简单spring: threads: virtual: enabled: true或者用编程方式自定义Bean public TomcatProtocolHandlerCustomizer? protocolHandlerCustomizer() { return protocolHandler - protocolHandler.setExecutor(Executors.newVirtualThreadPerTaskExecutor()); }虚拟线程的核心价值体现在 IO 密集型请求上。原来 Tomcat 工作线程池默认 200每个请求在等待数据库响应或下游 HTTP 调用时占住一个工作线程线程池耗尽后新请求就排队了。虚拟线程是轻量级线程创建和销毁成本极低理论上可以支持上万并发而不用配置庞大线程数。实测下来启用虚拟线程后最直观的变化是同样 200 线程配置接口吞吐量在 IO 密集型场景下能提升好几倍。但要注意如果项目里有大量synchronized块或使用了ThreadLocal的代码虚拟线程模式下可能引发新的线程安全问题。Java 官方已经提供了ThreadLocal的替代方案但老代码迁移到虚拟线程时还是要做充分的压测。5. 一份可直接参考的推荐配置组合把前面拆解的各个参数落在一个实际场景里。假设服务器是 4 核 8G部署的是一个面向外部的 REST API 服务平峰 QPS 几百、活动峰值两三千application.yml里的最终配置大致是server: port: 8080 servlet: context-path: / encoding: charset: UTF-8 enabled: true force: true tomcat: threads: max: 300 min-spare: 40 accept-count: 300 max-connections: 8000 connection-timeout: 10000 keep-alive-timeout: 30s max-keep-alive-requests: 200 accesslog: enabled: true directory: /data/logs/tomcat pattern: %h %l %u %t \%r\ %s %b %D compression: enabled: true mime-types: application/json,application/xml,text/html,text/plain min-response-size: 1024 shutdown: graceful forward-headers-strategy: framework启动命令建议放到一个start.sh脚本里管理#!/bin/bash export JAVA_HOME/usr/local/jdk-21 export CATALINA_OPTS-Xms2g -Xmx2g -XX:MetaspaceSize256m -XX:MaxMetaspaceSize512m nohup $JAVA_HOME/bin/java -Xms2g -Xmx2g \ -XX:MetaspaceSize256m -XX:MaxMetaspaceSize512m \ -XX:UseG1GC -XX:MaxGCPauseMillis200 \ -Djava.security.egdfile:/dev/./urandom \ -jar /opt/apps/demo/app.jar /data/logs/tomcat/app.log 21 echo $! /var/run/app.pid echo Application started, PID: $(cat /var/run/app.pid)这套组合在多数常规业务场景下不会翻车。如果后续业务量增长优先考虑横向扩容而不是先调大 max-threads因为单机 Tomcat 的线程调优在并发上去后很快就会遇到边际收益递减而且线程过多带来的上下文切换成本可能比收益还高。6. 我在实际项目中的几处体会最后从个人经验角度总结几条真正值钱的体会。第一改 Tomcat 线程池参数之前一定要先保证业务代码里没有阻塞操作。很多一线同学以为调大 max-threads 就能解决慢请求其实如果接口里有慢 SQL、外部 HTTP 调用超时重试线程调得再大也只是把更多请求放进数据库或下游系统的排队队列反而可能把故障面扩大。第二优雅停机配置一定要和部署脚本配合使用。shutdown: graceful只解决问题的一半另一半在于发布工具必须先发送 SIGTERM然后等一个超时周期后才强制执行 SIGKILL。如果用 kill -9 硬杀进程优雅停机等于白配。我见过有同事配好了 graceful但发布脚本用 kill -9结果每个服务都在发布瞬间报错。第三访问日志尽早开启。开发阶段不需要看但应用一上线访问日志就是你排查问题最直接的信息来源。建议 pattern 里带上%D耗时字段和%{X-Forwarded-For}i真实客户端 IP 字段这两个字段在定位慢请求和来源分析时会省很多时间。第四如果项目已经上了 Spring Boot 3.5 JDK 21我体验下来虚拟线程值得尽快尝试。配置成本很低但收益明显尤其是接口内部有较多外部 IO 调用的场景。建议先在压测环境跑一轮对比确认项目里的线程类库兼容性没问题再上生产。Tomcat 的配置其实不复杂难点在于理解每个参数在真实请求链路中的位置。把线程池、连接器、JVM、部署形态这四层想清楚再结合自己的业务特点去调整参数项目的稳定性和吞吐量都会有一个非常明显的改善。