FoundationDB on Hellokitty's Blog

3FS 如何使用 FoundationDB：元数据模型、事务与并发控制

Fri, 14 Aug 2026 19:10:00 +0800

3FS 是面向 AI 训练和推理负载设计的分布式文件系统。它没有把 FoundationDB 当成普通的持久化 KV 使用，而是围绕 FoundationDB 的有序键空间、乐观事务、冲突检测和 Versionstamp，构建了一套强一致的文件系统元数据服务。

本文从源码出发，梳理 3FS 如何接入 FoundationDB，如何编码 inode 和目录项，以及 create、rename、remove、list 等文件系统操作怎样映射为 FoundationDB 事务。

本文分析的源码位于 3FS 仓库中的以下目录：

src/fdb/             FoundationDB C API 封装
src/common/kv/       通用 KV 和事务接口
src/meta/store/      inode、目录项和元数据操作
src/meta/components/ ID 分配、服务分布和 GC 等组件
src/meta/service/    Meta Service RPC 入口

一、3FS 中 FoundationDB 的定位

3FS 将数据面和元数据面分开：

文件的 chunk 数据由 Storage Service 保存。
文件系统元数据由 Meta Service 管理，并持久化到 FoundationDB。

FoundationDB 中保存的主要内容包括：

inode；
directory entry，也就是目录项；
文件打开会话；
RPC 幂等记录；
Meta Server 分布信息；
用户、配置和其他全局状态。

整体调用链可以简化为：

FoundationDB 事务如何实现？从源码看 GRV、Resolver、TLog 与 Storage Server

Fri, 14 Aug 2026 17:00:00 +0800

FoundationDB 支持跨任意 key range 的 ACID 事务，并向应用提供严格可串行化语义。但它既没有让每个 Storage Server 参与经典的两阶段提交，也不是传统单机数据库中“共享缓冲池 + Undo/Redo”的事务实现。

它的核心方案可以概括为：

全局版本号 + MVCC 快照读 + 客户端暂存修改 + Resolver 乐观冲突检测 + 多副本 TLog 持久化。

本文结合 FoundationDB 官方源码，沿着一笔事务的完整路径，解释它如何从读取、提交、冲突检测，一直走到日志持久化和 Storage Server 应用。

本文分析的源码版本为：

commit: eab21ffe07c20575d5bac9ab0745375b8f7f8357
date:   2026-08-12

源码中的具体行号会随版本变化，阅读时应以函数和类型名为主要定位依据。

一、整体架构

FoundationDB 的事务涉及以下核心角色：

角色	主要职责
Client	保存事务 mutations、读冲突范围和写冲突范围
GRV Proxy	分配 Read Version
Commit Proxy	批量接收事务、分配 Commit Version、组织提交流水线
Resolver	检测乐观事务冲突
TLog	复制并持久化已提交 mutations
Storage Server	提供版本化读取，异步应用 TLog mutations
Sequencer	为事务系统提供版本推进基础

完整流程可以简化为：

Client
  │
  ├── 获取 Read Version
  │
  ├── 从 Storage Server 读取该版本
  │
  ├── 在客户端积累 mutations 和 conflict ranges
  │
  └── 提交
        │
        ▼
   Commit Proxy
        │
        ├── 组成 Commit Batch
        ├── 分配 Commit Version
        └── 按 key range 发给 Resolver
        │
        ▼
     Resolver
        │
        ├── 检查 read conflict ranges
        ├── 登记 write conflict ranges
        └── 返回 committed / conflict / too old
        │
        ▼
   Commit Proxy
        │
        ├── 丢弃冲突事务
        ├── 为 mutation 添加 Storage Server tag
        └── 将成功事务写入 TLog
        │
        ▼
       TLog
        │
        ├── 按冗余策略复制和持久化
        └── 返回 durable
        │
        ▼
   Commit Proxy
        │
        └── 向 Client 返回 Commit Version
        │
        ▼
 Storage Server
        ├── 异步读取自己的 tagged mutations
        ├── 应用到内存中的版本化数据
        └── 后台持久化到 Storage Engine

最关键的解耦是：

FoundationDB 中有 Undo 和 Redo 吗？从 TLog、MVCC 到故障恢复

Fri, 14 Aug 2026 10:00:00 +0800

传统数据库通过 Undo Log 和 Redo Log 保证事务的原子性与持久性：Undo 撤销未提交的修改，Redo 恢复已经提交但尚未写入数据文件的修改。那么，在采用分布式事务架构的 FoundationDB 中，是否也存在这两类日志？

简短回答是：

FoundationDB 有承担类似 Redo 职责的 TLog，但通常没有传统意义上的 Undo Log。

这并不意味着 FoundationDB 不支持事务回滚或 MVCC，而是因为它对未提交数据、提交日志和历史版本的组织方式与传统数据库不同。

一、先回顾传统数据库为什么需要 Undo 和 Redo

传统数据库通常允许事务直接修改缓冲池中的共享数据页。数据页何时写入磁盘，与事务何时提交并不完全同步。

因此会出现两种状态。

1. 事务未提交，数据页却已经落盘

例如事务把账户余额从 100 改成 80，但随后事务失败：

BEGIN;

UPDATE account
SET balance = 80
WHERE id = 'A';

ROLLBACK;

如果包含 80 的脏页已经写入磁盘，数据库就必须知道原值是 100，才能撤销这次修改。这是 Undo Log 的主要职责。

2. 事务已经提交，数据页却尚未落盘

另一个事务已经执行 COMMIT，但修改可能仍然只存在于内存中的脏页里。如果服务器此时断电，已提交的数据就会丢失。

因此数据库先持久化 Redo Log，再返回提交成功。重启后，即使数据页没有及时落盘，也可以通过 Redo 重新应用修改。

可以把二者概括为：

Undo：事务不应该生效，但修改可能已经进入数据文件。
Redo：事务应该生效，但修改可能还没有进入数据文件。

二、FoundationDB 的事务提交流程

FoundationDB 并不是把客户端事务中的每次 set 或 clear 立即写入 Storage Server。事务提交前，这些操作首先保存在客户端的事务对象中。