Bitcoin Core 钱包迁移故障复盘3 类根因、1 套 4 步修复 SOP 与零损失验收闭环【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoinError: Error loading main-wallet: Wallet is a legacy wallet. Please migrate to a descriptor wallet using the migration tool (migratewallet RPC). Error: Wallet decryption failed, the wallet passphrase was not provided or was incorrect20:00 的维护窗口里migratewalletLegacy 钱包迁移到 Descriptor 钱包的官方 RPC第二次失败加密钱包没有传口令剪枝节点缺数据。本文基于 Bitcoin Core 源码与官方测试带你完成三件事10 秒对号入座 3 类迁移故障按前置 → 操作 → 预期 → 回退执行修复用基准测试加人工清单做零损失验收。10 秒对号入座4 种故障模式速查表典型症状关键日志 / 指标归属类型加密钱包迁移立刻报错Wallet decryption failed, the passphrase was not provided or was incorrect口令缺失剪枝节点迁移中途失败last wallet synchronisation goes beyond pruned data. You need to -reindex数据不足大钱包迁移卡死、CLI 断开无输出最终RPC error -8 / timeout单线程慢迁移迁移成功但交易不全getwalletinfo的tx_count低于迁移前旧钱包数据一致性三条错误文案均出自仓库内真实断言可在 test/functional/wallet_migration.py 与 test/functional/wallet_backwards_compatibility.py 中逐行检索到不是猜测。根因剖析根因一加密钱包的口令在迁移入口就被拒绝现象加密的 Legacy 钱包调用migratewallet立即返回 -4 错误。复现bitcoin-cli migratewallet encrypted-wallet不带passphrase参数。证据链src/wallet/rpc/wallet.cpp 第 591–651 行的migratewalletRPC 定义明确写着 Encrypted wallets must have the passphrase provided as an argument to this calltest/functional/wallet_migration.py 第 563 行用错误口令做回归断言。注意错误发生在迁移开始前不产生任何脏数据可安全重试。根因二剪枝节点上迁移被硬校验拦停现象剪枝pruned只保留近期区块以节省磁盘的节点节点迁移到一定深度后失败。复现在启用prune550的节点上迁移一个最后同步块早于保留区间的旧钱包。证据链test/functional/wallet_migration.py 第 1705 行的断言锁死了这条错误路径last wallet synchronisation goes beyond pruned data。迁移需要读取旧钱包数据库记录的最后同步块而剪枝节点已删除该区块数据校验直接失败。根因三迁移是单线程长事务客户端默认等不及现象大钱包数万笔交易迁移期间 CLI 长时间无响应最终断开留下迁移是否完成的悬案。复现对大 Legacy 钱包执行migratewallet观察客户端超时。证据链src/wallet/rpc/wallet.cpp 第 601 行官方帮助文本直言 This RPC may take a long time to complete. Increasing the RPC client timeout is recommended.实现上整个迁移在单次 RPC 内完成第 633 行调用MigrateLegacyToDescriptor落点 src/wallet/wallet.cpp 第 4289 行。仓库自带的微基准 src/bench/wallet_migration.cpp 以 500 把私钥、20 个 watch-only只读监控地址构造钱包并完整迁移一次可作为正常负载的耗时锚点你的真实钱包若比它大一个数量级默认客户端超时大概率不够。修复 SOP4 步走步骤 1确认回滚底牌所有后续步骤的前置前置校验节点已停止旧钱包在磁盘上完好。命令检查wallets/目录下存在旧钱包数据库文件并记下其大小# 记录旧钱包文件与大小作为迁移前的基线 ls -lh ~/.bitcoin/wallets/main-wallet预期输出文件名与旧钱包同名大小非零。失败回退文件缺失或为 0 字节停止一切迁移操作先找回备份不要在损坏的源上迁移。步骤 2加密钱包带口令迁移前置校验已确认口令在测试钱包或恢复流程上先验证一次。命令# 迁移加密钱包第二个参数即钱包口令 bitcoin-cli migratewallet encrypted-wallet correct-passphrase预期输出JSON 返回wallet_name、backup_path形如名称-时间戳.legacy.bak如含只读脚本还会有watchonly_name。失败回退报Wallet decryption failed时确认口令无误后原样重试——该错误不产生半成品确认口令已遗忘则本路径走不通需从 BIP 3912/24 词助记词标准种子恢复。步骤 3剪枝节点先补全数据再迁移前置校验bitcoin-cli getblockchaininfo确认pruned为 true。命令先备份再改配置顺序不可颠倒# 备份数据目录后取消剪枝并重新索引补全历史区块 cp -r ~/.bitcoin/blockstore /backup/blockstore-$(date %F) # bitcoin.conf: 注释掉 prune550 bitcoind -reindex预期输出-reindex完成后pruned变 false区块完整。失败回退磁盘空间不足全量约 700 GB 级别时放弃补数据改用冷钱包流程导出密钥后在全节点机器上迁移。步骤 4大钱包迁移与加载分离前置校验钱包规模明显大于基准锚点500 钥 / 20 地址量级以上。命令# 只迁移不加载避免长事务卡死 RPC 客户端 bitcoin-cli migratewallet big-wallet false # 迁移落盘后单独加载 bitcoin-cli loadwallet big-wallet预期输出migratewallet快速返回 JSON随后loadwallet成功且getwalletinfo的tx_count与迁移前一致。失败回退loadwallet失败或数量对不上时用步骤 2/4 返回的backup_path执行restorewallet回滚到迁移前的 Legacy 状态官方机制见 doc/managing-wallets.md Migrating Legacy Wallets to Descriptor Wallets 一节禁止手工拼接.bak文件。验收闭环自动化构建基准并跑迁移专项。# 构建基准工具 cmake -B build -DBUILD_BENCHON cmake --build build -j # 只跑钱包迁移基准 build/bin/bench_bitcoin -filterWalletMigration -min-time5000指标达标标准出处迁移成功率断言全过res、wallet、watchonly_wallet非空src/bench/wallet_migration.cpp 第 96–101 行单次迁移耗时记录基线值回归时不超过该值 ×1.5本机-output-csv实测功能回归迁移相关用例全绿test/functional/wallet_migration.py人工检查项验证命令通过标准钱包格式bitcoin-cli -rpcwalletX getwalletinfodescriptor为true交易数量对比迁移前后tx_count新 ≥ 旧差值可由_solvables子钱包解释备份存在ls wallets/*.legacy.bak有且仅有一个新备份新备份对迁移后钱包执行backupwallet生成不含.legacy.的新备份复盘与防再发先留底牌再动手任何迁移前确认wallets/下源文件完好并记录大小步骤 1 已做成检查项。口令走参数不走猜加密钱包迁移必须显式传passphrase在测试环境先跑通一次口令正确性。剪枝节点不直接迁移先-reindex补数据或换全节点机器避免pruned data校验拦腰斩。大钱包拆两段load_walletfalse迁移 独立loadwallet杜绝客户端超时造成假死悬案。每次迁移后立即重做备份官方文档强调迁移后必须新建备份旧.legacy.bak只是回滚件不是长期备份。migratewallet自 24.0.1 起进入实验期见 doc/release-notes/release-notes-24.0.1.md新选项load_walletfalse已在后续发布说明doc/release-notes-35266中落地若遇到脚本被漏迁移的边界情况按 doc/managing-wallets.md 的指引向社区提 issue并附上.legacy.bak可复现的最小样本。【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Bitcoin Core 钱包迁移故障复盘：3 类根因、1 套 4 步修复 SOP 与零损失验收闭环
Bitcoin Core 钱包迁移故障复盘3 类根因、1 套 4 步修复 SOP 与零损失验收闭环【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoinError: Error loading main-wallet: Wallet is a legacy wallet. Please migrate to a descriptor wallet using the migration tool (migratewallet RPC). Error: Wallet decryption failed, the wallet passphrase was not provided or was incorrect20:00 的维护窗口里migratewalletLegacy 钱包迁移到 Descriptor 钱包的官方 RPC第二次失败加密钱包没有传口令剪枝节点缺数据。本文基于 Bitcoin Core 源码与官方测试带你完成三件事10 秒对号入座 3 类迁移故障按前置 → 操作 → 预期 → 回退执行修复用基准测试加人工清单做零损失验收。10 秒对号入座4 种故障模式速查表典型症状关键日志 / 指标归属类型加密钱包迁移立刻报错Wallet decryption failed, the passphrase was not provided or was incorrect口令缺失剪枝节点迁移中途失败last wallet synchronisation goes beyond pruned data. You need to -reindex数据不足大钱包迁移卡死、CLI 断开无输出最终RPC error -8 / timeout单线程慢迁移迁移成功但交易不全getwalletinfo的tx_count低于迁移前旧钱包数据一致性三条错误文案均出自仓库内真实断言可在 test/functional/wallet_migration.py 与 test/functional/wallet_backwards_compatibility.py 中逐行检索到不是猜测。根因剖析根因一加密钱包的口令在迁移入口就被拒绝现象加密的 Legacy 钱包调用migratewallet立即返回 -4 错误。复现bitcoin-cli migratewallet encrypted-wallet不带passphrase参数。证据链src/wallet/rpc/wallet.cpp 第 591–651 行的migratewalletRPC 定义明确写着 Encrypted wallets must have the passphrase provided as an argument to this calltest/functional/wallet_migration.py 第 563 行用错误口令做回归断言。注意错误发生在迁移开始前不产生任何脏数据可安全重试。根因二剪枝节点上迁移被硬校验拦停现象剪枝pruned只保留近期区块以节省磁盘的节点节点迁移到一定深度后失败。复现在启用prune550的节点上迁移一个最后同步块早于保留区间的旧钱包。证据链test/functional/wallet_migration.py 第 1705 行的断言锁死了这条错误路径last wallet synchronisation goes beyond pruned data。迁移需要读取旧钱包数据库记录的最后同步块而剪枝节点已删除该区块数据校验直接失败。根因三迁移是单线程长事务客户端默认等不及现象大钱包数万笔交易迁移期间 CLI 长时间无响应最终断开留下迁移是否完成的悬案。复现对大 Legacy 钱包执行migratewallet观察客户端超时。证据链src/wallet/rpc/wallet.cpp 第 601 行官方帮助文本直言 This RPC may take a long time to complete. Increasing the RPC client timeout is recommended.实现上整个迁移在单次 RPC 内完成第 633 行调用MigrateLegacyToDescriptor落点 src/wallet/wallet.cpp 第 4289 行。仓库自带的微基准 src/bench/wallet_migration.cpp 以 500 把私钥、20 个 watch-only只读监控地址构造钱包并完整迁移一次可作为正常负载的耗时锚点你的真实钱包若比它大一个数量级默认客户端超时大概率不够。修复 SOP4 步走步骤 1确认回滚底牌所有后续步骤的前置前置校验节点已停止旧钱包在磁盘上完好。命令检查wallets/目录下存在旧钱包数据库文件并记下其大小# 记录旧钱包文件与大小作为迁移前的基线 ls -lh ~/.bitcoin/wallets/main-wallet预期输出文件名与旧钱包同名大小非零。失败回退文件缺失或为 0 字节停止一切迁移操作先找回备份不要在损坏的源上迁移。步骤 2加密钱包带口令迁移前置校验已确认口令在测试钱包或恢复流程上先验证一次。命令# 迁移加密钱包第二个参数即钱包口令 bitcoin-cli migratewallet encrypted-wallet correct-passphrase预期输出JSON 返回wallet_name、backup_path形如名称-时间戳.legacy.bak如含只读脚本还会有watchonly_name。失败回退报Wallet decryption failed时确认口令无误后原样重试——该错误不产生半成品确认口令已遗忘则本路径走不通需从 BIP 3912/24 词助记词标准种子恢复。步骤 3剪枝节点先补全数据再迁移前置校验bitcoin-cli getblockchaininfo确认pruned为 true。命令先备份再改配置顺序不可颠倒# 备份数据目录后取消剪枝并重新索引补全历史区块 cp -r ~/.bitcoin/blockstore /backup/blockstore-$(date %F) # bitcoin.conf: 注释掉 prune550 bitcoind -reindex预期输出-reindex完成后pruned变 false区块完整。失败回退磁盘空间不足全量约 700 GB 级别时放弃补数据改用冷钱包流程导出密钥后在全节点机器上迁移。步骤 4大钱包迁移与加载分离前置校验钱包规模明显大于基准锚点500 钥 / 20 地址量级以上。命令# 只迁移不加载避免长事务卡死 RPC 客户端 bitcoin-cli migratewallet big-wallet false # 迁移落盘后单独加载 bitcoin-cli loadwallet big-wallet预期输出migratewallet快速返回 JSON随后loadwallet成功且getwalletinfo的tx_count与迁移前一致。失败回退loadwallet失败或数量对不上时用步骤 2/4 返回的backup_path执行restorewallet回滚到迁移前的 Legacy 状态官方机制见 doc/managing-wallets.md Migrating Legacy Wallets to Descriptor Wallets 一节禁止手工拼接.bak文件。验收闭环自动化构建基准并跑迁移专项。# 构建基准工具 cmake -B build -DBUILD_BENCHON cmake --build build -j # 只跑钱包迁移基准 build/bin/bench_bitcoin -filterWalletMigration -min-time5000指标达标标准出处迁移成功率断言全过res、wallet、watchonly_wallet非空src/bench/wallet_migration.cpp 第 96–101 行单次迁移耗时记录基线值回归时不超过该值 ×1.5本机-output-csv实测功能回归迁移相关用例全绿test/functional/wallet_migration.py人工检查项验证命令通过标准钱包格式bitcoin-cli -rpcwalletX getwalletinfodescriptor为true交易数量对比迁移前后tx_count新 ≥ 旧差值可由_solvables子钱包解释备份存在ls wallets/*.legacy.bak有且仅有一个新备份新备份对迁移后钱包执行backupwallet生成不含.legacy.的新备份复盘与防再发先留底牌再动手任何迁移前确认wallets/下源文件完好并记录大小步骤 1 已做成检查项。口令走参数不走猜加密钱包迁移必须显式传passphrase在测试环境先跑通一次口令正确性。剪枝节点不直接迁移先-reindex补数据或换全节点机器避免pruned data校验拦腰斩。大钱包拆两段load_walletfalse迁移 独立loadwallet杜绝客户端超时造成假死悬案。每次迁移后立即重做备份官方文档强调迁移后必须新建备份旧.legacy.bak只是回滚件不是长期备份。migratewallet自 24.0.1 起进入实验期见 doc/release-notes/release-notes-24.0.1.md新选项load_walletfalse已在后续发布说明doc/release-notes-35266中落地若遇到脚本被漏迁移的边界情况按 doc/managing-wallets.md 的指引向社区提 issue并附上.legacy.bak可复现的最小样本。【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考