Debian中Tomcat故障排查

Debian 上 Tomcat 故障排查清单

一 快速定位与日志分析

• 确认服务状态与进程：使用命令查看 Tomcat 是否运行、端口是否监听、进程是否存在。示例：sudo systemctl status tomcat9、ps aux | grep tomcat、ss -tulpen | grep ':8080'。
• 定位日志目录：常见路径为 /var/log/tomcat9、/opt/tomcat/logs 或 /usr/local/tomcat/logs。若不确定，可在 conf/server.xml 的 AccessLogValve 中查看日志目录与前缀。
• 实时查看与检索：使用 tail -f catalina.out 实时跟踪；用 grep -i "error\|exception\|failed" catalina.out 快速筛选错误；必要时查看 localhost..log 了解应用日志。
• 调整日志级别：编辑 conf/logging.properties，将相关 logger 级别调为 FINE/DEBUG 以获取更详细输出；确保日志目录对 tomcat 用户可写。

二 常见故障与修复对照表

三 配置文件与目录要点

• 主要配置：conf/server.xml（端口、连接器、Host/Context）、conf/web.xml（应用默认配置）、conf/logging.properties（日志级别与格式）。
• 环境配置：Debian 包常用 /etc/default/tomcat9 设置 JAVA_OPTS、堆大小、JMX 等；也可在 bin/setenv.sh 中设置（若不存在可创建）。
• 日志与访问日志：标准输出与异常通常在 catalina.out；应用日志在 localhost..log；访问日志由 AccessLogValve 定义，目录与前缀可在 server.xml 中查看与调整。
• 数据与临时目录：work/（编译 JSP）、temp/（临时文件）、应用目录 webapps/（WAR 部署与解压）。

四 高频报错速解

• Address already in use：端口冲突。用 ss -tulpen | grep ':8080' 找到占用进程 PID，结束或改端口；编辑 conf/server.xml 的 。
• SEVERE: Error starting Tomcat context：多半是 web.xml 或应用配置错误。查看 catalina.out 与 localhost..log 定位具体类/配置项并修复。
• java.lang.OutOfMemoryError：堆内存不足。在 /etc/default/tomcat9 或 setenv.sh 中调大 JAVA_OPTS（如 -Xms1g -Xmx2g），必要时用 jmap -dump 导出堆转储分析。
• ClassNotFoundException / NoClassDefFoundError：依赖缺失。将 JAR 放入 WEB-INF/lib，或检查应用打包是否完整。
• 管理页面无法登录：编辑 conf/tomcat-users.xml，添加用户并赋予 manager-gui/admin-gui 角色，保存后重启。
• 日志乱码：在 conf/logging.properties 设置 UTF-8；在 server.xml 的 Connector 增加 URIEncoding=“UTF-8”。

五 一键排查脚本与后续建议

• 一键排查脚本（以 tomcat9 为例，按需调整版本与路径）：

#!/usr/bin/env bash
set -e
TOMCAT_USER=tomcat
TOMCAT_SERVICE=tomcat9
TOMCAT_HOME=/usr/share/tomcat9
CATALINA_OUT=/var/log/tomcat9/catalina.out
JAVA_HOME=/usr/lib/jvm/default-java

echo "=== 服务状态 ==="
systemctl status "$TOMCAT_SERVICE" || true

echo "=== 端口监听 ==="
ss -tulpen | grep -E ':(8080|8005|8009)'

echo "=== 进程与内存 ==="
pgrep -x java && jps -v || echo "No Java process found"

echo "=== 最近错误日志 ==="
[ -f "$CATALINA_OUT" ] && tail -n100 "$CATALINA_OUT" | grep -i -E 'error|exception|failed' || echo "No catalina.out"

echo "=== 权限检查 ==="
ls -ld /var/log/tomcat9 /var/lib/tomcat9/{work,temp} 2>/dev/null || true

echo "=== JDK 版本 ==="
"$JAVA_HOME/bin/java" -version 2>&1

echo "=== 建议后续 ==="
echo "1) 查看完整日志: less $CATALINA_OUT"
echo "2) 动态调优: 在 /etc/default/$TOMCAT_SERVICE 设置 JAVA_OPTS"
echo "3) 无法定位时: 增大日志级别 logging.properties 并重启"

• 后续建议：
  • 将日志接入 ELK/Graylog 做集中分析与告警；
  • 配置 logrotate 或 cronolog 做日志切割归档；
  • 使用 jstat -gcutil 1000 持续观察 GC 与健康度；
  • 保持 Tomcat 与 JDK 为兼容版本并及时更新安全补丁。