listwalletdir和listwallets怎么区分？

运维脚本里同时出现listwalletdir和listwallets时，最容易写出的错误是：“只要钱包在目录列表中，它就已经可以接收RPC请求”。实际上，可发现、已加载和已完成扫描是三个状态。把它们拆开，备份、重启和故障切换才能复现。

一张表看懂两个列表

RPC	数据来源	回答的问题	不能回答
listwalletdir	配置的钱包目录	哪些钱包可被发现	当前是否已加载
listwallets	当前bitcoind进程	哪些钱包已加载	磁盘上是否还有其他钱包
loadwallet	加载操作	能否将目标加入当前进程	扫描是否已完成
getwalletinfo	已加载钱包	钱包标志、扫描和处理状态	其他未加载钱包状态

listwalletdir返回钱包目录中可被发现的钱包名称以及与加载相关的可选警告。 listwalletdir会列出钱包名称，并可带与加载相关的警告。警告不应被丢弃：监控系统若只取name字段，可能把需要管理员介入的钱包显示为正常。

listwallets只返回当前进程中已加载的钱包名称。 listwallets的范围更窄：它只说当前进程已加载什么。所以两个集合的差集很有价值：在listwalletdir但不在listwallets的项目，可能是备份钱包、手工卸载项、尚未加载项，也可能是加载失败。不能根据差集直接自动删除文件。

一条可重放的启动链

确认-walletdir与容器挂载
  → listwalletdir保存可发现清单与警告
  → 对预期项逐个loadwallet
  → listwallets确认进程状态
  → getwalletinfo检查扫描与标志

loadwallet用于加载钱包，返回已加载名称与警告；调用后仍应用getwalletinfo确认扫描和钱包标志。 loadwallet成功返回名称与警告，但它不能代替加载后验收。描述符钱包可能正在扫描，禁用私钥或外部签名器标志也会改变钱包可执行的操作。如果业务线程在扫描完成前就计算余额，可能报出虚假的资产缺口。

容器环境为什么要额外检查

主机上的钱包目录和容器内-walletdir可能不是同一个路径。挂载只读、UID不匹配、相对路径改变或秘密文件未挂载，都可能让listwalletdir看到的内容与管理员的主机检查不同。启动日志应记录bitcoind解析后的walletdir、加载名称和警告，不记录任何私钥或助记词。

对于绝对路径加载，还要校验路径白名单，避免操作人员或被攻击的控制面将任意文件当钱包加载。RPC的文件系统权限应尽量最小化，钱包目录也不应暴露给网站应用进程。

备份前后要比较的不是文件个数

备份前保存钱包名称、描述符checksum、wallet flags、最后处理区块和扫描状态；恢复后重复同一组检查。两边文件个数相同，不能证明加载的是同一组钱包；列表名称相同，也不能证明描述符和秘钥材料完整。生产恢复演练应使用小额、只读或测试网钱包，不在无监督的情况下操作生产私钥。

启动完成的定义要写清

对多钱包服务，“文件在”、“进程已加载”、“扫描已就绪”必须三个状态分别报告，否则监控的绿灯没有业务意义。

本文的三个可复核核心是：

listwalletdir返回钱包目录中可被发现的钱包名称以及与加载相关的可选警告。
listwallets只返回当前进程中已加载的钱包名称。
loadwallet用于加载钱包，返回已加载名称与警告；调用后仍应用getwalletinfo确认扫描和钱包标志。

目前仍需保留的边界：容器挂载、文件权限和定制-walletdir会改变可见范围，需与运行参数一起审计。

可结合migratewallet迁移验收、listdescriptors审计、getrpcinfo长请求继续查看相邻知识。本文为信息与技术教育内容，不构成投资、交易或法律建议；涉及资产或系统变更时，请先在隔离环境验证并自行承担风险。