Debian Tomcat故障排查指南

快速定位与最小复现

• 确认服务状态与版本
  使用命令查看服务与进程：sudo systemctl status tomcat9、ps aux | grep tomcat、java -version。若使用包管理安装，版本通常为 Tomcat 9（Debian 10/11/12 常见）。
• 立刻查看核心日志
  实时观察：tail -f /var/log/tomcat9/catalina.out；按日期查看：ls /var/log/tomcat9/。优先检索关键字：ERROR、SEVERE、Exception、Failed。
• 检查端口占用
  快速确认：ss -tulpen | grep 8080 或 lsof -i:8080。若被占用，结束占用进程或修改 server.xml 中的 Connector port。
• 做一次最小化自检
  重启服务：sudo systemctl restart tomcat9；若仍失败，立即回到日志定位首条报错。
  以上步骤覆盖了 Debian 上最常见的启动与运行异常路径，可快速判断是端口、权限、配置还是应用本身的问题。

日志分析与常见错误模式

• 核心日志与关键文件
  主要日志位于 CATALINA_HOME/logs/ 或 /var/log/tomcatX/，重点查看：catalina.out（启动/运行/关闭主日志）、catalina.yyyy-MM-dd.log（按日期分割）、localhost.yyyy-MM-dd.log（应用日志）、以及可选的 manager/host-manager 日志。
• 高效检索命令
  实时跟踪：tail -f catalina.out；错误筛选：grep -i "error\|exception\|failed" catalina.out；按时间定位：grep "2025-06-08" localhost.2025-06-08.log；统计高频 URL：cat localhost.*.log | grep "HTTP" | awk '{print $7}' | sort | uniq -c | sort -nr。
• 常见错误模式与处置要点

以上方法适用于 Debian 上 Tomcat 的日志定位与常见问题快速处置。

配置与运行环境核查清单

• 环境变量与 JDK 匹配
  确认 JAVA_HOME 指向 JDK（而非 JRE），echo $JAVA_HOME；确保 JDK 版本与 Tomcat 版本兼容（如 Tomcat 9 建议使用 JDK 8/11）。
• 配置文件语法与路径
  核查 /etc/tomcat9/server.xml（端口、协议、线程与连接器）、/etc/tomcat9/context.xml（数据源、资源）、/var/lib/tomcat9/webapps/应用/META-INF/context.xml（应用级资源）、以及 logging.properties（日志级别与路径）。
• JVM 内存与 GC
  在 /etc/default/tomcat9 或 bin/setenv.sh 中设置：
  • 示例：JAVA_OPTS="-Xms512m -Xmx2048m -XX:+UseG1GC"（Tomcat 9 使用 Metaspace，无需 PermSize/MaxPermSize）。
• 权限与属主
  确保 /var/log/tomcat9、/var/lib/tomcat9、/etc/tomcat9 归属 tomcat:tomcat，目录权限 750/755，日志文件 644。
• 应用与依赖
  校验 WEB-INF/lib 依赖齐全、无冲突版本；检查 web.xml 配置与过滤器/监听器初始化异常。
• 自启动与版本更新
  启用开机自启：sudo systemctl enable --now tomcat9；必要时执行 sudo apt-get update && sudo apt-get install --only-upgrade tomcat9 获取安全修复。
  以上检查可排除环境、配置与权限层面的绝大多数故障根因。

性能与高并发优化要点

• 连接器与线程池
  使用 NIO/NIO2 或 HTTP/2（Tomcat 8.5+），示例：
  • <Connector port="8080" protocol="org.apache.coyote.http11.Http11Nio2Protocol" connectionTimeout="20000" redirectPort="8443" />
  • HTTP/2（需 TLS）：<Connector port="8443" protocol="org.apache.coyote.http2.Http2Protocol" maxThreads="150" SSLEnabled="true">...</Connector>
  • 线程池：<Executor name="tomcatThreadPool" namePrefix="catalina-exec-" maxThreads="500" minSpareThreads="50" maxQueueSize="100"/>
• JVM 与内存
  结合负载设置堆与 GC：-Xms 与 -Xmx（如 2–4GB 起步）、-XX:+UseG1GC；避免频繁 Full GC。
• 传输与压缩
  开启压缩与合适 MIME：compression="on" compressionMinSize="2048" compressableMimeType="text/html,text/xml,text/css,text/javascript"。
• 操作系统层面
  提升文件描述符与网络参数：ulimit -n 65535；/etc/sysctl.conf 中调优 net.core.somaxconn、net.ipv4.tcp_max_syn_backlog、net.ipv4.ip_local_port_range、net.ipv4.tcp_tw_reuse、net.ipv4.tcp_fin_timeout。
• 架构与监控
  前端用 Nginx/Apache 做静态资源与反向代理，必要时禁用 AJP；接入 Prometheus + Grafana 或 ELK 做指标与日志可观测。
  以上优化项可显著提升吞吐、降低延迟，并增强稳定性与可维护性。

一键排障命令清单

# 1) 服务与进程
sudo systemctl status tomcat9
ps aux | grep tomcat
java -version

# 2) 端口占用
ss -tulpen | grep 8080
lsof -i:8080

# 3) 日志实时查看与检索
tail -f /var/log/tomcat9/catalina.out
grep -i "error\|exception\|failed" /var/log/tomcat9/catalina.out
ls /var/log/tomcat9/

# 4) JVM 内存与 GC
jps
jstat -gcutil <pid> 1000
jmap -heap <pid>
jmap -dump:format=b,file=heap.hprof <pid>

# 5) 配置与权限
ls -l /etc/tomcat9 /var/lib/tomcat9 /var/log/tomcat9
sudo systemctl restart tomcat9
sudo systemctl enable --now tomcat9

以上命令覆盖状态、端口、日志、JVM 与配置的关键环节，适合作为现场排障的“最小工具集”。