Ubuntu 下 HBase 故障排查手册
一 快速定位流程
- 先看进程与端口：在 Master 与 RegionServer 节点执行 jps，确认是否存在 HMaster/HRegionServer；必要时用 netstat -tulpen | grep -E ‘16000|16010|2181|8080|60010’ 检查监听端口。
- 立刻查看日志：到 $HBASE_HOME/logs/ 打开最新的 hbase--master-.log 与 hbase--regionserver-.log，从 ERROR/Exception/FATAL 行向上追溯首个异常栈。
- 校验依赖连通性：
- HDFS：执行 hdfs dfsadmin -safemode get（返回 Safe mode is OFF 才正常），必要时 hdfs dfsadmin -safemode leave；用 hdfs dfs -ls / 验证 NameNode 可读写。
- ZooKeeper：用 echo stat | nc <zk_host> 2181 或 zkCli.sh ls / 检查会话与 /hbase 节点。
- 基础环境自检：确认 Java 可用（java -version）、HBASE_HOME/PATH 正确（echo $HBASE_HOME、$PATH）、系统时间同步（建议 NTP，误差不超过 30 秒）。
- 配置语法与兼容性：检查 hbase-site.xml 是否可解析（常见为标签未闭合）、Hadoop 与 HBase 版本兼容、以及 HBase 与 Hadoop 的日志框架 SLF4J 冲突。
二 常见故障与修复要点
- 命令未找到 hbase：未设置环境变量或安装不完整。在 ~/.bashrc 加入
export HBASE_HOME=/usr/local/hbase
export PATH=$PATH:$HBASE_HOME/bin
执行 source ~/.bashrc 后用 hbase version 验证。
- 启动报错 SLF4J multiple bindings：Hadoop 与 HBase 的日志绑定冲突。保留其一，例如移除 Hadoop 的 slf4j-reload4j-*.jar 或 HBase 的 log4j-slf4j-impl-*.jar，再重启。
- hbase shell 报 ServerNotRunningYetException：
1）HDFS 处于安全模式则 hdfs dfsadmin -safemode leave；
2）检查 Hadoop 与 HBase 版本/依赖冲突；
3）分布式场景在 hbase-site.xml 明确：
hbase.cluster.distributedtrue
hbase.rootdirhdfs://:9000/hbase
hbase.wal.providerfilesystem
4）按“先停 HBase、再停 Hadoop”的顺序重启。
- 配置解析错误：如 hbase-site.xml 标签未闭合或属性缺失，修正后重启。
- HMaster 无法成为 Active：多为 HDFS 地址/端口不一致。若 core-site.xml 的 fs.defaultFS=hdfs://:9000，则 hbase.rootdir 必须显式写端口（例如 hdfs://:9000/hbase），避免默认 8020 误连。
- ZooKeeper 连接失败或 /hbase 节点异常：检查 HBASE_MANAGES_ZK、集群时间同步、/etc/hosts 一致；必要时清理 ZK 的 /hbase 根节点后重启（风险操作，先备份）。
- 启动报 hbase:namespace 已存在：ZK 残留元数据导致。先停 HBase，清理 /hbase（ZK），再启动；或使用 OfflineMetaRepair 修复元数据后启动。
- 无法优雅关闭：默认 PID 文件在 /tmp 易被清理。在 conf/hbase-env.sh 设置 HBASE_PID_DIR 到持久目录（如 /usr/local/hbase/pids）。
三 配置与端口速查
| 检查项 |
推荐值或路径 |
说明 |
| hbase.rootdir |
hdfs://:9000/hbase |
与 core-site.xml 的 fs.defaultFS 端口保持一致 |
| hbase.cluster.distributed |
true |
分布式模式必须显式开启 |
| hbase.zookeeper.quorum |
zk1,zk2,zk3 或 localhost |
与 ZK 部署一致 |
| hbase.wal.provider |
filesystem |
兼容性更好的 WAL 提供者 |
| HBASE_MANAGES_ZK |
true/false |
使用内置或外部 ZK |
| HBASE_PID_DIR |
/usr/local/hbase/pids |
避免 /tmp 清理导致无法 stop |
| Web UI |
16010（Master），旧版常见 60010 |
访问 http://:16010 查看集群状态与 RegionServer 列表 |
四 性能与稳定性问题
- OOM 与 GC：按负载设置 HBASE_MASTER_OPTS/HBASE_REGIONSERVER_OPTS（如 -Xms/-Xmx），大堆建议 G1 GC；结合 JMX/Prometheus+Grafana 持续观测。
- RegionTooBusyException：写入过快触发 MemStore 上限。可减小批次、适度提高 hbase.hregion.memstore.flush.size 与 hbase.hregion.memstore.block.multiplier、缩短 hbase.hstore.blockingwaits；大数据导入优先考虑 bulkload；优化 RowKey 避免热点（加盐/哈希/反转/时间戳反转）。
五 一键排查脚本示例
#!/usr/bin/env bash
set -e
echo "=== 1) Java & 环境变量 ==="
java -version || { echo "Java 未安装"; exit 1; }
echo "HBASE_HOME=$HBASE_HOME"
echo "PATH=$PATH"
which hbase || echo "hbase 命令未找到，请检查 HBASE_HOME/bin 是否在 PATH"
echo "=== 2) 进程与端口 ==="
jps
for p in 16000 16010 2181 8080 60010; do
ss -ltnp | grep -q ":$p " || echo "端口 $p 未监听"
done
echo "=== 3) HDFS 状态 ==="
hdfs dfsadmin -safemode get || true
hdfs dfs -ls / || true
echo "=== 4) ZooKeeper 状态 ==="
{ echo stat; sleep 1; } | nc localhost 2181 || echo "无法连接 ZK 2181"
echo "=== 5) 最近错误日志 ==="
LOGFILE=$(ls -1t $HBASE_HOME/logs/hbase-*-master-*.log 2>/dev/null | head -1)
[ -f "$LOGFILE" ] && tail -n 100 "$LOGFILE" | grep -i -A5 -B5 "ERROR\|Exception\|FATAL" || echo "未找到 Master 日志"
echo "=== 6) 配置语法检查 ==="
xmllint --noout $HBASE_HOME/conf/hbase-site.xml 2>/dev/null || echo "hbase-site.xml 可能格式错误"
echo "=== 7) 时间同步 ==="
timedatectl status || ntpq -p || echo "请检查 NTP 时间同步（建议误差 < 30s）"
将脚本保存为 check_hbase.sh，在 Master 与 RegionServer 上执行，可快速收集关键故障线索。
