RocksDB Resumable Remote Compaction 详解:基于 Checkpoint 的可恢复远程压缩机制
RocksDB Resumable Remote Compaction 详解:基于 Checkpoint 的可恢复远程压缩机制
导读
RocksDB 通过 CompactionService API 将压缩(compaction)任务卸载到远程 worker,让主实例的 CPU 与 I/O 专注于读写服务;但远程压缩任务动辄处理上百 GB 输入,一旦 worker 崩溃、被抢占或超时,整次压缩必须从头重来,浪费全部已产出结果。Resumable Remote Compaction 引入"检查点 + 恢复"(checkpoint-and-resume)机制:worker 在压缩过程中定期把进度持久化到 output_directory,中断后再次调用 DB::OpenAndCompact() 即可从最后一个检查点续跑。读完本文你将掌握该特性的完整工作流程、核心 API 与配置方式、进度文件与 delta 编码原理、跳过检查点的安全边界,以及统计指标的使用方法。
Background:远程压缩的收益与痛点
RocksDB 的远程压缩(Remote Compaction)模型基于 CompactionService API:
- 主 RocksDB 实例(primary) 负责挑选输入文件,把序列化后的
CompactionServiceInput发送给 worker; - 远程 worker 运行
DB::OpenAndCompact()完成压缩,将输出的 SST 写入output_directory,再返回序列化的CompactionServiceResult; - 主实例 把返回的结果安装进自己的 LSM 树中。
这套架构让运维人员可以用无状态(stateless)worker 横向扩展压缩吞吐,同时把主实例的 CPU 与 I/O 留给读写路径。相关类型与函数在 include/rocksdb/db.h 与 include/rocksdb/options.h 中均有完整声明。
但远程压缩任务可能运行很长时间(有时处理数百 GB 输入)。当 worker 崩溃、被抢占或超时时,整个压缩必须从头重启,之前产出的所有输出全部作废,并让主实例背上不断累积的压缩债务(compaction debt)。这正是 Resumable Remote Compaction 要解决的问题。
Resumable Remote Compaction 的工作原理
Resumable Remote Compaction 引入了检查点与恢复机制:
- 压缩过程中,worker 周期性地把进度保存到
output_directory; - 如果压缩被中断,后续以相同输出目录再次调用
OpenAndCompact(),即可从最后一个检查点继续,而不是从头开始。
检查点(Checkpointing)
每完成一个输出 SST 文件后,worker 就会向输出目录 output_directory 中的**压缩进度文件(compaction progress file)**持久化一个进度检查点,记录:
- 恢复时需要从哪个 internal key 继续;
- 所有已完成输出文件的元数据。
进度记录采用 delta 编码(delta encoding)——每条记录只包含自上一个检查点以来新完成的文件,从而保证序列化开销随进度线性增长,而不是随整个任务累计增长。
该进度文件是 RocksDB 中一类全新的文件类型:在 include/rocksdb/types.h 的 FileType 枚举中新增了 kCompactionProgressFile;在 file/filename.cc 中定义了 CompactionProgressFileName() 与 TempCompactionProgressFileName(),进度文件以 COMPACTION_PROGRESS- 前缀 + 时间戳命名(临时文件额外带 .tmp 后缀),先写临时文件、再原子改名,与 RocksDB 其他文件类型保持一致的文件管理规范。
worker 会在以下两类边界跳过检查点,因为在这些位置恢复可能不安全或需要复杂的特殊处理:
- 当 range deletions(范围删除)跨文件边界时;
- 当相邻输出文件共享同一个 user key 时。
这些约束保证了恢复后的结果与从未中断的压缩完全一致。
恢复(Resuming)
当以 allow_resumption = true 调用 OpenAndCompact() 时,系统会:
- 扫描输出目录,查找有效的进度文件;
- 若找到,加载检查点状态,将输入迭代器 seek 到记录的恢复 key,并恢复输出文件状态;
- 从该位置继续压缩;
- 若进度文件损坏或缺失,则清理目录后回退到全新压缩(fresh compaction)。
如何启用
主实例与 worker 两侧的配置
在主 RocksDB 实例上,为 DB options 设置一个 CompactionService 实现;在远程 worker 上,调用 DB::OpenAndCompact() 时在 OpenAndCompactOptions 中传入 allow_resumption = true。
关键前提:
output_directory在每次重试之间必须保持一致,恢复才能生效——每次使用相同目录的重试调用会自动检测并续跑之前的检查点;REMOTE_COMPACT_RESUMED_BYTES统计指标(ticker)记录"从上次中断运行中复用(resume)的输出文件总字节数",用于直观衡量恢复节省了多少工作量。
代码示例
// Primary RocksDB instance
DBOptions db_options;
db_options.compaction_service = std::make_shared<MyCompactionService>();
// Remote worker
OpenAndCompactOptions options;
options.allow_resumption = true;
std::string result;
Status s = DB::OpenAndCompact(
options,
db_path, // source database path
output_directory, // where output SSTs and progress are stored
compaction_input, // serialized CompactionServiceInput
&result, // serialized CompactionServiceResult
override_options);
OpenAndCompactOptions 完整字段语义
在 include/rocksdb/options.h 中,OpenAndCompactOptions 除 allow_resumption 外还包含以下字段(从源码可确认其完整语义):
canceled(std::atomic<bool>*,默认nullptr):允许取消进行中的压缩;max_secondary_open_retries(uint32_t,默认2):打开源 DB 作为 secondary 失败(因 CURRENT/MANIFEST 被并发替换)时的最大重试次数,为 0 则禁用重试;allow_resumption(bool,默认false):是否尝试从先前持久化的压缩进度恢复。
关于 allow_resumption 的详细行为,源码注释给出了比博客更精确的约定:
true时:尝试从output_directory中持久化的进度恢复;执行期间会周期性地把新进度持久化到同一目录,供后续调用续跑。如果恢复无法满足(例如恢复状态损坏或缺失),系统会尽力回退到全新压缩——先清理output_directory中的相关文件以获得干净状态;若连全新压缩都无法启动,则返回非 OK 状态。需要注意:若导致上一次OpenAndCompact()失败的根因仍然存在,恢复尝试同样会无效,大概率仍返回同样的非 OK 状态。进度持久化是串行且尽力而为(best-effort)的,在每个新输出文件完成时触发;若压缩在创建某个输出文件的中途被打断,该部分工作需要在恢复时重做。false时:从头开始全新压缩,执行期间不保存任何进度,中断后必须完全重来。关键要求:调用前output_directory必须为空,任何残留文件(包括上次运行的恢复状态或输出文件)都可能造成正确性错误。- 已知限制:目前与
paranoid_file_checks=true不兼容,启用该选项时此特性实际上被禁用。
另外,DB::OpenAndCompact() 的重载签名(include/rocksdb/db.h)还说明:output_directory 在 DBOptions::use_session_tmp_dir_for_remote_compaction 为 true 时必须是单层目录名,实际路径为 <name>/session_tmp/<output_directory>,否则为 <name>/<output_directory>。
统计指标
REMOTE_COMPACT_RESUMED_BYTES 在 include/rocksdb/statistics.h 的 TickerType 枚举中定义,其 C++ 端实现位于 monitoring/statistics.cc,Java 绑定位于 java/src/main/java/org/rocksdb/TickerType.java 与 java/rocksjni/portal.h。通过该指标,运维人员可以量化每次恢复实际复用了多少输出字节,从而评估重试是否真正"省下了活"。
测试与验证依据
仓库中的 db/compaction/compaction_service_test.cc 覆盖了该特性的关键场景:
- 多处测试以
allow_resumption = true配置OpenAndCompactOptions(如 L2601、L3312、L3354、L3357),验证恢复路径的正常执行; - 测试通过
statistics->getTickerCount(REMOTE_COMPACT_RESUMED_BYTES)(L3533、L3619)断言恢复后复用的字节数,直接印证了"复用输出文件"这一行为的正确性。
Future Work:从远程压缩走向本地压缩
目前该特性只针对远程压缩场景,但同一套 checkpoint-and-resume 机制未来也可支持本地压缩在崩溃后的恢复。核心的持久化与恢复逻辑已经落在 CompactionJob(见 db/compaction/compaction_job.cc 与 db/compaction/subcompaction_state.h,恢复状态在 db/compaction/compaction_service_job.cc 中用于远程任务编排)中,剩余工作主要是将其与本地压缩调度(scheduling)和崩溃恢复(recovery)流程集成。
总结
Resumable Remote Compaction 通过检查点文件 + delta 编码把远程压缩从"全有或全无"变成"可续跑",显著缓解了长任务中断时的算力浪费与主实例压缩债务问题。使用时的三条关键经验:
- 重试时保持
output_directory一致,否则无法续跑; - 不开恢复时务必保证输出目录为空,避免正确性错误;
- 通过
REMOTE_COMPACT_RESUMED_BYTES观察实际复用的输出量,验证恢复是否真正生效。
该特性当前标记为 EXPERIMENTAL,且与 paranoid_file_checks=true 不兼容,生产使用前请结合仓库中的源码注释与测试用例充分验证。