migratewallet迁移怎么验收？

Bitcoin Core migratewallet 会把传统钱包迁移为描述符钱包，并生成恢复备份。本文给出迁移前冻结、长请求保护、返回对象核对和恢复演练清单。

钱包迁移属于不可轻率重试的状态变更。migratewallet 不只是切换一个格式，它可能返回主钱包、watchonly 与 solvables 等不同结果，并在钱包目录写入带时间戳的 legacy 备份；每个产物都要进入验收清单。

迁移成功的定义不只是RPC无报错

迁移验收由四项组成：RPC 明确结束、返回的每个钱包可加载、迁移前资产与地址用途可解释、恢复材料完成独立演练。只看到“无报错”不能关闭变更单。

migratewallet 将钱包迁移为描述符钱包，并明确要求迁移后制作新的钱包备份。 迁移过程会在钱包目录生成带时间戳的 .legacy.bak，错误迁移可通过 restorewallet 使用该备份恢复。

执行前冻结钱包与备份基线

维护窗口开始前执行：

1. 停止收款地址派生与自动签名任务。
2. 记录钱包名称、加密状态、余额和描述符基线。
3. 为加密钱包准备隔离的 passphrase 输入。

同时复制钱包目录之外的既有备份并验证可读性。加密钱包的 passphrase 通过隔离输入提供，不写入 shell 历史或流水线日志。

长请求期间禁止哪些操作

bitcoin-cli -rpcclienttimeout=0 -rpcwallet="<LEGACY_WALLET>" migratewallet "<WALLET_NAME>"

加密钱包必须提供 passphrase；RPC 可能长时间运行，调用端应调整超时而不是在处理中途强制终止。 客户端超时不等于节点端失败。超时后先查 getrpcinfo 和节点日志，禁止立即重复提交或强制终止进程。

主钱包与拆分钱包逐项验收

返回项	验收动作	不通过时
wallet_name	迁移后的主描述符钱包	需要重新加载并核对余额
watchonly_name	可能拆出的仅观察钱包	不可因无私钥而删除
solvables_name	可解但不可签名的材料集合	应检查脚本用途和访问权限
backup_path	自动生成的 legacy 备份路径	迁移后仍要制作新备份

返回可包含主钱包、watchonly 钱包、solvables 钱包名称以及 backup_path，验收时应逐项核对。 主钱包、watchonly 与 solvables 可能各自承载历史用途；任何一个都不能因当前余额为零而直接删除。

迁移失败时的恢复路径

调用端在两分钟后超时，并不表示节点端迁移失败。最危险的动作是立刻重启节点或再次调用。操作者应先查长请求与日志，判断进程是否仍在执行；只有获得明确终态后，才能决定验收或从 legacy 备份恢复。

• 迁移前仍允许业务继续生成地址。
• 客户端超时后立即重复执行。
• 只检查主钱包忽略拆分钱包。
• 看到 legacy 备份便省略迁移后新备份。

恢复路径以 RPC 返回的 backup_path 为起点，使用 restorewallet 在另一数据目录演练。恢复成功后仍要制作新的描述符钱包备份，因为 legacy 备份只服务回退。

变更单证据和恢复资料

复制一个无真实资金的测试钱包，在隔离数据目录执行迁移。复核者按迁移前余额、地址、主钱包、watchonly、solvables、backup_path 和新备份逐项签字，再从备份恢复到另一目录核对可读性。

真实资金钱包必须在维护窗口内操作，且备份介质、口令保管和恢复权限属于组织安全流程。本文不能替代离线恢复演练，也不建议在未经验证的生产钱包上试跑。

迁移后的功能验收不只看余额。应抽样生成一个收款地址、识别找零描述符、构造但不广播一笔测试 PSBT，并核对仅观察材料不会突然获得签名能力。所有验证都在隔离测试资金上完成；任一地址用途与迁移前对不上，就暂停生产加载并走恢复分支。

变更单中的保留项：钱包数据目录权限、磁盘空间和历史版本跨度会影响迁移耗时，实际操作前需在离线副本演练。

• migratewallet 依据：Bitcoin Core 31 migratewallet
• migratewallet 依据：Bitcoin Core 31.0 Release Notes

迁移前可先读 deriveaddresses安全派生、HD密钥审计、描述符检查。