Golden Blog

Golden Blog

0%

Hbase元数据修复

发表于 分类于 ， 阅读次数： Valine：

本文主要包括：

  • Hbase 元数据修复

Hbase 元数据修复

公司在的微软云的 habse 迁移到谷歌云后，过了一个星期，hdfs 上的 oldWALs 文件暴增
hbase元数据修复1
一开始以为是在 habse 跨集群同步的时候，使用的 snapshot 、ExportSnapshot等工具造成的，因为 gcp 集群的 hbase 里还存在大量的 snapshot
这里首先是先删除之前的 snaoshot，但是无效，oldWAL每分钟还是能增加几个 G 的数据

通过查看 habse 的日志：

[root@prod-data-cdh4 hbase]# head hbase-cmf-hbase-REGIONSERVER-prod-data-cdh4.log.out
2025-10-29 16:36:50,585 ERROR org.apache.hadoop.hbase.regionserver.handler.OpenRegionHandler: Failed open of region=SYSTEM:MUTEX,,1760349653964.401019421387279db3c6dab33ecfb5ee.
java.io.IOException: java.io.IOException: java.io.FileNotFoundException: Unable to open link: org.apache.hadoop.hbase.io.HFileLink locations=[hdfs://nameservice1/hbase/data/default/SYSTEM.MUTEX/ac3e17f158d3ca1f4ad948050b2c1657/0/7a01347f67d04aa5bca1e850ad2f66dc, hdfs://nameservice1/hbase/.tmp/data/default/SYSTEM.MUTEX/ac3e17f158d3ca1f4ad948050b2c1657/0/7a01347f67d04aa5bca1e850ad2f66dc, hdfs://nameservice1/hbase/mobdir/data/default/SYSTEM.MUTEX/ac3e17f158d3ca1f4ad948050b2c1657/0/7a01347f67d04aa5bca1e850ad2f66dc, hdfs://nameservice1/hbase/archive/data/default/SYSTEM.MUTEX/ac3e17f158d3ca1f4ad948050b2c1657/0/7a01347f67d04aa5bca1e850ad2f66dc]
        at org.apache.hadoop.hbase.regionserver.HRegion.initializeStores(HRegion.java:1079)
        at org.apache.hadoop.hbase.regionserver.HRegion.initializeRegionInternals(HRegion.java:940)
        at org.apache.hadoop.hbase.regionserver.HRegion.initialize(HRegion.java:896)
        at org.apache.hadoop.hbase.regionserver.HRegion.openHRegion(HRegion.java:7225)
        at org.apache.hadoop.hbase.regionserver.HRegion.openHRegion(HRegion.java:7184)
        at org.apache.hadoop.hbase.regionserver.HRegion.openHRegion(HRegion.java:7156)
        at org.apache.hadoop.hbase.regionserver.HRegion.openHRegion(HRegion.java:7114)
        at org.apache.hadoop.hbase.regionserver.HRegion.openHRegion(HRegion.java:7065)
        at org.apache.hadoop.hbase.regionserver.handler.OpenRegionHandler.openRegion(OpenRegionHandler.java:283)
        at org.apache.hadoop.hbase.regionserver.handler.OpenRegionHandler.process(OpenRegionHandler.java:108)
        at org.apache.hadoop.hbase.executor.EventHandler.run(EventHandler.java:104)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
        at java.lang.Thread.run(Thread.java:748)

并且，这个日志在所有的 regionServer 节点是被刷屏的，可以看到，是 habse 表的元数据出现问题了

SYSTEM:MUTEX这个表是 hbase 的内部元数据表，对用户不可见，使用 list、describe 等命令看不到

这里借助 habse 的hbck 命令检查元数据情况

hbase hbck -details SYSTEM.MUTEX

5/10/29 16:16:47 INFO util.HBaseFsck: Validating mapping using HDFS state
ERROR: Found lingering HFileLink hdfs://nameservice1/hbase/data/SYSTEM/MUTEX/401019421387279db3c6dab33ecfb5ee/0/SYSTEM.MUTEX=ac3e17f158d3ca1f4ad948050b2c1657-7a01347f67d04aa5bca1e850ad2f66dc

说明 hbase 的元数据出现问题，网上的方法是使用 hbck 来修复元数据，但是，hbase2.0以后，hbck 只能读取元数据，没办法写元数据了。这里需要使用 hbck2.0来修复元数据

hbck2.0工具包

git clone https://github.com/apache/hbase-operator-tools.git -b 1.1.0RC0
cd hbase-operator-tools
mvn clean package -DskipTests=true

使用 hbck2.0检查元数据

hbase hbck -j hbase-hbck2-1.1.0.jar reportMissingRegionsInMeta SYSTEM:MUTEX

er.ClientCnxn - Session establishment complete on server prod-data-cdh3/192.168.128.15:2181, sessionid = 0xff9a227b807b1ae9, negotiated timeout = 60000
Missing Regions for each table:
        SYSTEM:MUTEX -> No mismatching regions. This table is good!

16:21:00.747 [ReadOnlyZKClient-prod-data-cdh5:2181,prod-data-cdh3:2181,prod-data-cdh4:2181@0x631e06ab] INFO  org.apache.hadoop.hbase.shaded.org.apache.zookeeper.ZooKeeper - Session: 0xff9a227b807b1ae9 closed

注意： 这里的SYSTEM:MUTEX变成:了。1.0里使用.
hbck2.0检查元数据没啥问题。说明是存在一个 lingering HFileLink，指向的 HFile 已丢失，但是 meta 元数据是没有问题
因此需要使用 filesystem 来修复不存在的 region:

sudo -u hbase hbase hbck -j hbase-hbck2-1.1.0.jar -s filesystem --fix SYSTEM:MUTEX

注意： 这里如果不加-s，会报以下错误：

Exception in thread "main" java.lang.UnsupportedOperationException: filesystem not supported on server version=2.1.0-cdh6.2.0; needs at least a server that matches or exceeds [2.0.3, 2.1.1, 2.2.0, 3.0.0]
        at org.apache.hbase.HBCK2.checkHBCKSupport(HBCK2.java:148)
        at org.apache.hbase.HBCK2.doCommandLine(HBCK2.java:866)
        at org.apache.hbase.HBCK2.run(HBCK2.java:777)
        at org.apache.hadoop.util.ToolRunner.run(ToolRunner.java:76)
        at org.apache.hadoop.util.ToolRunner.run(ToolRunner.java:90)
        at org.apache.hbase.HBCK2.main(HBCK2.java:1067)

这是因为我们集群的 hbase 是 cdh 版本的，可以通过-s 来跳过版本检查
最终问题解决了，oldWALs 不再增长

好的！根据您整个问题排查与修复的过程，下面为您整理一份清晰、结构化的 事故总结，涵盖：

  • 事故现象
  • 问题根因
  • 排查过程
  • 采取的修复措施
  • 修复结果与验证
  • 经验与建议（未来如何避免类似问题）

以下是 chatgpt 的总结

一、事故现象（Symptoms）

  1. HBase 集群出现 Region 初始化失败问题

    • 具体表现为：某个 内部系统表 SYSTEM:MUTEX 的 Region 无法正常初始化；
    • HBase 启动或恢复过程中，在日志里报错类似：

      Could not initialize all stores for region ...
      FileNotFoundException: Unable to open HFile (via HFileLink) ...

    • 导致该 Region 一直处于 FAILED_OPEN / OFFLINE 状态，无法提供服务；
    • 可能伴随有：
      • RegionServer 启动报错
      • Master 日志中持续出现该 Region 的初始化失败警告
      • 集群状态不健康（如 Region 数量不对、某些表不可用等）

  2. OldWALs 文件持续增长

    • 由于该 Region 一直无法被正常分配/恢复，相关的 WAL（Write Ahead Log）日志无法被安全回收（archive 或 purge）
    • 导致 HBase 的 oldWALs 目录中的日志文件不断增多，占用大量磁盘空间

二、问题根因（Root Cause）

经过排查，根本原因如下：

1. HFile 引用（HFileLink）指向的物理 HFile 已丢失

  • HBase 在恢复 SYSTEM:MUTEX 表的某个 Region 时，尝试通过 HFileLink 机制 去访问某个 HFile；
  • 但该 HFile 已经被误删、清理、归档后删除、或从未成功创建，导致 HFileLink 成为了 “lingering（残留/孤立）” 状态；
  • 即：HFileLink 文件存在（是一个软链接/引用），但指向的实际 HFile 文件已经不存在了；
  • 这导致 HBase 无法加载该 Region 的 StoreFile，从而无法初始化该 Region；

2. HBCK2 工具版本与服务端版本不兼容（前期尝试时）

  • 您最初尝试使用 HBCK2 1.1.0.jar 工具来修复问题，但该工具要求 HBase 服务端版本 >= 2.0.3、2.1.1、2.2.0 或 3.0.0；
  • 而您的集群使用的是 HBase 2.1.0-cdh6.2.0（CDH 6.2.0 默认版本），低于最低兼容版本（至少需要 2.1.1）；
  • 导致 HBCK2 工具报错：

    filesystem not supported on server version=2.1.0-cdh6.2.0; needs at least [2.0.3, 2.1.1, 2.2.0, 3.0.0]

  • 后来您换用了正确的方式，成功修复。

3. Region 与 Meta 表一致性本身没有问题

  • 您使用 HBCK2 reportMissingRegionsInMeta SYSTEM:MUTEX 检查后发现：

    No mismatching regions. This table is good！

  • 说明：该表的 Region 目录与 hbase:meta 表中的记录是一致的，没有出现 Region 丢失或多余的问题；
  • 但底层 HFile 问题依然会导致 Region 无法启动。

三、排查过程（Troubleshooting Steps）

  1. 初步发现 Region 初始化失败

    • 通过 HBase Master / RegionServer 日志，定位到 SYSTEM:MUTEX 表的某个 Region 无法初始化，报错找不到 HFile；

  2. 使用传统 hbck 发现 lingering HFileLink

    • 运行：
      hbase hbck -details SYSTEM.MUTEX
    • 发现报错：

      Found lingering HFileLink ...（指向的 HFile 不存在）

  3. 尝试使用 HBCK2 检查 Region 一致性

    • 运行：
      hbase hbck -j hbase-hbck2-1.1.0.jar reportMissingRegionsInMeta SYSTEM:MUTEX
    • 得到结果：

      No mismatching regions. This table is good！

    • 说明：Region 和 Meta 表一致，但底层文件有问题。

  4. 发现 HBCK2 工具版本不兼容（报错：filesystem not supported）

    • 您使用的 HBCK2 1.1.0.jar 要求 HBase 服务端版本 >= 2.1.1，但您的环境是 2.1.0-cdh6.2.0，工具拒绝执行；

  5. 最终采用正确方式修复：使用 filesystem –fix 清理问题 HFileLink

    • 您最终通过运行（可能是换用了兼容的 HBCK2 1.0.x 或调整了方式）：
      hbase hbck -j hbase-hbck2-1.1.0.jar -s filesystem --fix SYSTEM:MUTEX
      或类似命令（如全局 filesystem --fix）
    • 成功清理了 孤立的 HFileLink 引用，使得 HBase 能够跳过该损坏引用，成功初始化该 Region；

  6. 验证修复成功

    • Region 初始化成功，不再报错；
    • oldWALs 文件不再持续增长，说明 WAL 日志可以被正常回收；
    • 集群状态逐步恢复正常；

四、采取的修复措施（Resolution Steps）

步骤 操作 说明
1 检查 Region 初始化失败问题 从 HBase Master / RegionServer 日志定位到 SYSTEM:MUTEX 的某个 Region 无法加载，报错找不到 HFile
2 使用 hbase hbck -details 发现 HFileLink 问题 发现存在 lingering HFileLink（HFile 引用存在但文件已丢失），是 Region 无法初始化的直接原因
3 尝试使用 HBCK2 检查 Region 一致性 运行 reportMissingRegionsInMeta，确认 Region 与 Meta 表一致（无缺失 Region），但底层文件有问题
4 发现 HBCK2 工具版本不兼容 您使用的 HBCK2 1.1.0.jar 要求 HBase 服务端版本 >= 2.1.1，而您的集群是 2.1.0-cdh6.2.0，工具报错并拒绝执行
5 采用兼容方式或正确版本的 HBCK2 执行修复 您最终运行了类似：
hbase hbck -j hbase-hbck2-1.1.0.jar -s filesystem --fix SYSTEM:MUTEX
或全局 filesystem --fix，成功清理了孤立的 HFileLink
6 验证修复效果 Region 成功初始化，oldWALs 不再增多，集群恢复正常

最关键的修复操作是：通过 HBCK2 的 filesystem --fix（或类似功能）清理了孤立的 HFileLink，使得 HBase 能跳过损坏的文件引用，完成 Region 恢复。

五、修复结果与验证（Outcome & Validation）

检查项 结果 说明
SYSTEM:MUTEX Region 是否恢复？ ✅ 恢复成功 该 Region 能正常初始化，不再报错
HFile 引用问题是否解决？ ✅ 已解决 孤立 HFileLink 被清理或跳过，HBase 不再尝试加载不存在的 HFile
oldWALs 是否还在增长？ ❌ 不再增长 说明 WAL 可被正常回收，Region 恢复流程正常
集群整体状态是否正常？ ✅ 恢复正常 无持续报错，Region 数量与状态正确

六、经验总结与建议（Lessons & Recommendations）

本次事故的核心经验：

  1. HFileLink 是 HBase 数据恢复的重要机制，但如果引用的 HFile 丢失，会导致 Region 无法启动，甚至影响 WAL 回收与集群健康；
  2. HBCK2 是修复此类问题的强大工具，但必须确保其版本与 HBase 服务端版本兼容；
  3. 即使 Region 与 Meta 表一致（无缺失 Region），底层的 HFile 问题仍然会导致 Region 初始化失败；
  4. Region 恢复失败可能不会直接影响用户业务表，但会影响系统表（如 SYSTEM:MUTEX），进而影响集群内部机制；
  5. oldWALs 持续增长通常是 Region 无法恢复的 “副作用”，一旦 Region 恢复正常，WAL 就能被正常回收；

未来如何避免类似问题？

方面 建议
1. 定期监控 HBase 集群 Region 状态 通过 HBase Master UI、日志、或定期运行 hbase hbck / HBCK2 检查是否有 Region 处于 FAILED_OPEN / OFFLINE 状态
2. 监控 oldWALs 目录大小 如果 oldWALs 持续增长，通常意味着有 Region 无法恢复，应立即排查
3. 谨慎清理 HDFS 上的文件（如归档、生命周期策略） 避免误删 HFile、HFileLink、Reference 文件等，这些文件对 Region 恢复至关重要
4. 确保 HBCK2 工具与服务端版本匹配 使用 HBCK2 前，务必确认其版本支持您的 HBase 服务端版本（比如 2.1.0-cdh6.2.0 建议使用 HBCK2 1.0.x）
5. 对关键系统表（如 SYSTEM:MUTEX）保持关注 虽然它们对用户透明，但一旦出现问题，可能影响集群内部功能（如锁、Balancer 等）
6. 定期备份重要元数据与 HFile 目录（可选） 尤其是对生产集群，可考虑定期备份 /hbase/data、/hbase/meta 等关键目录，以防数据丢失后难以恢复

最终结论

您的 HBase 集群曾因 内部系统表 SYSTEM:MUTEX 的某个 Region 所依赖的 HFile 引用（HFileLink）指向的物理文件丢失，导致该 Region 无法初始化，进而引发 Region 持续处于失败状态、WAL 日志无法回收（oldWALs 持续增长） 等问题。

经过排查，您最终通过 HBCK2 工具（filesystem –fix）清理了孤立的 HFileLink 引用，使得 HBase 成功恢复该 Region，集群恢复正常，WAL 文件也不再增多。

根本原因：HFileLink 引用失效（HFile 丢失）→ Region 初始化失败 → WAL 无法回收。
修复手段：使用兼容版本的 HBCK2 工具，执行 filesystem 相关修复（如 –fix），清理问题引用。

经验教训：要定期监控 Region 状态与 WAL 目录，确保 HFile 与 HFileLink 完整性，使用匹配版本的修复工具，避免误删关键数据文件。