Bitcoin Core 文件系统完全指南数据目录、链子目录与安装产物布局解析【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin本篇技术指南以 Bitcoin Core 官方的文件系统文档doc/files.md为核心骨架系统讲解节点数据目录在各平台的默认位置、按链隔离的子目录规则、数据目录内每一类文件的职责以及多钱包环境、SQLite 钱包布局、GUI 设置、遗留文件与安装产物的完整清单。读完本文你将能够准确判断 Bitcoin Core 在任意平台上把链数据、区块文件、UTXO 状态、索引与钱包分别存放在哪里理解每个文件的生成与删除时机并掌握官方对文件系统选型的明确建议。数据目录datadir的位置数据目录data directory是 Bitcoin Core 所有文件的默认存储位置。确定它的路径遵循三条规则各平台的默认路径平台默认数据目录Linux$HOME/.bitcoin/macOS$HOME/Library/Application Support/Bitcoin/Windows%LOCALAPPDATA%\Bitcoin\见注 1可通过-datadir选项指定自定义数据目录路径。数据目录中除bitcoin.conf外的所有内容都是按链chain-specific隔离的。这意味着非主网的实际数据目录会落在带链名后缀的子目录中链选项数据目录路径-chainmain默认path_to_datadir/-chaintest或-testnetpath_to_datadir/testnet3/-chaintestnet4或-testnet4path_to_datadir/testnet4/-chainsignet或-signetpath_to_datadir/signet/-chainregtest或-regtestpath_to_datadir/regtest/从源码结构看这一行为由 src/common/args.cpp 中的GetDefaultDataDir()实现在 Windows 上如果旧的AppData\Roaming\Bitcoin已存在则沿用保持兼容否则新安装使用AppData\Local\BitcoinmacOS 返回~/Library/Application Support/Bitcoin其他类 Unix 系统返回~/.bitcoin。而链名子目录的拼接发生在 ArgsManager::GetDataDir先取-datadir未指定时回退到GetDefaultDataDir()再按网络参数追加BaseParams().DataDir()指定的链名子目录。链名与默认 RPC 端口的对应关系可在 src/chainparamsbase.cpp 中确认testnet318332、testnet448332、signet38332、regtest18443。注 1本文档使用/斜杠U002F作为跨平台的路径分隔符。数据目录布局总览下表完整继承自 doc/files.md列出数据目录中每个子目录与文件的用途除bitcoin.conf外均位于链子目录下。注 2NNNNN匹配正则[0-9]{5}。子目录文件说明blocks/—区块目录可由-blocksdir选项指定blocks/index/除外blocks/index/LevelDB 数据库区块索引-blocksdir选项不影响此路径blocks/blkNNNNN.dat注 2实际 Bitcoin 区块网络格式落盘每文件 128 MiBblocks/revNNNNN.dat注 2区块撤销数据自定义格式blocks/xor.dat区块文件与撤销数据文件的滚动 XOR 校验模式chainstate/LevelDB 数据库区块链状态当前所有未花费交易输出 UTXO 的紧凑表示及其来源交易元数据fees/block_policy_estimates.dat与mempool_policy_estimator.dat存储区块策略与内存池策略估算器数据indexes/txindex/LevelDB 数据库交易索引可选-txindex1时使用indexes/txospenderindex/LevelDB 数据库交易花费者索引可选-txospenderindex1时使用indexes/blockfilter/basic/db/LevelDB 数据库basic 过滤器类型的块过滤器索引 LevelDB 数据库可选-blockfilterindexbasic时使用indexes/blockfilter/basic/fltrNNNNN.dat注 2basic 过滤器类型的块过滤器索引文件可选-blockfilterindexbasic时使用indexes/coinstatsindex/db/LevelDB 数据库Coinstats 索引可选-coinstatsindex1时使用wallets/—存放钱包可由-walletdir选项指定若wallets/子目录不存在钱包位于数据目录本身./anchors.dat锚点AnchorIP 地址数据库关机时创建、启动时删除。锚点是最后已知的出方向 block-relay-only 对等节点启动时会尝试重连./banlist.json存储被封禁节点的地址/子网./bitcoin.conf用户为bitcoind或bitcoin-qt定义的配置项。软件不会写入此文件须手工创建。路径可由-conf选项指定./bitcoind.pid运行时保存bitcoind或bitcoin-qt的进程 IDPID启动时创建、关机时删除可由-pid选项指定./debug.logbitcoind或bitcoin-qt生成的调试信息与通用日志可由-debuglogfile选项指定./guisettings.ini.bak使用-resetguisettings选项后旧的 GUI 设置备份./mempool.dat内存池mempool交易的转储./onion_v3_private_key-listenonion选项所用的 Tor onion 服务私钥缓存./i2p_private_key与本机 I2P 地址对应的私钥。指定-i2psam时文件内容用于在连接及可能的入站连接I2P 对等节点时标识自身不存在时自动生成./peers.dat对等节点 IP 地址数据库自定义格式./settings.json通过 GUI 或 RPC 接口设置的读写设置是对 bitcoin.conf 手工设置的补充。除非用-nosettings禁用了读写设置存储该文件会自动创建。路径可用-settings选项指定./.cookie会话式 RPC 认证 cookie若启用启动时创建、关机时删除可用-rpccookiefile选项指定./.lock数据目录锁文件区块文件与 128 MiB 上限的源码依据文档中“每文件 128 MiB”的blkNNNNN.dat规格对应 src/node/blockstorage.h 中的常量inline constexpr unsigned int MAX_BLOCKFILE_SIZE{128_MiB};并在 src/node/blockstorage.cpp 的区块存储初始化中被引用。xor.dat的滚动 XOR 校验机制同样实现在 src/node/blockstorage.cppblocks_dir / xor.dat用于快速检测区块与撤销数据文件的位损坏。锚点与封禁列表的持久化anchors.dat与banlist.json的读写逻辑位于 src/addrdb.cpp 与 src/addrdb.h前者在关机时把出方向的 block-relay-only 对等节点地址转储为锚点代码中有“Dump ... to anchors.dat”的日志启动时读取并主动尝试重连读完后删除该文件——这种“只在重启瞬间存在”的设计使得节点能恢复与关键块中继节点的连接同时不保留长期状态。banlist.json则是从旧的banlist.datBDB 格式迁移而来的 JSON 格式封禁列表可被用户直接查看与编辑。多钱包环境当前版本的钱包都是SQLite 数据库。组织规则如下每个用户定义的钱包wallet_name位于wallets/wallet_name/子目录中。默认未命名钱包位于wallets/子目录中若wallets/不存在则钱包位于数据目录本身。钱包数据库路径可用-wallet选项指定。不同节点实例之间不得共享wallet.dat文件否则由于实例间缺乏同步会导致密钥重用和双花。复制/备份钱包应通过backupwalletRPC 调用完成它会先更新并锁定钱包避免复制过程中发生写入造成文件损坏。从源码结构看src/common/init.cpp 在创建全新数据目录时会一并创建wallets子目录并带有兼容性注释仅当检测到已有钱包位于数据目录根时才会回退到旧的存放位置以保持兼容。SQLite 数据库钱包的文件布局子目录文件说明./wallet.dat个人钱包SQLite 数据库包含密钥与交易./wallet.dat-journalwallet.dat的 SQLite 回滚日志文件。通常启动时创建、关机时删除。用户必须把它与wallet.dat同等对待一样妥善保管GUI 设置bitcoin-qt使用 Qt 的QSettings类管理 GUI 配置这意味着设置文件的存放位置由 Qt 按平台惯例决定各平台的应用设置存储路径遵循 QSettings 的规范。这也解释了为什么 GUI 配置不出现在数据目录的核心布局表中——它的落盘位置与数据目录相互独立。遗留子目录与文件以下子目录与文件已不再被当前版本的 Bitcoin Core 使用如果出现在老数据目录中可按表格中的演进历史理解其前身角色路径说明仓库演进记录banlist.dat封禁节点地址/子网22.0 起由banlist.json取代23.0 起被完全忽略PR #20966、PR #22570blktree/区块链索引0.8.0 起由blocks/index/取代PR #2231提交8fdc94cccoins/未花费交易输出数据库0.8.0 起由chainstate/取代PR #2231提交8fdc94ccblkindex.dat区块链索引 BDB 数据库0.8.0 起由{chainstate/, blocks/index/, blocks/revNNNNN.dat}取代PR #1677blk000?.dat区块数据自定义格式每文件 2 GiB0.8.0 起由blocks/blkNNNNN.dat取代PR #1677addr.dat对等节点 IP 地址 BDB 数据库0.7.0 起由peers.dat取代PR #1198提交928d3a01onion_private_key-listenonion的 Tor onion 服务私钥缓存用于 Tor v2 服务0.21.0 起由onion_v3_private_key取代PR #19954其中 0.8.0 从 Berkeley DB 迁移到 LevelDB 的变更可参考 doc/release-notes/release-notes-0.8.0.md 的 Improvements 部分。Berkeley DB 数据库钱包遗留0.8.0 之前钱包为 BDB 数据库其遗留布局如下子目录文件说明database/BDB 日志文件BDB 环境的一部分启动时创建、关机时删除用户必须把它与个人钱包wallet.dat同等对待一样妥善保管./db.logBDB 错误文件./wallet.dat个人钱包BDB 数据库包含密钥与交易./.walletlockBDB 钱包锁文件注意升级后的节点不能继续读取旧 BDB 钱包——迁移时必须先导出私钥/描述符再用新节点重建 SQLite 钱包。安装产物Installed Files下表描述 Bitcoin Core 在各平台安装或源码构建安装后落盘的文件路径说明README.md 或 readme.txt项目信息与说明bitcoin.conf由 生成脚本 产出的配置文件bin/bitcoin与 Bitcoin 交互的命令行工具内部调用下列其他二进制bin/bitcoin-cli发起节点与钱包 RPC 调用的工具bin/bitcoin-qtBitcoin 节点与钱包 GUIbin/bitcoin-tx创建与修改交易的工具bin/bitcoin-util杂项工具集bin/bitcoin-walletBitcoin 钱包工具bin/bitcoindBitcoin 节点与钱包守护进程lib/libbitcoinkernel.so包含核心共识与验证代码的共享库lib/pkgconfig/libbitcoinkernel.pc链接libbitcoinkernel的 pkg-config 元数据libexec/bench_bitcoin衡量节点性能的基准测试工具libexec/bitcoin-chainstate校验并连接区块的工具libexec/bitcoin-gui具备 IPC 能力的bitcoin-qt替代方案libexec/bitcoin-node具备 IPC 能力的bitcoind替代方案libexec/test_bitcoin单元测试二进制libexec/test_bitcoin-qtGUI 专属单元测试share/man/man1/bitcoin-cli、bitcoind等命令行工具的手册页见 doc/manshare/rpcauth/RPC 认证设置的文档与脚本见 share/rpcauth/README.md说明斜体文件仅在源码构建且相关 CMake 选项启用时安装二进制发布包不包含它们README与bitcoin.conf包含在二进制发布包中但源码构建不会安装它们Windows 上二进制带.exe后缀如bitcoin-cli.exe。这些目标在构建系统中的定义可参见 src/CMakeLists.txt 与各子目录的 CMake 配置IPC 相关二进制bitcoin-node、bitcoin-gui的实现在 src/ipc 目录。文件系统选型建议在macOS上为数据目录datadir或区块目录blocksdir选择文件系统时应避免使用exFAT。已有多份使用 exFAT 配合 Bitcoin Core 导致数据库损坏与数据丢失的报告相关讨论见上游 Issue #31454。实践上macOS 建议保持默认的 APFS 或 HFSLinux 下则建议常规使用 XFS/ext4 等本地文件系统并为blocks/区块文件体量最大预留充足的连续磁盘空间配合-blocksdir可将其独立放置到大容量磁盘。小结Bitcoin Core 的文件系统布局遵循“数据目录 → 链子目录 → 固定文件名”的清晰层次blocks/与chainstate/承载链数据本体indexes/下的 LevelDB 索引按功能选项启用wallets/存放 SQLite 钱包而peers.dat、banlist.json、settings.json、.cookie等则管理节点运行时状态。理解每个文件的创建/删除时机如anchors.dat与.cookie只在重启瞬间存在以及-datadir、-blocksdir、-walletdir、-conf等选项的覆盖关系是运维多链环境、迁移节点、备份钱包时的基础能力。【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考