Pageserver Layer 文件完整分析

一、Layer 文件类型

1. 按内容分类

2. 按 Key 范围分类（L0 vs L1）

// pageserver/src/tenant/layer_map.rs:793 pub fn is_l0(key_range: &Range<Key>, is_delta_layer: bool) -> bool { is_delta_layer && key_range == &(Key::MIN..Key::MAX) }

Key 结构（18 字节）：
spcnode(4) + dbnode(4) + relnode(4) + forknum(1) + segno(5) = 18 bytes

二、Layer 的生命周期状态

状态机

┌─────────────────────────────────────────────────────────────────────────────┐ │ Layer 状态转换 │ │ │ │ ┌──────────┐ WAL 写入 ┌──────────┐ 冻结 ┌──────────┐ │ │ │ Open │───────────────>│ InMemory │───────────>│ Frozen │ │ │ │ (活跃) │ │ (内存) │ │ (只读) │ │ │ └──────────┘ └──────────┘ └────┬─────┘ │ │ ▲ _FLUSH │ │ │ │ │ │ │ │ ┌──────────┐ ▼ │ │ │ │ OnDisk │<──────────────────┐ │ │ │ │ (本地) │ │ │ │ │ └────┬─────┘ │ │ │ │ ┌─────────────────┘ │ │ │ │ │ 上传完成 │ │ │ │ ▼ │ │ │ │ ┌──────────┐ │ │ │ │ │ Resident │<──────────────────────────────┘ │ │ │ │ (驻留) │ 读取时保持 │ │ │ └────┬─────┘ │ │ │ │ 驱逐（磁盘压力） │ │ │ ▼ │ │ │ ┌──────────┐ │ │ │ │ Evicted │── 按需下载 ──>Resident │ │ │ │ (已驱逐) │ │ │ │ └──────────┘ │ │ │ │ │ │ GC 删除 │ │ └──────>已删除 │ │ │ └─────────────────────────────────────────────────────────────────────────────┘

状态说明

三、Layer 文件在磁盘上的组织

目录结构

.neon/ └── tenants/ └── <tenant_id>/ └── timelines/ └── <timeline_id>/ ├── 00000001...Image_0000000160 # Image Layer ├── 00000001...Delta_0000000150-0000000160 # L1 Delta Layer ├── 00000001...Delta_0000000160-0000000170 # L1 Delta Layer ├── 00000000...Delta_0000000170-0000000180 # L0 Delta（全 key 范围） ├── 00000000...Delta_0000000180-0000000190 # L0 Delta（全 key 范围） └── ...

文件命名解析

Image Layer

Image Layer: ┌─────────────────────────────────────────────────────────────────────┐ │ 000000067F000032BE0000400000000070B6-000000067F000032BE0000400000000080B6__00000000346BC568 │ │ └───────────────────────┬───────────────────────┘ └────────────────┘ │ │ │ │ │ Key 范围 │ LSN │ │ (部分范围) │ │ └─────────────────────────────────────────────────────────────────────┘

Delta Layer

Delta Layer: ┌─────────────────────────────────────────────────────────────────────────────────────┐ │ 000000067F000032BE0000400000000020B6-000000067F000032BE0000400000000030B6__000000578C6B29-0000000057A50051 │ │ └───────────────────────┬───────────────────────┘ └──────────────────┬──────────────────┘ │ │ │ │ │ │ Key 范围 │ LSN 范围 │ │ │ (全量=L0, 部分=L1) │ │ │ └─────────────────────────────────────────────────────────────────────────────────────┘

四、Layer 的读取流程

GetPage@LSN 请求处理

// pageserver/src/tenant/storage_layer/layer.rs pub(crate) async fn get_or_maybe_download(&self) -> Result<ResidentLayer, ...> { // 1. 检查是否已驻留 // 2. 如果已驱逐，从 S3 下载 // 3. 返回 ResidentLayer 保护对象 }

读取路径

GetPage@LSN(key, lsn) 请求 │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 1. 检查 InMemory Layer（最快） │ │ ·如果命中 →直接返回 │ │ ·如果未命中 →继续 │ └───────────────────┬─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 2. 遍历 LayerMap（从新到旧） │ │ ·查找包含 (key, lsn) 的 Layer │ │ ·优先查找 Image Layer（终止点） │ │ ·收集 Delta Layer 中的 WAL 记录 │ └───────────────────┬─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 3. 检查 Layer 是否驻留 │ │ ·如果 Resident →直接读取 │ │ ·如果 Evicted →从 S3 下载（on-demand） │ └───────────────────┬─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 4. WAL Redo（页面重建） │ │ ·从 Image Layer 获取基础页面 │ │ ·按 LSN 顺序重放 Delta Layer 中的 WAL 记录 │ │ ·返回重建后的页面 │ └─────────────────────────────────────────────────────────────┘

五、Layer 的压缩（Compaction）

L0 → L1 压缩

压缩前（多个 L0 Delta）: ┌─────────────────────────────────────────────────────────────┐ │ L0-1: key=全量, lsn=100-110 (4MB) │ │ L0-2: key=全量, lsn=110-120 (4MB) │ │ L0-3: key=全量, lsn=120-130 (4MB) │ └─────────────────────────────────────────────────────────────┘ │ │ Compaction ▼ 压缩后（L1 Delta + Image）: ┌─────────────────────────────────────────────────────────────┐ │ Image: key=A-B, lsn=130 (32MB, 完整快照) │ │ Image: key=C-D, lsn=130 (32MB, 完整快照) │ │ L1-1: key=A-B, lsn=100-130 (8MB, 合并后增量) │ │ L1-2: key=C-D, lsn=100-130 (8MB, 合并后增量) │ └─────────────────────────────────────────────────────────────┘

关键参数

• compaction_threshold: L0 层数量阈值（默认 10）
• compaction_target_size: 单个 L1 层的目标大小（默认 128MB）
• image_creation_threshold: Image Layer 生成阈值（默认 3）

六、Layer 的驱逐（Eviction）

驱逐条件

// pageserver/src/disk_usage_eviction_task.rs // 驱逐策略：LRU + 热度感知 fn select_eviction_candidate( candidates: &[Layer], heat_scores: &HashMap<LayerName, f32>, min_resident_size: u64, ) -> Option<Layer> { // 1. 排除必须保留的层（热度 ≥0.7 且在最小保留内） // 2. 优先驱逐热度最低且久未访问的层 }

驱逐流程

磁盘使用率 > 阈值（如 80%） │ ▼ ┌─────────────────────────────────────────────────────┐ │ 1. 选择待驱逐层（LRU + 热度） │ │ ·热度低（heat_score < 0.3） │ │ ·久未访问 │ │ ·非 Image Layer（Image 层更稳定） │ └────────────────────────┬────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ 2. 删除本地文件，标记为 Evicted │ │ ·文件从本地磁盘删除 │ │ ·S3 中仍有备份 │ │ ·LayerMap 中仍保留元数据 │ └────────────────────────┬────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ 3. 释放磁盘空间 │ │ ·resident_physical_size 减少 │ │ ·检查是否需要继续驱逐 │ └─────────────────────────────────────────────────────┘

七、Layer 的垃圾回收（GC）

GC 条件

// GC 可删除层的条件： // 1. 层的所有 LSN < GC horizon（默认 64MB WAL） // 2. 有更新的 Image Layer 覆盖该层 // 3. 没有分支需要该层（分支创建点之后）

GC 流程

当前状态： LSN: 0 ───── 100 ───── 200 ───── 300 ───── 400 [Image] [Delta] [Delta] [InMemory] GC Horizon = 400 - 150 = 250 可删除的层： ✅ Image(LSN=100) →被 Delta(LSN=100-200) + Delta(LSN=200-300) 覆盖 ✅ Delta(LSN=0-100) →早于 GC Horizon ❌ Delta(LSN=200-300) →包含 GC Horizon 后的数据 ❌ Delta(LSN=300-400) →包含 GC Horizon 后的数据 ❌ InMemory →活跃数据，不能删除

八、总结：Layer 文件全景图

┌─────────────────────────────────────────────────────────────────────────────┐ │ Pageserver Layer 全景 │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 内存层（InMemory） │ │ │ │ ·Open: 接受 WAL 写入 │ │ │ │ ·Frozen: 只读，等待 flush │ │ │ └─────────────────────────┬───────────────────────────────────────────┘ │ │ │ flush │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 本地磁盘层（OnDisk） │ │ │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ L0 Delta │ │ L1 Delta │ │ Image Layer │ │ │ │ │ │ (全 key 范围) │ │ (部分 key) │ │ (单 LSN) │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ·新冻结的层 │ │ ·compaction │ │ ·快照 │ │ │ │ │ │ ·churn 快 │ │ 生成 │ │ ·终止点 │ │ │ │ │ │ ·窄 LSN 范围 │ │ ·宽 LSN 范围 │ │ ·部分 key │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ │ 状态：Resident（驻留） / Evicted（已驱逐） │ │ │ └─────────────────────────┬───────────────────────────────────────────┘ │ │ │ upload │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 对象存储（S3） │ │ │ │ ·所有层的最终持久化存储 │ │ │ │ ·不可变文件，创建后不修改 │ │ │ │ ·本地驱逐后，按需下载 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ LayerMap（层映射） │ │ │ │ ·记录所有层的元数据（key 范围、LSN 范围、文件大小） │ │ │ │ ·按 (key, lsn) 索引，支持快速查找 │ │ │ │ ·不存储层文件内容，仅存储索引 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘

关键指标

这个分析覆盖了 Layer 文件的类型、状态、命名、读取、压缩、驱逐和 GC 的完整机制。