[Feature] Support incremental backup and restore in hugegraph-tools

[imbajin]

Note

Task 核心目标：给 hugegraph-tools 支持图增量备份与恢复能力（保质保量, 设计实现优雅）

• 下描述和方案仅供参考, 有自己独立的思考和想法, 不确定的地方可以及时沟通

📌 1. 需求背景与目标 (Motivation & Goal)

目前 hugegraph-tools 的备份与恢复（backup / restore）走的是**通用逻辑图数据（Logical Backup）**路线：通过 REST API 分片扫描点边并序列化为 JSON 文本。这种方式通用性好（可跨异构存储迁移），但在单机 RocksDB（以及后续演进的 hstore）生产环境存在明显痛点：

1. 无法做增量备份：缺少系统级修改时间戳与变更日志流，无法识别增量变动；
2. 开销大、耗时长：大图场景下全量 Shard 扫描并经由 HTTP 传输大量 JSON，网络与磁盘 I/O 开销大；
3. 物理删除（DELETE）无法捕获：逻辑导出无法感知哪些点边已被删除，导致增量合并时无法重放删除操作，目标图残留脏数据。

本任务目标：

为 hugegraph-tools 增加基于底层存储物理快照能力的增量备份与恢复支持：

• Phase 1（本任务范围）：聚焦单机 RocksDB + Server 一体架构下的同一个图物理增量备份与精准恢复。
• Phase 2（后续规划）：后续再考虑拓展支持 hstore（Multi-Raft + RocksDB）分布式集群的增量物理备份。

---

🔍 2. 方案对比 (Before vs After)

比较维度	Before: 逻辑备份 (tools backup)	After: 物理增量备份 (snapshot-backup)
底层原理	REST API 分片扫描点边并序列化为 JSON	调用 Server 接口触发底层 RocksDB Checkpoint 硬链接
增量机制	不支持（Server 存储层硬编码禁止 Scan 下推条件过滤）	原生增量（仅同步增量产生的不可变 .sst 数据文件）
删除感知	完全无法感知 DELETE 操作	完美包含所有 DELETE（RocksDB 底层 Tombstone 原样保留）
生成耗时	线性依赖数据量（千万/亿级点边耗时数十分钟甚至数小时）	毫秒级 O(1) 完成（系统级 Hard Link，与图大小无关）
业务影响	长时间占用 Server CPU、磁盘 IO 和网络带宽	零写入阻塞，对在线业务读写几乎无影响
恢复速度	逐条调用 addVertices/addEdges 重新解析写入，慢	直接加载/软链接 SST 文件，秒级完成恢复

---

💡 3. 需求功能与命令预期 (Expected Features & CLI)

需要在 hugegraph-tools 提供（或扩展现有命令）物理快照级别的备份与恢复能力，建议提供类似如下命令及核心参数（具体命名与参数形态可结合 tools 规范调整）：

(1) 备份命令（例如 snapshot-backup）

• 核心参数：
  • --graph: 目标图名称
  • --directory, -d: 备份文件存放根目录
  • --mode, -m: 备份模式（如 full 强制全量 / incremental 增量，默认增量）
  • --keep-num: 可选，保留的历史快照版本份数
• 预期行为：
  • 触发快照生成，不阻塞线上业务写入；
  • 增量模式下，仅备份自上次备份以来发生变动/新增的物理文件与元数据，执行耗时短。

(2) 恢复命令（例如 snapshot-restore）

• 核心参数：
  • --graph: 目标图名称
  • --directory, -d: 备份根目录
  • --backup-id / --version: 可选，指定要恢复到的历史版本快照（默认最新一份）
• 预期行为：
  • 能将目标图的数据精准还原到对应备份点时刻的状态（包括新增、修改以及已删除的数据状态完全对齐）。

---

💡 4. 可供参考的实现方向 (Reference Direction)

开发者可自由设计具体的内部模块、目录结构与元信息组织格式，以下仅提供底层原理与服务端现成能力供参考：

• 核心原理：
  • RocksDB 底层数据由不可变（Immutable）的 .sst 文件组成，其原生的 Checkpoint 能力可以在毫秒级创建底层文件的系统硬链接（Hard Link），零锁写、零业务停机，且底层 Tombstone 天然记录了物理删除。
  • 增量备份通常只需识别并归档新产生的 .sst 文件及元数据，恢复时回溯完整的 SST 链条就位。
• 服务端现有快照 API：
  服务端目前已经内置了针对 RocksDB 的 Checkpoint 接口，可直接调用复用：
  • 创建快照：PUT /graphs/{name}/snapshot_create
  • 恢复快照：PUT /graphs/{name}/snapshot_resume

---

🧪 5. 验收标准 (Acceptance Criteria)

• 全量基线备份
  • 针对指定图能够生成首份物理快照基线
  • 备份过程不阻塞业务正常读写（零写入锁）
  • 备份目录正确产出快照物理文件与元数据清单记录
• 增量备份能力
  • 在图数据发生变更后执行备份，仅增量归档变动的物理文件
  • 备份耗时与数据传输量显著低于全量基线备份
  • 能够完整捕获包含新增、属性更新以及**物理删除（DELETE）**的操作
• 精准一致性恢复
  • 能够根据指定的备份版本将图数据精准还原到对应时间点
  • 恢复后图拓扑、点边属性与备份时刻 100% 对齐
  • 重点验证：在备份点前被物理删除的点和边，在恢复后确认不存在，无悬挂边与脏数据残留
• 自动化测试覆盖 (参考示例流程)
  • 基线测试：写入初始数据集（如 10,000 点 / 20,000 边），执行备份生成基线快照
  • 增量测试：追加新点、修改已有属性，并显式物理删除部分点和边（如删除 500 点），执行增量备份
  • 恢复校验：清空图或注入干扰数据后执行还原，断言点边总数与属性状态与快照时刻一致，断言已删除点边不可见

---

📚 6. 参考资料 (References)

• RocksDB 官方 Checkpoint 机制文档：
  • RocksDB Checkpoints Official Wiki
• HugeGraph-Server 现有源码参考：
  • 快照 REST 接口实现：GraphsAPI.java#L612-L640
  • RocksDB Checkpoint 底层调用：RocksDBStdSessions.java#L254-L256
• HugeGraph-Toolchain 现有源码参考：
  • Tools 现有命令行定义：SubCommands.java
  • Tools 备份恢复基础实现：BackupRestoreBaseManager.java