Ubuntu Tomcat 500 错误的定位与修复步骤
一、快速定位
- 查看关键日志，优先从 /var/log/tomcat/ 下的 catalina.out、localhost..log 入手，使用命令快速检索：
- grep -n “500|Exception|Error” /var/log/tomcat/catalina.out
- grep -n “SEVERE|FATAL” /var/log/tomcat/catalina.out
- 在日志中定位到具体请求与堆栈，例如出现 java.lang.NullPointerException at com.example.MyServlet.doGet(MyServlet.java:50) 时，即可锁定到代码行与类。
- 若日志提示“response already committed”，说明响应已提交，无法再转发到错误页，需调整异常处理，避免先输出内容再跳转。
二、常见根因与对应修复
- 应用代码缺陷：未捕获的运行时异常、逻辑错误。修复代码并用调试器或增加日志还原问题现场。
- 配置错误：server.xml、web.xml、context.xml 中路径、端口、过滤器/监听器配置不当。逐项校验语法与生效路径。
- 资源限制：内存、CPU、磁盘不足。检查系统资源并适当调整 JAVA_OPTS（如堆大小）。
- 数据库连接：URL、用户名、密码错误或数据库不可达。核对连接串、网络与账号权限，必要时先用命令行/客户端连通性验证。
- 版本/依赖冲突：Tomcat 版本与代码或依赖库不兼容；存在重复 JAR 或版本冲突。统一编译与运行 JDK 版本，清理并重打包依赖。
- 文件与权限：Tomcat 进程对应用目录、日志目录、临时目录无读写权限。校正 owner/group 与 mode，确保工作目录可写。
- 外部服务依赖：缓存、消息队列、第三方 API 异常。先隔离验证外部依赖健康度。
- 网络问题：请求未达或响应未回。排查防火墙、反向代理、负载均衡与健康检查配置。
三、配置与资源检查清单
- 环境变量：确认 JAVA_HOME / JRE_HOME 指向正确的 JDK，与编译版本一致，避免 UnsupportedClassVersionError。
- JVM 与内存：在 $CATALINA_HOME/bin/setenv.sh 中设置合适的 JAVA_OPTS（如 -Xms/-Xmx），并监控 GC 与内存使用。
- 连接器与端口：检查 server.xml 中 HTTP/HTTPS/AJP 端口占用与协议配置，避免端口冲突。
- 应用部署单元：确认 webapps/应用名.war 已完整解压，目录结构与 WEB-INF/lib、WEB-INF/classes 正确。
- 权限与属主：Tomcat 通常以 tomcat 用户运行，确保 /var/log/tomcat、应用目录、工作目录归属正确且可写。
- 数据库连通：在应用宿主机上用 psql/mysql 客户端直连数据库验证账号、白名单与 SSL 配置。
- 外部依赖：逐一健康检查缓存、消息队列、搜索等服务，必要时降级或熔断以排除干扰。
四、快速修复操作
- 重启服务：先优雅停止再启动，观察启动期是否抛出异常。
- sudo systemctl restart tomcat9
- tail -n100 /var/log/tomcat/catalina.out
- 重新部署：清理工作与临时目录，重新部署 WAR。
- sudo systemctl stop tomcat9
- rm -rf $CATALINA_HOME/work/* $CATALINA_HOME/temp/*
- 将新的 app.war 放入 webapps/，启动后观察解压与日志
- sudo systemctl start tomcat9
- 回滚版本：若近期变更引发问题，先回滚至上一个稳定 WAR 或镜像标签，确认问题边界。
五、日志示例与修复要点
- 场景一：类版本不兼容
- 日志特征：UnsupportedClassVersionError
- 处理：统一 编译 JDK 与 运行 JDK 版本，必要时用相同版本重新编译。
- 场景二：数据库连接失败
- 日志特征：SQLException/CommunicationsException/Access denied
- 处理：核对 JDBC URL、用户名、密码、驱动版本，确认数据库服务与网络可达。
- 场景三：响应已提交导致无法跳转错误页
- 日志特征：response already committed
- 处理：调整代码，确保在写入响应前完成异常处理与跳转，避免在页面已输出后再转发。