1. 从一次请求响应慢的排查说起Catalina到底管什么很多人第一次接触Tomcat注意力都放在server.xml里那个8080端口上觉得改改端口、配配虚拟目录就算会用Tomcat了。直到某天线上接口突然大面积超时日志里全是线程池打满的告警翻遍Spring配置也找不到原因最后才发现问题出在Servlet容器这一层——请求还没进到业务代码就已经在Catalina的管道里排队了。这个场景我遇到过不止一次也是从那时候起我才真正愿意花时间去啃Catalina这个模块。Catalina是Tomcat的Servlet容器实现也是整个Tomcat最核心的部分。Tomcat本身可以拆成两大块一块是Connector负责网络通信把字节流解析成HTTP请求另一块就是Catalina负责处理这些请求管理Servlet的生命周期维护会话执行过滤器和Servlet。你可以把Connector理解成前台接待把Catalina理解成后厨——接待把单子递进来后厨决定这道菜由谁做、怎么做、做完怎么端出去。绝大多数和业务逻辑相关的行为比如doGet、doPost、Filter、Listener、Session全部发生在Catalina这一层。这篇文章适合两类人看。一类是已经会用Tomcat部署应用但对内部机制一知半解遇到性能问题或者诡异Bug时无从下手的开发者另一类是想深入理解Servlet规范落地细节为后续读源码或者做容器定制打基础的人。我会从Catalina的整体架构讲起把Server、Service、Engine、Host、Context、Wrapper这条组件链拆开揉碎再讲请求是怎么在这条链上流转的最后落到实际使用中最容易踩的几个坑。全程不堆砌源码但关键机制会讲透让你看完之后能对着自己的Tomcat实例说出个所以然。需要提前说明的是Catalina的组件模型是典型的组合模式父容器管子容器层层嵌套。理解了这个嵌套关系后面看任何配置和源码都不会迷路。下面我们一层一层往下剥。2. Catalina的组件树Server到Wrapper的六层嵌套关系2.1 为什么Tomcat要设计这么多层容器刚看Tomcat架构图的人都会有一个疑问不就是处理个HTTP请求吗为什么要搞出Server、Service、Engine、Host、Context、Wrapper这么多层直接一个类处理完不行吗这个问题问得好答案藏在职责分离和多实例复用这两个需求里。设想一个场景一台机器上要跑两个不同的Web应用它们共享同一个端口但根据域名或者路径区分。如果没有Host这一层你就得为每个应用单独起一个Tomcat进程端口还得错开运维成本直接翻倍。再设想另一个场景同一个应用里你想给不同的Servlet配置不同的类加载器实现热部署隔离。如果没有Context和Wrapper的区分类加载器只能全局一份隔离就无从谈起。所以这些层级不是拍脑袋加的每一层都对应一个真实的隔离或复用需求。从最外层往里数这六层的关系是这样的Server代表整个Tomcat实例一个JVM里通常只有一个Service把Connector和Engine绑在一起一个Server可以有多个Service但一般也就一个Engine是Catalina的入口负责把请求路由到对应的HostHost代表一个虚拟主机也就是一个域名Context代表一个Web应用就是你部署的那个war包或者目录Wrapper代表一个具体的Servlet。每一层都是容器都可以有自己的管道Pipeline和阀门Valve请求从外层进来一层层往里传每层都有机会对请求做点手脚。2.2 各层组件的核心职责与配置落点光说概念容易飘我们直接对着server.xml看每一层在配置里长什么样这样印象最深。层级对应配置元素核心职责常见配置项ServerServer管理整个实例的生命周期监听关闭端口port、shutdownServiceService组合Connector和EnginenameEngineEngine请求路由到Host处理引擎级Valvename、defaultHostHostHost虚拟主机管理多个Contextname、appBase、unpackWARsContextContext单个Web应用管理Servlet和资源path、docBase、reloadableWrapper代码或注解单个Servlet的包装管理其生命周期load-on-startup、url-pattern这张表建议你对着自己的conf/server.xml看一遍把每个元素找出来。很多人用了几年Tomcat从来没打开过这个文件全靠Spring Boot自动配置结果一旦需要改线程池或者配虚拟主机就抓瞎。理解这六层之后你会发现Spring Boot内嵌Tomcat的那些配置项比如server.tomcat.threads.max最终都是映射到这张表里的某个组件上的。这里有个容易混淆的点Engine和Host之间是父子关系但一个Engine下可以有多个Host。默认配置里只有一个名为localhost的Host所以很多人以为它们是一对一的。实际上你完全可以在一个Engine下配多个Host用不同的域名区分这就是虚拟主机的实现方式。同理一个Host下可以有多个Context对应多个Web应用。这种一对多的关系是理解Catalina路由机制的关键。2.3 组合模式带来的生命周期联动这六层组件不是孤立的它们通过组合模式串成一条生命周期链。父组件启动时会依次启动子组件父组件停止时也会依次停止子组件。这个机制的好处是你只需要调用最外层Server的start()方法整个Tomcat就起来了不需要手动一个个启动。具体来说每个容器组件都实现了Lifecycle接口有init、start、stop、destroy四个核心阶段。当Server启动时它会触发Service启动Service触发Engine启动Engine触发Host启动Host触发Context启动Context触发Wrapper启动。每一层在启动时都会做一些自己的初始化工作比如Context启动时会解析web.xml、创建Servlet实例、初始化Filter链。这个联动机制是Tomcat能够一键启动的基础也是理解热部署和优雅停机的关键。注意生命周期联动是单向的父组件启动会带动子组件但子组件出问题不一定会让父组件停止。比如某个Context启动失败默认情况下Host会记录错误但继续启动其他Context不会导致整个Tomcat挂掉。这个设计是为了隔离故障但也意味着你不能只看Tomcat启动日志的最后一行判断是否一切正常得往上翻看有没有Context级别的报错。3. 请求在Catalina管道里的完整流转路径3.1 从Connector交接到Engine的那一刻请求到达Tomcat时最先接触它的是Connector。Connector负责监听端口、接收字节流、按照HTTP协议解析出请求行、请求头和请求体然后封装成一个Request对象和一个Response对象。做完这些之后Connector并不会自己处理业务逻辑而是把这对请求响应对象交给它所属的Service再由Service转交给Engine。这个交接点就是Catalina开始工作的地方。Engine拿到请求后第一件事是确定这个请求应该由哪个Host处理。判断依据是请求头里的Host字段也就是域名。Engine会遍历自己管理的所有Host找到名字匹配的那个。如果找不到匹配的Host就用defaultHost指定的那个兜底。这一步很关键因为如果域名配置错了请求可能被路由到错误的虚拟主机表现出来的现象就是访问A域名却打开了B应用的内容。找到Host之后Host会继续往下找Context。Context的匹配依据是请求的URI路径。比如请求路径是/myapp/user/listHost会先看有没有一个Context的path是/myapp如果有就把请求交给它剩下的/user/list作为Servlet路径继续往下传。如果没有任何Context匹配Host会返回404。这里有个细节Context的匹配是前缀匹配而且遵循最长匹配原则。也就是说如果同时存在/myapp和/myapp/admin两个Context请求/myapp/admin/xxx会优先匹配到后者。3.2 Pipeline和Valve请求处理的拦截器链请求进入每一层容器后并不是直接调用目标Servlet而是要经过一条管道Pipeline。管道里装着若干个阀门Valve每个Valve都可以对请求做处理然后决定是否继续往下传递。这个设计模式就是经典的责任链模式和Servlet规范里的Filter链非常像但层级更高作用范围更大。每一层容器都有自己的Pipeline。Engine的Pipeline里默认有一个StandardEngineValve负责把请求转发给合适的HostHost的Pipeline里默认有一个StandardHostValve负责转发给合适的ContextContext的Pipeline里默认有一个StandardContextValve负责转发给合适的WrapperWrapper的Pipeline里默认有一个StandardWrapperValve负责调用最终的Servlet。这些Standard开头的Valve是Tomcat内置的负责完成核心的路由和调用逻辑。除了这些内置Valve你还可以往Pipeline里加自定义Valve。比如你想在请求进入Engine之前记录一下访问日志就可以写一个Valve加到Engine的Pipeline里。Valve和Filter的区别在于Valve是Tomcat容器级别的能访问到容器的内部结构Filter是Servlet规范级别的只能访问Servlet API。如果你需要做和容器强相关的操作比如动态修改Context配置Valve是更合适的选择。但大多数业务场景下Filter已经够用了没必要上Valve。3.3 StandardWrapperValve如何调用到你的Servlet请求流转到Wrapper这一层时离你的业务代码就只有一步之遥了。StandardWrapperValve是负责这最后一步的Valve它做的事情比看起来要复杂得多。首先它会检查对应的Servlet是否已经加载。如果还没加载它会触发Servlet的加载流程包括实例化、调用init()方法。这个过程是懒加载的默认情况下Servlet在第一次被请求时才会初始化除非你在web.xml里配了load-on-startup。懒加载的好处是启动快坏处是第一次请求会慢一些。对于核心Servlet建议配load-on-startup提前初始化避免第一次请求超时。Servlet加载好之后StandardWrapperValve会创建Filter链。它会根据web.xml或注解里配置的Filter映射规则把所有匹配当前请求的Filter按顺序串起来形成一个链。然后它调用链头的FilterFilter处理完再调用下一个直到最后一个Filter调用到Servlet的service()方法。这个链条的执行顺序是先按Filter的配置顺序执行doFilter的前半段然后执行Servlet最后按相反顺序执行doFilter的后半段。理解这个顺序对排查Filter相关的问题非常重要。Servlet执行完毕后StandardWrapperValve会负责把响应写回。如果Servlet抛了异常它还会根据异常类型决定是返回500错误页还是交给其他错误处理机制。整个过程中它还负责管理Servlet实例的并发访问确保service()方法不会被多个线程同时调用同一个实例——这也是为什么Servlet默认是单例多线程的你的Servlet代码必须保证线程安全。4. 实际使用中最容易踩的五个坑4.1 Context路径配置错误导致404这是新手最常遇到的问题没有之一。现象是应用明明部署成功了Tomcat启动日志也没报错但访问就是404。原因通常是Context的path和docBase配错了或者war包的名字和访问路径对不上。Tomcat默认会把webapps目录下的war包自动解压并部署Context的path就是war包的名字去掉.war后缀。比如你放了一个myapp.war进去访问路径就是/myapp。但如果你把war包改名为ROOT.war访问路径就变成了根路径/。很多人不知道这个规则把war包随便命名结果访问路径和预期不符。还有一种情况是server.xml里手动配了Context但path写成了/myapp/多了个斜杠导致匹配失败。排查这个问题的思路很简单先看Tomcat启动日志里有没有Deploying web application这样的行确认应用确实被部署了然后看日志里打印的context path是什么最后用这个path去访问。如果日志里根本没有部署记录说明war包没被扫描到检查appBase配置和文件权限。4.2 类加载器冲突引发的NoClassDefFoundErrorCatalina为每个Context维护了独立的类加载器这是实现应用隔离的基础。但这也带来了一个经典问题同一个类被不同的类加载器加载了两次导致类型转换失败或者静态变量不共享。最常见的场景是你把某个jar包同时放在了Tomcat的lib目录和应用的WEB-INF/lib目录下。Tomcat的类加载器会优先加载lib目录下的但应用代码里引用的可能是WEB-INF/lib下的两个类虽然名字一样但在JVM看来是两个不同的类于是抛出ClassCastException或者NoClassDefFoundError。解决办法是统一jar包的位置要么全放lib要么全放WEB-INF/lib不要两边都放。另一个常见场景是使用了一些需要和容器交互的框架比如数据库连接池或者日志框架。这些框架的类如果被应用类加载器加载可能无法访问容器的内部类导致初始化失败。这时候需要把相关jar包放到Tomcat的lib目录下让容器类加载器来加载。判断依据是看异常堆栈里有没有ClassNotFoundException或者NoClassDefFoundError以及涉及的类是不是容器相关的。4.3 线程池配置不当导致请求堆积Catalina的Engine组件有一个线程池负责处理所有进入的请求。这个线程池的大小直接决定了Tomcat的并发处理能力。默认配置下最大线程数是200最小空闲线程数是10这个配置对于大多数中小型应用够用但在高并发场景下可能成为瓶颈。线程池打满的典型现象是请求响应时间突然变长日志里出现大量超时但CPU和内存都不高。这是因为请求在队列里排队等待空闲线程来处理。排查方法是看Tomcat的线程状态可以通过JMX或者/manager/status页面查看当前活跃线程数和队列长度。如果活跃线程数长期接近最大值说明需要调大线程池。调大线程池不是简单地改个数字就行得考虑下游系统的承受能力。比如你的应用要调用数据库数据库连接池只有50个连接你把Tomcat线程池调到500结果就是大量线程阻塞在获取数据库连接上反而更糟。正确的做法是先压测找到系统的瓶颈点然后根据瓶颈点来配置线程池。一般来说Tomcat线程池的最大值应该和下游资源池的大小相匹配或者略大一些。4.4 Session持久化配置遗漏导致重启丢会话Catalina的Context组件负责管理Session。默认情况下Session是存在内存里的Tomcat一重启就全没了。对于需要保持登录状态的应用这会导致用户被强制登出。解决办法是配置Session持久化让Tomcat在关闭时把Session写到磁盘启动时再读回来。配置方式是在Context里加一个Manager元素指定pathname属性。比如Context path/myapp docBasemyapp Manager classNameorg.apache.catalina.session.StandardManager pathname/tmp/myapp-sessions.ser/ /Context这样Tomcat关闭时会把Session序列化到指定文件启动时再反序列化回来。但要注意Session里的对象必须实现Serializable接口否则序列化会失败。另外如果应用是集群部署的单机持久化就不够了需要配置Session共享比如用Redis或者Tomcat自带的集群方案。4.5 Valve顺序配错导致逻辑不执行前面说过Pipeline里的Valve是按顺序执行的。如果你往Pipeline里加了自定义Valve但顺序配错了可能导致逻辑不执行或者执行结果不符合预期。比如你把一个做权限校验的Valve加在了StandardContextValve后面那它永远不会被执行因为StandardContextValve已经把请求转发到下一个容器了不会再把控制权交回来。Valve的顺序由server.xml里的配置顺序决定或者由context.xml里的Valve元素顺序决定。内置的Standard Valve总是最后执行自定义Valve应该加在它们前面。如果你不确定顺序可以在Valve的invoke()方法里打日志看实际执行顺序是否符合预期。这个坑比较隐蔽因为配错了不会报错只是逻辑静默失效排查起来比较费时间。5. 从源码视角理解Catalina的设计取舍5.1 为什么用组合模式而不是继承Catalina的容器组件用的是组合模式父容器持有子容器的引用而不是通过继承来扩展功能。这个选择背后有很实际的考虑。如果用继承那么Engine要继承HostHost要继承ContextContext要继承Wrapper形成一条继承链。这样做的问题是耦合太紧每一层都依赖上一层的实现细节想单独替换某一层几乎不可能。而且Java是单继承的一旦继承了父容器就没法再继承其他类了扩展性大打折扣。用组合模式就不一样了。每个容器组件都是独立的类只依赖接口不依赖具体实现。父容器通过接口调用子容器的方法子容器可以自由替换。比如你可以把默认的StandardContext替换成自定义的Context实现只要实现了Context接口就行其他层完全不受影响。这种灵活性是Tomcat能够支持多种部署方式和扩展机制的基础。5.2 Lifecycle接口的事件驱动机制Catalina的另一个核心设计是Lifecycle接口。所有容器组件都实现了这个接口它定义了组件的生命周期状态和状态转换事件。当组件状态发生变化时会触发相应的事件注册的监听器会收到通知并执行相应逻辑。这个机制的好处是解耦。比如Context启动时需要做很多事情解析web.xml、创建Servlet实例、初始化Filter、启动Session管理器等等。如果把这些逻辑都写在Context的start()方法里代码会非常臃肿。用事件驱动的方式每个功能模块注册一个监听器监听Context的启动事件各自处理自己的初始化逻辑。Context本身只需要负责状态转换和事件通知不需要知道具体有哪些功能模块。这个设计也方便了扩展。你想在Context启动时加点自定义逻辑不需要改Context的代码只需要写一个监听器注册进去就行。Tomcat内部的很多功能比如JSP支持、JMX注册、日志初始化都是通过监听器实现的。理解了这个机制你看Tomcat源码时就不会被各种Listener搞晕。5.3 类加载器层次结构的设计意图Catalina的类加载器结构是理解Tomcat行为的关键。它不像普通的Java应用那样只有一层类加载器而是分成了好几层每层负责加载不同范围的类。最顶层是Bootstrap类加载器加载JVM自身的核心类。往下一层是System类加载器加载CLASSPATH环境变量指定的类主要是Tomcat启动所需的类。再往下是Common类加载器加载Tomcat的lib目录下的类这些类对所有应用可见。然后是Catalina类加载器加载Tomcat自身的实现类。最后是Webapp类加载器每个Context一个加载WEB-INF/classes和WEB-INF/lib下的类只对当前应用可见。这个层次结构的设计意图是隔离和共享的平衡。Common类加载器加载的类所有应用共享节省内存Webapp类加载器加载的类应用独享保证隔离。但这也带来了前面提到的类加载器冲突问题。理解这个结构之后你就能判断一个类应该放在哪个目录下以及为什么会出现ClassNotFoundException。提示Tomcat默认的类加载顺序是先父后子也就是先尝试用父类加载器加载加载不到再用自己的。但可以通过配置Loader delegatefalse/改成先自己加载再委托父加载器这就是所谓的Webapp类加载器优先模式。这个配置在某些框架下是必须的比如应用里用了和Tomcat内置版本冲突的库时。6. 几个能直接抄的配置模板与调优参数6.1 生产环境server.xml关键配置下面这份配置是我在多个生产环境里用过的去掉了一些不常用的元素保留了核心部分。你可以直接对照修改自己的server.xml。Server port8005 shutdownSHUTDOWN Service nameCatalina Connector port8080 protocolHTTP/1.1 connectionTimeout20000 maxThreads400 minSpareThreads50 acceptCount200 maxConnections8000 redirectPort8443/ Engine nameCatalina defaultHostlocalhost Host namelocalhost appBasewebapps unpackWARstrue autoDeployfalse Context path/myapp docBase/data/apps/myapp reloadablefalse crossContextfalse Manager classNameorg.apache.catalina.session.StandardManager pathname/data/sessions/myapp.ser/ /Context /Host /Engine /Service /Server几个关键参数的解释maxThreads是最大工作线程数根据压测结果调整acceptCount是等待队列长度当所有线程都在忙时新请求会进入这个队列队列满了才会拒绝maxConnections是最大连接数NIO模式下可以设得比maxThreads大很多autoDeploy设为false是为了避免生产环境自动部署带来的不确定性部署操作应该由运维流程控制reloadable设为false是为了关闭类变更检测提升性能。6.2 线程池与连接数的匹配计算线程池大小不是拍脑袋定的有一个粗略的计算公式可以参考最大线程数 (目标QPS × 平均响应时间) / 并发系数假设你的应用目标QPS是1000平均响应时间是50毫秒并发系数取0.8那么最大线程数大约是(1000 × 0.05) / 0.8 ≈ 62。但这只是理论值实际还要考虑下游资源的限制。如果数据库连接池只有20个连接那线程数设到62也没用多出来的线程都会阻塞在获取连接上。我的经验是先按理论值配置然后压测观察线程池的活跃线程数和队列长度。如果活跃线程数长期低于最大值的70%说明配置偏大可以适当调小如果队列长度经常大于0说明配置偏小需要调大。调大之前先确认下游资源是否充足否则只是把瓶颈从Tomcat转移到了数据库。6.3 常见问题速查表现象可能原因排查方向访问404Context路径错误看启动日志的context path启动报ClassNotFoundjar包位置不对检查lib和WEB-INF/lib响应慢但CPU低线程池打满看线程状态和队列长度重启丢登录态Session未持久化检查Manager配置自定义Valve不执行Valve顺序错误看Pipeline配置顺序内存溢出类加载器泄漏检查Context是否正常关闭这张表建议存下来遇到问题先对照排查能省不少时间。很多问题其实都是配置层面的不需要改代码就能解决。7. 我在实际运维中总结的几条经验Catalina这个模块刚看的时候觉得组件多、关系复杂但真正理解之后会发现它的设计非常清晰。组合模式加生命周期事件把复杂的容器管理拆成了一个个独立的关注点每层只管自己的事层与层之间通过接口交互。这种设计思路值得在写业务代码时借鉴。第一条经验是不要轻易改Tomcat的默认配置。很多人一上来就调线程池、改类加载策略结果引入了新的问题。默认配置是经过大量测试的适用于大多数场景。只有在明确知道瓶颈在哪、并且有压测数据支撑的情况下才去调整。我见过太多因为乱调参数导致的问题最后回滚到默认配置反而好了。第二条经验是日志级别不要开太细。Catalina的日志在DEBUG级别下会打印大量请求流转信息对排查问题有帮助但在生产环境开着会严重影响性能还会把磁盘写满。建议生产环境用INFO级别需要排查时临时调到DEBUG排查完立刻调回来。可以通过JMX动态调整日志级别不需要重启。第三条经验是定期检查Context的关闭情况。Tomcat在停止时如果某个Context没有正常关闭会导致类加载器泄漏进而引发内存溢出。判断方法是看Tomcat停止日志里有没有The web application appears to have started a thread but has failed to stop it这样的警告。如果有说明应用里有线程没有正确关闭需要检查代码里的线程池和定时任务是否在contextDestroyed时做了清理。第四条经验是用JMX监控Catalina的关键指标。Tomcat暴露了很多MBean可以监控线程池、请求处理时间、Session数量等。把这些指标接入监控系统能在问题发生前发现异常趋势。比如线程池活跃数持续上升说明可能有慢请求堆积Session数量异常增长说明可能有爬虫或者攻击。这些指标比看日志更直观也更及时。最后说一个容易被忽略的点Catalina的版本升级要谨慎。Tomcat不同版本之间Catalina的实现可能有较大变化特别是一些内部API。如果你的应用依赖了Tomcat的内部类升级时可能会编译失败或者运行时报错。升级前一定要在测试环境充分验证重点测试Servlet、Filter、Listener、Session这些和Catalina强相关的功能。