Aptos 节点存储体系深度解析：AptosDB 架构、Storage 配置与备份恢复实战-平芜编程栈

Aptos 节点存储体系深度解析：AptosDB 架构、Storage 配置与备份恢复实战

【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core

Aptos 是一个面向大规模区块链应用的一层（Layer 1）区块链，其节点内部的存储层（storage/模块）承担着认证区块链数据结构（Authenticated Blockchain Data Structure）的持久化、历史数据修剪与备份恢复等关键职责。本文以 storage/README.md 为骨架，结合仓库内的 storage_config.rs、备份 CLI 实现等源码，系统讲解 AptosDB 的组件构成、完整的storage配置项（含默认值与语义）、内部索引器（Internal Indexer）以及备份/恢复工具链，帮助你掌握节点存储的调优、排障与灾备实操能力。

存储层在 Aptos 节点中的角色

Aptos 节点的存储模块（位于 storage/）实现了两个核心子系统：

AptosDB：节点内保存认证区块链数据结构的数据存储。它同时服务于两类读取方——
- Move 合约执行：为正在执行的交易提供当前 "状态"（state）的读取；
- 其他 Aptos 节点与 Rest API：提供可配置长度的区块链历史数据。
AptosDB 的新数据来自共识（consensus）或状态同步（state sync）组件，二者持续将新数据写入，从而不断增长区块链历史。
备份系统（backup）：将交易的完整历史持久化到备份存储。正常运行时备份并非必需，但在以下紧急场景中至关重要：
- 无法依赖广泛可用的健康节点来重建 AptosDB 时（如灾难恢复）；
- 需要回溯恢复某个历史状态（recover a historical state back in time）；
- 为了克服不可预见的灾难性情况而创建替代账本并重新分发结果（即硬分叉 hard fork）时。

从模块划分上看，storage/目录还包含 jellyfish-merkle/（状态认证树 JMT 的实现）、schemadb/（RocksDB schema 封装）、scratchpad/（执行期内存缓存）、accumulator/（交易哈希累加器）、indexer/ 与 indexer_schemas/（内部索引）、db-tool/（数据库工具）、backup/（备份/恢复 CLI 与备份服务）以及 storage-interface/（对外接口）。注意整个 "Execution"（执行）模块位于本目录之外（见 execution/），但两者高度耦合——执行产生的写入集与状态树最终都落入 AptosDB。

系统架构

下图展示了存储相关组件在节点中的堆叠关系（原图位于 storage/storage_and_execution_components.png）：

从图中可以直观看到：最底层是 AptosDB 所依赖的多个 RocksDB 实例（Ledger DB、State Merkle DB、State KV DB、Index DB 等），向上是存储接口层（AptosDB统一暴露读写 API），再向上分别通向 Move 执行引擎（VM/Executor）、状态同步（State Sync）与备份服务（Backup Service）；Rest API 与备份 CLI 工具则通过各自的服务端口访问存储层。这种分层设计把认证数据结构的持久化与交易执行解耦，让状态认证结构可以在执行关键路径之外异步批量落盘。

Storage 配置详解

作为 Aptos 节点配置（NodeConfig）的一部分，storage段专用于存储组件。使用默认配置时无需在配置文件中写入任何内容——只有当需要覆盖某个默认值时，才需要显式配置。这也意味着：除非确有原因，否则不建议覆盖默认值，因为 Aptos 开发者会随新版本软件发布而调整默认配置，本地覆盖会让节点错过这些调优。

完整的storage配置块如下（来自 storage/README.md，注释为原文所附）：

storage: # 备份服务监听地址。默认仅对 localhost 开放端口， # 因此备份 CLI 工具只能访问同一主机上的数据。 backup_service_address: "127.0.0.1:6186" # `base` 段中 `data_dir` 配置下的子目录，用于存放 RocksDB 实例。 # 例如顶层配置为： # base: # data_dir: /opt/aptos/data # 且本项取默认值（db），则数据库位于 # /opt/aptos/data/db/ledger_db 和 /opt/aptos/data/db/state_merkle_db dir: db # AptosDB 在交易执行关键路径之外持久化状态认证结构，并批量缓存近期变更。 # 一旦缓冲的状态更新数超过该值，就触发将所有缓冲值转储为快照。 # （此外，如果自上次转储以来处理了过多交易，也会触发新的转储。） buffered_state_target_items: 100000 # 决定 JMT 节点 LRU 缓存的最大内存占用。缓存越大性能越好， # 但会消耗大量内存，并可能与文件系统缓存竞争。 max_num_nodes_per_lru_cache_shard: 8192 # AptosDB 保留近期区块链账本历史与近期版本的状态树。 # 修剪器（pruner）负责修剪旧数据，默认值确保网络在数据可用性方面保持健康， # 且不会在推荐硬件规格上占用过多空间。 storage_pruner_config: # 账本修剪器。账本数据包括交易、交易输出（含事件、写入集） # 以及相关认证数据结构。值得注意的是：状态键值（state key values） # 属于账本的一部分，而状态认证结构（状态树）由另一个修剪器单独修剪。 ledger_pruner_config: enable: true prune_window: 150000000 batch_size: 500 user_pruning_window_offset: 200000 # 纪元内（inner-epoch）状态树修剪器。若某个状态树节点在同一纪元内 # 被后续交易覆盖，则由该修剪器按这些配置稍后修剪。 state_merkle_pruner_config: enable: true prune_window: 100000 batch_size: 1000 # 纪元间（inter-epoch）状态树修剪器。若某个状态树节点被后续 # 处于更晚纪元的交易覆盖，则由该修剪器按这些配置稍后修剪。 # prune_window 看起来很大（单位为交易数），但在树的每个位置， # 该修剪器只会保留（或修剪）该位置在同一纪元内所有更新中的最后一个节点。 # 实际上，这些配置保证了每个近期纪元结束时的完整状态树（"epoch 快照"） # 可供对等节点访问，这对链的健康至关重要。 epoch_snapshot_pruner_config: enable: true prune_window: 80000000 batch_size: 1000 # 针对存储组件所控制的每个 RocksDB 实例的可调性能参数。 # 除非熟悉 RocksDB 性能调优，否则不应改动。 rocksdb_configs: ledger_db_config: max_open_files: 5000 max_total_wal_size: 1073741824 max_background_jobs: 16 block_cache_size: 8388608 block_size: 4096 cache_index_and_filter_blocks: false state_merkle_db_config: max_open_files: 5000 max_total_wal_size: 1073741824 max_background_jobs: 16 block_cache_size: 8388608 block_size: 4096 cache_index_and_filter_blocks: false index_db_config: max_open_files: 1000 max_total_wal_size: 1073741824 max_background_jobs: 16 block_cache_size: 8388608 block_size: 4096 cache_index_and_filter_blocks: false

配置项语义与源码对应

上述配置在源码中的对应结构为 config/src/config/storage_config.rs 中的StorageConfig、PrunerConfig、RocksdbConfigs与RocksdbConfig。下面结合源码注释与默认实现，逐类说明其核心影响：

backup_service_address：备份服务监听地址，默认127.0.0.1:6186（见StorageConfig::default()，storage_config.rs）。仅绑定 localhost 意味着备份 CLI 只能访问本机数据，增强了安全性。另有backup_service_runtime_threads（默认 2）控制备份服务的运行时线程数。
dir：RocksDB 实例所在目录（相对于顶层base.data_dir），默认"db"。若dir为相对路径，源码会通过data_dir.join(&self.dir)解析（StorageConfig::dir()）；存储分片（sharding）开启后，实际目录还包括ledger_db、state_merkle_db、state_kv_db、index_db等细分目录。源码中默认enable_storage_sharding: true。
buffered_state_target_items：状态认证结构缓冲转储阈值，默认100_000（常量BUFFERED_STATE_TARGET_ITEMS，测试用值为 10）。它决定状态树在内存中批量缓冲后何时被写入快照，是执行关键路径与落盘解耦的关键参数。
max_num_nodes_per_lru_cache_shard：JMT 节点 LRU 缓存每个 shard 的最大节点数，默认1 << 13 = 8192，源码注释指出该默认值下 LRU 缓存约消耗 2GB 内存（DEFAULT_MAX_NUM_NODES_PER_LRU_CACHE_SHARD）。

三类数据修剪器

修剪器配置（storage_pruner_config）对应的默认实现在 storage_config.rs，值得注意的是：当前源码默认值与 README 文档中给出的示例值并不完全相同，这正是上文所说"默认值会随版本演进"的实例。以当前仓库源码为准的默认值如下：

修剪器	`enable`	`prune_window`（版本数）	`batch_size`	职责
`ledger_pruner_config`	true	90_000_000	5_000	修剪交易、事件、写入集等账本数据（状态树除外）；另有`user_pruning_window_offset: 200_000`供用户调整窗口
`state_merkle_pruner_config`	true	1_000_000	1_000	修剪状态树节点（同纪元内被覆盖的节点）；窗口需大于执行一个区块期间状态提交线程能提交的版本数
`epoch_snapshot_pruner_config`	true	80_000_000	1_000	只保留纪元结束版本处的状态快照，供状态同步快速同步（fast sync）使用；约为 5K TPS × 2 小时/纪元 × 2 个纪元

源码注释还给出了修剪窗口的权衡逻辑：修剪窗口至少要大于一次 RPC 请求所跨越的版本区间（其子请求需要在同一版本返回一致的 DB 视图），按数千 TPS 与数分钟的一致视图估算，约 100 万版本是一个保守安全的最小窗口。另外PrunerConfig还包含stale_node_cleanup_batch_size（默认 50_000），用于启动时一次性清理历史遗留的过期节点；NO_OP_STORAGE_PRUNER_CONFIG（全部关闭、窗口为 0）可作为完全禁用修剪的参考配置。

RocksDB 调优参数

rocksdb_configs为不同 DB 实例（ledger_db_config、state_merkle_db_config、state_kv_db_config、index_db_config）提供独立的 RocksDB 选项。源码RocksdbConfig::default()（storage_config.rs）给出了当前默认行为：

max_open_files: 5000（允许 DB 关闭旧的 SST 文件以节省内存；index_db_config为 1000）；
max_total_wal_size：各 DB 默认 512MB（state merkle / state kv 为 256MB），WAL 超过该值强制触发 flush；
max_background_jobs: 4（flush 与 compaction 合计的并发作业数，另有high/low_priority_background_threads默认各 4）；
block_size: 4KB；index_type默认TwoLevelIndexSearch，partition_filters: true；cache_index_and_filter_blocks: true且pin_l0_filter_and_index_blocks_in_cache: true；
block_cache_size已弃用（为兼容保留），新版本统一由shared_block_cache_size控制所有 DB 共享的块缓存，默认24GB（RocksdbConfigs::DEFAULT_BLOCK_CACHE_SIZE）；
高级选项还包括bloom_filter_bits（state kv DB 默认 10.0 并配合bloom_before_level: 2）、stats_level（默认ExceptHistogramOrTimers）等。

由于 README 示例值（如max_total_wal_size: 1073741824、block_cache_size: 8388608、max_background_jobs: 16）与当前源码默认值存在差异，建议以 storage_config.rs 中的Default实现和版本发布说明为准；若要覆盖，务必理解每个参数对内存与 IO 的影响。

内部索引器（Internal Indexer）

DB 分片（DB sharding）之后，节点需要为部分基于账户（account based）的 Rest API 提供查询数据，这正是内部索引器的用途。它支持以下 API：

基于账户的事件 API

/accounts/{address}/events/{event_handle}/{field_name}
/accounts/{address}/events/{creation_number}

基于账户的交易 API

/accounts/{address}/transactions

基于账户的资源 API

/accounts/{address}/modules
/accounts/{address}/resources

内部索引器的配置如下（batch_size用于在写入内部索引器 DB 前将交易切分为更小的批次）：

indexer_db_config: enable_transaction: true // 账户交易 API 所需 enable_event: true // 账户事件 API 所需 enable_statekeys: true // 账户资源 API 所需 batch_size: 10000

在源码中，该配置对应 config/src/config/internal_indexer_db_config.rs 的InternalIndexerDBConfig。当前源码的默认实现（internal_indexer_db_config.rs）中三个开关默认均为false、batch_size默认 10_000、runtime_threads默认 2，即索引器默认不启用，需要按需显式开启；is_internal_indexer_db_enabled()只要任一开关为 true 即视为启用。配置经 config/src/config/node_config.rs 挂载到NodeConfig.indexer_db_config，并在 config_sanitizer.rs 中被引用做配置校验。

备份与恢复 CLI 工具

DB 备份采用精简格式来保留区块链原始数据，对区块链整体数据安全意义重大，也提供了一条离线批量处理区块链数据的途径。但它并非在空盘上启动 AptosDB 的首选方式——请优先使用状态同步（State Sync）的快速同步（Fast Sync）模式。

备份数据由三类增量组成，对应 storage/backup/backup-cli/src/backup_types/ 中的三个子模块：

epoch_ending：纪元结束时的账本信息（LedgerInfo），用于后续证明验证；
state_snapshot：纪元结束版本处的完整状态快照；
transaction：按版本区间切分的增量交易备份。

持续备份到云存储

备份协调器（backup coordinator）持续运行，与内嵌在 Aptos 节点中的备份服务（backup service）通信，并自动将备份数据写入配置好的云存储。其实现见 storage/backup/backup-cli/src/coordinators/backup.rs：协调器每 1 秒轮询一次节点DbState（watch_db_state），随后按依赖顺序调度三条工作流——先备份 epoch ending（供证明使用），再据此触发状态快照与交易备份，形成可靠的备份流水线。

备份存储的访问方式通过command_adapter配置（即 yaml 配置文件中用 shell 命令描述读写行为，可附加压缩等处理）。仓库提供了可直接改用的示例配置：sample_configs/ 下有s3.sample.yaml、gcp.sample.yaml、azure.sample.yaml与local_folder.sample.yaml四个模板。以 s3.sample.yaml 为例，它通过环境变量（BUCKET、SUB_DIR）与一组命令（create_backup、create_for_write、open_for_read、save_metadata_line、list_metadata_files、backup_metadata_file）实现基于aws s3 cp的读写，并用gzip完成压缩；local_folder.sample.yaml 则演示了纯本地目录的备份方式（主要用于测试）。

持续备份命令的完整帮助如下（来自 storage/README.md，对应实现BackupCoordinatorOpt，backup.rs）：

$ cargo run -p aptos-debugger aptos-db backup continuously --help Finished dev [unoptimized + debuginfo] target(s) in 1.06s Running `target/debug/aptos-debugger aptos-db backup continuously --help` aptos-db-tool-backup-continuously 0.1.0 Run the backup coordinator which backs up blockchain data continuously off a Aptos Node. USAGE: aptos-debugger aptos-db backup continuously [OPTIONS] <--local-fs-dir <LOCAL_FS_DIR>|--command-adapter-config <COMMAND_ADAPTER_CONFIG>> OPTIONS: --backup-service-address <ADDRESS> Backup service address. By default a Aptos Node runs the backup service serving on tcp port 6186 to localhost only. [default: http://localhost:6186] --command-adapter-config <COMMAND_ADAPTER_CONFIG> Select the CommandAdapter backup storage type, which reads shell commands with which it communicates with either a local file system or a remote cloud storage. Compression or other filters can be added as part of the commands. --concurrent-downloads <CONCURRENT_DOWNLOADS> Number of concurrent downloads from the backup storage. This covers the initial metadata downloads as well. Speeds up remote backup access. [Defaults to number of CPUs] -h, --help Print help information --local-fs-dir <LOCAL_FS_DIR> Select the LocalFs backup storage type, which is used mainly for tests. --max-chunk-size <MAX_CHUNK_SIZE> Maximum chunk file size in bytes. [default: 134217728] --metadata-cache-dir <DIR> Metadata cache dir. If specified and shared across runs, metadata files in cache won't be downloaded again from backup source, speeding up tool boot up significantly. Cache content can be messed up if used across the devnet, the testnet and the mainnet, hence it [Defaults to temporary dir]. --state-snapshot-interval-epochs <STATE_SNAPSHOT_INTERVAL_EPOCHS> Frequency (in number of epochs) to take state snapshots at epoch ending versions. Adjacent epochs share much of the state, so it's inefficient storage-wise and bandwidth-wise to take it too frequently. However, a recent snapshot is obviously desirable if one intends to recover a snapshot and catch up with the chain by replaying transactions on top of it. Notice: If, while a snapshot is being taken, the chain advanced several epoch, past several new points where a snapshot is eligible according to this setting, we will skip those in the middle and take only at the newest epoch among them. For example, if the setting is 5, then the snapshots will be at at 0, 5, 10 ... If when the snapshot at 5 ends the chain is already at 19, then snapshot at 15 will be taken instead of at 10 (not at 18). [default: 1] --transaction-batch-size <TRANSACTION_BATCH_SIZE> The frequency (in transaction versions) to take an incremental transaction backup. Making a transaction backup every 10 Million versions will result in the latest transaction to appear in the backup potentially 10 Million versions later. If the net work is running at 1 thousand transactions per second, that is roughly 3 hours. On the other hand, if backups are too frequent and hence small, it slows down loading the backup metadata by too many small files. [default: 1000000] -V, --version Print version information

各参数的使用要点：

--backup-service-address：默认http://localhost:6186，与storage.backup_service_address对应；跨主机访问需调整节点配置。
--local-fs-dir与--command-adapter-config二选一（互斥，命令用法中的<...>语法已体现）：前者是本地文件系统存储（主要用于测试），后者对接云存储并可通过命令附加压缩/过滤。
--metadata-cache-dir：元数据缓存目录，跨多次运行共享可显著加快工具启动；但不要跨 devnet / testnet / mainnet 混用，否则缓存内容会错乱；未指定时默认使用临时目录。
--state-snapshot-interval-epochs：状态快照频率（以纪元计）。快照太频繁存储/带宽效率低；若快照期间链又跨过多个可快照的纪元点，则跳过中间点、只在最新合格纪元点拍摄。默认 1。
--transaction-batch-size：增量交易备份的版本间隔。默认 1_000_000；过大会让最新交易在备份中出现得晚（如每 1000 万版本约延迟 3 小时，按 1K TPS 估算），过小则会因大量小文件拖慢元数据加载。
--max-chunk-size：单个 chunk 文件的最大字节数，默认 134217728（128MB）。
--concurrent-downloads：从备份存储并发下载的线程数（含初始元数据下载），默认等于 CPU 核数。

示例命令（使用s3.yaml作为 command adapter 配置）：

$ cargo run -p aptos-debugger aptos-db backup continuously \ --metadata-cache-dir ./mc \ --state-snapshot-interval-epochs 1 \ --concurrent-downloads 4 \ --command-adapter-config s3.yaml

aptos-debugger aptos-db还有其他子命令，全部处于实验性状态，可能破坏备份存储，请自行承担风险使用。

从备份创建最小数据的 AptosDB

利用备份引导（bootstrap）AptosDB 是 Aptos API 功能的一部分。紧急情况需要手动引导时，Aptos 会以 yaml 配置文件的形式提供备份源；平时也可以用自己创建的配置（通常是上一节备份过程中使用的同一份配置）来演练。

命令帮助如下：

aptos-node-bootstrap-db-from-backup 0.3.5 Tool to bootstrap DB from backup USAGE: aptos node bootstrap-db-from-backup [OPTIONS] --config-path <CONFIG_PATH> --target-db-dir <DB_DIR> OPTIONS: --concurrent-downloads <CONCURRENT_DOWNLOADS> Number of concurrent downloads from the backup storage. This covers the initial metadata downloads as well. Speeds up remote backup access. [Defaults to number of CPUs] --config-path <CONFIG_PATH> Config file for the source backup, pointing to local files or cloud storage and commands needed to access them. -h, --help Print help information --metadata-cache-dir <DIR> Metadata cache dir. If specified and shared across runs, metadata files in cache won't be downloaded again from backup source, speeding up tool boot up significantly. Cache content can be messed up if used across the devnet, the testnet and the mainnet, hence it [Defaults to temporary dir]. --replay-concurrency-level <REPLAY_CONCURRENCY_LEVEL> concurrency_level used by the transaction executor, applicable when replaying transactions after a state snapshot. [Defaults to number of CPUs] --target-db-dir <DB_DIR> Target dir where the tool recreates a AptosDB with snapshots and transactions provided in the backup. The data folder can later be used to start an Aptos node. e.g. /opt/ aptos/data/db -V, --version Print version information

示例命令：

RUST_LOG=info ./aptos \ node bootstrap-db-from-backup \ --metadata-cache-dir ./mc \ --config-path s3.yaml \ --target-db-dir data/db

该功能与cargo run -p aptos-debugger aptos-db restore的 "auto" 模式本质相同，但选项更有限。restore工具能够手动篡改本地 DB，高度实验性；如果你不能 100% 确认自己在做什么，不建议使用。恢复协调器的实现同样位于 storage/backup/backup-cli/src/coordinators/restore.rs，负责编排从备份存储拉取元数据、快照与交易增量并重建 DB 的完整流程。

总结与最佳实践

默认优先：storage配置在大多数场景下可直接使用默认值；需要覆盖时请先阅读 storage_config.rs 中的详细注释，并注意默认值会随版本演进，本地覆盖可能错过官方调优。
修剪即平衡：三个修剪器分别管理账本数据、纪元内状态树节点与纪元末状态快照的保留窗口，是数据可用性与磁盘占用之间的关键权衡点；epoch 快照的保留对 fast sync 模式的对等节点尤其重要。
索引按需开启：内部索引器三个开关默认全关，仅在需要账户维度的事件/交易/资源 API 时显式开启，并可用batch_size控制写入粒度。
备份 ≠ 启动方式：新节点引导首选状态同步的 Fast Sync；备份用于灾难恢复、历史状态回溯与硬分叉场景。持续备份用 backup coordinator + command adapter（参考 sample_configs/），恢复引导用bootstrap-db-from-backup，且注意元数据缓存目录不要跨网络混用。