Tomcat在Debian上的故障排查技巧

Debian 上 Tomcat 故障排查技巧

一 快速定位流程

• 查看服务状态与端口：使用 systemctl status tomcat9 判断是否在运行；用 ss -tulnp | grep ‘:8080’ 或 netstat -tulnp | grep ‘:8080’ 检查端口占用；必要时用 lsof -i :8080 定位占用进程 PID。
• 实时查看日志：到日志目录（如 /var/log/tomcat9/ 或 /opt/tomcat/logs/）执行 tail -f catalina.out，并用 grep -i “error|exception|severe” catalina.out 过滤关键信息。
• 核对进程与资源：用 ps aux | grep tomcat 确认进程；若疑似内存问题，用 jmap -heap 查看堆，或 jmap -dump:format=b,file=heap.hprof 导出堆转储进一步分析。
• 版本与组件：确认 JDK 版本与 Tomcat 兼容，检查数据库驱动、SSL 证书等第三方组件是否正确配置。

二 常见故障与修复

• 端口冲突：默认 8080 被占用时，可停止占用进程（如 kill ），或修改 /etc/tomcat9/server.xml 中 Connector 的 port 为未占用端口（如 8081），随后 systemctl restart tomcat9。
• 配置错误：server.xml / web.xml 语法或路径错误会导致启动失败或应用不可用，逐项核对标签闭合、路径与权限配置。
• 内存不足或 OOM：在 /etc/default/tomcat9 或 bin/setenv.sh 中调整 JAVA_OPTS（如 -Xms512m -Xmx1024m），必要时分析堆转储定位泄漏。
• 权限问题：确保 tomcat 用户对 logs、work、webapps 等目录具备读写权限，避免因权限不足导致无法写日志或部署失败。
• 管理页面不可达：在 conf/tomcat-users.xml 中为管理用户配置正确角色（如 manager-gui、admin-gui），并确认安全约束未误拦截。
• 部署后 404：确认 WAR 已解压到 webapps/应用名，访问路径与 Context 配置一致。

三 日志与编码问题

• 日志位置与级别：常见路径为 /var/log/tomcatX/ 或安装目录下的 logs/；通过 logging.properties 调整日志级别（如将 org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level 设为 FINE 提高详细度），便于定位初始化与请求处理问题。
• 访问日志定位：若 AccessLogValve 配置了 directory/prefix，按该路径查看访问日志，核对 客户端 IP、URL、状态码，快速判断是应用错误还是路由问题。
• 日志过大与切割：使用 cronolog 等工具按日期切割日志，便于管理与检索。
• 控制台与请求乱码：在 conf/logging.properties 将控制台日志编码设为 UTF-8，并在 server.xml 的 Connector 上添加 URIEncoding=“UTF-8”，同时在应用层设置 request.setCharacterEncoding(“UTF-8”)。

四 配置与环境核查清单

• 环境变量：确保 JAVA_HOME 指向 JDK 安装目录，且 PATH 包含 $JAVA_HOME/bin；在 /etc/default/tomcat9 或 setenv.sh 中显式设置更稳妥。
• 配置文件：逐项核查 server.xml（端口、协议、重定向端口）、web.xml（Servlet 映射、过滤器）、context.xml（资源与权限）。
• 内存与 GC：结合应用负载设置 -Xms/-Xmx，必要时开启 GC 日志 辅助分析。
• 自启动与运行用户：使用 systemd 管理（如 tomcat9.service），设置正确的 User/Group 与 Environment（如 JAVA_HOME、CATALINA_HOME、CATALINA_BASE），执行 systemctl daemon-reload 后 systemctl enable --now tomcat9。
• 版本匹配与安全：确认 JDK 与 Tomcat 版本匹配，定期 apt-get update && apt-get upgrade tomcat9 获取修复；谨慎开放管理接口，遵循最小权限原则。

五 一键诊断命令清单

• 服务与端口：
  • systemctl status tomcat9
  • ss -tulnp | grep ‘:8080’
  • lsof -i :8080
• 进程与内存：
  • ps aux | grep tomcat
  • jmap -heap
  • jmap -dump:format=b,file=heap.hprof
• 日志与配置：
  • tail -f /var/log/tomcat9/catalina.out
  • grep -i “error|exception|severe” /var/log/tomcat9/catalina.out
  • less /opt/tomcat/conf/server.xml
  • cat /etc/default/tomcat9
• 在线修改与重启：
  • sudo systemctl restart tomcat9