第七章：Tomcat 常见问题与故障排除

文档摘要

第七章：Tomcat 常见问题与故障排除第七章：Tomcat 常见问题与故障排除 7.1 引言本章将涵盖 Tomcat 启动、部署、性能、安全以及应用层面等多个方面的常见问题，并结合实际的代码示例和 Mermaid 图表，力求将抽象的故障排除过程可视化、具体化，提升读者对 Tomcat 故障诊断和解决的实战能力。 7.2 Tomcat 启动问题 Tomcat 启动阶段是问题高发期，启动失败的原因多种多样，以下列举常见的启动问题及其排查方法： 7.2.1 端口冲突 (Port Conflict) 问题描述: Tomcat 启动时，控制台报错类似，表明指定的端口已被其他程序占用。

第七章：Tomcat 常见问题与故障排除

7.1 引言

本章将涵盖 Tomcat 启动、部署、性能、安全以及应用层面等多个方面的常见问题，并结合实际的代码示例和 Mermaid 图表，力求将抽象的故障排除过程可视化、具体化，提升读者对 Tomcat 故障诊断和解决的实战能力。

7.2 Tomcat 启动问题

Tomcat 启动阶段是问题高发期，启动失败的原因多种多样，以下列举常见的启动问题及其排查方法：

7.2.1 端口冲突 (Port Conflict)

问题描述: Tomcat 启动时，控制台报错类似 java.net.BindException: Address already in use: bind，表明指定的端口已被其他程序占用。Tomcat 默认使用 8080 (HTTP), 8005 (shutdown), 8009 (AJP) 等端口。

故障排除:

确定冲突端口: 仔细查看 Tomcat 启动日志，错误信息会明确指出冲突的端口号。
查找占用端口的进程: 使用系统命令查找占用端口的进程。
- Linux/macOS: lsof -i :<端口号> 或 netstat -tulnp | grep <端口号>
- Windows: netstat -ano | findstr "<端口号>" 然后使用 tasklist /fi "pid eq <PID>" 查找进程名。
解决端口冲突:
- 停止冲突进程: 如果冲突进程是不需要的，直接停止该进程。
- 修改 Tomcat 端口: 修改 Tomcat 的 conf/server.xml 文件，更改 <Connector> 和 <Server port> 元素的 port 属性，使用未被占用的端口。

代码实践 (修改 server.xml):


<!-- conf/server.xml -->
<Server port="8005" shutdown="SHUTDOWN">
    ...
    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />
    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
    ...
</Server>

Mermaid 图表 (端口冲突排查流程):

7.2.2 配置错误 (Configuration Error)

问题描述: server.xml, web.xml, context.xml 等配置文件语法错误或配置项错误，导致 Tomcat 解析配置失败，无法启动。

故障排除:

检查配置文件语法: XML 配置文件对格式要求严格，检查标签是否闭合，属性值是否正确，避免拼写错误。可以使用 XML 编辑器或在线 XML 校验工具检查语法。
查看启动日志: Tomcat 启动日志会详细记录配置解析过程中的错误信息，例如哪个配置文件哪一行出现错误。仔细阅读日志，根据错误提示定位到具体错误位置。
验证配置项: 参考 Tomcat 官方文档，确认配置项的含义和取值范围，确保配置项设置正确。
逐步排查: 如果配置文件较复杂，可以逐步注释或删除部分配置，缩小问题范围，逐个验证配置项的正确性。

代码实践 (server.xml 配置错误示例 - 标签未闭合):


<!-- conf/server.xml (错误示例) -->
<Server port="8005" shutdown="SHUTDOWN">
    <Service name="Catalina">
        <Connector port="8080" protocol="HTTP/1.1" />  <!-- Connector 标签未闭合 -->
        ...
    </Service>
</Server>

Mermaid 图表 (配置错误排查流程):

7.2.3 JAR 包冲突 (JAR Conflict)

问题描述: Tomcat 的 lib 目录或 Web 应用的 WEB-INF/lib 目录下存在版本冲突或重复的 JAR 包，导致类加载器加载类时出现问题，引发 ClassNotFoundException, NoClassDefFoundError, NoSuchMethodError 等异常，Tomcat 启动失败或应用功能异常。

故障排除:

分析异常信息: 仔细查看启动日志或应用报错信息，定位到具体的类加载异常和冲突的 JAR 包名称。
检查 JAR 包来源: 确定冲突 JAR 包来自 Tomcat lib 目录还是 Web 应用的 WEB-INF/lib 目录。
版本冲突排查: 对比冲突 JAR 包的版本，确定是否存在版本不兼容的情况。
重复 JAR 包排查: 检查是否存在同名但不同版本的 JAR 包，或完全重复的 JAR 包。
解决 JAR 包冲突:
- 移除冲突 JAR 包: 删除重复或低版本的 JAR 包，保留需要的版本。
- 调整类加载顺序: 在 conf/catalina.properties 文件中调整类加载顺序，例如修改 shared.loader 或 server.loader 属性，但需谨慎操作，可能影响其他应用。
- 使用 Maven/Gradle 依赖管理: 对于 Web 应用，使用 Maven 或 Gradle 等构建工具进行依赖管理，避免手动管理 JAR 包，可以有效解决依赖冲突问题。

代码实践 (使用 Maven 管理依赖):


<!-- pom.xml (Maven 依赖管理) -->
<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-webmvc</artifactId>
        <version>5.3.20</version>
    </dependency>
    <!-- 其他依赖 -->
</dependencies>

Mermaid 图表 (JAR 包冲突排查流程):

7.2.4 资源不足 (Resource Insufficient)

问题描述: 服务器资源不足，例如内存不足 (OutOfMemoryError), 磁盘空间不足，文件句柄耗尽等，导致 Tomcat 启动失败或运行不稳定。

故障排除:

检查服务器资源: 使用系统命令 (例如 top, free, df, ulimit -n) 检查服务器 CPU, 内存, 磁盘空间, 文件句柄等资源使用情况。
内存不足 (OutOfMemoryError):
- 增加 JVM 内存: 修改 bin/catalina.sh (Linux/macOS) 或 bin/catalina.bat (Windows) 文件，调整 JAVA_OPTS 环境变量，增加 JVM 堆内存和永久代/元空间大小，例如 -Xms2g -Xmx2g -XX:MaxPermSize=256m 或 -XX:MaxMetaspaceSize=256m (JDK 8+)。
- 分析内存泄漏: 如果频繁出现 OOM，可能存在内存泄漏，需要分析 Heap Dump (堆转储文件) 定位泄漏对象。
磁盘空间不足: 清理无用文件，增加磁盘空间。
文件句柄耗尽: 调整系统文件句柄限制 (ulimit -n)，并检查应用是否存在文件句柄泄漏。

代码实践 (修改 catalina.sh 增加 JVM 内存):


# bin/catalina.sh (Linux/macOS)
JAVA_OPTS="-Xms2g -Xmx2g -XX:MaxPermSize=256m"  # JDK 8 之前
JAVA_OPTS="-Xms2g -Xmx2g -XX:MaxMetaspaceSize=256m" # JDK 8 及之后

Mermaid 图表 (资源不足排查流程):

7.2.5 日志分析 (Log Analysis)

问题描述: Tomcat 启动过程中出现各种错误，但控制台信息不足以定位问题。

故障排除:

查看 Tomcat 日志: Tomcat 的日志文件位于 logs 目录下，主要关注以下日志文件：
- catalina.out: Tomcat 启动和运行过程中的标准输出和标准错误信息，包括 JVM 日志、Tomcat 内部日志、Web 应用日志等。
- catalina.yyyy-MM-dd.log: Tomcat Catalina 组件的日志，记录 Tomcat 启动、停止、部署、卸载等事件。
- localhost.yyyy-MM-dd.log: 默认 Host (localhost) 的访问日志和错误日志。
- manager.yyyy-MM-dd.log, host-manager.yyyy-MM-dd.log: Manager 应用和 Host Manager 应用的日志。
- access_log.yyyy-MM-dd.txt: 访问日志，记录 HTTP 请求的详细信息 (如果配置了 AccessLogValve)。
分析日志信息: 仔细阅读日志文件，搜索 ERROR, WARN, Exception, Fail 等关键字，查找错误信息和异常堆栈，根据错误信息定位问题原因。
调整日志级别: 如果默认日志级别信息不足，可以修改 conf/logging.properties 文件，调整日志级别，例如将 java.util.logging.ConsoleHandler.level 和 org.apache.catalina.level 设置为 FINEST 或 ALL，获取更详细的日志信息。

代码实践 (修改 logging.properties 调整日志级别):


# conf/logging.properties
java.util.logging.ConsoleHandler.level = FINEST
org.apache.catalina.level = FINEST

Mermaid 图表 (日志分析流程):

7.3 Tomcat 部署问题

Web 应用部署到 Tomcat 过程中也可能遇到各种问题，导致部署失败或应用无法正常访问。

7.3.1 WAR 包部署失败 (WAR Deployment Failure)

问题描述: 将 WAR 包复制到 webapps 目录下，Tomcat 无法自动解压部署，或部署过程中报错。

故障排除:

检查 WAR 包完整性: 确保 WAR 包文件没有损坏，可以尝试重新构建 WAR 包。
检查 WAR 包格式: WAR 包应符合标准 WAR 格式，包含 WEB-INF 目录 (至少包含 web.xml 或 classes 目录)。
查看 Tomcat 日志: 部署过程中的错误信息会记录在 Tomcat 日志中 (例如 catalina.out, localhost.log)，仔细查看日志定位错误原因。
权限问题: 确保 Tomcat 进程有权限读取和解压 WAR 包，以及在 webapps 目录下创建应用目录和文件的权限。
Context Path 冲突: 如果部署的应用 Context Path 与已部署的应用冲突，会导致部署失败。检查 server.xml, context.xml 或 WAR 包中的 Context Path 配置。
手动部署: 如果自动部署失败，可以尝试手动部署，在 conf/server.xml 中配置 <Context> 元素，指定应用的 Context Path 和 docBase。

代码实践 (server.xml 手动部署 Context):


<!-- conf/server.xml -->
<Host name="localhost"  appBase="webapps"
      unpackWARs="true" autoDeploy="true">
    ...
    <Context path="/myapp" docBase="/path/to/myapp.war" reloadable="true" />
    ...
</Host>

Mermaid 图表 (WAR 包部署失败排查流程):

7.3.2 Context Path 冲突 (Context Path Conflict)

问题描述: 多个 Web 应用配置了相同的 Context Path，导致部署冲突，Tomcat 启动或部署报错，或访问应用时路由错误。

故障排除:

检查 Context Path 配置: 检查 server.xml, context.xml, WAR 包中的 META-INF/context.xml 以及 Web 应用的 web.xml 中是否配置了 Context Path。
确定冲突 Context Path: 查看 Tomcat 日志，错误信息会指出冲突的 Context Path。
修改 Context Path: 修改冲突应用的 Context Path 配置，确保每个应用的 Context Path 唯一。
- 修改 server.xml/context.xml: 修改 <Context path="..."> 属性。
- 修改 WAR 包名: 如果使用自动部署，Tomcat 默认使用 WAR 包的文件名 (不含 .war 后缀) 作为 Context Path，可以修改 WAR 包文件名来修改 Context Path。

代码实践 (修改 server.xml Context Path):


<!-- conf/server.xml -->
<Context path="/myapp1" docBase="/path/to/myapp1.war" reloadable="true" />
<Context path="/myapp2" docBase="/path/to/myapp2.war" reloadable="true" />  <!-- 修改 Context Path 为 /myapp2 -->

Mermaid 图表 (Context Path 冲突排查流程):

7.3.3 依赖缺失 (Missing Dependencies)

问题描述: Web 应用依赖的 JAR 包在 Tomcat 的 lib 目录或 Web 应用的 WEB-INF/lib 目录下缺失，导致类加载失败，应用启动或运行时报错 ClassNotFoundException, NoClassDefFoundError。

故障排除:

分析异常信息: 查看 Tomcat 日志或应用报错信息，定位到缺失的类和 JAR 包名称。
确定依赖 JAR 包: 根据异常信息和应用代码，确定缺失的 JAR 包。
添加依赖 JAR 包: 将缺失的 JAR 包复制到 Tomcat 的 lib 目录 (所有应用共享) 或 Web 应用的 WEB-INF/lib 目录 (仅当前应用使用)。推荐将应用依赖的 JAR 包放在 WEB-INF/lib 目录下，避免与其他应用冲突。
使用 Maven/Gradle 依赖管理: 对于 Web 应用，使用 Maven 或 Gradle 等构建工具进行依赖管理，自动下载和管理依赖 JAR 包。

代码实践 (手动添加依赖 JAR 包):

将缺失的 JAR 包 (例如 mysql-connector-java-8.0.29.jar) 复制到 Web 应用的 WEB-INF/lib 目录下。

Mermaid 图表 (依赖缺失排查流程):

7.3.4 权限问题 (Permissions Issue)

问题描述: Tomcat 进程没有足够的权限访问 Web 应用的文件或目录，例如读取静态资源、写入日志文件、访问数据库连接池配置文件等，导致部署失败或应用功能异常。

故障排除:

检查文件/目录权限: 使用 ls -l (Linux/macOS) 或文件资源管理器 (Windows) 检查 Web 应用相关文件和目录的权限，确保 Tomcat 运行用户 (通常是 tomcat 用户) 具有相应的读写权限。
修改文件/目录权限: 使用 chmod (Linux/macOS) 或文件资源管理器 (Windows) 修改文件和目录权限，赋予 Tomcat 运行用户所需的权限。
SELinux/AppArmor 等安全模块: 如果服务器启用了 SELinux 或 AppArmor 等安全模块，可能需要配置相应的策略，允许 Tomcat 进程访问 Web 应用的文件和目录。

代码实践 (Linux/macOS 修改文件权限):


sudo chown -R tomcat:tomcat /path/to/webapp  # 修改所有者和组
sudo chmod -R 755 /path/to/webapp        # 修改权限为 755 (读写执行/读执行/读执行)

Mermaid 图表 (权限问题排查流程):

7.3.5 热部署问题 (Hot Deployment Issue)

问题描述: Tomcat 配置了热部署 (autoDeploy="true", reloadable="true")，但修改 Web 应用后，Tomcat 没有自动重新部署，导致修改不生效。

故障排除:

检查热部署配置: 确认 conf/server.xml 中 <Host> 元素的 autoDeploy 和 unpackWARs 属性设置为 true，以及 <Context> 元素的 reloadable 属性设置为 true (如果手动配置了 Context)。
检查修改文件类型: 热部署通常只监听 Web 应用 WEB-INF/classes 和 WEB-INF/lib 目录下的文件修改，以及 web.xml, context.xml 等配置文件的修改。修改 JSP 页面或静态资源可能不会触发热部署。
检查文件修改时间: 确保修改文件的修改时间确实发生了变化，某些编辑器或操作可能不会更新文件修改时间。
手动触发热部署: 可以尝试手动触发热部署，例如通过 Tomcat Manager 应用的 "Reload" 功能，或重启 Tomcat。
日志分析: 查看 Tomcat 日志，检查是否有热部署相关的日志信息，例如是否检测到文件修改，是否触发了重新部署。

代码实践 (server.xml 热部署配置):


<!-- conf/server.xml -->
<Host name="localhost"  appBase="webapps"
      unpackWARs="true" autoDeploy="true">
    <Context path="/myapp" docBase="myapp" reloadable="true" />
    ...
</Host>

Mermaid 图表 (热部署问题排查流程):

7.4 Tomcat 性能问题

Tomcat 性能问题是生产环境中常见且重要的问题，影响用户体验和系统稳定性。

7.4.1 响应缓慢 (Slow Response Time)

问题描述: Web 应用响应时间过长，用户访问页面或接口时等待时间过长。

故障排除:

性能监控: 使用性能监控工具 (例如 JConsole, VisualVM, Prometheus + Grafana, APM 工具) 监控 Tomcat 的 CPU 使用率、内存使用率、线程池状态、数据库连接池状态、HTTP 请求处理时间等指标。
线程池瓶颈: 检查 Tomcat Connector 的线程池配置 (maxThreads, acceptCount)，如果线程池耗尽，新的请求将被阻塞。可以增加 maxThreads 或优化请求处理速度。
数据库瓶颈: 如果应用依赖数据库，检查数据库查询语句是否效率低下，数据库连接池配置是否合理 (maxActive, maxIdle, minIdle)，数据库服务器性能是否足够。
应用代码瓶颈: 使用 Profiler 工具 (例如 JProfiler, YourKit) 分析应用代码，定位耗时操作，例如复杂的业务逻辑、IO 操作、同步阻塞等。
JVM 垃圾回收 (GC) 瓶颈: 监控 JVM GC 频率和耗时，频繁 Full GC 会导致应用停顿。可以调整 JVM GC 参数，优化 GC 策略。
网络瓶颈: 检查网络带宽、延迟、丢包率等，网络问题也可能导致响应缓慢。
静态资源优化: 对于静态资源 (例如图片、CSS、JS), 可以启用 Tomcat 的静态资源缓存，或使用 CDN 加速。

代码实践 (JConsole 监控 Tomcat 线程):

启动 Tomcat，并启用 JMX 远程监控 (修改 bin/catalina.sh 或 bin/catalina.bat):


JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote
           -Dcom.sun.management.jmxremote.port=9001
           -Dcom.sun.management.jmxremote.authenticate=false
           -Dcom.sun.management.jmxremote.ssl=false"

启动 JConsole，连接到 Tomcat 进程 (localhost:9001)。
在 "MBeans" 选项卡中，选择 "Catalina" -> "ThreadPool" -> "http-nio-8080" (或你的 Connector 名称)，查看 currentThreadCount, currentThreadsBusy, maxThreads 等属性。

Mermaid 图表 (响应缓慢排查流程):

7.4.2 CPU 使用率过高 (High CPU Usage)

问题描述: Tomcat 进程 CPU 使用率持续过高，导致服务器负载过高，影响系统性能。

作者与出处

原作者：灏天文库

来源：灏天文库

原文： https://aiknowledge.cn/collection/182-tomcat-web%E6%9C%8D%E5%8A%A1%E5%99%A8%E9%85%8D%E7%BD%AE%E4%B8%8E%E7%AE%A1%E7%90%86

整理：灏天文库整理

由灏天文库平台收录，内容或由平台用户上传，仅供学习交流