Ubuntu 上 Tomcat 出现 HTTP 500 的排查与修复
一、快速定位
- 查看关键日志，优先打开：/opt/tomcat/logs/catalina.out、/opt/tomcat/logs/localhost.<日期>.log、以及应用的 WEB-INF/logs/。使用命令：sudo tail -n100 /opt/tomcat/logs/catalina.out。日志中通常会直接给出异常堆栈或关键线索（如类版本错误、空指针、数据库连接失败等）。
- 复现并最小化请求：用 curl 直连接口（例如：curl -v http://localhost:8080/yourapp/health），比对静态资源与动态接口的差异，判断是否为业务逻辑或资源配置问题。
- 检查端口与进程：确认 8080/8005 等端口未被占用，Tomcat 进程处于正常运行状态（ps -ef | grep tomcat；必要时 kill 后重启）。
- 若页面包含验证码或图片生成，先暂时关闭相关功能验证是否为图形环境导致。
二、常见原因与对应修复
- 代码或配置异常：Servlet/JSP 抛出未捕获异常、web.xml 映射错误、过滤器/监听器初始化失败等。修复方式：依据日志定位到类与行号，修正代码或配置，并做输入校验与异常兜底。
- 版本不兼容：编译用的 JDK 与运行 Tomcat/JRE 版本不一致，典型报错为 UnsupportedClassVersionError。修复：统一 JDK 主版本（如应用用 JDK 11 编译，运行环境也需 JDK 11），或按需重新编译。
- 数据库连接问题：URL、用户名、密码错误，数据库未启动，连接池耗尽或网络不通。修复：核对 context.xml/数据源配置，确认数据库服务与网络可达，检查连接池参数（maxActive、maxWait 等）。
- 资源不足：内存、CPU、磁盘空间不足导致请求处理失败。修复：监控资源（free -m、df -h、top），释放或扩容，并优化应用与 JVM 参数（如 -Xms/-Xmx）。
- 文件权限或工作目录不可写：JSP 编译、上传文件、缓存写入失败。修复：确保 tomcat:tomcat 对 work/、temp/、logs/ 及部署目录具备读写权限（chown -R tomcat:tomcat /opt/tomcat）。
- 外部依赖不可用：缓存、消息队列、第三方 API 异常。修复：逐一检查依赖健康状态与超时/重试策略。
- WAR 过大或部署缓慢：大包（如 >50MB）在部分环境下可能部署失败或触发超时。修复：增大连接器与部署超时（server.xml 中 Connector 的 connectionUploadTimeout、以及后台部署工具的超时），或拆分包、先停服务再部署。
三、Ubuntu 下的操作清单
- 安全获取日志：sudo tail -n200 /opt/tomcat/logs/catalina.out /opt/tomcat/logs/localhost.*.log。
- 彻底重启 Tomcat：
- sudo systemctl stop tomcat9（若通过 apt 安装）
- ps -ef | grep tomcat && sudo kill -9
- sudo systemctl start tomcat9 或 /opt/tomcat/bin/startup.sh
- 清理工作目录缓存（JSP 编译残留常致 500）：
- sudo rm -rf /opt/tomcat/work/Catalina/localhost/<你的应用名>/*
- 必要时也清理 temp 目录。
- 权限修复：sudo chown -R tomcat:tomcat /opt/tomcat/{work,temp,logs,webapps}。
- 图形验证码或图片生成异常（常见于无 X11 的服务器）：在 /opt/tomcat/bin/catalina.sh 的 JAVA_OPTS 增加：-Djava.awt.headless=true，重启。
- 端口冲突排查：ss -tlnp | grep 8080；必要时在 /opt/tomcat/conf/server.xml 调整 Connector 的 port。
四、高频错误速查表
| 现象 |
日志关键词 |
快速修复 |
| 类版本错误 |
UnsupportedClassVersionError |
统一编译与运行的 JDK 主版本，重新编译 |
| 验证码不显示 |
headless、AWT 相关异常 |
启动参数增加 -Djava.awt.headless=true |
| 静态资源可访问，接口 500 |
业务异常堆栈、SQLException |
查业务代码与数据源配置、连接池与健康 |
| 部署大 WAR 失败 |
超时、OutOfMemoryError |
增大连接器/部署超时，优化 JVM 内存，拆分包 |
| 重启后仍 500 |
work 缓存未清 |
删除 work/Catalina/localhost// 后重启 |
五、仍未解决时建议准备的信息
- 异常完整堆栈（来自 catalina.out 或 localhost.<日期>.log）。
- JDK 与 Tomcat 版本（java -version、/opt/tomcat/bin/version.sh）。
- 关键配置片段：server.xml Connector 配置、context.xml 数据源、相关 web.xml。
- 复现步骤与最小请求示例（curl 命令）。
- 部署方式（war 自动部署/manager 部署/手动拷贝）与大致 WAR 大小。
- 服务器资源快照（free -m、df -h、top 前几行）。
