Debian 上 Tomcat 故障排查技巧
一 快速定位与通用流程
- 查看服务状态与系统日志：使用 systemctl status tomcat9 或 journalctl -xe 获取启动失败的直接线索与系统级报错。
- 定位并实时跟踪日志：Tomcat 日志通常在 /var/log/tomcat9/ 或 $CATALINA_HOME/logs/，优先查看 catalina.out，配合 tail -f、grep “ERROR|SEVERE|WARNING” 快速筛选关键信息。
- 检查端口占用：用 ss -tulpen | grep 8080 或 netstat -tuln | grep 8080 确认 8080/8005/8009 是否被占用；若冲突，结束占用进程或修改 conf/server.xml 中的 Connector port。
- 校验关键配置：检查 server.xml（端口、协议、线程与超时）、web.xml（应用配置）、以及访问日志 AccessLogValve 的 directory/prefix 是否指向可写目录。
- 确认 Java 与权限：执行 java -version，确保 JAVA_HOME 指向 JDK；检查 tomcat 用户对 conf/、logs/、webapps/ 的读写权限。
- 重启并复测：修正后执行 systemctl restart tomcat9 并再次观察日志与端口状态。
二 常见故障与对应处理
| 症状 |
快速检查 |
处理要点 |
| 端口被占用无法启动 |
ss/netstat 查 8080/8005/8009 |
结束占用进程或改 server.xml 的 Connector port |
| JAVA_HOME 或 JDK 不匹配 |
java -version；核对版本要求 |
安装合适 JDK，正确设置 JAVA_HOME |
| server.xml 配置错误 |
启动日志报解析错误 |
校验标签闭合、端口与路径；必要时回滚 |
| 权限不足导致无法写日志/部署 |
查看 logs/ 与 work/ 权限 |
以 tomcat 用户运行，修正目录属主/权限 |
| 内存不足或频繁 Full GC |
日志出现 OutOfMemoryError；jstat 观察 |
调整 JAVA_OPTS（如 -Xms/-Xmx），分析并优化内存使用 |
| 部署失败 |
catalina.out/localhost 报部署异常 |
检查 web.xml、依赖 WEB-INF/lib、MANIFEST.MF 与上下文配置 |
| 访问异常（404/500） |
访问日志与 localhost 日志 |
核对应用上下文路径、过滤器/监听器异常、静态资源映射 |
以上要点对应的命令与配置位置可参考：日志与端口检查、配置文件校验、JDK 与权限确认、内存与部署问题处理等实践。
三 日志分析与性能瓶颈定位
- 访问与错误日志分析：在 catalina.out 与 localhost.yyyy-MM-dd.log 中检索 ERROR/SEVERE，结合访问日志统计 HTTP 状态码分布、请求耗时，定位异常高发接口与时段。
- GC 与内存：启用 GC 日志（如 -Xloggc、-XX:+PrintGCDetails、-XX:+PrintGCDateStamps），用 jstat -gc 观察 YGC/FGC 频率与停顿；必要时用 jmap -heap 查看堆配置与使用，生成 heap dump 深入分析。
- 线程与锁：用 jstack 获取线程转储，排查 BLOCKED/长时间运行线程 与潜在死锁。
- 系统资源：结合 top/htop、vmstat、iostat 观察 CPU、内存、I/O 瓶颈；配合 ss 检查连接状态与队列。
- 数据库与应用：核对 连接池 配置（最大连接、超时、泄漏）；必要时引入 APM（如 New Relic/Datadog）做调用链与热点定位。
四 配置与维护要点
- 日志级别与输出：在 conf/logging.properties 合理设置日志级别（生产常用 INFO/WARN），避免 DEBUG/ALL 导致 I/O 膨胀；必要时开启 异步日志 降低业务线程阻塞。
- 日志轮转与清理：配置 AccessLogValve 的 directory/prefix，使用 logrotate/cronolog 定期归档与清理旧日志，防止磁盘占满。
- JVM 与线程池：在 setenv.sh 或系统环境设置 JAVA_OPTS（如 -Xms512M -Xmx1024M），结合并发量调整 server.xml 的 maxThreads/acceptCount 等参数。
- 安全与自启动：确保以 tomcat 非特权用户运行；使用 systemctl enable tomcat9 配置开机自启，变更配置前先备份。
五 一键排查命令清单
- 服务与系统日志：systemctl status tomcat9；journalctl -xe
- 端口占用：ss -tulpen | grep 8080（或 netstat -tuln | grep 8080）
- 进程与线程：ps -ef | grep tomcat；top/htop；jstack
- 内存与 GC：jstat -gc ；jmap -heap ；生成 dump：jmap -dump:format=b,file=heap.hprof
- 日志跟踪与筛选：tail -f /var/log/tomcat9/catalina.out；grep -i “ERROR|SEVERE” catalina.out