1. 项目背景与核心价值
最近在维护一个基于若依（RuoYi）框架开发的企业级项目时，安全团队扫描出Tomcat容器存在多个高危漏洞。作为项目负责人，我不得不立即着手升级Tomcat版本。但在实际操作中发现，若依框架与Tomcat的集成存在不少隐性兼容性问题，官方文档也没有详细的升级指南。经过三天踩坑和反复验证，最终整理出这套可复现的升级方案。
这次升级涉及从Tomcat 8.5升级到最新稳定版10.0.23，过程中需要解决Servlet API兼容性、日志配置迁移、性能调优参数适配等关键问题。对于使用若依框架的开发团队来说，直接替换Tomcat安装包会导致控制台乱码、定时任务失效等典型问题，本文将分享完整的避坑方案。
2. 环境准备与前置检查
2.1 版本兼容性矩阵
在开始升级前，必须确认当前技术栈的版本支持情况。根据Apache官方文档，各版本Tomcat对JDK和Servlet规范的支持如下：
| Tomcat版本 | JDK要求 | Servlet规范 | 若依框架支持 |
|---|---|---|---|
| 8.5.x | 1.8+ | 3.1 | 完全支持 |
| 9.0.x | 1.8+ | 4.0 | 需验证 |
| 10.0.x | 1.8+ | 5.0 | 需调整 |
关键提示：若依4.7.3及以上版本才开始支持Tomcat 10，低版本需要先升级框架
2.2 必备工具清单
- JDK 1.8（建议使用OpenJDK 11获得更好性能）
- Maven 3.6+（用于依赖管理）
- 文本对比工具（推荐Beyond Compare）
- 原Tomcat的server.xml备份
- 项目war包备份
3. 详细升级步骤
3.1 依赖项调整
首先修改pom.xml中的Servlet API依赖。Tomcat 10开始使用Jakarta EE命名空间，这与之前版本存在二进制不兼容：
xml复制<!-- 旧版本依赖 -->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
<scope>provided</scope>
</dependency>
<!-- 新版本替换为 -->
<dependency>
<groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId>
<version>5.0.0</version>
<scope>provided</scope>
</dependency>
3.2 配置文件迁移
将原Tomcat的conf目录下这些关键配置文件迁移到新版本：
- server.xml（需检查Connector配置）
- context.xml（注意Resource链接）
- logging.properties（日志格式需要调整）
- web.xml（若依自定义的filter配置）
典型问题案例：原配置中使用URIEncoding="UTF-8"，在Tomcat 10中需要改为：
xml复制<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443"
URIEncoding="UTF-8"
useBodyEncodingForURI="true" />
3.3 日志系统适配
Tomcat 10的日志系统有重大改进，需要调整若依的日志配置：
- 在logging.properties中添加：
properties复制org.apache.catalina.core.ContainerBase.[Catalina].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler
- 修改logback.xml中的控制台输出格式：
xml复制<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
4. 关键问题解决方案
4.1 控制台中文乱码
现象：启动后控制台日志出现??乱码
解决方法：
- 修改bin/catalina.bat（Linux下是catalina.sh）
- 添加JVM参数：
bash复制set "JAVA_OPTS=%JAVA_OPTS% -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"
4.2 定时任务失效
问题原因：Tomcat 10的线程池实现变化导致@Scheduled注解失效
解决方案：
- 在application.yml中添加：
yaml复制spring:
task:
scheduling:
pool:
size: 10
- 或者在启动类添加：
java复制@Bean
public TaskScheduler taskScheduler() {
ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
scheduler.setPoolSize(10);
return scheduler;
}
5. 性能调优建议
5.1 连接池优化参数
在server.xml中调整这些关键参数：
xml复制<Executor name="tomcatThreadPool"
namePrefix="catalina-exec-"
maxThreads="500"
minSpareThreads="30"
maxQueueSize="1000"/>
<Connector executor="tomcatThreadPool"
acceptCount="1000"
maxConnections="10000"
keepAliveTimeout="60000"/>
5.2 JVM内存配置
在catalina.sh中添加（根据服务器内存调整）：
bash复制JAVA_OPTS="-server -Xms2048m -Xmx2048m -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m"
6. 验证与监控
升级完成后需要验证：
- 所有REST API接口是否正常响应
- 文件上传下载功能测试
- 会话保持功能验证
- 监控线程数变化：
bash复制watch -n 1 "ps -ef | grep tomcat | grep -v grep"
建议使用Arthas工具进行运行时诊断：
bash复制# 查看线程堆栈
thread -n 3
# 监控方法调用
monitor -c 5 org.springframework.web.servlet.DispatcherServlet doDispatch
7. 回滚方案
如果升级后出现不可解决的问题，可按此步骤回滚：
- 停止新版本Tomcat服务
- 恢复备份的war包
- 还原原Tomcat目录
- 回退pom.xml修改
- 重启旧版本服务
建议在升级前使用Docker创建快照：
bash复制docker commit -p ruoyi_tomcat ruoyi_backup