写这篇HBase常见问题排查的避坑笔记是因为两年前的深夜被一条RegionServer告警折腾到凌晨后实在想把这些教训记下来。HBase至今仍是海量KeyValue存储的中坚力量线上集群一旦跑起来端口不通、Region卡住、RowKey设计歪了、GC停顿拖垮会话这类问题总会遇到。这篇不写“高大上”的架构图只讲一线排查中真正好用的思路、命令和参数适合刚接手HBase集群的大数据工程师也适合正在做HBase开发、表设计或者准备大数据相关面试的朋友。1. 先吃透HBase架构排查问题才能一击命中1.1 一张请求链路图记住三个角色很多排查动作一开始就偏是因为对HBase的角色分工不够敏感。集群里最关键的就是HMaster、RegionServer、ZooKeeper三个角色再加一个底层存储HDFS。客户端发起读写时不会直接找HMaster而是先连ZooKeeper拿到hbase:meta表所在的RegionServer地址然后去meta表里查目标RowKey对应哪个Region最后才去真正的RegionServer上做数据操作。这个“先找ZK再找meta最后找到RegionServer”的过程是排查一切通信问题的地基。HMaster负责的是Region分配、Table的增删改、Region的合并与迁移平时读写数据不一定经过它。RegionServer则直接对客户端提供读写服务一个RegionServer会托管多个Region每个Region又包含MemStore和HFile。理解不了这层关系看到报错日志就只能乱猜。还有个容易忽略的点RegionServer挂了之后HMaster会把它上面的Region重新分配到其他节点同时通过WALWrite-Ahead Log恢复内存中还没落盘的数据。所以实际排查时问题常常不在HBase本身而在它依赖的ZooKeeper和HDFS。比如ZK会话超时、HDFS的DataNode坏盘都会表现为HBase RegionServer异常。1.2 端口清单一张表定位八成通信故障通信类故障是HBase新手第一个重灾区而端口又经常被防火墙策略挡住。不同的HBase大版本默认端口还不一样这里一定要看版本说话。我整理了一份常用端口对照排查时可以直接对号入座。用途HBase 1.x默认端口HBase 2.x默认端口主要配置文件ZooKeeper客户端访问21812181zoo.cfgclientPortZooKeeper节点间选举28882888zoo.cfgZooKeeper节点间同步38883888zoo.cfgHMaster RPC端口6000016000hbase-site.xmlHMaster Web UI6001016010hbase.master.info.portRegionServer RPC端口6002016020hbase.regionserver.portRegionServer Web UI6003016030hbase.regionserver.info.portHDFS NameNode RPC8020或90008020或9000core-site.xml注意HBase进程要跟ZooKeeper通信也要跟HDFS通信所以2181、2888、3888、8020、16020这些端口之间必须全部放通。很多集群起不来的原因不是配置写错而是节点之间防火墙把16020和16010拦了RegionServer和Master之间根本拉不起握手你去看日志只会看到“Connection refused”第一反应以为进程挂了实际上进程活得好好的只是端口不通。建议在部署HBase时就把端口清单维护进CMDB或者运维文档里。每次排查通信故障先telnet目标IP的端口确认链路是通的再往深查。如果是从1.x升级到2.x更要重点检查客户端配置里的端口是否都换成新端口因为默认值整体改成了1.6万段旧客户端带过来的代码很可能会连不上。2. 安装与配置阶段的高频问题排查2.1 集群起不来先看这三类日志安装配置阶段最容易翻车HBase起不来主要体现在三件事HMaster起不来、RegionServer起不来、进程起来了但注册不到ZK上。遇到这类问题我第一件事都是直接看日志日志路径在$HBASE_HOME/logs/下Maste r和RegionServer日志是分开的。第一类ZK连接失败。日志里大量出现“Cannot connect to ZooKeeper”或者“Session expired”。这时候先排查2181端口通不通再看hbase-site.xml里hbase.zookeeper.quorum配的节点是不是都能解析、都存活。注意ZK集群是“超过一半存活即可服务”不是全部节点必须在线但客户端配置的quorum列表里如果有节点不可达虽然不一定会挂却会拖慢连接速度。第二类HMaster启动后立刻退出。日志中如果出现“FileSystem is in an inconsistent state”或者访问hbase.rootdir失败多半是HDFS上的根目录权限不对或者hbase.rootdir指向的路径不存在且无法自动创建。遇到过好多次有人把hbase.rootdir配成了/hbase但HDFS没开WebHDFS权限Master初始化时建不了目录直接退出日志却只报一个Permission denied。解决不难先确认HDFS状态正常再手动创建目录并授权给运行HBase的Linux用户。第三类RegionServer启动失败报DataNode连接异常。这往往不是HBase的问题而是HDFS的dfs.client.block.write.replace-datanode-on-failure策略、DataNode数量不足或磁盘异常导致写入失败。RegionServer启动时会做数据目录检查、写WAL检查一旦发现HDFS不可写就会停止启动。看RegionServer日志时别只盯着最后几行把“Caused by”往上翻几层基本都能看到根因。2.2 内存、GC与超时参数的老坑配置HBase时内存参数和GC策略最容易埋雷而且埋得特别隐蔽。首先是堆内存很多人在hbase-env.sh里只改了HADOOP_HOME忘了设HBASE_HEAPSIZE导致RegionServer用默认值线上数据量稍微大一点就频繁Full GC。Master堆和RegionServer堆要分开想RegionServer才是承压的核心通常可以给到32GB到64GBMaster没必要给那么大。其次是MemStore和BlockCache的比例RegionServer堆主要被它们瓜分。hbase.regionserver.global.memstore.size默认大约是0.4表示堆内最多40%拿来缓存写入hfile.block.cache.size也类似控制读缓存比例。如果这两个值加起来太夸张RegionServer会出现内存互相挤压甚至触发写阻塞。这种问题很难通过看报错发现通常是GC日志里看到频繁Full GC或者写入突然被Blocked。还有一类隐蔽的坑来自超时和重试。客户端的hbase.client.retries.number、hbase.rpc.timeout、hbase.client.operation.timeout在默认情况下适合小型集群大型集群或网络抖动频繁时客户端会重试很久然后抛超时异常业务侧看起来就是“写入失败”。我曾经因为没调超时某次HDFS NameNode故障切换导致所有HBase客户端写入阻塞了一个多小时业务日志里全是重试。建议线上统一把客户端超时参数压到合理范围宁可快速失败也不要做无意义重试拖垮线程池。2.3 安装配置完成后做一次健康自检新集群装完不要直接丢业务上去就完事先花十分钟做自检。进入hbase shell依次执行version、status、list看Master、RegionServer、ZooKeeper是否都正常。然后用运维账号在每台RegionServer上跑一下hbase top -b观察系统负载和请求指标。我个人习惯自检时检查这几个点status输出中Live RegionServers数量是否符合预期。list能正常返回表列表说明meta表可读。创建一张测试表指定预分区为10个Region写入少量数据再scan确认读写链路完整。打开HMaster Web UI确认Active Master只有一个Standby Master正常备份。检查RegionServer Web UI里的heap使用、MemStore大小、BlockCache命中率。自检过程中发现问题优先记录下日志时间点对应的GC情况和系统负载方便后面对照。不要一看到异常就重启进程HBase进程重启后会自动做Region恢复和WAL回放如果是配置问题重启多少次都白搭。3. 客户端开发与表设计相关的坑3.1 用Java操作HBase时最常见的连接问题热词里有句“HBase开发使用Java操作HBase”这确实是大数据工程师绕不开的一步。很多人写客户端时习惯每次操作都创建一个新的Connection这是最典型的性能杀手。Connection是重量级对象内部要维护到ZooKeeper、RegionServer的连接池和元数据缓存频繁创建会导致句柄泄漏、创建连接的超时以及Meta缓存失效。正确姿势是全局只创建一个Connection多线程共享它同时依据业务拆出多个Table、BufferedMutator来操作数据。Table实例不是线程安全的但一个线程用一个Table没问题Connection是线程安全的。下面是实际项目中常写的客户端骨架。Configuration conf HBaseConfiguration.create(); conf.set(hbase.zookeeper.quorum, node1,node2,node3); conf.set(hbase.zookeeper.property.clientPort, 2181); try (Connection conn ConnectionFactory.createConnection(conf)) { try (Table table conn.getTable(TableName.valueOf(device_event))) { Put put new Put(Bytes.toBytes(rowkey_001)); put.addColumn(Bytes.toBytes(cf), Bytes.toBytes(status), Bytes.toBytes(online)); table.put(put); } }误区在于Table和Connection都实现了AutoCloseable于是有人把Table也放到了全局共享多线程并发操作同一个Table时就会遇到线程安全问题和因为Region迁移导致的RetriesExhausted异常。读写量大时更推荐用BufferedMutator批量提交它可以自动做异步批量写入和刷写控制而不是自己写循环调put。开发期还常见一个异常“RegionTooBusyException”。它表示某个Region已经忙到写不进去了通常的原因是RowKey设计导致单点热点或者Region刚经历过split还处于迁移状态。此时不要盲目加大重试次数而是要看这个Region所在RegionServer的负载、MemStore状态然后考虑表设计优化。3.2 表设计不合理引发的热点和雪崩表设计和RowKey设计是HBase面试必问题也是线上问题最深的来源。RowKey设计的第一原则是散列避免单调递增。举个例子做网约车订单轨迹存储如果直接用“订单ID”作为RowKey前缀订单ID一般是递增的新订单会持续写入同一个Region表现为单台RegionServer CPU被打满而其他机器闲置。通常我会建议把RowKey设计成“反转”或“加盐”形式。所谓加盐就是在RowKey最前面拼一个随机前缀或分片编号比如订单号取模后拼上原订单号让数据均匀分布到预设的预分区里。反装则是把订单号或时间戳倒序让高位变化更分散。注意加盐后你如果想按时间范围扫描就不能再用纯前缀Scan了查询模式需要在业务侧折中。建表时就应预分区。比如按24个前缀自然分桶建表时使用SPLITS配置。没有预分区的表默认只有一个Region无论RowKey多散最终都会先在一个Region上写入直到它split。热点问题一旦出现最好的修复窗口是在大流量进入之前否则只能等业务低峰期做迁移或重新建表。列族也要克制。HBase的优势是列动态伸缩但不代表需要多个列族。一个列族是最佳实践两个列族已是上限。多个列族会让同一行数据分散到多个HFile中读取时要跨文件合并还会让Region的flush和compaction复杂度上升。之前接过一个案例业务为了区分属性建了六个列族结果每次读写都要拉一堆文件RegionServer的读延迟直接翻倍。大对象更不建议直接怼进HBase。超过几十MB的文件、图片、日志全文放进HBase会拖垮MemStore的刷写和Region的split机制。典型做法是图片视频放对象存储大压缩包放HDFSHBase里只存文件路径和元数据。这个经验听起来简单但在数据和介质选型混乱的项目里几乎每隔几个月都会吐槽一次。3.3 读写数据不对先查Scan和版本设计客户端经常反馈“数据查不出来”或者“结果比预期多”这时候别急着怀疑数据丢了先看Scan参数和版本设置。HBase中一个Cell可以保存多个版本如果你建表时没指定VERSIONS默认只保留1个版本。写入相同RowKey、相同列但时间戳不同的数据时老版本会被自动清理读出来自然“比想象中少”。Scan还有一个经典坑未设置Caching或设置过大。Scan默认Caching比较小如果扫描大量数据客户端和RegionServer之间会频繁交互表现为慢扫描但Caching设得过大比如一次性把几万行塞进客户端又会把内存撑爆。我的经验是按单行大小和网络带宽折中常规3到5KB的行Caching设为500到1000是比较稳的起步值再做压测调整。setBatch和setCaching是两个不同维度Caching控制RPC请求一次最多拉取的行数Batch控制每行最多返回的列数。Scan一张宽表时如果单行有很多列把Batch设小可以减少单次网络传输量但会增加RPC次数。理解这个权衡才能解释为什么有些Scan明明数据不多却跑了十几秒。对于删除HBase丢弃的是“删除标记”而不是立即物理抹除数据。如果你连续写入、删除、再写入同一个Key旧版本的数据可能会在某些时间点重新可见尤其是在没有及时Major Compaction时。遇到这种“幽灵数据”不要慌查Delete的时间戳和默认的KV丢弃策略通常做一次Major Compaction就能稳定结果。4. 运行期稳定性与性能抖动的排查实战4.1 写入速度突然下降MemStore刷写才是幕后黑手线上表现最让人头疼的不是集群直接挂而是写入从每秒几万降到几百。大多数时候问题出在MemStore刷写和写阻塞。MemStore相当于Regions的“内存蓄水池”数据先写进内存攒批再刷成HFile落到HDFS。蓄水池满了就必须清理但清理会影响正在进行的写入。当单个Region的MemStore达到hbase.hregion.memstore.flush.size或者整个RegionServer的MemStore使用率超过hbase.regionserver.global.memstore.size时就会触发刷写。如果MemStore持续在高位RegionServer会进入“写阻塞”状态表现为大量写请求排队客户端报RegionTooBusy或者超时。遇到这类告警我会先在RegionServer UI上或通过JMX看两件事MemStore大小曲线和Flush队列长度。队列持续增长说明刷写速度跟不上写入速度。处理办法分三步走第一步暂时降级写入流量给刷写腾时间第二步检查是否有人手动触发过大量Major Compaction如果正在做可以先把compaction线程调低优先级第三步检查表行大小和Region数量如果单Region数据量过大做一次合理的Region Split要趁流量低峰。还有一个容易被忽视的原因WAL同步拖慢写入。HBase写数据前要先写WAL日志而且是同步刷到HDFS的如果HDFS磁盘性能差或者WAL文件所在目录和DataNode之间网络抖一下写入速度就会肉眼可见地下滑。看RegionServer日志里是否有大量关于WAL sync耗时过长的记录一旦确认是HDFS问题优先查磁盘坏道和网络。4.2 读延迟毛刺与缓存命中率没你想的那么简单读延迟高很多人第一反应是加机器但实际是BlockCache命中率和Compaction在作怪。HBase读一个Key时会先查MemStore再查BlockCache最后才到HFile缓存命中率低意味着大量请求要去扫磁盘文件延迟自然高。BlockCache命中率受RowKey设计影响极大。如果你的get请求很随机且RowKey没有前缀聚集性每次读都会加载不同的数据块到缓存命中率一定是低的。反过来如果把相关数据设计成连续的行前缀一次BlockCache加载就能服务多次查询缓存利用率会高很多。所以读延迟问题排查到最后常常又回到表设计。Compaction也经常制造读毛刺。做过线上的朋友都知道Major Compaction会把一个Region里的所有HFile合并成一个期间会产生大量磁盘IO和CPU开销读请求延迟瞬时飙升。HBase自身有机制去错开compaction时间但多RegionServer同时进行major compaction时仍然可能造成“压缩风暴”。我一般会在业务低峰期手动指定窗口执行major compaction日常小范围自动compaction保持默认。如果你能看到每个RegionServer的吞吐曲线当延迟飙升时间和compaction执行时间重合基本就能坐实这个原因。还需要关注HFile数量。Region的HFile数量如果持续上涨读请求就需要跨更多文件查找延迟自然变高。后台也有日志记录split和compaction异常时可以看有没有“too many store files”之类的提示。4.3 RegionServer宕机、Region迁移与RIT卡死处理RegionServer宕机后的恢复过程是HBase最常见也最容易引发二次故障的现场。宕机后HMaster会重新分配该节点上的所有Region同时通过WAL恢复数据这个过程会让集群进入RegionInTransition状态简称RIT。正常情况下RIT会很快收敛但如果卡住就会看到部分RowKey读写报“Region not found”或“No server for region”。RIT卡住的典型原因有几种hbase:meta表中Region的状态和实际RegionServer上报的状态不一致、ZooKeeper上的节点信息残留、HDFS上有损坏的临时文件或旧Region目录没清理干净。我在一个集群里碰到过Region一直卡在OPENINGMaster日志里反复打“Unable to open region”最后排查到是HDFS上一个StoreFile文件长度是0读元数据时异常手动把这个损坏文件移走后RIT自动恢复。处理RIT要非常克制不要一上来就assign/unassign。老版本里盲目assign会因为meta信息不一致导致Region被重复打开问题反而扩大。正确顺序是先看Master日志定位到底是open失败还是close失败再用hbase hbck检查一致性确认是meta和HDFS文件不一致后再决定用hbck2去修复。2.x集群现在普遍用hbase hbck2常见修复动作包括scheduleRecoveries、setTableState、assigns。不过任何修复命令执行前强烈建议把meta表和HDFS目录做一次快照至少也要导出meta表数据。宕机场景另一个灵魂拷问是为什么RegionServer会宕机大多数不是网络原因而是GC停顿太长导致ZK会话超时。ZK给RegionServer的会话超时时间内如果节点发生长时间Full GCZK就会认为这个RegionServer挂了然后把它踢出集群。此时可以在RegionServer的GC日志里看到明显的长停顿堆内存曲线也通常是梯形上升。优化方向是调整堆内存和GC策略HBase 2.x可以尝试G1但仍要根据线上堆大小和对象分布来做压测没有万能参数。5. 高频问题排查速查表与个人心法5.1 先把“症状—原因—对策”速查表收藏下面这个表我基本每周都会翻一次很多看似复杂的问题最后都能归到这几类。排查HBase时先把问题分类确定是“通信类”“数据类”还是“性能类”再动手要快得多。症状可能原因推荐处理HMaster启动后自动退出hbase.rootdir权限不对或HDFS路径不可写检查core-site配置、HDFS目录权限RegionServer频繁与ZK断连GC停顿过长、网络抖动、ZK会话超时调GC策略检查节点网络调大ZK会话超时观察写入报RegionTooBusyExceptionRowKey热点、MemStore写阻塞、region split停掉部分写入检查负荷优化RowKey和预分区读取超时或延迟飙升BlockCache命中率低、Compaction风暴、Scan参数不合理调整Scan参数优化RowKey控制Major Compaction窗口数据查不到或结果不一致版本数设置过小、删除标记未清理、Scan条件不对确认表VERSIONS做Major Compaction核对ScanRegion长期处于RITmeta表不一致、ZK残留、HDFS文件损坏看Master日志用hbck/hbck2修复不要乱assign所有写入都变慢WAL同步慢、HDFS磁盘IO高、DataNode故障检查HDFS健康度和网络带宽排查磁盘坏道5.2 排查工具箱日志、命令、监控一个不能少工具不在多关键在于每个工具什么时候用。最基础的是HBase Shellstatus、status detailed、list、describe、scan这些命令能快速确定集群整体状态、Region分布、表属性和实际数据范围。稍微深一点可以用hbase top它类似Linux的top命令按Region查看读写指标、延迟分位值定位热点Region特别管用。一致性检查用hbase hbck和hbase hbck2。老版本直接跑hbck就能输出不一致的Region列表2.x中hbck主要负责只读检查修复则交给hbck2。注意一个原则先只读检查再决定修复不要在没搞清楚问题前执行大批量的修复操作。日志是最终真相来源。HBase日志通常在$HBASE_HOME/logs/下Master和RegionServer日志命名类似hbase-hbase-master-xxx.log、hbase-hbase-regionserver-xxx.log。看日志时配合GC日志和jstack能定位JVM线程是否卡在锁、是否在做class加载、还是长时间GC。另外客户端日志也很关键生产环境建议打开客户端日志并记录关键时间点。监控方面建议尽早接入Prometheus和Grafana这类开源方案。HBase社区有一些现成的exporter可以采集Master/RegionServer的metrics重点看RegionServer的MemStore大小、BlockCache命中率、Compaction队列长度、ZK连接数和系统GC次数。我遇到过很多“重启一下就好”的问题其实都是监控盲区掩盖了真实原因一旦有曲线很多规律自己就暴露出来了。5.3 我的排错顺序和心得最后分享一点个人习惯可能对你之后排查有帮助。我的顺序永远是先确认范围再确认时间点最后才是动操作。先看是整个集群还是一台RegionServer是所有表还是某一张表再看异常是从哪个时间点开始的当时是否做过发版、扩容、Compaction、数据补录。这个习惯帮我过滤掉了大量无效重启和无头绪查日志的时间。有一次运维同学反馈HBase写入慢我第一反应不是进集群而是先看业务发版记录果然当天凌晨上线了一个新任务用默认配置批量写入数百万条数据还都是同一个前缀的RowKey直接把某个Region打成热点。找到时间点和范围后处理方案就很简单把批量任务改成夜间低峰执行临时重建了带有预分区和加盐RowKey的新表问题就消失了。HBase面试题里总喜欢问RowKey设计、Region热点、RIT恢复、MemStore刷写这些概念其实这些恰恰是线上排障中最值钱的知识点。遇到问题不要慌按照“链路顺序 时间范围 日志证据 计量指标”来推大多数坑都能在十几分钟内定位。希望这份避坑手记能让你少熬几个夜。