imbajin opened a new issue, #770: URL: https://github.com/apache/hugegraph-toolchain/issues/770
### Search before asking - [x] I had searched in the [feature](https://github.com/apache/hugegraph-toolchain/issues?q=is%3Aissue+label%3A%22Feature%22) and found no similar feature requirement. ### Feature Description (功能描述) ## 📌 1. 任务背景与目标 (Goal & Motivation) 目前 `hugegraph-tools` 的备份与恢复（`backup` / `restore`）走的是**通用逻辑图数据（Logical Backup）**路线：通过 REST API 分片扫描点边并序列化为 JSON 文本。这种方式通用性好（可跨异构存储迁移），但对于主流的单机 RocksDB（以及后续演进的 hstore）生产环境，存在显著瓶颈： 1. **无法做增量备份**：缺少系统级修改时间戳与变更日志流，无法识别增量变动； 2. **开销大、耗时长**：大图场景下全量 Shard 扫描并经由 HTTP 传输大量 JSON，网络与磁盘 I/O 极高； 3. **物理删除（DELETE）无法捕获**：逻辑导出无法感知哪些点边已被删除，导致增量合并时无法重放删除操作，目标图残留脏数据。 ### 本任务目标： 利用 LSM-Tree 的 **不可变 SST 文件（Immutable SST）** 与 **RocksDB Checkpoint（秒级硬链接快照）** 原生能力，为 `hugegraph-tools` 打造生产级**物理增量备份与恢复（Physical Incremental Backup & Restore）**能力。 > **阶段规划说明**： > - **Phase 1（本任务范围）**：聚焦**单机 RocksDB + Server 一体**架构下的**同一个图**物理增量备份与精准恢复。 > - **Phase 2（后续规划）**：进一步联动 PD 协调器，扩展支持 **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. 核心设计与执行时序 (Architecture & Flow) ```mermaid sequenceDiagram autonumber actor Admin as 管理员 / 定时调度任务 participant Tools as hugegraph-tools participant Client as hugegraph-client participant Server as hugegraph-server participant RocksDB as RocksDB 引擎 participant Storage as 备份归档目录 rect rgb(240, 248, 255) Note over Admin, Storage: 增量备份阶段 (Incremental Backup) Admin->>Tools: 执行 snapshot-backup --graph g -d /backup Tools->>Client: client.graphs().createSnapshot("g") Client->>Server: PUT /graphs/{name}/snapshot_create Server->>RocksDB: sessions.createSnapshot() -> Checkpoint.create() RocksDB-->>Server: 秒级生成快照目录 (SST 硬链接) Server-->>Tools: 返回快照创建成功与路径 Tools->>Tools: 对比上次备份元数据 (Manifest)，找出新增/变更的 .sst 文件 Tools->>Storage: 仅增量拷贝新增 .sst 文件 + 写入新的备份元数据 (metadata.json) Tools->>Server: 清理临时 Checkpoint 目录 Tools-->>Admin: 增量备份完成 (耗时秒级，仅传输增量数据) end rect rgb(255, 245, 245) Note over Admin, Storage: 恢复阶段 (Restore) Admin->>Tools: 执行 snapshot-restore --graph g -d /backup --backup-id <id> Tools->>Storage: 根据 backup-id 回溯基线与增量 SST 链条 Tools->>Server: 停止图服务 或 设置维护模式 Tools->>Server: 将对应版本的 SST 集合恢复至 Server 数据目录 Tools->>Client: client.graphs().resumeSnapshot("g") 或 重启服务 Tools-->>Admin: 精准恢复到指定时间点状态 (包含新增/修改/删除) end ``` --- ## 🛠️ 4. 详细开发拆解与实现步骤 (Implementation Steps) ### Step 1: `hugegraph-client` 补全快照管理 API 在 `hugegraph-client` 的 `GraphsManager` 中封装快照 REST 请求（目前 Server 端已具备该接口）： - `createSnapshot(String graph)`: 对应调用 `PUT /graphs/{name}/snapshot_create` - `resumeSnapshot(String graph)`: 对应调用 `PUT /graphs/{name}/snapshot_resume` > **服务端已有实现参考**： > - REST API 端点：[`GraphsAPI.java#L612-L640`](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java#L612-L640) > - RocksDB Checkpoint 调用：[`RocksDBStdSessions.java#L254-L256`](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-rocksdb/src/main/java/org/apache/hugegraph/backend/store/rocksdb/RocksDBStdSessions.java#L254-L256) ### Step 2: `hugegraph-tools` 新增命令行参数定义 在 [`SubCommands.java`](https://github.com/apache/hugegraph-toolchain/blob/master/hugegraph-tools/src/main/java/org/apache/hugegraph/cmd/SubCommands.java) 中新增快照备份与恢复命令参数： - `snapshot-backup`: - `--directory, -d`: 备份文件存放根目录（必填） - `--mode, -m`: 备份模式，支持 `full`（强制全量）或 `incremental`（增量，默认） - `--keep-num`: 保留的历史快照版本数量（默认 7 份） - `snapshot-restore`: - `--directory, -d`: 备份根目录（必填） - `--backup-id`: 指定要恢复的历史快照版本 ID（不传则恢复最新一份） ### Step 3: 实现快照与增量文件管理器 (`SnapshotManager`) 新建 `org.apache.hugegraph.manager.SnapshotManager`： 1. **元数据管理 (`metadata.json`)**： 记录每次备份的快照清单： ```json { "backup_id": "backup_20260911_180000", "timestamp": 1789120800000, "graph": "hugegraph", "base_backup_id": "backup_20260911_120000", "files": [ {"name": "000124.sst", "size": 1048576, "checksum": "a1b2c3..."}, {"name": "000125.sst", "size": 2097152, "checksum": "d4e5f6..."} ] } ``` 2. **增量判定逻辑**： - 比较当前 Checkpoint 目录与上一版 `metadata.json`： - 若 `.sst` 文件名、大小一致，直接复用上一版硬链接/引用记录； - 若出现新产生的 `.sst` 文件、`CURRENT`、`MANIFEST` 等元数据文件，则执行物理归档复制。 ### Step 4: 恢复重组机制 1. 根据目标 `backup_id` 依赖链追溯所有必需的 SST 集合； 2. 将完整文件集合还原到目标图的数据目录中； 3. 调用服务端的 `snapshot_resume` 或重启校验数据完整性。 --- ## 🧪 5. 验收标准与测试用例 (Acceptance Criteria) ### 场景验证（在同一个图上执行）： 1. **测试用例 1：全量基线备份** - 初始化图并写入 10,000 个点、20,000 条边。 - 执行 `hugegraph snapshot-backup -d /backup/hugegraph`。 - **验收**：生成首份全量快照，耗时在秒级，校验备份元数据完整。 2. **测试用例 2：包含 C/U/D 的增量备份** - 继续写入 2,000 个新增顶点；修改 500 个顶点的属性；**删除 1,000 个既有顶点和关联边**。 - 执行 `hugegraph snapshot-backup -d /backup/hugegraph`。 - **验收**：成功生成增量快照，耗时极短（仅为复制少量新增 SST 文件的时间），检查归档目录，未产生重复历史 SST 数据。 3. **测试用例 3：精准灾备恢复验证** - 模拟数据损坏或误操作（执行清空图 `graph-clear`）。 - 执行 `hugegraph snapshot-restore -d /backup/hugegraph` 恢复最新增量快照。 - **验收**： - 恢复后顶点数与边数与备份前**完全一致**（包含正确的属性修改）； - **重点验证**：在测试用例 2 中被删除的 1,000 个点和边**在恢复后确定不存在**，无任何孤儿悬挂边与脏数据残留。 --- ## 🚀 6. 演进前瞻 (Phase 2 Preview) 单机版本完成后，后续可进一步向 **分布式 hstore（Multi-Raft + RocksDB）** 演进： - 由 HugeGraph-PD 担任中央协调器下发打快照指令； - 避免 3 副本数据膨胀，只针对各 Partition 的 Leader 节点收集 SST 增量文件； - 结合 PD 元数据快照，实现分布式集群级的物理增量备份。 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
