做 HBase 运维和开发的同学应该都遇到过这种场景：一条 Put 请求明明返回成功了，RegionServer 突然宕机，等 region 恢复后再去查询，发现数据竟然还在。为什么在？因为有一份 WAL（Write-Ahead Log，写前日志）在数据真正落盘之前，先把这次变更写进了磁盘。这篇文章我想把这套机制从头到尾拆开，讲清楚它到底在保护什么、append 和 hsync 之间有什么区别、RegionServer 宕机后日志是怎么被拆分回放的、生产环境有哪些参数值得调，以及我自己踩过的坑。
这篇文章适合正在做 HBase 开发和运维的人，尤其是想搞懂写入链路、故障恢复和数据持久性边界的朋友。如果是做选型评估，想确认 HBase 的一致性到底能保证到什么程度，这篇也能帮你把问题想明白。内容以 Apache HBase 2.x 为主，涉及旧版本差异的地方我会单独说明。
1. WAL 到底保护了什么：一次 HBase 写入的完整旅程
1.1 先写日志再进内存：这个顺序为什么不能反
先看一条 Put 请求的正常路径。客户端把数据发到对应的 RegionServer，RegionServer 并不是立刻把数据写进内存，而是先往 WAL 里追加一条记录，确认这条日志成功落盘后，再更新 MemStore，最后才向客户端返回成功。MemStore 攒到一定大小或触发条件后，再以 HFile 的形式批量刷到 HDFS。
这个顺序看着反直觉，但背后的理由非常实在。MemStore 在 JVM 堆里，进程崩溃或者机器断电，内存内容说没就没；HFile 是磁盘文件，但每次请求都直接刷 HFile 代价太高，既慢又会把大量小文件写到磁盘上。WAL 的作用就是在性能和持久性之间架一座桥：把每次写入变成顺序追加的一条日志，先把变化固定下来，再让内存慢慢攒、最后批量落盘。
打个比方，这就像小卖部老板收款：客人付钱时，先在账本上记一笔，再收钱放进抽屉。抽屉里的现金可以打烊后再盘点，但账本是随时可以核对的。万一老板中途晕倒，只要账本还在，钱就不会乱。HBase 里的 MemStore 就是那个抽屉，HFile 是打烊后的盘点表，WAL 就是账本。
很多人容易忽略一个细节：只有“WAL 写入并同步成功”这一步完成后，服务端才会给客户端返回成功。也就是说，你看到写入成功，真正意味着的是“这条日志已经被固化了”，而不是“数据已经在热点表里了”。这正是 HBase 不会丢已确认数据的根基。
1.2 WAL 保证的一致性是“持久性”，别指望它解决所有事
标题里有“数据一致性保障”这几个字，但先得把一致性这个词拆细。WAL 直接保证的核心是持久性（Durability），也就是已经向客户端确认成功的数据，在单集群内不会因为 RegionServer 宕机而丢失。它不负责跨行事务，也不负责分布式共识，更不是多副本之间实时强一致的那把锁。
HBase 自身在单行层面是原子的，跨行原子性需要依赖其他机制；而集群里 Region 的可用性切换、ZooKeeper 的会话管理，又是另一套逻辑。所以遇到“一致性”问题，先分清楚你问的是持久性、原子性、还是副本一致性，否则很容易把锅甩给 WAL。
HBase 的写入持久化级别其实有四种，很多开发同学只知道一个默认值，这个表值得存下来：
| 持久化级别 | 服务端行为 | 宕机可能丢失的数据 | 适用场景 |
|---|---|---|---|
| SYNC_WAL | 写 WAL 并执行 hflush 后才返回成功 | 理论上不丢已确认数据 | 默认级别，线上核心数据 |
| FSYNC_WAL | 写 WAL 并执行 hsync（真正 fsync）后才返回成功 | 落盘保证更强 | 对物理落盘有更高要求的场景 |
| ASYNC_WAL | 异步写 WAL，不等同步完成就返回 | 可能丢最近一批已返回成功的数据 | 监控、日志类可容忍少量丢失的业务 |
| SKIP_WAL | 完全不写 WAL | 宕机时该批数据基本全丢 | 临时批量导入，且数据可重新生成 |
默认的 SYNC_WAL 本质上调用的是 HDFS 的 hflush，而不是 hsync。这两个动作的区别后面会细讲，这里先记住一个结论：默认配置在“进程崩溃”场景下是安全的，但在“整机断电、HDFS 数据节点也掉电”的极端场景下，hflush 的保证强度不如 hsync。FSYNC_WAL 才是把 hsync 落到底的那一档。
还有一条容易被人忽视的前提：WAL 文件本身是放在 HDFS 上的，所以 WAL 的持久性建立在 HDFS 可用、副本正常的基础上。如果整个 HDFS 集群都损毁了，那没有任何日志能救得回来，这也是为什么生产环境仍然要做跨集群备份。
2. 深入拆解 append、hflush、hsync 与 sequenceid
2.1 WAL 文件里装的到底是什么
WAL 文件在 HDFS 上有独立的目录，一般是/hbase/WALs/<RegionServer的host,port,startcode>下按文件生成。每个 RegionServer 默认有一个自己的 WAL 写入流。文件内部是一条条追加的 WAL Entry 组成的，每条 Entry 大致包含两部分：HLogKey 和 WALEdit。
HLogKey 里放的是这条日志所属的 region、写入时的 sequenceid、写入时间等元信息；WALEdit 里放的是真正的变更内容，可以包含一个或多个 Cell 的 Put、Delete 操作。需要特别注意的是，一个 WAL 文件里会混着多个 region 的数据，因为 RegionServer 上所有 region 的写入都往同一个 WAL 里追加。这就给故障恢复埋了一个伏笔：宕机后拆分 WAL 时，必须先按 region 把日志分组，再分别回放。
最早版本的 WAL 底层是基于 Hadoop SequenceFile 实现的，后来版本用 Protobuf 封装替换，并支持更灵活的压缩。但从使用者的角度看，你不需要关心文件内部的具体字节布局，只需要记住它是“只追加、顺序写”的，顺序写带来的性能优势就是 WAL 能扛住高并发写入的原因。
2.2 append / hflush / hsync：三个词决定了你会不会丢数据
这是 WAL 机制里最值得深挖的一段。RegionServer 往 HDFS 上写 WAL，不是一次 API 调用就完事的，而是走 HDFS 客户端管线写入，简单说是 RegionServer 作为客户端连到第一个 DataNode，数据再往后接力传到第二、第三个 DataNode。
先看 append。RegionServer 把数据写入 HDFS 文件的输出流，数据进入管线，可能只到了 DataNode 的内存缓冲区，并逐级往后传。这个动作很快，但此时数据并没有真正落到任何一块磁盘上。
接着是 hflush。这个操作会把客户端缓冲区里的数据推送到整个管线里的所有 DataNode，并等待管线确认收到，但注意，它不要求 DataNode 把数据 fsync 到本地磁盘。换句话说，如果三个 DataNode 同时掉电，内存里还没来得及落盘的数据一样会丢。
最后是 hsync。它在 hflush 的基础上，要求每个 DataNode 都把数据 fsync 到本地磁盘，确认落盘成功后才算完成。所以“真正写进物理磁盘”的是 hsync，不是 hflush。
回到上一节的结论：默认的 SYNC_WAL 走的是 hflush，FSYNC_WAL 走的是 hsync。HBase 还提供了 hbase.wal.hsync、hbase.wal.hflush 这样的参数，可以控制 WAL writer 默认调用哪种方式，不同小版本的默认值有区别，使用前一定要去确认当前发行版本的默认行为，不要凭记忆下结论。
这里还有一个性能相关的机制必须提：Group Commit。因为 fsync 的代价很高，如果每条写请求都独立做一次磁盘同步，吞吐量会非常难看。HBase 会把一小段时间内的并发写请求合并成一撮，在 WAL 层做成一个批次，用一次 hsync 完成落盘，再把成功结果返回给这一批客户端。这样既保证了落盘，又摊薄了 fsync 的开销。副作用是，如果批次合并等待时间过长，延迟的 P999 会出现毛刺，后面排查写入抖动时还会提到。
2.3 sequenceid：恢复时不重放的关键
WAL 里每个 region 的数据都带着一个严格递增的 sequenceid。这个序号是 HBase 判断“哪些日志还需要回放”的核心依据。
正常运行时，MemStore 攒够数据后会 flush 成 HFile。每个 HFile 在生成时会记录自己包含的数据最大 sequenceid，本质上就是“这次 flush 之前，WAL 里已经推进到第几条日志了”。宕机恢复时，HBase 会先找到该 region 现存 HFile 的最大 sequenceid，再把 WAL 中所有小于等于这个序号的日志直接跳过，只回放那些序号更大的部分。
这意味着恢复不是一个“从头重放所有历史”的笨办法，而是一种“断点续传”。已经刷进 HFile 的数据不需要再进一遍内存，回放的数据量被严格限制在“上次 flush 之后新增的那一段”，恢复速度因此快得多。
sequenceid 还有一个隐藏作用：让重复回放变得安全。如果恢复任务中途失败被重新调度，它再次比对 HFile 的最大 sequenceid，已经回放过的日志依然会被跳过，不会因为重复执行而把同一份数据写两遍。
3. WAL 生产调参：参数、MultiWAL 与存储策略
3.1 四个调参方向和一张参数速查表
生产环境里调 WAL，核心方向其实是四个：文件大小与滚动频率、文件数量上限、同步强度、拆分开销。这四个方向互相牵制，比如想减少文件数量就得调大滚动阈值，但单文件太大又会拖慢拆分的粒度判断；想加快同步就得接受 fsync 次数变多。下面这张表是我在 HBase 2.x 上常用的速查表，不同发行版默认值会有差异，最终以集群的 hbase-default.xml 为准。
| 参数名 | 作用 | 常见默认值 | 调参建议 |
|---|---|---|---|
| hbase.wal.provider | 选择 WAL 实现 | defaultWAL | 高并发大 Region 数场景可改 multiwal |
| hbase.regionserver.hlog.blocksize | 单个 WAL 文件的滚动基准大小 | 0（沿用 HDFS 块大小） | 写入量大可调大，降低滚动频率 |
| hbase.regionserver.logroll.multiplier | 滚动系数，实际阈值为 blocksize 乘该值 | 0.95 | 通常不用动 |
| hbase.regionserver.logroll.period | 时间滚动周期 | 3600000 ms（1 小时） | 无写入时段也建议保留周期滚动 |
| hbase.regionserver.maxlogs | RegionServer 上 WAL 文件数上限 | 32 | 过小会阻塞写入，过大拖累恢复 |
| hbase.wal.hsync / hbase.wal.hflush | 控制 WAL 同步方式 | 版本差异大 | 核心数据优先保证 hsync 落盘 |
| hbase.master.logcleaner.ttl | WAL 归档后保留时间 | 600000 ms（10 分钟） | 复制延迟大时适当调大 |
先说文件滚动。WAL 文件不是写到无穷大的，它会在当前文件大小达到 blocksize 乘以 multiplier 时滚动成一个新文件，或者即使在空闲期，只要超过了 logroll.period，也会按时切换到新文件。为什么空闲也要滚动？因为如果没有写入，旧文件一直不封口，等哪天宕机要拆分时，面对的可能是跨越很长时间、体积巨大的文件。定时滚动让文件大小和覆盖时间段都变得可控。
再说文件数量上限。一个 RegionServer 同时打开的 WAL 文件数不是越多越好。文件数超过 maxlogs 后，RegionServer 会阻塞新的写入请求，并强制触发 flush，直到文件数回落到限制以内。这个机制是用来给系统踩刹车的，避免日志堆积到恢复时变成灾难。我见过一些集群为了“不阻塞写入”把 maxlogs 调得特别大，结果一次宕机，WAL 拆分数百个文件，恢复时间飙到小时级，属于典型把隐患往后挪。
3.2 MultiWAL：高写入场景要不要开
默认情况下，一个 RegionServer 只有一个 WAL 写入流，即使机器有几十个核，所有 region 的写日志也是串行落盘的。在高写入 QPS、高核数机器上，单 WAL 的追加同步很容易成为瓶颈，这就是 MultiWAL 存在的意义。
MultiWAL 的思路是把这台 RegionServer 上的 region 分成若干组，每组有自己独立的 WAL 文件写入流，多组之间并行追加、并行同步。配置方式是把 hbase.wal.provider 设置为 multiwal。开启后，写入吞吐通常会有肉眼可见的提升，尤其是多核机器上承载大量 put 请求时。
但它不是免费的。多组 WAL 意味着同时会有更多 WAL 文件存在，文件句柄变多，RegionServer 崩溃后需要拆分的文件数量也变多，恢复阶段反而可能变慢。所以我的建议是：Region 数量很少的小集群没必要开；写入压力大到已经观察到单 WAL 是瓶颈时再开；开之前一定要做一次压测和一次故障演练，确认吞吐提升的幅度大于恢复代价。
3.3 WAL 目录与 HDFS 存储策略怎么配合
WAL 目录在 HDFS 上的路径和 HFile 数据目录是分开的，默认是/hbase/WALs与/hbase/data这样互不相干的顶层目录。这个隔离意味着你有机会让 WAL 走不同的存储介质。
如果集群用的是混合存储，比如机械盘加 SSD，或者支持 HDFS 异构存储策略，优先考虑让 WAL 落在更快的那一档存储上。WAL 是顺序写、小文件、故障恢复时还要频繁读取，SSD 对它的帮助比对 HFile 大得多。HBase 也提供针对 WAL 目录的存储策略参数，可以在部署层面对齐。
但有一点我必须强调：不要为了追求性能把 WAL 从 HDFS 挪到本地。HDFS 上的 WAL 有副本冗余，某个数据节点坏掉不影响日志完整性；WAL 改到非 HDFS 位置，等于亲手放弃了这层保障。丢了 HDFS 副本的 WAL，已经失去“写前日志”的意义，这点没法靠灵感补救。
4. RegionServer 宕机后：WAL 拆分与回放的完整过程
4.1 从 ZooKeeper 超时到 region 重新上线
先串一遍宕机恢复的全过程，你会看到 WAL 不只是“写在前面”，它还是整套恢复逻辑的原材料。
第一步，RegionServer 的 ZooKeeper 会话超时，Master 判定这个节点已经死亡。此时该节点上所有 region 都处于不可服务状态，客户端请求这些 region 会得到重试提示。第二步，Master 或恢复流程把死节点遗留的 WAL 文件放入恢复队列，并分配给其他幸存的 RegionServer 去执行拆分任务。在 HBase 2.x 里这套流程由 Procedure 承担，1.x 里更多依赖 ZooKeeper 队列，但整体思路一致。
第三步是拆分。拆分任务逐个读取 WAL 文件，把里面混着的不同 region 的日志按 region 分开，分别生成恢复用的编辑文件。第四步是最关键的跳跃判断：对每个 region，对照它现有 HFile 的最大 sequenceid，跳过所有已经落盘的日志段。第五步，把剩下的日志回放进对应 region 的 MemStore，之后按正常流程继续服务或触发 flush。
这套流程的结果就是：你在宕机前已经确认写入的数据，会从 WAL 里被捞出来重新放回内存，最后再落成 HFile。只要 WAL 完整，数据就找得回来。反过来，如果 SKIP_WAL 了，那这个阶段什么都没有可捞的，数据就真的没了。
4.2 为什么回放不会造成数据重复
一个合理的问题是：拆分回放和正常写入同时进行，会不会把同一条数据写两遍？答案是不会，但要说明白为什么。
回放是有幂等保护的，核心就是 sequenceid。每条 WAL 日志都带 region 级别递增的 sequenceid，而每个 HFile 记录了 flush 时涵盖到的最大 sequenceid。回放前先算差集，小于等于这个最大值的日志全部丢弃，只保留更大的那部分。这个“断点”判断天然保证了回放数据不会和已有 HFile 重叠。
还有一种情况是客户端视角的重复。假设服务端 WAL 同步成功，但还没来得及给客户端返回成功就宕机了。客户端会因超时重试，导致服务端可能收到两条内容一样的写请求。不要把这种情况理解为“脏写”。重复执行写入最终态是一致的：后到的请求会得到一个新的更高 sequenceid，覆盖先到的数据；如果是同一个 rowkey 的重复 put，最终看到的是最后一次写入的值，而不是两份数据叠加。所以 WAL 回放可以在日志层面不重、不丢，再叠加客户端重试后，最终数据依然收敛。
另外，恢复任务本身也是可重试的。万一拆分任务中途失败，恢复队列里的记录还在，任务会被重新调度，再去读同一批 WAL。因为有 sequenceid 断点判断，重复执行不会造成破坏，这是整个机制设计里很关键的一个闭环。
4.3 缩短恢复时间的实操建议
我对恢复时间被拖长的场景印象很深。一次多台 RegionServer 同时异常，WAL 拆分任务排队，核心 region 半小时上不了线，业务方在群里连环追问。事后复盘，真正有效的措施是下面这些：
第一，控制未 flush 的数据量。MemStore 太大意味着还没生成 HFile 的数据段更长，回放的数据自然更多。合理调整 memstore 的 flush 阈值，不要追求“攒一把大的再刷”，恢复成本会随着积压量线性上升。
第二，控制 WAL 文件的大小和数量。把 blocksize 调得过小会导致文件频繁滚动，拆分的文件数量暴增；过大又会让单个拆分任务读很久。你要的是“数量可控、单文件大小适中”的状态。文件数量上限 maxlogs 也要配合着设，别把刹车拆掉。
第三，在 2.x 里拆分是分布式的，存活 RegionServer 越多，并行拆分的速度越快。如果集群只剩一两个节点扛所有拆分任务，那是天然瓶颈，这时候优先考虑让集群保持足够的冗余度。
第四，定期做故障演练。不要只在事故时才知道自己的恢复时间。挑个低峰期，手动 kill 一台 RegionServer，掐表看 region 从异常到重新可用的时间，同时检查数据完整性。演练能逼出很多“理论上没问题”的隐藏问题。
5. 生产环境 WAL 常见问题与排查实录
5.1 写入毛刺高，先查 WAL sync 是不是瓶颈
最常见的现象是集群整体写入 QPS 不高，但延迟的 P999 一直在高位抖动。很多人第一个想到的是 GC 或者 Compaction，盯了半天 JVM 也没找到结论。这时候把目光放到 WAL sync 上。
WAL sync 慢通常有几个来源：HDFS 数据节点的磁盘本身是机械盘，fsync 消耗大；WAL 目录和数据目录共用同一批磁盘，HFile 写入、Compaction 和 WAL 同步抢 IO；Group Commit 批次合并的等待时间过长，造成个别请求多等了一轮同步。排查时先看 RegionServer 日志里有没有明显的 sync 耗时告警或 WAL 慢日志，再看数据盘的 iostat 和 HDFS 的延迟指标。
解决办法也很直接：让 WAL 走更快的盘，把 WAL 目录和 HFile 目录在物理上隔离；如果业务允许，把非核心表的写入降级为 ASYNC_WAL，摊掉机械盘的负担。有一点要提醒：不要为了灭掉毛刺顺手把 hbase.wal.hsync 关掉，这个开关一旦关掉，你只是把故障风险藏进了未来某次断电事故里。
5.2 WAL 文件堆积不滚动怎么办
正常情况下，WAL 文件数应该是平稳的，某个 RegionServer 的WALs目录里同时存在的文件不会太多。如果发现文件数量持续增长，先看当前 WAL 是不是一直没触发滚动条件。文件大小没到 blocksize 乘 multiplier，时间周期也没到，理论上不会切新文件；但如果写入持续灌入，文件迅速增大，滚动又来不及清理，数量就会堆起来。
另一个常见原因是 flush 跟不上写入速度。WAL 文件多了以后，RegionServer 会强制触发 flush 来让日志可以滚动归档。如果 flush 本身被 Compaction 或慢盘拖住，WAL 就会继续积压。这时优先解决的其实是 flush 和 Compaction 效率，而不是 WAL 参数。
遇到 WAL 文件堆积，我会先看一眼 maxlogs 有没有生效，再查 RegionServer 日志里有没有“too many WAL files”相关的阻塞提示。如果只是临时积压，可以稍微调大 maxlogs 并观察；如果长期如此，说明写入模型或者存储能力出了问题，靠调参只是延后事故。
5.3 恢复任务卡死，region 迟迟不能上线
RegionServer 宕机后最让人着急的就是拆分任务卡住。典型表现是某个 region 长时间处于下线状态，Master 日志反复出现恢复重试，用户请求一直超时。
优先排查三个方面：拆分任务是否因为 HDFS 异常反复失败，比如 NameNode 抖动或者数据节点掉线导致读 WAL 报错；WAL 文件是不是特别大，单文件拆分耗时过久；是不是多个 RegionServer 同时宕机，恢复任务互相抢占资源。日志里出现拆分失败或重试的次数如果不正常，基本就是上面三种之一。
这种时候不要靠删 WAL 文件来“解决问题”。删掉 WAL 等于告诉集群“这批数据我不要了”，相当于主动丢数据。真要面对损坏的 WAL，正确做法是评估丢失范围，再结合备份去恢复。恢复期间最怕的是人为操作把本来能捞回来的数据亲手抹掉。
5.4 被误用的三种写入持久化级别
我见过程序员为了压测方便，把客户端统一设成 SKIP_WAL，压测完忘记改回来，直接上线跑了好几天。这种事故一般不会立刻暴露，直到某次 RegionServer 宕机，业务才发现丢了近几天写入的数据。
SKIP_WAL 不是不能用于生产，前提是业务明确知道这批数据可以重建。比如离线预计算结果的回填，重新跑一遍任务就能恢复。同样的逻辑适用于 ASYNC_WAL，它适合“丢几条监控数据无所谓”的场景。比较稳妥的做法是按表或者按请求维度区分，而不是全局一刀切：核心交易类数据保持默认 SYNC_WAL，埋点、日志类数据用 ASYNC_WAL。同一集群里不同业务不同保障，这是成本优化，不是偷工减料。
还有一点容易被忽略：BulkLoad 批量导入本身是绕过 WAL 直接生成 HFile 的路径，它也没有 WAL 保护。批量导入前务必确认源数据还能不能重新生成，不要以为所有写入都默认走 WAL。
6. 写在最后：几个我用真金白银换来的运维习惯
做了几年 HBase 之后，我对 WAL 的态度从“理解原理就行”慢慢变成了“每个参数改动都值得敬畏”。分享几个个人习惯，不一定适合所有团队，但至少能帮你少踩一些坑。
第一个习惯：改 WAL 相关配置时，一次只动一个变量。HBase 的稳定性问题往往是一堆参数叠加出来的，今天调 blocksize，明天调 maxlogs，后天改 provider，等到出问题的时候，谁也没法说清是哪一步把系统推到了临界点。我自己的做法是每次变更只改一个参数，并记录下修改前后的写入延迟、文件数和恢复时间，留好变更档案。
第二个习惯：监控里必须盯住几个 WAL 相关指标。我用得最频繁的是这五组：WALs 目录下的文件数量、当前 WAL 文件大小、sync 操作耗时、拆分任务执行的时长和次数、以及跨集群复制场景下的日志清理延迟。这几个指标能提前暴露很多隐患，比如文件数量开始增长、sync 耗时逐步抬高，趋势比绝对值更有信号意义。
第三个习惯：定期做故障演练，而且要在低峰期真的 kill 一台 RegionServer。纸上谈兵永远发现不了问题。第一次演练时，我原以为恢复只要几分钟，实际等 region 重新可用花了二十分钟，原因就是 WAL 文件堆积得比预想严重。练过一次之后，后面再遇到真宕机，处理起来就从容很多。
第四个习惯：对持久化级别的改成负有敬畏心。把一张表的写入从 SYNC_WAL 改成 ASYNC_WAL 或 SKIP_WAL 之前，先问一句：如果这台机器今晚就断电，这个决定会让我后悔吗？如果答案是会，就不要改。
WAL 的设计本身并不复杂，复杂的是在它身上做取舍时，得时刻记得它替你扛住的是最底线的“不丢数据”。参数可以调，异构存储可以用，MultiWAL 可以开，但那份写前日志的分量，值得每一次变更之前多想一分钟。
