Spring Boot部署独立Tomcat时Netty TCP服务未启动问题排查

一、两次启动问题的根源 #

• 独立Tomcat部署Spring Boot WAR包时，若SpringBootServletInitializer实现不规范，容易触发两次上下文初始化。比如项目中存在多个SpringBootServletInitializer子类，或重写configure方法时逻辑有误，都会导致Tomcat启动阶段重复加载Spring上下文。
• 检查WAR包内的WEB-INF/web.xml，如果手动配置了DispatcherServlet同时又依赖SpringBootServletInitializer自动初始化，会引发重复启动。Spring Boot WAR部署通常无需手动编写web.xml，交由SpringBootServletInitializer处理即可。

二、Netty TCP服务无法启动的核心原因 #

1. 启动逻辑执行时机错误 #

嵌入式Tomcat环境下，Netty启动逻辑如果写在主类的main方法中，会随应用启动执行；但独立Tomcat中，main方法不会被调用，Netty代码自然不会执行。解决方法是将Netty启动逻辑移到Spring上下文初始化完成后的回调中：

• 用@PostConstruct注解标记启动方法：

@Component
public class NettyServerBootstrap {
    @PostConstruct
    public void start() {
        // 这里写Netty服务的初始化、绑定端口逻辑
    }
}

• 或者实现ApplicationListener<ContextRefreshedEvent>接口，在上下文刷新完成后启动Netty：

@Component
public class NettyServerListener implements ApplicationListener<ContextRefreshedEvent> {
    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        // 启动Netty服务
    }
}

2. 端口权限或占用问题 #

• 独立Tomcat的运行用户可能没有绑定低端口（1024以下）的权限，而嵌入式Tomcat用当前用户启动，权限足够。可以尝试将Netty端口改为1024以上，或给Tomcat运行用户赋予端口绑定权限。
• 用netstat -tulpn | grep <你的Netty端口>命令检查端口是否被其他进程占用，若占用则更换端口或停止占用进程。

3. 上下文生命周期依赖冲突 #

独立Tomcat中Spring上下文由容器管理，若Netty启动依赖的Bean未完成初始化，会导致启动失败。可以调整日志级别为DEBUG，查看Bean的加载顺序，确保Netty启动前所有依赖Bean都已初始化。
另外，Netty启动属于耗时操作，建议用异步方式启动，避免阻塞Tomcat的上下文初始化流程，比如用Spring的@Async注解或自定义线程池。

4. WAR打包依赖配置错误 #

检查项目的构建文件（pom.xml或build.gradle）：

• 确保spring-boot-starter-tomcat被设置为provided（避免与独立Tomcat的Tomcat包冲突）；
• Netty相关依赖必须是compile级别（默认），不能设为provided，否则独立Tomcat环境下会找不到Netty类，导致服务无法启动。

三、快速排查步骤 #

1. 开启Spring和Tomcat的DEBUG日志，定位两次启动的触发源头，确认是重复初始化逻辑导致的问题。
2. 将Netty启动逻辑迁移到Spring上下文回调方法中，验证服务是否能正常启动。
3. 检查Netty端口的权限和占用情况，更换端口测试。
4. 对比嵌入式与独立Tomcat环境下的依赖包差异，确保WAR包包含所有必要依赖。

内容的提问来源于stack exchange，提问作者sajjad Movahedi