Ubuntu 上部署与运行 HBase 的常见问题汇总
一 环境与配置类问题
- Java 与 Hadoop 版本不匹配或 JAVA_HOME 未正确设置，导致启动脚本异常或类找不到；HBase 2.x 通常建议使用 Java 8。建议统一 Hadoop 与 HBase 的版本矩阵，并在 hbase-env.sh 明确设置 JAVA_HOME。伪分布式下应先启动 HDFS，再启动 HBase。
- /etc/hosts 主机名解析错误（如将主机名错误指向 127.0.1.1 或回环地址），会引发 RegionServer 无法注册、连接异常等。应将主机名正确解析到本机非回环地址，保持集群内解析一致。
- SSH 免密登录未打通，Hadoop/HBase 启动脚本无法远程启停进程；需确保本机与自身（以及集群节点）之间可免密 SSH。
- HDFS 客户端配置未透传到 HBase，导致访问 HDFS 时使用默认配置（如副本数不一致）。可在 hbase-env.sh 设置 HBASE_CLASSPATH=$HADOOP_CONF_DIR，或在 conf 下放置 hdfs-site.xml 软链。
- **ZooKeeper 端口冲突（默认 2181）**或地址配置不当，HBase 无法形成 Quorum。需检查端口占用（如 lsof -i:2181）、确认 HBase 内嵌 ZK 与外部 ZK 的取舍与地址一致性。
- 系统时间不同步，超过 HBase 允许的时钟偏差（默认约 180000 ms）会被拒绝注册，表现为 RegionServer 无法加入集群。建议使用 NTP 同步时间。
二 启动与运行期错误
- MasterNotRunningException / PleaseHoldException：常见根因包括 HDFS 处于 SafeMode、HBase 与 Hadoop 的 RPC 协议/依赖版本不一致、ZooKeeper 未就绪、或元数据异常。处理步骤：确认 HDFS 已退出 SafeMode、核对 Hadoop 与 HBase 版本与依赖一致、检查 ZK 状态、查看 HBase 日志定位具体异常。
- HMaster 启动失败并抛出 TableExistsException: hbase:namespace：多为异常关闭或 ZK/元数据残留导致。处理步骤：停 HBase → 运行 OfflineMetaRepair 修复元数据 → 清理 ZooKeeper 的 /hbase 节点（如 hbase zkcli rmr /hbase）→ 重启。
- 端口冲突（如 2181 被占用）导致内嵌 ZK 启动失败或客户端无法连接。处理步骤：lsof/ss 查占用进程并停止或调整端口，确保 HBase 配置与运行环境一致。
- Shell 报错 “Master not running”：本质是 Master 未成功变为 Active 或 ZK 不可达。应先确认 HMaster 进程与日志、ZooKeeper 状态、网络与 hosts 解析均正常。
三 配置示例与关键检查
- 伪分布式常用 hbase-site.xml 要点（示例）：
- hbase.rootdir：指向 HDFS（如 hdfs://master:9000/hbase）
- hbase.cluster.distributed：true
- hbase.zookeeper.quorum：master
- dfs.replication：1（伪分布式单节点）
- 关键检查清单：
- 启动顺序：先 start-dfs.sh，再 start-hbase.sh
- 进程与日志：jps 查看 HMaster/HRegionServer，异常时优先查看 logs/ 下对应日志
- Web UI：访问 http://master:60010/master-status 检查集群状态与 Region 分布
- 客户端连通：hbase shell 执行 list/status 验证读写路径与 ZK 连通性
四 性能与稳定性优化要点
- 内存与 GC：合理设置堆大小（如 -Xms/-Xmx 相同），写密集提高 MemStore 占比、读密集提高 BlockCache 占比；大堆优先 G1GC，中小堆可用 CMS，减少停顿。
- 文件句柄与内核：提升 ulimit -n（如 32768），降低 vm.swappiness，使用 XFS/ext4 + noatime 降低 I/O 开销。
- 存储与 Compaction：优先 SSD/NVMe，合理设置 Compaction 阈值与策略，避免频繁或高峰期的 Major Compaction。
- 表与 RowKey：避免单调递增 RowKey，采用 哈希/加盐/前缀 打散热点；必要时 预分区 减少后期分裂。
- 客户端：适当增大 scan caching、使用批量 Put/Get、明确列族/列减少传输量。
