Spring Boot项目从Tomcat迁移到TongWeb 7.0.E.6嵌入式版的实战避坑指南
去年接手了一个金融行业的国产化改造项目，其中最关键的一环就是将Spring Boot默认的Tomcat容器替换为国产的TongWeb嵌入式容器。本以为只是简单替换几个依赖包就能搞定，结果在实际操作中踩了不少坑。这篇文章就记录下那些让我加班到凌晨的典型问题，希望能帮正在做类似迁移的朋友少走弯路。
1. 环境准备与基础配置
1.1 获取TongWeb嵌入式版资源
不同于Tomcat直接下载就能用，TongWeb需要先联系东方通官方获取嵌入式版JAR包和试用License。这里有个小技巧：在申请时明确说明是用于Spring Boot嵌入式场景，这样技术支持人员会直接提供适配的版本包。
关键资源包括：
tongweb-embedded-7.0.E.6.jar（核心嵌入式包）license.dat（授权文件）- 用户指南文档（特别注意
70E6P2A01.pdf中的嵌入式章节）
提示：License文件默认有效期为3个月，生产环境记得提前申请正式授权。
1.2 基础依赖配置
在pom.xml中需要移除Tomcat的starter依赖，并添加TongWeb嵌入式支持。最容易出错的是版本兼容性问题：
<!-- 移除Tomcat starter --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <exclusions> <exclusion> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-tomcat</artifactId> </exclusion> </exclusions> </dependency> <!-- 添加TongWeb嵌入式支持 --> <dependency> <groupId>com.tongweb</groupId> <artifactId>tongweb-spring-boot-starter</artifactId> <version>7.0.E.6</version> </dependency>常见问题排查表：
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| ClassNotFoundException | 依赖包未正确引入 | 检查Maven仓库中是否存在tongweb-spring-boot-starter |
| NoSuchMethodError | 版本不匹配 | 确保Spring Boot版本与TongWeb starter兼容 |
| License验证失败 | license.dat路径错误 | 使用绝对路径或确认文件在classpath下 |
2. 核心配置类改造
2.1 替换TomcatServletWebServerFactory
项目中如果有自定义的Tomcat配置类，需要将其改造为TongWeb的实现。这是迁移过程中最关键的步骤之一。原始Tomcat配置通常长这样：
@Configuration public class TomcatConfig { @Bean public TomcatServletWebServerFactory tomcatServletWebServerFactory() { TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory(); // 各种自定义配置... return factory; } }需要修改为TongWeb的实现：
@Configuration public class TongWebConfig { @Bean public TongWebServletWebServerFactory tongWebServletWebServerFactory() { TongWebServletWebServerFactory factory = new TongWebServletWebServerFactory(); // 保持原有配置逻辑 factory.addConnectorCustomizers(connector -> { ProtocolHandler handler = connector.getProtocolHandler(); if (handler instanceof Http11NioProtocol) { Http11NioProtocol protocol = (Http11NioProtocol) handler; protocol.setKeepAliveTimeout(60000); protocol.setMaxKeepAliveRequests(60000); } }); return factory; } }2.2 特殊配置项处理
TongWeb在某些配置上与Tomcat存在差异，需要特别注意：
- HTTPS配置：TongWeb的SSL协议实现略有不同
- 线程池参数：最大线程数等参数的默认值与Tomcat不同
- JSP支持：需要额外引入JSP相关依赖
典型HTTPS配置示例：
factory.addConnectorCustomizers(connector -> { Http11NioProtocol protocol = (Http11NioProtocol) connector.getProtocolHandler(); protocol.setSSLEnabled(true); protocol.setKeystoreFile("path/to/keystore"); protocol.setKeystorePass("password"); protocol.setKeystoreType("PKCS12"); });3. 部署与验证
3.1 License配置技巧
TongWeb要求license.dat文件必须能被正确加载，常见的配置方式有三种：
- classpath根目录：最简单的方式，将license.dat放在resources目录下
- 外部文件指定：通过JVM参数指定路径
-Dtongweb.license=/path/to/license.dat - 编程方式设置：在Spring Boot启动类中设置
注意：Windows路径需要使用双反斜杠或正斜杠，如
C:\\path\\to\\license.dat或C:/path/to/license.dat
3.2 验证迁移成功
迁移后需要通过多种方式验证是否真正使用了TongWeb容器：
- 启动日志检查：成功启动后会显示TongWeb的banner
- API端点验证：访问
/actuator/env查看server.*相关属性 - JMX检查：通过JConsole查看MBean中的服务器信息
关键验证点检查表：
| 验证项 | Tomcat表现 | TongWeb表现 |
|---|---|---|
| 服务器头信息 | Apache-Coyote | TongWeb |
| JMX域名 | Catalina | TongWeb |
| 线程名前缀 | http-nio | tw-http-nio |
| 错误页面 | Tomcat默认页 | TongWeb默认页 |
4. 性能调优与问题排查
4.1 性能参数对比
TongWeb与Tomcat在默认参数上存在差异，需要根据实际场景调整：
| 参数项 | Tomcat默认值 | TongWeb默认值 | 建议值 |
|---|---|---|---|
| 最大线程数 | 200 | 150 | 根据负载调整 |
| 最小空闲线程 | 10 | 20 | 保持默认 |
| 连接超时 | 20000ms | 30000ms | 根据网络状况 |
| 最大连接数 | 8192 | 10000 | 保持默认 |
4.2 常见问题排查
问题1：静态资源访问404
可能原因：TongWeb对静态资源的默认处理路径与Tomcat不同
解决方案：
@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/static/**") .addResourceLocations("classpath:/static/"); } }问题2：文件上传大小限制
虽然配置了MultipartConfigElement，但TongWeb还有自己的限制：
# application.properties tongweb.max-http-post-size=104857600 tongweb.max-swallow-size=104857600问题3：WebSocket连接不稳定
需要额外配置TongWeb的WebSocket引擎：
factory.addContextCustomizers(context -> { context.setUseHttpOnly(true); context.setSessionTimeout(30, TimeUnit.MINUTES); });5. 进阶技巧与最佳实践
5.1 健康检查与监控
TongWeb提供了额外的监控端点，需要在application.properties中启用：
management.endpoints.web.exposure.include=health,info,tongweb management.endpoint.tongweb.enabled=true监控指标包括：
- 当前活跃会话数
- 请求处理时间分布
- JVM内存使用情况
- 线程池状态
5.2 类加载隔离方案
对于需要隔离依赖的场景，TongWeb支持模块化部署：
- 在项目根目录创建
modules文件夹 - 将需要隔离的JAR包放入其中
- 配置模块描述文件
module.xml
示例module.xml：
<module name="my-module" version="1.0"> <resource-root path="my-lib.jar"/> <dependencies> <module name="javax.api"/> </dependencies> </module>5.3 生产环境建议
经过多个项目实践，总结出以下经验：
- 性能测试时重点关注内存使用情况，TongWeb的默认堆内存配置可能不足
- 日志系统建议使用Logback而非Log4j，兼容性更好
- 定期检查License有效期，设置到期前提醒
- 对于高并发场景，适当调整NIO工作线程数
// 生产环境推荐配置示例 @Bean public TongWebServletWebServerFactory tongWebServletWebServerFactory() { TongWebServletWebServerFactory factory = new TongWebServletWebServerFactory(); factory.addConnectorCustomizers(connector -> { Http11NioProtocol protocol = (Http11NioProtocol) connector.getProtocolHandler(); protocol.setMaxThreads(500); protocol.setMinSpareThreads(50); protocol.setConnectionTimeout(10000); }); return factory; }
