RocksDB Resumable Remote Compaction 详解:基于 Checkpoint 的可恢复远程压缩机制

原创2026-09-18 19:21:251,901 阅读
文章标签:数据库KV存储嵌入式数据库存储高性能计算

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 引入了检查点与恢复机制:

  1. 压缩过程中,worker 周期性地把进度保存到 output_directory;
  2. 如果压缩被中断,后续以相同输出目录再次调用 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() 时,系统会:

  1. 扫描输出目录,查找有效的进度文件;
  2. 若找到,加载检查点状态,将输入迭代器 seek 到记录的恢复 key,并恢复输出文件状态;
  3. 从该位置继续压缩;
  4. 若进度文件损坏或缺失,则清理目录后回退到全新压缩(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 编码把远程压缩从"全有或全无"变成"可续跑",显著缓解了长任务中断时的算力浪费与主实例压缩债务问题。使用时的三条关键经验:

  1. 重试时保持 output_directory 一致,否则无法续跑;
  2. 不开恢复时务必保证输出目录为空,避免正确性错误;
  3. 通过 REMOTE_COMPACT_RESUMED_BYTES 观察实际复用的输出量,验证恢复是否真正生效。

该特性当前标记为 EXPERIMENTAL,且与 paranoid_file_checks=true 不兼容,生产使用前请结合仓库中的源码注释与测试用例充分验证。

登录后查看全文
rocksdb