返回文章列表

用 Rust 从零实现 WAL:关键不在写日志,在 fsync 的时机

541 字·5 分钟阅读
Rust从零造轮子存储

所有数据库都提到 WAL,但真正决定它可靠与否的,是一行代码:fsync 放在哪里。

这篇从零实现一个预写日志(Write-Ahead Log)。重点不是"怎么写文件",而是三件事:日志记录的格式、fsync 的时机、崩溃后怎么恢复。


为什么需要 WAL

假设你要更新一个数据结构(B 树、LSM-Tree、甚至一个内存表)。如果不写日志,直接改数据结构:

  1. 改到一半进程崩了 → 数据结构处于"改了一半"的状态,无法判断哪部分生效
  2. 即使改完了,操作系统可能还没把数据刷到盘 → 掉电就丢

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,缺一不可:

  1. BufWriter::flush() 把用户态缓冲推到内核(否则数据还在 BufWriter 里)
  2. 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。