Debian 上 Tomcat 故障排查清单
一 快速定位与通用检查
- 查看服务状态与日志
- 使用 systemd：执行 systemctl status tomcat9（或 tomcat8/tomcat7），从输出中确认是否 active (running)、是否 failed，并查看最近的 journalctl -u tomcat9 -xe 日志片段。
- 查看关键日志：优先检查 /var/log/tomcat9/catalina.out（启动与致命错误）、/var/log/tomcat9/localhost.<日期>.log（应用部署与初始化）、以及 /var/log/tomcat9/access.<日期>.log（访问日志）。使用 tail -f 实时跟踪最新输出。
- 确认进程与端口
- 进程：执行 ps aux | grep tomcat 确认 java 进程是否存在且以 tomcat 用户运行。
- 端口：执行 ss -tulnp | grep ‘:8080|:8005|:8009’ 检查 HTTP 8080、SHUTDOWN 8005、AJP 8009 是否被占用；若被占用，记录 PID 以便处理。
- 配置与环境
- 配置文件：/etc/tomcat9/server.xml（连接器端口、协议、编码、Host/Context）、/etc/default/tomcat9（环境变量如 JAVA_HOME/JAVA_OPTS、内存、用户等）。
- 环境变量：确保 JAVA_HOME 指向 JDK 安装目录（如 /usr/lib/jvm/default-java），并且 PATH 包含 $JAVA_HOME/bin。
- 文件权限与目录
- 确认 /var/log/tomcat9、/var/lib/tomcat9、/usr/share/tomcat9 等目录属主为 tomcat:tomcat，权限合理（日志可写、工作目录可读写）。
二 常见故障与修复对照表
| 症状 |
快速检查 |
修复建议 |
| 启动失败或进程秒退 |
查看 catalina.out 首屏报错；检查 JAVA_HOME 与 /etc/default/tomcat9 |
修正 JAVA_HOME；在 /etc/default/tomcat9 设置合适的 JAVA_OPTS（如 -Xms512m -Xmx1024m）；修复 server.xml 语法错误后重启 |
| 端口被占用（8080/8005/8009） |
**ss -tulnp |
grep ‘:8080|:8005|:8009’** |
| 管理页面 403/401 或无法登录 |
查看 tomcat-users.xml 角色与用户 |
在 /etc/tomcat9/tomcat-users.xml 配置如 manager-gui/admin-gui 角色与用户，注意服务重启后生效 |
| 部署 WAR 后 404 |
检查 webapps 是否解压出目录；确认 Context 路径 |
确认 WAR 已上传且解压；必要时在 server.xml 或应用目录设置正确 path；查看应用自身日志 |
| 控制台或请求中文乱码 |
查看日志与浏览器编码 |
在 conf/logging.properties 设置 java.util.logging.ConsoleHandler.encoding=UTF-8；在 server.xml 的 增加 URIEncoding=“UTF-8” |
| 内存不足或频繁 Full GC |
catalina.out 出现 OutOfMemoryError |
在 /etc/default/tomcat9 或 bin/setenv.sh 提升堆内存（如 -Xms1g -Xmx2g），并分析应用内存泄漏 |
| 权限错误（无法写日志/无法部署） |
检查目录属主与权限 |
将 /var/log/tomcat9、/var/lib/tomcat9/work 等目录属主设为 tomcat:tomcat，确保可写 |
| 配置文件错误导致无法启动 |
启动日志含 SEVERE 指向 server.xml/web.xml |
使用 xmlstarlet 或 IDE 校验 XML 结构；回滚最近变更并逐步恢复配置 |
| 应用启动慢或卡死 |
检查线程、连接池、数据库与依赖 |
调整 server.xml 线程与超时；优化 JDBC 连接池；排查应用依赖与初始化逻辑 |
以上对照要点涵盖了 端口冲突、配置错误、权限不足、内存不足、部署失败 等高频问题及处置路径。
三 关键配置文件与路径
- 环境与内存
- /etc/default/tomcat9：设置 JAVA_HOME、JAVA_OPTS（如 -Xms512m -Xmx1024m）、CATALINA_HOME/CATALINA_BASE、运行用户等。
- 可选：在 /usr/share/tomcat9/bin/setenv.sh 中导出自定义变量（若不存在可创建）。
- 主配置
- /etc/tomcat9/server.xml：、 与 路径与部署方式。
- 日志
- /var/log/tomcat9/catalina.out、localhost.<日期>.log、access.<日期>.log；必要时检查 conf/logging.properties 的编码与日志级别。
- 用户与权限
- /etc/tomcat9/tomcat-users.xml：配置 manager-gui/admin-gui 等角色与用户；确保与 /etc/default/tomcat9 的运行用户一致。
- 应用部署
- /var/lib/tomcat9/webapps/（自动解压 WAR）、/var/lib/tomcat9/conf/Catalina/localhost/（外部 Context 配置）。
四 重启与验证
- 重启服务
- 使用 systemd：sudo systemctl restart tomcat9；重启后用 systemctl status tomcat9 与 journalctl -u tomcat9 -xe 复核状态与日志。
- 验证访问
- 访问 http://服务器IP:8080/ 与 http://服务器IP:8080/manager/html（若启用管理应用），确认返回 200 页面；必要时查看 access.log 的请求记录。
