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-coreAptos 是一个面向大规模区块链应用的一层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 ServiceRest 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控制备份服务的运行时线程数。dirRocksDB 实例所在目录相对于顶层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_shardJMT 节点 LRU 缓存每个 shard 的最大节点数默认1 13 8192源码注释指出该默认值下 LRU 缓存约消耗 2GB 内存DEFAULT_MAX_NUM_NODES_PER_LRU_CACHE_SHARD。三类数据修剪器修剪器配置storage_pruner_config对应的默认实现在 storage_config.rs值得注意的是当前源码默认值与 README 文档中给出的示例值并不完全相同这正是上文所说默认值会随版本演进的实例。以当前仓库源码为准的默认值如下修剪器enableprune_window版本数batch_size职责ledger_pruner_configtrue90_000_0005_000修剪交易、事件、写入集等账本数据状态树除外另有user_pruning_window_offset: 200_000供用户调整窗口state_merkle_pruner_configtrue1_000_0001_000修剪状态树节点同纪元内被覆盖的节点窗口需大于执行一个区块期间状态提交线程能提交的版本数epoch_snapshot_pruner_configtrue80_000_0001_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为 1000max_total_wal_size各 DB 默认 512MBstate merkle / state kv 为 256MBWAL 超过该值强制触发 flushmax_background_jobs: 4flush 与 compaction 合计的并发作业数另有high/low_priority_background_threads默认各 4block_size: 4KBindex_type默认TwoLevelIndexSearchpartition_filters: truecache_index_and_filter_blocks: true且pin_l0_filter_and_index_blocks_in_cache: trueblock_cache_size已弃用为兼容保留新版本统一由shared_block_cache_size控制所有 DB 共享的块缓存默认24GBRocksdbConfigs::DEFAULT_BLOCK_CACHE_SIZE高级选项还包括bloom_filter_bitsstate 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 IndexerDB 分片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 秒轮询一次节点DbStatewatch_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对应实现BackupCoordinatorOptbackup.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 wont 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 its 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 文件的最大字节数默认 134217728128MB。--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.yamlaptos-debugger aptos-db还有其他子命令全部处于实验性状态可能破坏备份存储请自行承担风险使用。从备份创建最小数据的 AptosDB利用备份引导bootstrapAptosDB 是 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 wont 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_LOGinfo ./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且注意元数据缓存目录不要跨网络混用。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考