在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

base/node

菜单

卷管理

相关源文件

本文档介绍了 Base Node 数据持久化存储的管理方式，包括存储卷的配置、默认数据位置以及管理区块链数据的最佳实践。有关 Docker 基础设施和容器配置的信息，请参阅Docker 基础设施和Docker Compose 配置。

Base Node 数据存储概述

Base Node 需要持久化存储来在容器重启后维护区块链数据。这包括执行客户端的链数据、节点密钥和其他持久化状态信息。如果没有正确配置持久化存储，在容器被重新创建时，您将丢失所有已同步的数据。

来源: README.md89-94 docker-compose.yml14

默认配置

默认情况下，Base Node 将执行客户端数据存储在项目根目录下的一个目录中

  • Geth: ${PROJECT_ROOT}/geth-data/
  • Reth: ${PROJECT_ROOT}/reth-data/
  • Nethermind: ${PROJECT_ROOT}/nethermind-data/

这些目录被挂载到执行客户端容器的 /data 路径，从而在容器重启之间建立持久化存储。

来源: README.md91-92 docker-compose.yml14 .dockerignore1-3

卷配置

数据目录挂载由环境变量控制

  • HOST_DATA_DIR - 定义将要挂载到执行客户端容器中的主机目录
  • GETH_HOST_DATA_DIR - 可用于覆盖 .env 文件中的默认数据目录

映射在 Docker Compose 文件中定义，该文件将主机目录挂载到执行客户端容器内的 /data

来源: docker-compose.yml13-14 README.md91-92

数据目录结构

每个执行客户端存储数据的结构略有不同

执行客户端数据结构关键组件
Gethgeth-data/chaindata/, lightchaindata/, keystore/, nodekey
Rethreth-data/db/, network/, keystore/
Nethermindnethermind-data/chainspec/, keystore/, nethermind_db/

无论选择哪个客户端，所有区块链数据都存储在配置的主机数据目录中，并在容器重启时保持不变。

来源: .dockerignore1-3 README.md91-92

特定客户端的卷管理

Base Node 系统支持三种执行客户端，数据目录根据正在使用的客户端确定

来源: README.md71-78 docker-compose.yml3-16

使用快照

为了加速节点同步，Base Node 系统支持从快照加载。此功能依赖于卷管理系统

  1. 从 Base 文档中提供的 URL 下载快照
  2. 将快照解压到您配置的数据目录 ($GETH_HOST_DATA_DIR 或等效目录)
  3. 使用 Docker Compose 启动节点

来源: README.md93-94 README.md108-110

卷管理最佳实践

存储注意事项

为了有效地运行 Base 节点，请遵循以下存储建议

  1. 存储容量: 确保有足够的存储空间用于快照恢复和持续的链数据

    • 最低要求为 (当前链大小 * 2) + 快照大小 + 20% 缓冲
    • 这可以同时容纳恢复过程和未来的增长

  2. 存储性能: 使用高性能存储

    • 建议使用本地连接的 NVMe SSD 驱动器
    • 如果使用云存储（例如 Amazon EBS），请确保足够的 I/O 性能
    • 特别是对于 AWS，推荐使用 io2 block express

  3. 卷持久性: 删除容器时要小心

    • 使用 docker compose down 而不是 docker compose down -v 以保留卷
    • 定期备份您的数据目录

来源: README.md36-37 README.md39

特定网络的目录

考虑为不同网络（主网与测试网）维护独立的数据目录，以避免混淆和潜在的数据损坏

project-root/
├── geth-data-mainnet/
├── geth-data-sepolia/
├── reth-data-mainnet/
├── reth-data-sepolia/
└── ...

您可以在环境配置中或启动容器时指定相应目录。

来源: README.md50-53 README.md58-64

卷问题故障排除

与数据卷相关的常见问题包括

  1. 磁盘空间不足: 定期监控可用磁盘空间
  2. 权限问题: 确保运行 Docker 的用户对数据目录具有适当的权限
  3. 数据损坏: 如果链数据损坏，您可能需要
    • 删除损坏的数据目录
    • 从快照恢复
    • 重新启动同步

如果您遇到持久性卷相关的问题，请参阅项目 README 中的故障排除部分，或通过 GitHub Issues 或 Discord 联系我们。

来源: README.md42-46

容器架构与卷映射

下图说明了 Docker 容器系统如何与主机文件系统交互以实现数据持久化

来源: docker-compose.yml1-32 README.md89-94

这种架构确保了所有区块链数据在容器生命周期结束后仍然存在，从而支持节点重启而不会丢失数据，并支持诸如快照恢复之类的进阶操作。