Debian 上 Tomcat 启动失败的排查与修复指南
一 快速定位问题
- 查看服务状态与立即输出：使用命令查看状态并获取最新日志片段，例如：sudo systemctl status tomcat9；sudo journalctl -xeu tomcat9；tail -n50 /var/log/tomcat9/catalina.out。Debian 常见安装路径为 /var/log/tomcat9/ 或安装目录下的 logs/。
- 定位日志目录与关键文件：Tomcat 主要日志为 catalina.out，常见还有 localhost..log、catalina..log 等；若使用软件包安装，日志多在 /var/log/tomcatX/，源码安装通常在 $CATALINA_HOME/logs。
- 实时跟踪与关键字过滤：使用 tail -f 实时查看，配合 grep 过滤错误，如：tail -f /var/log/tomcat9/catalina.out | grep -i “error|exception|failed”。
- 检查端口占用：确认 8080/8005/8009 是否被占用，示例：ss -ltnp | grep ‘:8080’ 或 lsof -iUDP:8080；若冲突，结束占用进程或修改 conf/server.xml 的 Connector 端口。
二 常见原因与对应修复
- 端口冲突：日志出现 “Address already in use”。处理：lsof -i:8080 找到 PID，kill -9 ；或编辑 server.xml 的 改为未占用端口。
- 环境变量或 Java 版本不匹配：未设置 JAVA_HOME/CATALINA_HOME 或 JDK 版本与 Tomcat 不兼容。处理：在系统环境或 /etc/default/tomcat9 中正确设置 JAVA_HOME（指向 JDK 而非 JRE），确认版本匹配后重启。
- 配置文件语法错误：server.xml/web.xml 配置不当会导致启动失败。处理：逐项核查标签闭合、路径、权限与 Valve 配置；必要时用默认配置替换进行对比。
- 权限问题：Tomcat 用户对 conf、logs、work、temp 等目录无读写权限。处理：chown -R tomcat:tomcat /var/lib/tomcat9 /var/log/tomcat9 /usr/share/tomcat9；确保启动用户与目录属主一致。
- JVM 内存不足或超限：出现 OutOfMemoryError 或系统 OOM-killer。处理：在 /etc/default/tomcat9 或 bin/setenv.sh 中设置 JAVA_OPTS=“-Xms512m -Xmx1024m”（根据物理内存调整），并排查内存泄漏。
- 文件句柄限制：出现 “Too many open files”。处理：在 systemd 服务中设置 LimitNOFILE=65535，或 /etc/security/limits.conf 提升 ulimit -n。
- 应用部署失败：WAR 包损坏、依赖缺失、web.xml 错误等。处理：查看 localhost..log 与 catalina.out 的堆栈，修正依赖或重新部署。
三 与服务管理相关的检查
- 正确的 systemd 服务单元：若使用源码安装，需自建服务并确保 Type=forking、正确设置 JAVA_HOME/CATALINA_HOME，ExecStart 指向 bin/startup.sh，ExecStop 指向 bin/shutdown.sh，然后执行 systemctl daemon-reload、systemctl enable tomcat9。
- 环境变量放置位置：Debian 软件包版推荐在 /etc/default/tomcat9 设置 JAVA_HOME/JAVA_OPTS，避免直接改动脚本内部。
- 启动后立即退出：多与 Type、工作目录、权限或环境变量不当有关；用 journalctl -xeu tomcat9 查看“Main process exited, code=exited, status=1/FAILURE”的具体原因并逐项修正。
四 高频错误速查表
| 症状关键词 |
可能原因 |
快速修复 |
| Address already in use |
端口被占用 |
ss/lsof 查进程并 kill，或改 server.xml 端口 |
| JAVA_HOME not defined |
环境变量未设置 |
在 /etc/default/tomcat9 设置 JAVA_HOME 指向 JDK |
| SEVERE: Parse error |
server.xml 语法错误 |
校验 XML、注释与闭合标签，恢复默认对比 |
| Permission denied |
目录权限不足 |
chown/chmod 调整 tomcat 用户权限 |
| OutOfMemoryError |
堆内存不足 |
在 JAVA_OPTS 提升 -Xms/-Xmx，排查内存泄漏 |
| Too many open files |
句柄数限制 |
systemd LimitNOFILE 或 limits.conf 提升上限 |
| Failed to start connector |
端口/协议配置错误 |
检查 server.xml Connector 配置与协议 |
| Application deployment failed |
WAR/依赖/web.xml 问题 |
查 localhost..log 堆栈并修正应用 |
五 最小可行修复操作清单
- 查看状态与日志：sudo systemctl status tomcat9；sudo journalctl -xeu tomcat9；tail -n100 /var/log/tomcat9/catalina.out。
- 释放端口或改端口：ss -ltnp | grep ‘:8080’；kill -9 ；或编辑 server.xml 的 。
- 校正 Java：echo $JAVA_HOME；在 /etc/default/tomcat9 设置 JAVA_HOME（如 /usr/lib/jvm/java-11-openjdk-amd64），确认版本兼容。
- 设置内存：在 /etc/default/tomcat9 增加 JAVA_OPTS=“-Xms512m -Xmx1024m”（按内存调整）。
- 修复权限：chown -R tomcat:tomcat /var/lib/tomcat9 /var/log/tomcat9 /usr/share/tomcat9。
- 重启并验证：sudo systemctl restart tomcat9；sudo systemctl status tomcat9；tail -f /var/log/tomcat9/catalina.out。
