Bitcoin Core 钱包管理实战创建、加密、备份、恢复与 Descriptor 迁移【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin本文围绕 Bitcoin Core 仓库中的钱包管理文档展开系统讲解钱包的完整生命周期从createwallet创建、encryptwallet加密、backupwallet备份到restorewallet恢复以及将 Legacy 钱包迁移为 Descriptor 钱包的migratewallet流程。读完本文后你可以独立完成多钱包环境下各操作系统路径配置、RPC 参数选择、备份频率制定与故障恢复的全部操作并能对照源码理解每个 RPC 的实际行为边界。1. 创建钱包0.21 之后没有默认钱包自 0.21 版本起Bitcoin Core 不再附带默认钱包。钱包通过createwalletRPC 或 GUI 的Create wallet菜单项创建GUI 主屏幕在没有任何钱包加载时会显示Create a new wallet按钮也可以通过File→Create wallet创建。最基本的创建命令如下它创建的是一个 Descriptor 钱包$ bitcoin-cli createwallet wallet-01bitcoin rpc也可以替换bitcoin-cli使用。更多参数信息可通过bitcoin-cli help createwallet查看。1.1 createwallet 的完整参数从源码 createwallet 定义 可以看到该 RPC 支持 8 个参数比文档示例更丰富参数类型默认值说明wallet_nameSTR必填新钱包名称。若传入的是路径钱包将创建在该路径位置disable_private_keysBOOLfalse禁用私钥仅允许只监视watchonly用途blankBOOLfalse创建空钱包无任何密钥后续可用importdescriptors导入passphraseSTR省略创建时即用该密码加密钱包avoid_reuseBOOLfalse跟踪金币复用出于隐私考虑区分干净币与脏币descriptorsBOOLtrue若设置必须为true即当前只能创建 Descriptor 钱包load_on_startupBOOL省略true将钱包加入启动加载列表false移除null保持不变external_signerBOOLfalse使用硬件钱包等外部签名器要求配置-signer且必须同时设置disable_private_keys和descriptors为true创建时直接加密的写法-named调用形式$ bitcoin-cli -named createwallet wallet_namewallet-01 passphrasepassphrase1.2 默认钱包目录与自定义路径默认情况下钱包创建在数据目录的wallets子目录下各操作系统的默认位置如下操作系统默认钱包目录Linux/home/user/.bitcoin/walletsWindowsC:\Users\user\AppData\Local\Bitcoin\walletsmacOS/Users/user/Library/Application Support/Bitcoin/wallets用户可通过-datadir或-walletdir初始化参数修改默认位置。注意createwallet的wallet_name参数本身也接受路径传入路径时钱包会直接建在该位置见 源码参数注释这是与-walletdir并行的另一条自定义途径。2. 加密钱包权衡安全与可恢复性wallet.dat文件默认不加密。一旦攻击者拿到存放钱包或备份的设备即可直接读取。加密可以防止未授权访问但需要清醒认识以下事实与源码行为一致加密后若忘记口令没有任何恢复途径币将永久丢失。这是一个需要用户仔细权衡的 tradeoff加密并不能对抗更高级的进攻手段例如攻击者在用户机器上安装键盘记录器窃取口令加密或修改口令后必须立即重新备份。原因是加密过程会清空 keypool 并生成新的 HD seed——新 seed 收到币之后旧备份无法恢复。这一行为在 encryptwallet 帮助文本 中被明确标注为 IMPORTANTFor security reasons, the encryption process will generate a new HD seed, resulting in the creation of a fresh set of active descriptors. Therefore, it is crucial to securely back up the newly generated wallet file using the backupwallet RPC.加密命令$ bitcoin-cli -rpcwalletwallet-01 encryptwallet passphrase修改口令用walletpassphrasechange$ bitcoin-cli -rpcwalletwallet-01 walletpassphrasechange oldpassphrase newpassphrase其中-rpcwallet参数指定要操作的钱包名。从 encryptwallet 实现 还能确认两个边界条件对不含私钥的钱包调用会报 Error: wallet does not contain private keys, nothing to encrypt.对已加密钱包重复调用会报 Error: running with an encrypted wallet, but encryptwallet was called.此时应改用walletpassphrasechange。加密仅作用于私钥交易记录等其余钱包信息依然可见。3. 解锁钱包walletpassphrase 与超时机制加密钱包在未解锁时执行任何私钥相关操作如发送都会收到错误$ bitcoin-cli -rpcwalletwallet-01 sendtoaddress tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx 0.01 error code: -13 error message: Error: Please enter the wallet passphrase with walletpassphrase first.解锁需调用walletpassphrase第二个参数timeout为解密密钥在内存中保留的秒数到期后需再次执行$ bitcoin-cli -rpcwalletwallet-01 walletpassphrase passphrase 120从 walletpassphrase 实现 可补充两点细节timeout上限为 100000000约 3 年对已解锁的钱包再次调用walletpassphrase会覆盖旧的解锁时间而不是叠加。操作完成后建议用walletlock提前上锁。若钱包正处于 rescan 过程中尝试上锁会提示先调用abortrescan见 walletlock 实现。GUI 中没有专门的解锁菜单项——发送比特币时会自动弹出密码输入框。4. 备份钱包为什么必须用 backupwallet备份必须使用backupwalletRPC 或 GUI 的Backup Wallet菜单项以保证拷贝时钱包文件处于一致的安全状态。RPC 的destination参数必须包含文件名否则返回 Error: Wallet backup failed!——这一点在 backupwallet 实现 中可得到印证RPC 先调用BlockUntilSyncedToCurrentChain()等待钱包同步到当前链尖再对cs_wallet加锁后执行拷贝失败即抛出文档所述的错误消息。$ bitcoin-cli -rpcwalletwallet-01 backupwallet /home/node01/Backups/backup-01.datGUI 流程在右上角Wallet下拉列表选择钱包若列表不存在可先用File→Open Wallet加载然后File→Backup Wallet…。存放与运维建议备份文件应存放在一台或多台离线设备上设备需足够可靠、无恶意软件定期验证备份可用性避免真正需要时才发现损坏若本机疑似存在恶意软件恢复备份时不要将其接入联网设备以免备份在恢复过程中被感染若钱包与所有备份同时丢失其中的比特币将永久无法访问。功能层面对应的自动化测试在 wallet_backup.py 与 wallet_basic.py 中。5. 备份频率HD 钱包与非 HD 钱包的差异理解备份频率需要先理解钱包的密钥模型演变早期 Bitcoin Core 钱包是互不相关私钥的集合。如果非 HD 钱包收到资金后从该地址生成之前的备份恢复则发往该地址的币会全部丢失——没有确定性机制可以重新推导出该地址0.13 版本 引入 HD分层确定性钱包后所有地址都由 HD seed 推导恢复旧备份不再丢失资金。因此HD 钱包单次备份即可在任何时间恢复币。但仍建议每周定期备份或在积累了大量新交易后备份以保留标签labels等元数据。元数据无法通过区块链重新扫描找回——备份过旧元数据就永久丢失0.13 之前创建的 Legacy 非 HD 钱包不满足上述条件必须在每次使用约 100 个密钥之后备份或为了元数据更频繁地备份。6. 从备份恢复钱包恢复使用restorewalletRPC 或 GUI 的Restore WalletFile→Restore Wallet…$ bitcoin-cli restorewallet restored-wallet /home/node01/Backups/backup-01.dat随后可用getwalletinfo确认钱包完整恢复$ bitcoin-cli -rpcwalletrestored-wallet getwalletinfoGUI 中也可通过File→Open wallet加载恢复后的钱包。从 restorewallet 实现 补充三个实用信息加速重扫帮助文本指出启动时加上-blockfilterindex1开启区块过滤器索引rescan 会显著变快——对大钱包尤其值得配置第三个参数load_on_startup可选true将恢复的钱包加入启动加载列表false移除null不改变返回值成功时返回 JSON包含name字段恢复后的钱包名和可选的warnings数组可用于判断恢复是否带有告警。该功能的行为在功能测试 wallet_backup.py 和 wallet_backwards_compatibility.py 中有覆盖。7. 钱包口令Wallet Passphrase的定位与局限这部分澄清一个常见误解钱包口令不是助记词两者职责完全不同。不是 SeedHD seed助记词是推导私钥/公钥的主密钥口令则是保护钱包内私钥的另一层安全机制是访问资金的额外认证层防未授权访问当他人接触到你处于活动状态的钱包应用所在的电脑时口令能阻止其访问资金或发起交易。但同样要意识到有访问权限的人可能通过键盘记录器窃取你的口令不加密元数据与公钥口令保护的是私钥与资金访问权交易历史、涉及的公钥等信息仍然可见丢失即丢失资金口令过于复杂导致忘记意味着钱包永远无法解锁资金永久不可访问。8. 将 Legacy 钱包迁移为 Descriptor 钱包Legacy传统非 Descriptor钱包可通过migratewalletRPC 迁移为 Descriptor 钱包。migratewallet 定义 与文档描述一致并补充了两个参数细节加密钱包必须提供passphrase参数迁移耗时可能较长建议调大 RPC 客户端超时。RPC 还会在迁移前自动创建备份文件名为wallet name-timestamp.legacy.bak出错时可用restorewallet回滚。迁移规则迁移后原钱包的所有地址与私钥会被加入一个与原钱包同名的新 Descriptor 钱包由于 Descriptor 钱包不允许同时持有私钥和只监视脚本迁移可能额外产生最多两个钱包name_watchonly包含全部 watchonly 脚本name_solvables包含钱包知道但没有监视对应 P2(W)SH 包装脚本的脚本。若 Legacy 钱包只含 watchonly 脚本而无任何私钥则只创建name_watchonly且该只监视 Descriptor 钱包不启用私钥同名 Descriptor 钱包不会创建。地址生成方式改变迁移后仍使用同一 BIP 32 seed但会改用 BIP 44/49/84/86 标准派生路径。迁移完成后必须为钱包创建新备份。尽力而为的迁移Legacy 钱包可能知晓、监视、可签名的脚本组合数量极其庞大migratewallet只做 best effort 捕获存在个别脚本被遗漏的可能。若迁移意外失败或漏掉脚本应向上游提交 issue。原始钱包的备份name-timestamp.legacy.bak位于钱包目录中可按照本文第 6 节的方法恢复。迁移过程包括回滚与备份命名由功能测试 wallet_migration.py 与 wallet_ancient_migration.py 验证可作为行为正确性的参考依据。9. 实操要点速查场景命令 / 操作关键注意创建 Descriptor 钱包bitcoin-cli createwallet wallet-01默认路径在wallets目录可用-walletdir改变创建并直接加密bitcoin-cli -named createwallet wallet_namewallet-01 passphrase...密码丢失 资金永久丢失加密已有钱包bitcoin-cli -rpcwalletwallet-01 encryptwallet passphrase生成新 HD seed立即重新备份改密码walletpassphrasechange old new改完同样立即备份解锁walletpassphrase passphrase 120timeout 上限约 3 年重复调用覆盖旧超时上锁walletlockrescan 中需先abortrescan备份backupwallet /path/backup-01.dat目标必须带文件名恢复restorewallet name /path/backup-01.dat加-blockfilterindex1启动可显著加速重扫Legacy 迁移migratewallet加密钱包需传passphrase迁移后建新备份整体来看Bitcoin Core 的钱包管理围绕钱包文件 RPC 生命周期展开创建createwallet→ 加密encryptwallet→ 解锁/上锁walletpassphrase/walletlock→ 备份backupwallet→ 恢复restorewallet→ 迁移migratewallet。RPC 定义集中在 src/wallet/rpc/ 下的wallet.cpp、backup.cpp、encrypt.cpp等文件行为验证集中在 test/functional/ 的wallet_*系列测试阅读源码与测试是核对本文各结论的最佳途径。【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Bitcoin Core 钱包管理实战：创建、加密、备份、恢复与 Descriptor 迁移
Bitcoin Core 钱包管理实战创建、加密、备份、恢复与 Descriptor 迁移【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin本文围绕 Bitcoin Core 仓库中的钱包管理文档展开系统讲解钱包的完整生命周期从createwallet创建、encryptwallet加密、backupwallet备份到restorewallet恢复以及将 Legacy 钱包迁移为 Descriptor 钱包的migratewallet流程。读完本文后你可以独立完成多钱包环境下各操作系统路径配置、RPC 参数选择、备份频率制定与故障恢复的全部操作并能对照源码理解每个 RPC 的实际行为边界。1. 创建钱包0.21 之后没有默认钱包自 0.21 版本起Bitcoin Core 不再附带默认钱包。钱包通过createwalletRPC 或 GUI 的Create wallet菜单项创建GUI 主屏幕在没有任何钱包加载时会显示Create a new wallet按钮也可以通过File→Create wallet创建。最基本的创建命令如下它创建的是一个 Descriptor 钱包$ bitcoin-cli createwallet wallet-01bitcoin rpc也可以替换bitcoin-cli使用。更多参数信息可通过bitcoin-cli help createwallet查看。1.1 createwallet 的完整参数从源码 createwallet 定义 可以看到该 RPC 支持 8 个参数比文档示例更丰富参数类型默认值说明wallet_nameSTR必填新钱包名称。若传入的是路径钱包将创建在该路径位置disable_private_keysBOOLfalse禁用私钥仅允许只监视watchonly用途blankBOOLfalse创建空钱包无任何密钥后续可用importdescriptors导入passphraseSTR省略创建时即用该密码加密钱包avoid_reuseBOOLfalse跟踪金币复用出于隐私考虑区分干净币与脏币descriptorsBOOLtrue若设置必须为true即当前只能创建 Descriptor 钱包load_on_startupBOOL省略true将钱包加入启动加载列表false移除null保持不变external_signerBOOLfalse使用硬件钱包等外部签名器要求配置-signer且必须同时设置disable_private_keys和descriptors为true创建时直接加密的写法-named调用形式$ bitcoin-cli -named createwallet wallet_namewallet-01 passphrasepassphrase1.2 默认钱包目录与自定义路径默认情况下钱包创建在数据目录的wallets子目录下各操作系统的默认位置如下操作系统默认钱包目录Linux/home/user/.bitcoin/walletsWindowsC:\Users\user\AppData\Local\Bitcoin\walletsmacOS/Users/user/Library/Application Support/Bitcoin/wallets用户可通过-datadir或-walletdir初始化参数修改默认位置。注意createwallet的wallet_name参数本身也接受路径传入路径时钱包会直接建在该位置见 源码参数注释这是与-walletdir并行的另一条自定义途径。2. 加密钱包权衡安全与可恢复性wallet.dat文件默认不加密。一旦攻击者拿到存放钱包或备份的设备即可直接读取。加密可以防止未授权访问但需要清醒认识以下事实与源码行为一致加密后若忘记口令没有任何恢复途径币将永久丢失。这是一个需要用户仔细权衡的 tradeoff加密并不能对抗更高级的进攻手段例如攻击者在用户机器上安装键盘记录器窃取口令加密或修改口令后必须立即重新备份。原因是加密过程会清空 keypool 并生成新的 HD seed——新 seed 收到币之后旧备份无法恢复。这一行为在 encryptwallet 帮助文本 中被明确标注为 IMPORTANTFor security reasons, the encryption process will generate a new HD seed, resulting in the creation of a fresh set of active descriptors. Therefore, it is crucial to securely back up the newly generated wallet file using the backupwallet RPC.加密命令$ bitcoin-cli -rpcwalletwallet-01 encryptwallet passphrase修改口令用walletpassphrasechange$ bitcoin-cli -rpcwalletwallet-01 walletpassphrasechange oldpassphrase newpassphrase其中-rpcwallet参数指定要操作的钱包名。从 encryptwallet 实现 还能确认两个边界条件对不含私钥的钱包调用会报 Error: wallet does not contain private keys, nothing to encrypt.对已加密钱包重复调用会报 Error: running with an encrypted wallet, but encryptwallet was called.此时应改用walletpassphrasechange。加密仅作用于私钥交易记录等其余钱包信息依然可见。3. 解锁钱包walletpassphrase 与超时机制加密钱包在未解锁时执行任何私钥相关操作如发送都会收到错误$ bitcoin-cli -rpcwalletwallet-01 sendtoaddress tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx 0.01 error code: -13 error message: Error: Please enter the wallet passphrase with walletpassphrase first.解锁需调用walletpassphrase第二个参数timeout为解密密钥在内存中保留的秒数到期后需再次执行$ bitcoin-cli -rpcwalletwallet-01 walletpassphrase passphrase 120从 walletpassphrase 实现 可补充两点细节timeout上限为 100000000约 3 年对已解锁的钱包再次调用walletpassphrase会覆盖旧的解锁时间而不是叠加。操作完成后建议用walletlock提前上锁。若钱包正处于 rescan 过程中尝试上锁会提示先调用abortrescan见 walletlock 实现。GUI 中没有专门的解锁菜单项——发送比特币时会自动弹出密码输入框。4. 备份钱包为什么必须用 backupwallet备份必须使用backupwalletRPC 或 GUI 的Backup Wallet菜单项以保证拷贝时钱包文件处于一致的安全状态。RPC 的destination参数必须包含文件名否则返回 Error: Wallet backup failed!——这一点在 backupwallet 实现 中可得到印证RPC 先调用BlockUntilSyncedToCurrentChain()等待钱包同步到当前链尖再对cs_wallet加锁后执行拷贝失败即抛出文档所述的错误消息。$ bitcoin-cli -rpcwalletwallet-01 backupwallet /home/node01/Backups/backup-01.datGUI 流程在右上角Wallet下拉列表选择钱包若列表不存在可先用File→Open Wallet加载然后File→Backup Wallet…。存放与运维建议备份文件应存放在一台或多台离线设备上设备需足够可靠、无恶意软件定期验证备份可用性避免真正需要时才发现损坏若本机疑似存在恶意软件恢复备份时不要将其接入联网设备以免备份在恢复过程中被感染若钱包与所有备份同时丢失其中的比特币将永久无法访问。功能层面对应的自动化测试在 wallet_backup.py 与 wallet_basic.py 中。5. 备份频率HD 钱包与非 HD 钱包的差异理解备份频率需要先理解钱包的密钥模型演变早期 Bitcoin Core 钱包是互不相关私钥的集合。如果非 HD 钱包收到资金后从该地址生成之前的备份恢复则发往该地址的币会全部丢失——没有确定性机制可以重新推导出该地址0.13 版本 引入 HD分层确定性钱包后所有地址都由 HD seed 推导恢复旧备份不再丢失资金。因此HD 钱包单次备份即可在任何时间恢复币。但仍建议每周定期备份或在积累了大量新交易后备份以保留标签labels等元数据。元数据无法通过区块链重新扫描找回——备份过旧元数据就永久丢失0.13 之前创建的 Legacy 非 HD 钱包不满足上述条件必须在每次使用约 100 个密钥之后备份或为了元数据更频繁地备份。6. 从备份恢复钱包恢复使用restorewalletRPC 或 GUI 的Restore WalletFile→Restore Wallet…$ bitcoin-cli restorewallet restored-wallet /home/node01/Backups/backup-01.dat随后可用getwalletinfo确认钱包完整恢复$ bitcoin-cli -rpcwalletrestored-wallet getwalletinfoGUI 中也可通过File→Open wallet加载恢复后的钱包。从 restorewallet 实现 补充三个实用信息加速重扫帮助文本指出启动时加上-blockfilterindex1开启区块过滤器索引rescan 会显著变快——对大钱包尤其值得配置第三个参数load_on_startup可选true将恢复的钱包加入启动加载列表false移除null不改变返回值成功时返回 JSON包含name字段恢复后的钱包名和可选的warnings数组可用于判断恢复是否带有告警。该功能的行为在功能测试 wallet_backup.py 和 wallet_backwards_compatibility.py 中有覆盖。7. 钱包口令Wallet Passphrase的定位与局限这部分澄清一个常见误解钱包口令不是助记词两者职责完全不同。不是 SeedHD seed助记词是推导私钥/公钥的主密钥口令则是保护钱包内私钥的另一层安全机制是访问资金的额外认证层防未授权访问当他人接触到你处于活动状态的钱包应用所在的电脑时口令能阻止其访问资金或发起交易。但同样要意识到有访问权限的人可能通过键盘记录器窃取你的口令不加密元数据与公钥口令保护的是私钥与资金访问权交易历史、涉及的公钥等信息仍然可见丢失即丢失资金口令过于复杂导致忘记意味着钱包永远无法解锁资金永久不可访问。8. 将 Legacy 钱包迁移为 Descriptor 钱包Legacy传统非 Descriptor钱包可通过migratewalletRPC 迁移为 Descriptor 钱包。migratewallet 定义 与文档描述一致并补充了两个参数细节加密钱包必须提供passphrase参数迁移耗时可能较长建议调大 RPC 客户端超时。RPC 还会在迁移前自动创建备份文件名为wallet name-timestamp.legacy.bak出错时可用restorewallet回滚。迁移规则迁移后原钱包的所有地址与私钥会被加入一个与原钱包同名的新 Descriptor 钱包由于 Descriptor 钱包不允许同时持有私钥和只监视脚本迁移可能额外产生最多两个钱包name_watchonly包含全部 watchonly 脚本name_solvables包含钱包知道但没有监视对应 P2(W)SH 包装脚本的脚本。若 Legacy 钱包只含 watchonly 脚本而无任何私钥则只创建name_watchonly且该只监视 Descriptor 钱包不启用私钥同名 Descriptor 钱包不会创建。地址生成方式改变迁移后仍使用同一 BIP 32 seed但会改用 BIP 44/49/84/86 标准派生路径。迁移完成后必须为钱包创建新备份。尽力而为的迁移Legacy 钱包可能知晓、监视、可签名的脚本组合数量极其庞大migratewallet只做 best effort 捕获存在个别脚本被遗漏的可能。若迁移意外失败或漏掉脚本应向上游提交 issue。原始钱包的备份name-timestamp.legacy.bak位于钱包目录中可按照本文第 6 节的方法恢复。迁移过程包括回滚与备份命名由功能测试 wallet_migration.py 与 wallet_ancient_migration.py 验证可作为行为正确性的参考依据。9. 实操要点速查场景命令 / 操作关键注意创建 Descriptor 钱包bitcoin-cli createwallet wallet-01默认路径在wallets目录可用-walletdir改变创建并直接加密bitcoin-cli -named createwallet wallet_namewallet-01 passphrase...密码丢失 资金永久丢失加密已有钱包bitcoin-cli -rpcwalletwallet-01 encryptwallet passphrase生成新 HD seed立即重新备份改密码walletpassphrasechange old new改完同样立即备份解锁walletpassphrase passphrase 120timeout 上限约 3 年重复调用覆盖旧超时上锁walletlockrescan 中需先abortrescan备份backupwallet /path/backup-01.dat目标必须带文件名恢复restorewallet name /path/backup-01.dat加-blockfilterindex1启动可显著加速重扫Legacy 迁移migratewallet加密钱包需传passphrase迁移后建新备份整体来看Bitcoin Core 的钱包管理围绕钱包文件 RPC 生命周期展开创建createwallet→ 加密encryptwallet→ 解锁/上锁walletpassphrase/walletlock→ 备份backupwallet→ 恢复restorewallet→ 迁移migratewallet。RPC 定义集中在 src/wallet/rpc/ 下的wallet.cpp、backup.cpp、encrypt.cpp等文件行为验证集中在 test/functional/ 的wallet_*系列测试阅读源码与测试是核对本文各结论的最佳途径。【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
