Apache Doris FE 问题排查与故障分析全景指南

前言： FE（Frontend）是 Apache Doris 集群架构中的“大脑”，负责元数据管理、查询解析和调度等关键任务。一旦 FE 出现问题，整个集群的稳定性和可用性将受到严重影响。因此，掌握 FE 故障定位与排查方法对于保障 Doris 运行至关重要。本文将结合官方文档与实际经验，系统梳理 FE 问题排查的完整路径。

---

一、FE 元数据结构与排查文档

在排查 Doris 问题时，理解 FE 元数据的组织方式非常重要。以下是官方提供的两篇核心文档，建议在遇到问题时首先阅读：

• 🔗 FE 元数据设计原理
• 🔗 元数据操作失败的排查方法

---

二、排查 FE 问题需要收集哪些信息？

定位问题，第一步是“取证”。这里列出你在排查 FE 相关故障时必须要收集的文件与信息清单：

✅ 日志类文件

1. FE 日志目录（fe/log/）下的：

   • fe.log：主日志，核心排查依据
   • fe.audit.log：用户行为与 SQL 审计
   • fe.gc.log：GC 详情，有助分析是否存在 GC pause 过长
   • fe.out：FE 控制台日志，有时比 fe.log 更早打印异常栈（尤其是FE core的信息都在这里记录）

2. BDBJE 元数据日志（fe/doris-meta/bdb/je.info.0）

   • 注意：日志时间为 UTC，需+8小时换算为北京时间

3. 版本信息：

   • 执行 start_fe.sh --version 查看 commit ID

4. FE 状态：

   • 执行 SHOW FRONTENDS 获取当前所有 FE 节点状态与角色

5. Prometheus 监控指标（如接入 Grafana，使用Doris Manager也是可以的）

   • JVM 堆内存使用率
   • 线程数
   • 当前导入 job 数
   • checkpoint 失败次数等

6. 如果怀疑“卡住”或“死锁”，请提供以下内容：

   • jstack -l <pid> 获取线程状态
   • jmap -heap <pid> 查看堆内存分布
   • jmap -histo:live <pid> 查看对象统计
   • jmap -dump:file=xxx.hprof <pid> 获取内存镜像用于离线分析

7. 主机级别的信息：

   • dmesg -T > dmesg.txt 查看操作系统层异常（看看是不是OOM）
   • CPU、内存、磁盘、网络使用情况指标

---

三、FE 挂掉的常见原因与排查方法

1. 无法达成多数写副本，FE 崩溃

Insufficient acks for policy:SIMPLE_MAJORITY. Need replica acks: 1. Missing replica acks: 1

• 可能原因：

  • GC 暂停时间过长，导致心跳超时
  • 堆内存不足，JVM 被 OOM
  • Follower 节点挂掉，Master 成为孤岛
  • Fsync 写磁盘耗时过长（je.info.0 会有 fsync 超时日志）

• 建议做法：

  • 查看 GC 日志中是否存在"concurrent mode failure"或"promotion failed"
  • 使用 jmap 分析堆中是否存在大对象或泄漏
  • 检查是否有节点宕机或物理资源（CPU/磁盘）异常

2. JVM 堆内存 OOM

• 现象：FE 异常退出，日志出现 OOM 相关堆栈信息。

• 建议做法：

  • 优化导入 label 保留参数，避免内存长期被事务占用：

    label_keep_max_second = 21600
    streaming_label_keep_max_second = 21600
    

  • 将 GC 策略从 CMS 改为 G1，并设置合理的 pause 时间

    JAVA_OPTS="-Xmx8g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"
    

    注意⚠️：Doris 2.1.x之后默认使用G1

3. 操作系统 OOM Killer 杀死 FE

• 排查路径：

  • 使用 dmesg -T | grep -i java 查看 OOM 记录
  • 检查是否其他进程抢占了系统内存

• 建议做法：

  • FE 和 BE尽量不要混合部署
  • 适当增加机器内存（终极解决办法）

四、FE 启动失败的常见原因

1. BDBJE 元数据损坏或磁盘空间不足

• 报错提示：DiskLimitException、meta out of date
• 检查点：
  • 查看 je.info.0 是否有异常
  • 检查磁盘空间是否充足

2. 集群时钟不同步

• 报错：Clock delta: xxx ms. between Feeder
• 建议所有节点启用 ntpd 或 chronyd 同步时间

3. 启动 jar 包不一致或 jar 包冲突

• 如高版本的 meta 使用了低版本 Doris jar 启动
• 或 jar 包残留版本冲突，导致反序列化失败

4. 节点间网络通信受限

• 防火墙导致 heartbeat、editlog 传输失败

---

五、其他 FE 常见故障与处理建议

1. FE 卡住、死锁、CPU 飙高

• 检查点：
  • jstack 查看是否存在死锁
  • Prometheus 查看 GC 时间、LoadJob 数量
  • 检查 checkpoint 是否阻塞主线程

2. checkpoint 无法完成导致 image 巨大

• /doris-meta/image/ 下 image 文件几十 GB
• 可能因为导入 label 未清理、ccr binlog 堆积等导致

3. SHOW FRONTENDS 执行缓慢

• 原因可能是域名解析问题/ 线程泄漏 / 内存泄漏导致 FE 状态无法快速响应

---

六、常用 Java 内存分析工具

工具	用途
jmap	查看堆结构、对象统计、dump 内存镜像
jstack	查看线程状态、排查死锁
GCEasy	分析 GC 日志
[JProfiler / Eclipse MAT]	分析 .hprof 文件，定位内存热点
Arthas	在线火焰图分析、方法跟踪

---

七、Grafana FE 常用监控指标

1. JVM Heap 使用率：是否频繁达到 70% 阈值
2. 线程数量：是否存在异常增长，是否持续活跃
3. 导入 Job 数量：是否持续过高未清理
4. checkpoint 成功率与耗时：是否频繁失败或超时
5. editlog 写入延迟：是否磁盘卡顿或主线程阻塞
6. CPU/内存/磁盘 IO/网络：系统资源瓶颈是否影响 FE

---

结语

FE 是 Apache Doris 的“心脏”，掌握其运行机制与问题排查路径，是数据库平台稳定运行的基础。建议在生产环境中部署完善的日志采集、监控系统，并对 GC 策略、内存设置等进行合理调优。如果你遇到 FE 崩溃、卡顿、无法启动等问题，不要轻易使用 recovery 方法拉起，请先查日志、取 dump、看指标，再分析、再修复。搞不定的话，可以联系社区同学，他们嘎嘎热心～