企业官网建设流程全解析

Bitcoin Core 旧钱包迁移到描述符钱包：migratewallet 操作、核对与回退要点

【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin

如果你用 Bitcoin Core 加载一个老钱包时，收到"legacy wallet 需要先迁移"的提示，或者想把加密的旧 HD 钱包统一进描述符（Descriptor）体系，就需要做一次钱包迁移。这里以官方migratewallet命令为主线，说明迁移前该确认什么、命令怎么跑、结果怎么核对，以及万一失败如何用备份回退。

迁移前：先弄清钱包会变成什么样

理解三件事，能避免迁移后"钱包数量对不上"的困惑：

• 迁移会创建一个与原钱包同名的描述符钱包，原来的地址和私钥都会被写入其中。
• 描述符钱包不允许私钥和纯监控脚本混装，所以原钱包里若有监控地址（watch-only），还会额外生成<原名>_watchonly；若存在"可解但未被监控"的脚本，则可能再多一个<原名>_solvables。
• 如果旧钱包里只有监控脚本、没有任何私钥，则只会创建_watchonly钱包，不会有同名主钱包。

另外两点值得提前知道：新钱包生成地址沿用原来的 BIP 32 种子，但改用 BIP 44/49/84/86 标准派生路径；migratewallet官方说明"可能需要很长时间完成，建议调大 RPC 客户端超时"，跑起来没反应不代表卡死。

执行步骤：备份先行，再跑 migratewallet

迁移本身是"尽力而为"的过程——旧钱包里脚本组合形态极多，官方工具只保证尽力覆盖。所以稳妥顺序是先留一份自己的备份，再迁移。

# 第 1 步：在旧钱包上手工备份一份，存到安全位置 bitcoin-cli -rpcwallet="legacy-wallet" backupwallet "legacy-wallet-backup.dat" # 第 2 步：执行迁移；加密钱包必须把口令作为第二个参数传入 bitcoin-cli migratewallet "legacy-wallet" "你的钱包口令"

预期结果：命令正常返回，包含四段信息——主钱包名wallet_name、视情况出现的watchonly_name/solvables_name，以及backup_path。这个路径指向工具自动生成的<钱包名>-<时间戳>.legacy.bak，它就在钱包目录里，是迁移失败时的回退凭据，先记下来。

常见报错只有一类需要特别注意：钱包是加密的但没提供口令（或口令不对）。这种情况下没有产生迁移结果，直接补上正确口令重跑即可，旧钱包原封不动。

迁移后：如何核对新钱包确实完整

核对分四步，全部通过才算完成：

1. 钱包名对得上：对同名新钱包执行getwalletinfo，确认钱包名、加密状态与迁移前记录一致。
2. 余额对得上：执行getbalance，与迁移前手工记录的可用余额比对。若旧钱包含监控脚本，还需对_watchonly钱包各核对一次。
3. 描述符覆盖对得上：执行listdescriptors true，确认钱包内的地址都能对应到描述符。发现某些老地址没有对应描述符，说明该脚本没被迁移进来（属于已知限制，可在项目 issue 跟踪器中反馈）。
4. 新备份已建立：迁移完成后旧备份已失效于新钱包，必须对新钱包重新执行一次backupwallet，把备份文件放到独立存储位置。

回退方案：失败或异常时怎么退回

⚠️ 在确认新钱包余额、描述符都无误、且新备份已建立之前，不要删除自动备份文件，也不要卸载它。

• 迁移中途失败或结果异常：用restorewallet从.legacy.bak恢复，例如bitcoin-cli restorewallet "legacy-wallet" "/钱包目录/xxx.legacy.bak"，即可恢复出原钱包。
• 恢复后涉及重新扫描：启动节点时加上-blockfilterindex=1，利用区块过滤器可显著加快重扫速度（这是restorewallet帮助文档中的官方提示）。
• 迁移完成但漏了个别脚本：先确认该脚本是否重要；重要且无法通过其他途径恢复的，同样可用.legacy.bak回退，再等待后续版本修复或寻求社区协助。
• 只想验证流程、不想动生产钱包：先在测试网（Testnet）上完整走一遍"备份—迁移—核对—回退"，确认口令、路径、超时都没问题后再操作主网钱包。

附：用基准测试量化迁移耗时

如果你对迁移耗时没有概念，或者想验证自己节点上是否出现性能回归，可以用仓库自带的专项基准：src/bench/wallet_migration.cpp会构造一个含监控地址、500 个私钥及对应交易的模拟旧钱包，然后完整跑一遍迁移并计时。

cmake -B build -DBUILD_BENCH=ON cmake --build build -t bench_bitcoin build/bin/bench_bitcoin -filter=wallet_migration

它给出的是你自己机器上的参考耗时。钱包越大（私钥数、交易数越多）耗时越长，拿它和迁移生产钱包前的预期做对比即可，不必追求某个固定数字。

收尾清单

• 迁移前手工backupwallet一份 ✅
• 加密钱包迁移时带入口令 ✅
• 迁移返回后记下backup_path✅
• 新钱包getbalance、listdescriptors核对通过 ✅
• 新钱包重新备份、旧备份暂不删除 ✅

做到这五步，迁移就处在"最坏情况可回退"的安全状态；之后无论钱包规模多大，流程都是一样的。

【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin