【RocksDB 内核机制】Checkpoint、Backup 与 External Ingest

第 14 篇 讲完单机事务边界。生产运维还依赖三类 不经过普通 Put 路径 的数据搬运：Checkpoint 做一致性快照目录、BackupEngine 做可验证的增量备份、SstFileWriter + IngestExternalFile 做离线 bulk load。Flink 增量 checkpoint 上传本地 不可变 SST，语义上贴近 Checkpoint 的硬链接思想（stream/12）。

本文是系列 第 15 篇，沿 Wiki Checkpoints、How to backup RocksDB、Creating and Ingesting SST files 与 utilities/checkpoint/、utilities/backup/ 说明机制与风险点。本篇 不 跑 BackupEngine 吞吐 benchmark；不伪造 checkpoint 耗时。

本文是「RocksDB 内核机制」系列第 15 篇（共 18 篇）。→ 系列目录

篇目	核心内容
第 14 篇 · 事务与 OCC	OptimisticTransactionDB
第 15 篇 · Checkpoint / Ingest	硬链接快照、Backup、SstFileWriter
第 16 篇 · 生产嵌入对照	Flink / TiKV

版本锚定：RocksDB 9.x（include/rocksdb/utilities/checkpoint.h、backup_engine.h、sst_file_writer.h）。Ingest DB-generated SST（9.5+ 实验、10.6+ 扩展）仅作版本边界提示，不展开。

一、三类接口的分工

三者都依赖 SST 不可变 与 MANIFEST 描述文件集（第 6 篇），但 一致性手段不同：Checkpoint 硬链接 + 复制元数据；Backup 在 Checkpoint 思路上加 共享存储与校验；Ingest 则 暂停前台写 以分配 global sequence number。

flowchart LR
  LIVE["运行中 DB"]
  LIVE --> CP["Checkpoint 目录"]
  LIVE --> BK["BackupEngine 仓库"]
  OFF["SstFileWriter 离线"]
  OFF --> ING["IngestExternalFile"]
  ING --> LIVE
  CP --> RO["只读打开 / 克隆"]
  BK --> RST["RestoreDBFromBackup"]

二、Checkpoint：硬链接快照

Wiki Checkpoints（A 级）：

• 在 指定新目录 创建运行 DB 的 一致快照；目录 须不存在，由 API 创建。
• 快照与源 DB 同文件系统 时，SST 硬链接；否则 复制 SST。
• MANIFEST、CURRENT、OPTIONS 等 复制（非硬链接）。
• 多 CF 时，复制 覆盖 checkpoint 起止时间段内的 WAL，以保证 跨 CF 一致（各 CF 共享 WAL，第 13 篇）。

#include "rocksdb/utilities/checkpoint.h"

Checkpoint* ckpt;
Checkpoint::Create(db, &ckpt);
Status s = ckpt->CreateCheckpoint("/data/db_checkpoint_20260707");
delete ckpt;

使用方式：

• 只读打开：查询时间点数据，不影响源 DB。
• 读写打开：SST 仍为硬链接；文件 obsolete 时解除链接——适合 同机克隆，不适合长期双写。

删除快照：直接删目录；不影响源 DB，除非仍共享 inode 的 SST 被一方 compaction 删除（硬链接 refcount 机制保证另一方仍可读）。

与 Flink：TaskManager 增量 checkpoint 上传 SST 文件 而非必须调用 Checkpoint::CreateCheckpoint API；内核依赖的是 flush 后 SST 不可变、MANIFEST 可描述文件集 同一原理。Flink 协调层在 stream/12 展开。

三、BackupEngine：Checkpoint 之上的备份仓库

Wiki How to backup RocksDB（A 级）：BackupEngine 管理 专用备份目录，格式 BackupEngine 私有，支持：

• 增量备份：share_table_files 下 SST 内容寻址共享（shared_checksum/ 等），新 backup 只复制 新 SST。
• 跨 FileSystem：本地 DB → 远程 HDFS/S3 抽象（backup_env）。
• VerifyBackup：比对文件大小；可选 checksum 全量读。
• RestoreDBFromBackup：按 backup ID 还原到目标 DB 目录。

CreateNewBackup 内部（Wiki Under the hood，A 级）：

1. DisableFileDeletions
2. 枚举 live files（SST + CURRENT + MANIFEST + OPTIONS）
3. 复制/链接到备份目录（SST 已存在则跳过）
4. 若 flush_before_backup=false，另复制 live WAL
5. EnableFileDeletions

目录结构（Wiki 示例）：meta/（backup 元数据）、private/（MANIFEST、OPTIONS、WAL）、shared_checksum/（带 checksum 文件名的 SST）。

注意：BackupEngine::Open 耗时与 已有 backup 数量 成正比；Wiki 建议 长生命周期 复用 engine 实例，并用 PurgeOldBackups(N) 控制规模。

四、SstFileWriter：离线生成 SST

Wiki Creating and Ingesting SST files（A 级）：

• SstFileWriter 用与目标 DB 相同的 Options/comparator（及 CF 级选项）建表。
• Key 严格递增（range tombstone 例外可乱序）。
• 生成文件内 key 的 sequence 为 0；ingest 时再赋 global sequence number（include/rocksdb/sst_file_writer.h）。

#include "rocksdb/sst_file_writer.h"

SstFileWriter writer(EnvOptions(), options, options.comparator);
Status s = writer.Open("/tmp/bulk1.sst");
s = writer.Put(key, value);  // keys strictly increasing
s = writer.Finish();

约束：

• Comparator 与目标 CF 完全一致（第 13 篇）。
• TableFactory、compression 等由传入 Options 决定，影响与线上 CF 格式兼容。

五、IngestExternalFile：进入 LSM 的步骤

DB::IngestExternalFile({paths}, IngestExternalFileOptions)（Wiki What happens when you ingest a file，A 级）：

1. 将文件 copy 或 link 进 DB 目录
2. 阻塞（block）前台写，以保证 sequence 分配与 DB 状态一致
3. 若文件 key range 与 memtable 重叠 → flush memtable
4. 选择 LSM 尽可能低的合法 level
5. 为文件内所有 key 分配 同一 global sequence number
6. 恢复前台写

选层条件（Wiki）：文件能放入该层；与 该层及以上 无 key 重叠；不与 进行中的 compaction 输出 重叠。

write_global_seqno（5.16+）：是否在 SST metablock 物理写入 global seqno；false 时由 MANIFEST 推导，利于 无随机写 文件系统或减少 sync。

ingest_behind=true（5.5+，Universal compaction）：在 最底层 ingest，重复 key 跳过 而非覆盖；要求 DB 自创建起 allow_ingest_behind=true。

多 CF：DB::IngestExternalFiles() all-or-nothing——任一 CF 失败则 全部不 ingest（Wiki，A 级）。

与 write stall 的关系

Ingest 的 block writes 是短期 写停顿；若需 flush memtable 则叠加 flush I/O。TiKV 等 bulk load 场景社区讨论过 allow_blocking_flush=false 时 ingest 可能 失败而非阻塞 flush（B 级工程文章，作运维线索，非 RocksDB 官方规范替代）。

六、Checkpoint vs Backup vs Ingest 对照

七、与 Column Family、MANIFEST 的交界

• Ingest 须指定 目标 ColumnFamilyHandle*；文件 key 范围只与 该 CF 的 LSM 比较重叠。
• 成功后 VersionEdit::AddFile 写入 global_seqno（第 6 篇 External ingest 行）。
• Checkpoint/Backup 捕获 全局 MANIFEST + 各 CF 文件列表；restore 后须 Open 时列出全部 CF。

八、工程注意点

1. 硬链接 checkpoint 与源 DB 共 SST；compaction 删除源侧文件时 refcount 递减——快照目录仍可用，但 磁盘空间 在两边都删除前不会释放。
2. Backup 还原 后应用 LoadLatestOptions 加载 OPTIONS；Wiki 注明 部分选项无法完全文本化，需人工补全。
3. Ingest 大文件 可能触发 memtable flush + 选层 compaction，计划维护窗口；与 第 11 篇 write stall 同类信号可在 LOG 中叠加出现。
4. Flink 增量 checkpoint 走 上传 SST + 元数据，restore 时重建本地 DB；与 BackupEngine restore 概念相近、实现不同（第 16 篇对照）。

九、小结

• Checkpoint 在同盘用 硬链接 SST + 复制 MANIFEST/WAL（多 CF） 做轻量时间点快照。
• BackupEngine 在 Checkpoint 流程上增加 增量共享、校验、跨 FS、Restore API。
• SstFileWriter 离线按 递增 key 建 SST；IngestExternalFile 阻塞写、flush 重叠 memtable、分配 global sequence 后挂入 LSM。
• 三者都是 生产嵌入（Flink、TiKV、MyRocks）运维工具链的一环；读 LOG 时需区分 ingest block 与 compaction stall。

下一篇 生产嵌入对照 把 Flink KeyGroup、TiKV key 编码与上述接口串成一张落地表。

上一篇：事务与 OptimisticTransactionDB

下一篇：生产嵌入对照

返回 系列目录

参考资料

1. RocksDB Wiki, Checkpoints（硬链接、MANIFEST/WAL 复制、多 CF WAL；A 级）。
2. RocksDB Wiki, How to backup RocksDB（BackupEngine API、目录结构、CreateNewBackup 步骤、flush_before_backup；A 级）。
3. RocksDB Wiki, Creating and Ingesting SST files（SstFileWriter、Ingest 步骤、global seqno、ingest_behind；A 级）。
4. RocksDB 9.x 源码：utilities/checkpoint/checkpoint_impl.*；utilities/backup/backup_engine.cc；include/rocksdb/utilities/checkpoint.h、backup_engine.h、sst_file_writer.h；db/db_impl/db_impl.cc（IngestExternalFile）（A 级）。
5. RocksDB 官方博客, Bulkloading by ingesting external SST files（2017；B 级背景）。
6. 第 6 篇 MANIFEST；第 13 篇 Column Family；stream/12 RocksDB State Backend。