EdenFS 术语表深度解析:Backing Store、Checkout、Inode 与 Materialization 核心概念指南

原创2026-10-06 12:58:041,846 阅读
文章标签:开发工具CLI后端

EdenFS 术语表深度解析:Backing Store、Checkout、Inode 与 Materialization 核心概念指南

EdenFS 是 Sapling 项目(Meta 开源的版本控制系统)中的虚拟文件系统守护进程,它以按需加载的方式把版本控制数据暴露为本地工作区。本文以 eden/fs/docs/Glossary.md 为骨架,逐条剖析 EdenFS 文档与源码中反复出现的核心术语——Backing Repository、Backing Store、Checkout、Inode、Journal、Overlay 等,并结合仓库源码实现(如 BackingStore.h、Journal.h)与配套文档(如 Inodes.md、InodeStorage.md)展开纵深讲解。读完本文,你将能准确读懂 EdenFS 的源码注释、Thrift 接口与配置输出,理解"加载/卸载""物化/非物化""填充"这些状态词的精确含义及其相互关系。

术语表概览:为什么 EdenFS 需要一份专属 Glossary

EdenFS 同时横跨"版本控制"与"操作系统文件系统"两个领域,两边的既有术语在此交汇后极易产生歧义。例如 VCS 里的 "checkout" 与文件系统里的 "mount",以及 "repository" 与工作区之间的差别。因此 Glossary.md 以官方术语表的形式,为代码库、文档与讨论提供一套统一、自洽的词汇约定。下文按"数据来源→工作区→内存与磁盘状态→变更记录"的脉络展开,每个词条同时给出官方定义与仓库内可验证的实现依据。

数据来源类术语:Repository、Backing Repository、Backing Store、Local Store

Repository(仓库)

官方定义中,"repository" 特指版本控制系统对提交(commit)、目录(tree)和文件(blob)等历史数据的存储,与代表"当前工作目录状态"的 checkout 严格区分。这套对象模型对应仓库中的 eden/fs/model 目录(Tree、Blob、TreeEntry 等数据类)。值得强调的是,InodeStorage.md 指出:Git 与 Mercurial 的树结构是"抽象的、以哈希索引的",它只表达文件层级,并不记录文件属主、权限(仅记录可执行位)、硬链接等信息——这正是 EdenFS 需要 overlay 与 inode 元数据层来补齐文件系统语义的原因。

Backing Repository(支撑仓库)

EdenFS 从 Mercurial 或 Git 获取数据时,需要一个单独的、位于本地的**裸仓库(bare repository)**作为数据来源,这就是 backing repository:

  • 它是本地磁盘上真实存在的仓库,供 EdenFS 拉取源控制数据;
  • 多个 checkout 可以共享同一个 backing repository;
  • 它与下文 Backing Store 的区别在于:后者指 EdenFS 内部获取源控制数据的抽象实现,前者指底层源控制状态的具体本地磁盘存储。

Backing Store(支撑存储)

Backing store 一词源于 BackingStore 抽象类——它为"从源控制获取对象数据"提供统一 API,理论上可支持多种源控制类型(EdenSCM、Mercurial、Git 等)。从源码看,该抽象接口的核心职责包括(BackingStore.h):

  • 对象获取:co_getRootTree(按 RootId 取根树)、getTree/co_getTree(取树)、getBlob/co_getBlob(取文件内容 blob),以及 getTreeAuxData、co_getBlobAuxData 等辅助数据获取;
  • 对象比较:compareObjectsById 与 compareRootsById,用于在 ID 编码不同但内容可能相同的情况下短路递归比较,返回 ObjectComparison::{Unknown, Identical, Different} 三种结果;
  • 批量预取与状态管理:prefetchBlobs、dropAllPendingRequestsFromQueue、workingCopyParentHint、startRecordingFetch/stopRecordingFetch 等。

代码中还提供了 BijectiveBackingStore 基类(BackingStore.h),用于"对象 ID 与对象一一对应(如以加密哈希标识对象)"这一常见场景,直接按字节比较即可判定两个 ID 是否指向同一对象。

官方词条特别提醒两点:其一,从 backing store 取数据通常被视为代价高昂的操作,因为它可能触发从远端主机拉取;其二,注意区分:backing store 是 EdenFS 内部的获取实现,backing repository 才是底层源控制状态的本地磁盘存储。

Local Store(本地存储)与 State Directory

本地存储是 EdenFS 对源控制数据的本地缓存,数据存放在 EdenFS 状态目录](#state-directory) 下的 .eden/storage。官方词条同时指出:随着时间推移,EdenFS 正在逐渐减少在 local store 中跟踪数据,更多依赖源控制特有的数据获取与缓存机制。这一演进思路在 [Caching.md、ObjectStoreStats.md 等文档中有更深入的体现。

工作区类术语:Checkout 与 Overlay

Checkout(检出的工作区)

在 EdenFS 语境中,"checkout" 指客户端本地的源控制检出,尤其是工作目录状态本身。它和 "repository"(历史元数据存储)相对:repository 保存历史提交与对象信息,checkout 展示当前检出提交的工作目录状态。

官方词条还交代了一段术语演进史:EdenFS 早期曾用 "client" 和 "mount point" 指代 checkout,因此在少量旧代码位置(尤其是 EdenMount 类)仍能看到这些历史称呼;而新代码与文档已统一改用 "checkout"。此外,EdenFS 通过 FUSE、NFS、ProjFS 等内核接口把 checkout 暴露给用户,底层数据仍从 repository 拉取——Linux 上这一暴露路径的完整机制见 Inodes.md。

Overlay(覆盖层)

Overlay 是 EdenFS 存储已物化(materialized)文件与目录信息的地方,是 checkout 状态的"增量层":

  • 每个 checkout 拥有独立的一份 overlay 存储,位于状态目录下的 .eden/clients/CHECKOUT_NAME/local;
  • 术语 "overlay" 源于它就像联合文件系统(overlay/union filesystem):本地修改被"覆盖"在底层源控制状态之上。

结合 InodeStorage.md 的 Concrete Storage 一节可以看到 overlay 更底层的角色:它是以 inode 编号为键的磁盘映射(inode number → 时间戳 + 文件/树内容)。其中有两个关键不变量与持久性保证相关:

  • 若树的孩子条目没有源控制 ID(即标记为已物化),该 inode 的数据必须存在于 overlay 中;
  • 因此物化前必须先写入孩子的 overlay 数据,而反物化时必须在删除孩子 overlay 数据之前先在父节点中标记反物化——以防进程在两步之间崩溃导致状态不一致。

状态类术语:Inode、Loaded/Unloaded、Materialized/Non-Materialized、Populated

Inode

Inode 表示文件系统中的一个文件或目录,是 Unix 文件系统通用概念(原文档给出了维基百科的完整描述链接)。在 EdenFS 中,inode 由两个核心类实现:Inodes.md 指出 TreeInode 表示目录 inode,FileInode 表示所有非目录 inode(普通文件、符号链接、socket 等),二者共享 InodeBase 基类,并通过 InodePtr 智能指针进行引用计数管理。InodeMap 则负责按 inode 编号查找 inode 对象。

Loaded / Unloaded(已加载 / 未加载)

这两个词描述的是:EdenFS 是否在内存中为该 inode 保留了状态。

  • 若某个文件或目录在内存中有对应的 FileInode/TreeInode 对象,则称其为 loaded;
  • 否则为 unloaded;
  • checkout 首次挂载时大多数 inode 处于 unloaded 状态,EdenFS 按需(lazily)在访问时加载它们。

需要留意 InodeStorage.md 中提出的一个细节:Eden 对 "loaded" 一词存在两种用法——在讨论 inode 是否被 InodeMap 跟踪时它指"内存中是否有状态记录",而 FileInode 自己的 blob 是否加载是另一回事。该文档还给出了 unloaded inode 被 unloadedInodes_ 表"记住"的条件:只要它仍有非零的 FUSE 引用计数,其编号、ID、权限位、父 inode 编号与孩子名就会被保留在内存映射中。

Materialized / Non-Materialized(已物化 / 未物化)

这是 EdenFS 最重要的状态词之一,官方词条给出精确定义:

  • 非物化(non-materialized):我们知道一个可用于获取文件/目录内容的源控制对象 ID,其内容与某个源控制对象完全一致;
  • 物化(materialized):我们不知道可用于查找内容的源控制对象 ID(例如文件被修改后,无法再从源控制获取内容)。

关于物化的几条关键规则(官方词条 + Inodes.md 双重印证):

  1. 初始状态全为非物化:checkout 首次 clone 时,根目录对应当前提交的根树,每个孩子也一一对应源控制中的孩子,故全部非物化;
  2. 修改触发物化:文件从源控制状态被修改后即变为物化;本地新建的文件一开始就处于物化状态;
  3. 物化向上递归:一旦孩子 inode 物化,其祖先目录因不再对应已知源控制树,也必须递归物化,直到仓库根或某个已物化的树为止。TreeInode 在孩子条目被增删时物化,FileInode 在内容更新时物化;
  4. 物化与"被修改"正交:把非物化文件重命名到新位置不会使其物化(内容仍对应已知对象),但从源控制视角该文件必须被报告为已修改;同样,把文件改回原始内容也未必立即反物化,EdenFS 可能在后续 checkout 或 commit 时检测到内容一致才反物化;
  5. 物化与 Loaded 正交:loaded/unloaded 与 materialized/non-materialized 四种组合都可能出现——例如 EdenFS 重启并重新挂载含已物化 inode 的 checkout 时,物化 inode 也常常处于 unloaded 状态。

存储位置差异:物化文件存储在 overlay 中;非物化文件无需进 overlay,内容随时可从源控制仓库取回。ProjFS(Windows)挂载下还有一个特殊案例:被重命名的文件被视为物化 inode——技术上我们仍知道与之关联的源控制对象,但不再在 overlay 中保存该关联,因为 ProjFS 总是以原路径发起读请求,且读只由源控制对象服务。

以下两张图直观展示了非物化与物化两种状态下 inode 数据来源的差别(原图出自 Inodes.md 的 Inode Materialization 一节):

非物化 inode:仅保存 20 字节源控制对象 ID,内容按需从源控制仓库取回

物化 inode:源控制对象 ID 被移除,文件内容存储到 overlay

Populated(已填充)

"Populated" 描述的是内核已经观察到其内容、但文件尚未被修改的 inode/文件,且它与 materialized 状态有意保持独立(没有 populated 文件对应物化 inode,反之亦然):

  • ProjFS 挂载下:populated 文件指内容已存在于文件系统、读取将直接由 ProjFS 处理直至 EdenFS 使其失效;对文件而言大致等价于 "hydrated placeholder(已补水占位符)" 状态,对目录则大致等价于"无物化子项的占位符";
  • FUSE 与 NFS 挂载下:populated 指内核可能已将文件内容缓存在其缓存中,但 FUSE/NFS 也可能自行决定将其逐出缓存。

这一术语的意义在于描述内核缓存与 EdenFS 数据源之间的交互时机,是理解 Windows.md、Caching.md 等平台与缓存文档的前提。

变更记录类术语:Journal

Journal 是 EdenFS 用于记录近期修改性文件系统 I/O 操作的数据结构,它服务于 getFilesChangedSince() 这类 API,watchman 正是借助它告知客户端近期文件系统变化。

从源码看(Journal.h),Journal 的核心设计是:

  • 它只包含元数据,不是文件系统在某时刻的完整快照,设计意图是回答"时间 A 到时间 B 之间哪些文件变了"这类问题;
  • 它是线程安全的(folly::Synchronized/SharedMutex 内部同步),订阅者回调在调用 addDelta 的线程上被触发。

其记录接口覆盖了文件系统修改操作的完整分类(Journal.h):

接口 语义
recordCreated(path, type) 记录新建文件/目录
recordRemoved(path, type) 记录删除
recordChanged(path, type) 记录内容/元数据修改
recordRenamed(oldName, newName, type) 记录由 mv 产生的"新名被创建"
recordReplaced(oldName, newName, type) 记录由 mv 产生的"新名被旧名覆盖"
recordRootUpdate(fromRoot, toRoot) 记录根更新(如切换检出提交),可附带 recordUncleanPaths 记录脏路径集

变更事件的实际记录点在 inode 层触发,例如 InodeBase.cpp 中会调用 getMount()->getJournal().recordChanged(...)(见 InodeBase.cpp),EdenMount、TreeInode、CheckoutAction 中也有对应调用。而 getFilesChangedSince 则作为 Thrift 服务接口在 EdenServiceHandler.cpp 中实现,这印证了官方词条"用于实现 getFilesChangedSince(),进而被 watchman 使用"的描述。Journal 还记录了 fromRoot/toRoot 与序号(JournalDelta::SequenceNumber),配合 JournalTest.cpp 与 JournalBenchmark.cpp 可以看到该数据结构的正确性与性能行为如何被验证。

State Directory(状态目录)

状态目录是 EdenFS 存放全部本地状态的地方,其默认位置可通过配置控制:

  • 系统配置:/etc/eden/edenfs.rc;
  • 用户配置:$HOME/.edenrc;
  • 默认值:一般为 $HOME/.eden/,但在部分 Meta 环境中默认为 $HOME/local/.eden。

配置的加载与合并规则详见 Config.md:EdenFS 依次加载 /etc/eden/config.d/、/etc/eden/edenfs.rc、/etc/eden/edenfs_dynamic.rc,最后是 ~/.edenrc;相同 section 以最后加载者为准并整体替换。用户配置为 TOML 格式,例如:

# ~/.edenrc
[mount]
readdir-prefetch = "trees"

运行 edenfsctl fsconfig 可获得带注解的配置视图。状态目录内部则按职责分派:.eden/storage 存放 local store,.eden/clients/CHECKOUT_NAME/local 存放该 checkout 的 overlay。

术语关系速览:一张表理清全部状态

为便于快速查阅,将上述核心术语归纳如下:

术语 一句话定义 关键存储/实现位置
Repository 源控制提交/目录/文件数据的存储 eden/fs/model
Backing Repository EdenFS 取数所用的本地裸仓库 磁盘裸仓库,可被多 checkout 共享
Backing Store 从源控制取数的抽象 API BackingStore.h
Local Store 源控制数据的本地缓存 .eden/storage
Checkout 客户端工作目录状态(旧称 client/mount point) EdenMount 等
Overlay 物化数据存储,行为类似联合文件系统 .eden/clients/CHECKOUT_NAME/local
Inode 文件/目录在内核与 EdenFS 中的表示 FileInode / TreeInode / InodeBase
Loaded / Unloaded inode 状态是否在内存中 InodeMap 的 loadedInodes_ / unloadedInodes_
Materialized / Non-Materialized 是否知道可获取内容的源控制对象 ID 物化数据进 overlay
Populated 内核已观察内容但文件未修改 ProjFS/FUSE/NFS 缓存语义
Journal 近期修改性 I/O 操作记录,支撑 getFilesChangedSince Journal.h
State Directory 全部本地状态的根目录 默认 $HOME/.eden/

理解这套术语的核心诀窍是把握三对正交关系:repository 与 checkout(历史数据 vs 工作区状态)、loaded 与 materialized(内存有无状态 vs 能否从源控制取数)、materialized 与 modified(存储形态 vs 版本控制视角的改动)。InodeStorage.md 的 Metadata State Machine 与 Data State Machine 两节,正是基于这三对关系完整刻画了 inode 从"未知"到"加载→物化→反物化/卸载"的完整状态机。掌握这份术语表,无论是阅读 EdenFS 源码注释、调试 edenfsctl 输出,还是研读 Overview.md、Inodes.md 等深入文档,都会顺畅得多。

登录后查看全文
sapling