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 默认选择 Tomcat
Spring 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-count
Tomcat 处理 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:MetaspaceSize=256m \ -XX:MaxMetaspaceSize=512m \ -XX:+UseG1GC \ -XX:MaxGCPauseMillis=200 \ -XX:+DisableExplicitGC \ -Djava.security.egd=file:/dev/./urandom \ -jar app.jarXms和Xmx我倾向于设置成相等，避免运行期堆动态扩容导致的性能抖动。G1 GC 是 JDK 11+ 默认值，MaxGCPauseMillis控制期望的 GC 停顿时间。DisableExplicitGC这个参数很多人没加，作用是禁止代码里显式调用System.gc()，防止某些框架强行触发 Full GC 造成长时间停顿。
最后那个-Djava.security.egd=file:/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] Description=Demo Spring Boot App After=network.target [Service] Type=simple User=appuser WorkingDirectory=/opt/apps/demo ExecStart=/usr/bin/java -Xms2g -Xmx2g -jar /opt/apps/demo/app.jar ExecStop=/bin/kill -s TERM $MAINPID Restart=on-failure RestartSec=10 Environment=JAVA_HOME=/usr/local/jdk-21 [Install] WantedBy=multi-user.target几个关键点。
Type=simple意味着 systemd 认为 ExecStart 进程本身就是主进程，应用启动后就是前台运行。ExecStop发送 SIGTERM 信号，配合前面说过的server.shutdown: graceful实现优雅停机。Restart=on-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找到占用进程的 PID：
netstat -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/classes，Spring 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:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m" nohup $JAVA_HOME/bin/java -Xms2g -Xmx2g \ -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m \ -XX:+UseG1GC -XX:MaxGCPauseMillis=200 \ -Djava.security.egd=file:/dev/./urandom \ -jar /opt/apps/demo/app.jar >> /data/logs/tomcat/app.log 2>&1 & 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、部署形态这四层想清楚，再结合自己的业务特点去调整参数，项目的稳定性和吞吐量都会有一个非常明显的改善。
