用 Rust 从零实现 WAL:关键不在写日志,在 fsync 的时机
所有数据库都提到 WAL,但真正决定它可靠与否的,是一行代码:
fsync放在哪里。
这篇从零实现一个预写日志(Write-Ahead Log)。重点不是"怎么写文件",而是三件事:日志记录的格式、fsync 的时机、崩溃后怎么恢复。
为什么需要 WAL
假设你要更新一个数据结构(B 树、LSM-Tree、甚至一个内存表)。如果不写日志,直接改数据结构:
- 改到一半进程崩了 → 数据结构处于"改了一半"的状态,无法判断哪部分生效
- 即使改完了,操作系统可能还没把数据刷到盘 → 掉电就丢
WAL 的解法是把"修改"变成两步可重放的记录:
1. 把"我要做什么"追加写入日志文件,然后 fsync
2. 写成功之后再改真正的数据结构这样崩溃后,只要重放日志里"已经 fsync 成功"的部分,就能恢复。
核心保证:日志里有的,数据里最终一定有。
第一步:日志记录格式
每条日志是一段自描述的数据。设计格式时考虑三件事:
- 能判断记录是否完整(崩溃可能写了一半)
- 能校验内容损坏(磁盘位翻转)
- 能知道自己有多长(顺序读取)
#[derive(Debug, Clone, PartialEq)]
pub enum Record {
Put { key: Vec<u8>, value: Vec<u8> },
Delete { key: Vec<u8> },
Checkpoint { lsn: u64 },
}
impl Record {
fn encode(&self) -> Vec<u8> {
let mut body = Vec::new();
match self {
Record::Put { key, value } => {
body.push(0x01);
body.extend_from_slice(&(key.len() as u32).to_le_bytes());
body.extend_from_slice(key);
body.extend_from_slice(&(value.len() as u32).to_le_bytes());
body.extend_from_slice(value);
}
Record::Delete { key } => {
body.push(0x02);
body.extend_from_slice(&(key.len() as u32).to_le_bytes());
body.extend_from_slice(key);
}
Record::Checkpoint { lsn } => {
body.push(0x03);
body.extend_from_slice(&lsn.to_le_bytes());
}
}
body
}
}用 u32 小端存长度,而不是变长整数。 变长整数省空间,但解析边界更复杂。存储系统里"简单可验证"比"省几个字节"更重要——何况后面会加对齐。
第二步:给记录加校验
一条完整的日志帧 = 长度 + 校验 + 内容:
+--------+--------+--------+------------------+
| len | crc32 | type | payload |
| 4 bytes| 4 bytes| 1 byte | len-1 bytes |
+--------+--------+--------+------------------+struct Frame {
len: u32,
crc: u32,
body: Vec<u8>,
}
impl Frame {
fn new(body: Vec<u8>) -> Self {
let crc = crc32(&body);
Frame { len: body.len() as u32, crc, body }
}
fn write_to(&self, out: &mut impl std::io::Write) -> std::io::Result<()> {
out.write_all(&self.len.to_le_bytes())?;
out.write_all(&self.crc.to_le_bytes())?;
out.write_all(&self.body)?;
Ok(())
}
}CRC32 是存储系统里的标准选择——足够快地发现随机位翻转,实现也简单。
fn crc32(data: &[u8]) -> u32 {
let mut crc = 0xFFFF_FFFFu32;
for &byte in data {
crc ^= byte as u32;
for _ in 0..8 {
let mask = (crc & 1).wrapping_neg();
crc = (crc >> 1) ^ (0xEDB8_8320 & mask);
}
}
!crc
}生产实现会用查表或硬件 CRC 指令(crc32 在 x86 上是一条指令),但算法就是上面这个。
为什么校验是必需的? 因为磁盘和文件系统都不保证写入的原子性。一次 4KB 的写,可能在扇区之间断电,造成中间一段是旧数据、一段是新数据。没有 CRC,这种"撕裂写"会被当成合法记录读取。
第三步:长度前缀解决了什么问题
前面已经用了长度前缀,这里单独说清它为什么重要。
没有长度前缀,你怎么读一条记录?只能靠"读到某个分隔符"——但二进制数据里任何字节都可能出现,没法当分隔符。
有了长度前缀,读取逻辑非常确定:
fn read_frame(reader: &mut impl std::io::Read) -> std::io::Result<Option<Frame>> {
// 1. 读长度
let mut len_buf = [0u8; 4];
match reader.read_exact(&mut len_buf) {
Ok(()) => {}
Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
Err(e) => return Err(e),
}
let len = u32::from_le_bytes(len_buf) as usize;
// 2. 读 crc
let mut crc_buf = [0u8; 4];
reader.read_exact(&mut crc_buf)?;
let crc = u32::from_le_bytes(crc_buf);
// 3. 读 body
let mut body = vec![0u8; len];
reader.read_exact(&mut body)?;
// 4. 校验
if crc32(&body) != crc {
return Err(std::io::Error::new(
std::io::ErrorKind::InvalidData,
"checksum mismatch",
));
}
Ok(Some(Frame { len: len as u32, crc, body }))
}崩溃恢复的关键就在第 3 步的 read_exact: 如果文件在中间被截断(写了一半),read_exact 会返回 UnexpectedEof,我们把这条不完整的记录丢弃,从它之前的位置恢复。
"写到一半的记录"不是错误,是崩溃恢复必须正常处理的常态。 恢复逻辑要能判断"最后一条有效记录在哪"。
第四步:WAL 主体
use std::fs::{File, OpenOptions};
use std::io::{BufWriter, Seek, SeekFrom, Write};
use std::path::{Path, PathBuf};
pub struct Wal {
file: BufWriter<File>,
path: PathBuf,
/// 下一条记录的序号
next_lsn: u64,
/// 已写入但可能未 fsync 的字节数
unsynced: usize,
}打开:
impl Wal {
pub fn open(path: impl AsRef<Path>) -> std::io::Result<Self> {
let path = path.as_ref().to_path_buf();
let file = OpenOptions::new()
.create(true)
.read(true)
.append(true)
.open(&path)?;
// 从已有日志里恢复 next_lsn
let next_lsn = Self::scan_last_lsn(&path)?;
Ok(Self {
file: BufWriter::new(file),
path,
next_lsn,
unsynced: 0,
})
}
}写入:
pub fn append(&mut self, record: &Record) -> std::io::Result<u64> {
let lsn = self.next_lsn;
self.next_lsn += 1;
let body = record.encode();
let frame = Frame::new(body);
// 重要:把 lsn 也写进帧头,恢复时用
let bytes = {
let mut v = Vec::with_capacity(4 + 4 + 8 + frame.body.len());
v.extend_from_slice(&frame.len.to_le_bytes());
v.extend_from_slice(&frame.crc.to_le_bytes());
v.extend_from_slice(&lsn.to_le_bytes());
v.extend_from_slice(&frame.body);
v
};
self.file.write_all(&bytes)?;
self.unsynced += bytes.len();
Ok(lsn)
}第五步:fsync 到底在保证什么
这是全文最核心的部分。很多人把 write 当成"数据已经落盘",这是错的。
一次写入要经过至少三层缓存才真正落到磁盘:
应用 write() --> 内核页缓存 --> 磁盘控制器缓存 --> 盘片/闪存
(oops 就丢) (掉电就丢)write()只是把数据交给内核页缓存。进程崩溃不会丢,但内核 panic 或掉电会丢fsync()才把数据推到持久介质,并等待磁盘确认
pub fn sync(&mut self) -> std::io::Result<()> {
if self.unsynced == 0 {
return Ok(()); // 没有新数据,省一次系统调用
}
self.file.flush()?; // 把 BufWriter 的缓冲推给内核
self.file.get_ref().sync_all()?; // 内核 -> 磁盘
self.unsynced = 0;
Ok(())
}注意这里有两个层次的 flush,缺一不可:
BufWriter::flush()把用户态缓冲推到内核(否则数据还在BufWriter里)File::sync_all()才做真正的 fsync
漏掉第一个是经典 bug:sync_all 作用在 File 上,BufWriter 里那部分数据根本没进内核。
fsync 的代价
fsync 很慢。在机械盘上,一次 fsync 要等盘片转到正确位置,可能 5-10ms。如果每条记录都 fsync,吞吐就被限制在 100-200 TPS。
这就引出了 WAL 最重要的性能取舍:
| 策略 | 可靠性 | 吞吐 |
|---|---|---|
| 每条记录都 fsync | 最强(不丢任何已确认的写) | 低(受 fsync 限制) |
| 固定间隔 fsync(如 10ms) | 崩溃可能丢最后 10ms | 高 |
| 不 fsync,靠 OS 刷盘 | 掉电丢大量数据 | 最高 |
决定权应该交给调用方,因为不同数据对"丢多少"的容忍度不同:
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum SyncPolicy {
/// 每条都 fsync:最安全,最慢
Always,
/// 每 N 条 fsync:折中
EveryN(usize),
/// 由调用方显式调用 sync()
Manual,
/// 交给操作系统(测试用,不可靠)
Never,
}impl Wal {
pub fn append_with(&mut self, record: &Record, policy: SyncPolicy) -> std::io::Result<u64> {
let lsn = self.append(record)?;
match policy {
SyncPolicy::Always => self.sync()?,
SyncPolicy::EveryN(n) if self.next_lsn % n as u64 == 0 => self.sync()?,
_ => {}
}
Ok(lsn)
}
}fsync 的位置决定了系统的可靠性边界。 "盲目每条 fsync"和"完全不 fsync"都是错的——正确的是让调用方根据数据重要性选择。
组提交(group commit) 是这里最有效的优化:把多个线程的写请求攒在一起,一次 fsync 覆盖全部。Redis 的 AOF everysec 和 PostgreSQL 的 commit_delay 都是这个思路。
第六步:崩溃恢复
恢复的目标:重放所有完整且校验通过的记录,遇到第一条不完整的就停。
impl Wal {
pub fn recover(path: impl AsRef<Path>) -> std::io::Result<(Self, Vec<(u64, Record)>)> {
let path = path.as_ref();
let data = std::fs::read(path)?;
let mut cursor = std::io::Cursor::new(&data);
let mut records = Vec::new();
let mut valid_bytes = 0usize;
loop {
let start = cursor.position() as usize;
let frame = match read_frame_with_lsn(&mut cursor) {
Ok(Some(f)) => f,
Ok(None) => break, // 正常 EOF
Err(_) => {
// 校验失败或截断:从这里截断文件
eprintln!("WAL 在偏移 {start} 处损坏,截断到 {valid_bytes}");
break;
}
};
valid_bytes = cursor.position() as usize;
records.push(frame);
}
// 把文件截断到最后一个有效记录
let file = OpenOptions::new().write(true).open(path)?;
file.set_len(valid_bytes as u64)?;
// 重新以追加模式打开
let wal = Self::open(path)?;
Ok((wal, records))
}
}set_len 截断这一步不能省。 如果不截断,损坏的尾巴会一直留在文件里,每次重启都要重新报错;而且下次追加会写在损坏数据之后,永远恢复不了。
恢复之后怎么用:
fn open_store(path: &Path) -> std::io::Result<Store> {
let (_wal, records) = Wal::recover(path)?;
let mut store = Store::default();
for (lsn, record) in records {
match record {
Record::Put { key, value } => { store.put(key, value); }
Record::Delete { key } => { store.delete(&key); }
Record::Checkpoint { .. } => {}
}
store.last_applied = lsn;
}
println!("恢复完成,重放了 {} 条记录", store.last_applied + 1);
Ok(store)
}第七步:幂等——重放两次不能出错
这里有个容易被忽略的要求:重放必须是幂等的。
为什么?因为崩溃可能发生在"日志已 fsync、但数据结构只改了一部分"的时候。恢复时会把最后一批记录全部重放——包括那些其实已经生效的。
时间线:
t1: WAL fsync (记录 1,2,3) ✓
t2: 应用到数据结构 (记录 1,2) ← 崩在这里
t3: 恢复,重放记录 1,2,3记录 1、2 会被应用两次。对 Put 和 Delete 来说,这不是问题(覆盖写天然幂等)。但对自增计数器这类操作就不行:
// 不幂等:重放会多加一次
Record::Increment { key, delta }
// 幂等:改为记录最终值
Record::Put { key, value: (old + delta).to_string() }WAL 里应该记录"结果",而不是"操作"。 记录
SET x = 5是幂等的,记录x += 1不是。
这也是为什么很多数据库的 WAL 记录的是物理页的"前像/后像",而不是 SQL 语句:物理记录天然幂等,逻辑操作可能要额外的幂等性保证。
第八步:日志轮转和清理
WAL 会无限增长。真实系统用**检查点(checkpoint)**来回收:
1. 把数据结构刷到持久化存储(如 SSTable)
2. 记录一个 checkpoint 标记,表示"到此为止的日志可以丢弃"
3. 删除 checkpoint 之前的日志文件 pub fn checkpoint(&mut self, lsn: u64) -> std::io::Result<()> {
self.append(&Record::Checkpoint { lsn })?;
self.sync()?;
// 可以安全删除 lsn 之前的日志段了
self.truncate_before(lsn)?;
Ok(())
}
fn truncate_before(&mut self, lsn: u64) -> std::io::Result<()> {
// 简单实现:清空整个文件并重新打开
// 生产实现:按段(segment)轮转,删掉整个旧段
self.file.flush()?;
let file = OpenOptions::new()
.write(true)
.truncate(true)
.open(&self.path)?;
file.sync_all()?;
drop(file);
self.file = BufWriter::new(OpenOptions::new().append(true).open(&self.path)?);
self.unsynced = 0;
Ok(())
}生产实现按"段"(segment)轮转:每个段一个固定大小(比如 64MB),写满就换新文件。这样删除是"删文件",而不是"改文件"——既快又安全。
只截断单个文件的问题是:set_len 之后,文件系统的元数据更新本身也需要 fsync,否则崩溃后截断丢失,又回到损坏状态。
结论
WAL 的代码不长,但它把存储系统最核心的几个概念都串起来了:
长度前缀让读取可确定;CRC 让撕裂写能被识别;write 只到页缓存、fsync 才到磁盘;fsync 的位置决定了可靠性边界;恢复时遇到不完整记录就截断;重放必须幂等;检查点负责回收空间。
下次看到 synchronous_commit = off(PostgreSQL)或者 appendfsync everysec(Redis),你就知道它们改的正是那个 fsync 的时机——而这是"性能"和"不丢数据"之间那道最明确的取舍线。
下一篇,我们用这个 WAL 做持久化层,去造一个 LSM-Tree。