3.6 常见问题排查与故障排除

3.6 常见问题排查与故障排除

摘要：本节系统梳理 Tomcat 运行过程中高频出现的六大类典型故障——启动失败、内存溢出、Servlet/JSP 加载异常、数据库连接池失效、Session 管理异常及日志管理低效问题。结合日志分析路径、配置修正要点、代码级修复实践与生产环境最佳实践，提供可立即落地的结构化排障指南，全面提升 Tomcat 服务稳定性与可观测性。

一、Tomcat 无法启动问题排查

1.1 问题现象

启动脚本（startup.sh 或 startup.bat）执行后无响应，或控制台快速退出；logs/catalina.out 中出现 SEVERE 级错误，进程未出现在 ps aux | grep java 或 tasklist | findstr java 结果中。

1.2 根本原因与诊断流程

1.3 实操修复方案

• 端口重映射示例（conf/server.xml）：

  <!-- 修改 HTTP 连接器端口 -->
  <Connector port="8081" protocol="HTTP/1.1" 
             connectionTimeout="20000" 
             redirectPort="8443" />
  <!-- 同步修改 AJP 连接器（如需） -->
  <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
  ​

• 环境变量加固（bin/setenv.sh，Linux/macOS）：

  # 显式声明 JAVA_HOME（避免依赖系统变量）
  export JAVA_HOME="/usr/lib/jvm/java-11-openjdk-amd64"
  # 设置合理 JVM 内存（避免启动失败）
  export JAVA_OPTS="-Xms512m -Xmx1024m -Dfile.encoding=UTF-8"
  # 禁用 RMI 服务器（防止端口冲突）
  export CATALINA_OPTS="-Dcom.sun.management.jmxremote=false"
  ​

二、内存溢出（OutOfMemoryError）问题

2.1 问题现象

应用运行中突然中断，catalina.out 出现以下典型错误：

• java.lang.OutOfMemoryError: Java heap space
• java.lang.OutOfMemoryError: Metaspace
• java.lang.OutOfMemoryError: GC overhead limit exceeded

2.2 分层诊断策略

2.3 生产级修复实践

• JVM 参数调优模板（bin/setenv.sh）：

  export JAVA_OPTS="-Xms1024m -Xmx2048m \
                    -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m \
                    -XX:+UseG1GC -XX:MaxGCPauseMillis=200 \
                    -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/tomcat/logs/"
  ​

• 代码级防护：
  • 使用 try-with-resources 确保 Connection、Statement、ResultSet 自动关闭
  • 避免 static 集合缓存大对象（改用 WeakReference 或分布式缓存）
  • Spring Boot 应用启用 spring.datasource.hikari.leak-detection-threshold=60000（毫秒）检测连接泄漏

三、Servlet 与 JSP 加载失败问题

3.1 问题现象

• 访问 http://localhost:8080/app/servlet-path 返回 404 Not Found 或 500 Internal Server Error
• JSP 页面报 org.apache.jasper.JasperException: Unable to compile class for JSP
• 控制台输出 Servlet [xxx] is not available

3.2 关键检查点

3.3 快速修复方案

• Servlet 3.0+ 注解替代 XML（推荐）：

  @WebServlet(name = "UserServlet", urlPatterns = "/user")
  public class UserServlet extends HttpServlet {
      protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
          // 实现逻辑
      }
  }
  ​

• JSP 编码统一声明（web.xml）：

  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.jsp</url-pattern>
      <page-encoding>UTF-8</page-encoding>
      <scripting-invalid>false</scripting-invalid>
    </jsp-property-group>
  </jsp-config>
  ​

四、数据库连接池配置与泄漏问题

4.1 问题现象

• 应用响应缓慢，Connection refused 或 Connection timeout 频发
• Tomcat 启动后日志出现 Abandoned connection cleanup 或 Pool is closed
• netstat -an \| grep :3306 显示大量 TIME_WAIT 或 ESTABLISHED 连接

4.2 连接池核心参数校验表

4.3 context.xml 安全配置示例

<Resource name="jdbc/MyDB"
          auth="Container"
          type="javax.sql.DataSource"
          factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
          driverClassName="com.mysql.cj.jdbc.Driver"
          url="jdbc:mysql://localhost:3306/mydb?useSSL=false&amp;serverTimezone=UTC"
          username="app_user"
          password="secure_password"
          maxTotal="30"
          minIdle="5"
          maxWaitMillis="30000"
          validationQuery="SELECT 1"
          testOnBorrow="true"
          removeAbandonedOnBorrow="true"
          removeAbandonedTimeout="60"
          logAbandoned="true"
          timeBetweenEvictionRunsMillis="30000"
          minEvictableIdleTimeMillis="60000"/>
​

关键提示：生产环境禁用 logAbandoned="true"（性能损耗），改用监控告警（如 Prometheus + Grafana）跟踪 abandonedCount 指标。

五、Session 超时与持久化问题

5.1 问题现象

• 用户登录后频繁跳转至登录页（HttpSession 提前失效）
• 集群环境下 Session 数据不共享，导致负载均衡后状态丢失
• SESSION 表（数据库持久化）持续增长，无自动清理

5.2 配置层级与作用域

5.3 高可用 Session 方案对比

5.4 Redis Session 配置（Spring Boot）

# application.yml
spring:
  session:
    store-type: redis
    redis:
      flush-mode: on_save
      namespace: tomcat:session
  redis:
    host: 192.168.1.100
    port: 6379
    password: redis_pass
    timeout: 5000
​

六、日志文件管理与分析优化

6.1 日志性能瓶颈与治理策略

6.2 Tomcat 日志配置优化（conf/logging.properties）

# 全局日志级别
handlers = java.util.logging.ConsoleHandler, org.apache.juli.AsyncFileHandler

# Catalina 核心日志（INFO 级别）
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].handlers = java.util.logging.ConsoleHandler

# 应用访问日志（独立文件，按天轮转）
1catalina.org.apache.juli.AsyncFileHandler.level = FINE
1catalina.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
1catalina.org.apache.juli.AsyncFileHandler.prefix = catalina.
1catalina.org.apache.juli.AsyncFileHandler.rotatable = true
1catalina.org.apache.juli.AsyncFileHandler.maxDays = 30

# 关键组件日志（降低冗余）
org.apache.jasper.compiler.TldLocationsCache.level = WARNING
org.apache.catalina.session.ManagerBase.level = WARNING
​

故障排查黄金法则（总结）

1. 日志为先：90% 的问题可通过 logs/catalina.out + logs/localhost.<date>.log 定位，启用 FINE 级别快速聚焦
2. 配置隔离：修改 conf/ 下配置后，必须重启 Tomcat（热更新不生效）
3. 环境一致性：开发/测试/生产环境的 JAVA_HOME、JVM 参数、数据库驱动版本 必须严格对齐
4. 最小复现：剥离业务代码，用最简 Servlet/JSP 验证基础功能，排除应用层干扰
5. 版本验证：Tomcat 9+ 默认禁用 JSP 编译缓存，若遇 JSP 变更不生效，检查 conf/web.xml 中 development="true"

SEO 关键词自然融入：Tomcat 故障排查、Tomcat 启动失败、Tomcat 内存溢出、Servlet 加载异常、Tomcat 连接池配置、Tomcat Session 管理、Tomcat 日志优化、Tomcat 生产环境调优