Debian Java故障排查思路

Debian Java故障排查思路

一 快速定位与最小化复现

• 明确运行方式与环境：是命令行 java -jar、systemd 服务、还是容器/应用服务器；记录启动用户、工作目录、JDK/JRE 版本与启动命令。
• 复现并固化命令：在终端直接执行与程序一致的命令，避免 IDE/脚本带来的额外变量干扰。
• 捕获完整输出：重定向标准输出与错误输出到日志文件，便于回溯。
• 最小化复现：暂时移除复杂的 JVM 参数、Spring Profile、外部配置，逐步加回定位触发点。
• 区分问题域：是启动失败（类找不到、版本不匹配）、运行异常（内存、线程、网络）、还是崩溃/退出（JVM 崩溃日志、OOM、信号）。

二 环境与版本基线检查

• 检查可用与默认 Java：
  • 列出包：dpkg -l | grep -E “openjdk|java”
  • 查看/切换默认：update-alternatives --config java；验证：java -version、javac -version
• 设置与验证环境变量（以实际安装路径为准）：
  • 建议写入 /etc/environment 或 ~/.bashrc：
    • JAVA_HOME=“/usr/lib/jvm/java-11-openjdk-amd64”
    • PATH=“$JAVA_HOME/bin:$PATH”
  • 使生效：source /etc/environment 或 source ~/.bashrc；验证：echo $JAVA_HOME、which java
• 多版本并存策略：统一构建与运行使用同一 JDK 主版本；必要时用 alternatives 为 java/javac 分别设置。
• 系统与时区：
  • 更新索引与系统：sudo apt update && sudo apt upgrade
  • 时区一致性：检查 /etc/timezone 与 /etc/localtime，必要时修正并重启应用。

三 常见错误与对应处理

• UnsupportedClassVersionError：编译版本高于运行版本。处理：安装并使用更高版本的 JDK/JRE，或降低代码编译目标版本；用 alternatives 切换默认 java。
• NoSuchMethodError/NoClassDefFoundError：依赖冲突或版本不一致。处理：统一依赖版本、清理构建产物（如 target/classes、.m2/repository 冲突副本）、检查第三方库与运行 JDK 的兼容性；在 IDE/构建工具中显式指定 JDK。
• 字体/图形环境错误（如无头环境）：启用 headless 或虚拟 X：
  • java -Djava.awt.headless=true -jar app.jar
  • 无 X11 时安装虚拟帧缓冲：sudo apt-get install xvfb
• 依赖/安装问题：修复破损依赖与未配置包：sudo apt -f install；sudo dpkg --configure -a；必要时重装 JDK：sudo apt install --reinstall openjdk-11-jdk。

四 日志与诊断信息采集

• 系统层面：
  • 实时日志：tail -f /var/log/syslog
  • 诊断与启动日志：journalctl -xe；内核/驱动线索：dmesg
• 应用层面：
  • 启用 GC 与诊断日志（示例）：
    • java -Xmx512m -Xms256m
      -XX:+UnlockDiagnosticVMOptions -XX:+PrintGCDetails -XX:+PrintGCDateStamps
      -Xloggc:/var/log/java_gc.log -XX:+PrintGCTimeStamps
      -XX:+PrintSafepointStatistics -XX:PrintSafepointStatisticsCount=1
      -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/cache/java/heapdump.hprof
      -jar your-app.jar
  • 运行期抓取线程与内存快照：
    • jstack > /tmp/threaddump-$(date +%F-%H%M%S).txt
    • jmap -heap ；必要时 jmap -dump:format=b,file=/var/cache/java/heap-$(date +%F-%H%M%S).hprof
    • jstat -gc 间隔采集观察 GC 行为
• 资源与健康：
  • 资源占用：top/htop、free -m、df -h
  • 进程状态：ps aux | grep java
  • 网络连通性：ping、curl/telnet 到依赖服务端口。

五 内存与稳定性问题处理

• 内存不足与 OOM：
  • 合理设置堆与元空间：-Xms/-Xmx、-XX:MaxMetaspaceSize；开启并分析 GC 日志与堆转储（HeapDumpOnOutOfMemoryError）。
  • 若容器化运行，确保容器内存限制与 JVM 参数匹配，避免被 cgroup OOM Killer 终止。
• 长时间 GC 停顿或频繁 Full GC：
  • 从 GC 日志观察停顿时间与回收效果，优化对象生命周期、缓存与集合使用；必要时调整新生代/老年代比例与 GC 算法。
• 线程与死锁：
  • 用 jstack 多次采样，分析 BLOCKED/WAITING 线程与锁持有链；结合业务日志定位竞争点。
• 稳定性加固：
  • 设置合适的 JVM 异常退出钩子与监控告警；对关键服务使用 systemd 的 Restart=on-failure 与 Watchdog。
  • 变更前在测试环境复现与压测，逐步调优参数并固化到部署脚本/镜像。