Bitcoin Core 0.19.1 发布说明详解：升级方法、平台兼容性与全部修复项剖析

本文以 Bitcoin Core 0.19.1 的官方发布说明 release-notes-0.19.1.md 为主体，完整解读这次小型版本（minor release）的升级步骤、操作系统兼容性与 RISC-V 平台支持，并逐项剖析其钱包、RPC/ZMQ/PSBT、GUI 与构建平台等六大类修复，同时结合当前仓库源码（如 scantxoutset 实现、PSBT 解析、ChainStateFlushed 回调）说明这些修复在代码层面的实际落点，帮助读者理解 0.19.1 各变更的技术含义与适用边界。

发布定位：一次聚焦缺陷修复的小型版本

Bitcoin Core 0.19.1 是一次 minor release。官方发布说明明确其定位：

This minor release includes various bug fixes and performance improvements, as well as updated translations.（本次小型版本包含多项缺陷修复与性能改进，以及更新后的翻译。）

也就是说，0.19.1 不引入新功能，而是对 0.19.0 的稳定性收尾。所有变更可按六大类归纳：Wallet（钱包）、RPC and other APIs（RPC 与其他 API）、GUI、Tests and QA（测试与质量保障）、Platform support（平台支持）、Miscellaneous（杂项），外加翻译更新。对正在运行 0.19.0 的节点与钱包使用者而言，升级到 0.19.1 的主要收益是：PSBT 解析的越界防护、scantxoutset 参数校验收紧、ZMQ 多通知器下的正确性修复，以及钱包地址复用判断的若干修正。

官方渠道信息（来自发布说明原文）：

• 预编译发布包自 bitcoincore.org 的 0.19.1 目录提供；
• 缺陷报告走 GitHub issue tracker；
• 安全与更新通知可订阅 bitcoincore.org 的公告邮件列表。

如何升级到 0.19.1

发布说明给出了明确的升级操作流程，这里完整保留其要点：

1. 先干净关闭旧版本：如果正在运行旧版本，先将其关闭，并等待它完全退出——对较老的版本来说，完全停止可能需要几分钟时间。
2. 按平台部署新程序：
   • Windows：运行安装程序（installer）；
   • macOS：覆盖 /Applications/Bitcoin-Qt；
   • Linux：直接替换 bitcoind / bitcoin-qt 可执行文件。
3. 跨版本升级：从已到达 EOL（End of Life，停止维护）的旧版本直接升级是可行的；但注意，如果 datadir（数据目录）需要迁移，这个过程可能耗时较长。旧版本的比特币钱包在升级后通常仍受支持。

实操含义：对于以 bitcoind 方式运行的 Linux 节点，升级本质上是"停止进程 → 替换二进制 → 重启"，无需迁移数据库（除非跨越了需要迁移的大版本）。升级期间应保留数据目录备份，尤其是钱包文件。

兼容性支持矩阵

发布说明对 0.19.1 的平台支持范围做了明确声明，这些约束对部署决策有直接影响：

平台	支持状态	备注
Linux 内核系统	支持并广泛测试	主要测试平台
macOS 10.10 及以上	支持	自 0.17.0 起因 Qt 5.9.x 要求，不再支持 macOS 10.10 以下
Windows 7 及以上	支持	—
其他 Unix-like 系统	可能可用	应能在多数类 Unix 系统上工作，但测试频率较低，官方不推荐在不支持的系统上使用
RISC-V	本版本新增	预编译发布包首次提供 RISC-V 平台二进制

两个值得注意的 macOS 细节（原文照录）：

• 自 Bitcoin Core 0.17.0 起，由于构建使用的 Qt 5.9.x 要求 macOS 10.10+，更早的 macOS 版本不再受支持；
• 0.19.1 的 GUI 在 macOS 开启"深色模式"时不会随之改变外观。

"提供 RISC-V 平台预编译二进制"是这一版平台支持上的增量亮点，意味着非 x86 的单指令集架构用户第一次可以不依赖自行编译。

0.19.1 变更日志全解

以下逐条列出发布说明中的完整 changelog，并对其中具有代码落点可考的修复补充源码级解读。

Wallet（钱包）

• #17643 Fix origfee return for bumpfee with feerate arg（instagibbs）：修复 bumpfee 携带费率参数时 origfee（原始交易费用）返回值不正确的问题。
• #16963 Fix unique_ptr usage in boost::signals2（promag）：修正 boost::signals2 信号连接中 unique_ptr 的使用方式，属于内存管理正确性修复。
• #17258 Fix issue with conflicted mempool tx in listsinceblock（adamjonas, mchrostowski）：修复 listsinceblock 在处理"处于内存池但已冲突"的交易时的问题。
• #17924 Bug: IsUsedDestination shouldn't use key id as script id for ScriptHash（instagibbs）：修复 IsUsedDestination 判定地址是否已使用时，不应把 key id 当作 ScriptHash 的 script id 来匹配的问题。
• #17621 IsUsedDestination should count any known single-key address（instagibbs）：IsUsedDestination 应把所有已知的单钥地址都计入"已使用"，改善地址复用启发式。
• #17843 Reset reused transactions cache（fjahr）：重置"被复用交易"缓存，避免缓存陈旧导致选币行为错误。

这几项的共同主题是地址复用启发式与缓存正确性。0.19 版本引入了对地址复用（address reuse）的检测与提醒机制，0.19.1 修正了其判定边界（#17924/#17621）以及与之联动的交易缓存（#17843）。从源码结构看，IsUsedDestination 这类判定在后续版本中已迁移到钱包层的 WalletModel/地址使用统计相关代码中，0.19.1 的修复正是为了让"是否复用地址"的统计既不漏判（单钥地址）也不误判（key id 与 script id 混淆）。

RPC and other APIs（RPC 与其他 API）

• #17687 cli: Fix fatal leveldb error when specifying -blockfilterindex=basic twice（brakmic）：修复通过 bitcoin-cli/命令行把 -blockfilterindex=basic 重复指定两次时触发致命 leveldb 错误的问题——重复的命令行选项本应被幂等处理。
• #17728 require second argument only for scantxoutset start action（achow101）：收紧 scantxoutset 的参数校验——只有 start 动作才要求第二个参数（scanobjects 描述符列表）。
• #17445 zmq: Fix due to invalid argument and multiple notifiers（promag）：修复 ZMQ 发布器在参数无效且存在多个通知器（notifiers）时的错误处理。
• #17524 psbt: handle unspendable psbts（achow101）：PSBT 流程要能处理"不可花费"（unspendable）的部分签名交易，而非直接失败。
• #17156 psbt: check that various indexes and amounts are within bounds（achow101）：PSBT 解析时校验各类索引与金额是否在合法范围内，堵住越界输入。

其中两项在当前仓库源码中可以直接看到演进后的实现形态：

1. scantxoutset 的 start 动作强制要求 scanobjects。当前仓库 src/rpc/blockchain.cpp 中，action == "start" 分支先通过 CoinsViewScanReserver 抢占扫描名额（已存在扫描则报 Scan already in progress），随后：

const UniValue* scanobjects = self.MaybeArg<UniValue>("scanobjects");
if (!scanobjects) {
    throw JSONRPCError(RPC_MISC_ERROR, "scanobjects argument is required for the start action");
}

status/abort 动作则完全不触碰 scanobjects——这正是 #17728 修复后沉淀下来的参数契约：第二个参数仅对 start 必需。描述符语法（addr、raw、combo、pkh、sh(multi(...))、tr 等）的完整说明见 doc/descriptors.md。

2. PSBT 的边界与合并防护。#17156 与 #17524 针对的是 PartiallySignedTransaction 的解析健壮性。当前仓库 src/psbt.cpp 中，Merge 首先强制两个 PSBT 必须对应同一交易且版本一致，否则直接拒绝：

std::optional<Txid> this_id = GetUniqueID();
std::optional<Txid> psbt_id = psbt.GetUniqueID();
if (!this_id || !psbt_id || this_id != psbt_id) {
    return false;
}
if (GetVersion() != psbt.GetVersion()) {
    return false;
}

构造阶段也以 assert(m_version == 0 || m_version == 2) 限制版本取值。这类"输入先校验、再处理"的模式，正是 0.19.1 为 PSBT 系列 API 加固的延续。PSBT 的完整协议说明可参考 doc/psbt.md。

GUI

• #17427 Fix missing qRegisterMetaType for size_t（hebasto）：补上 Qt 元类型注册，修复跨线程队列信号中 size_t 参数的传递问题。
• #17695 disable File→CreateWallet during startup（fanquake）：启动期间禁用"文件 → 创建钱包"菜单项，避免初始化未完成时创建钱包引发异常状态。
• #17634 Fix comparison function signature（hebasto）：修正排序比较函数的签名（使其符合 std::sort/Qt 容器要求的布尔返回约定），消除未定义行为风险。
• #18062 Fix unintialized WalletView::progressDialog（promag）：修复 WalletView::progressDialog 未初始化就使用的问题。

Tests and QA（测试与质量保障）

• #17416 Appveyor improvement - text file for vcpkg package list（sipsorcery）：Appveyor CI 中使用纯文本文件管理 vcpkg 包列表，提升 Windows 构建流水线稳定性。
• #17488 fix "bitcoind already running" warnings on macOS（fanquake）：修复 macOS 上功能测试误报"bitcoind 已在运行"的警告。
• #17980 add missing #include to fix compiler errors（kallewoof）：补上缺失的头文件以修复部分编译器下的编译错误。

Platform support（平台支持）

• #17736 Update msvc build for Visual Studio 2019 v16.4（sipsorcery）：将 MSVC 构建更新到 VS 2019 v16.4 工具链。
• #17364 Updates to appveyor config for VS2019 and Qt5.9.8 + msvc project fixes（sipsorcery）：Appveyor 配置同步到 VS2019 + Qt 5.9.8，并修复 MSVC 工程文件。
• #17887 bug-fix macos: give free bytes to F_PREALLOCATE（kallewoof）：macOS 上文件预分配（F_PREALLOCATE 命令）修复，避免把"空闲字节"错误地纳入预分配长度。

从源码结构看，F_PREALLOCATE 对应的是各平台的 ftruncate/F_PREALLOCATE 系统调用封装（compat/ 目录下的 POSIX 兼容层），该修复保证 macOS 上链文件、块文件的预分配不会因错误长度而失败或浪费空间。

Miscellaneous（杂项）

• #17897 init: Stop indexes on shutdown after ChainStateFlushed callback（jimpo）：关停顺序调整——索引（block filter index、coins index 等）应在 ChainStateFlushed 回调之后再停止。当前仓库 src/init.cpp 中保留了这一时序约束的注释：

// FlushStateToDisk generates a ChainStateFlushed callback, which we should avoid missing

其原理是：FlushStateToDisk 会向校验接口（validation interface）发出 ChainStateFlushed 回调，索引模块依赖该回调把内存中的增量状态刷到各自的 LevelDB。如果索引先于回调被停止，可能漏掉最后一批写入。ChainStateFlushed 的回调分发实现见 src/validationinterface.cpp，索引侧的处理见 src/index/base.cpp。

• #17450 util: Add missing headers to util/fees.cpp（hebasto）：为 util/fees.cpp 补齐缺失头文件。
• #17654 Unbreak build with Boost 1.72.0（jbeich）：修复与 Boost 1.72.0 的构建不兼容（该类头文件/接口变更是各发行版升级 Boost 时的常见构建破坏源）。
• #17857 scripts: Fix symbol-check & security-check argument passing（fanquake）：修复 guix 构建脚本中 symbol-check.py 与 security-check.py 的参数传递问题（两个脚本分别位于 contrib/guix/symbol-check.py 与 contrib/guix/security-check.py）。
• #17762 Log to net category for exceptions in ProcessMessages（laanwj）：将 ProcessMessages 中出现的异常统一记录到 net 日志类别，便于排查 P2P 消息处理异常。
• #18100 Update univalue subtree（MarcoFalke）：更新随仓库分发的 UniValue 子树（JSON 解析库，见 src/univalue）。

修复项的技术主线归纳

把 0.19.1 的 20 余项变更放在一起看，可以归纳出四条主线：

1. 输入校验加固：PSBT 索引/金额越界检查（#17156）、scantxoutset 参数契约收紧（#17728）、ZMQ 无效参数处理（#17445）——核心原则是"非法输入在边界处被明确拒绝，而不是深处理中崩溃"。
2. 钱包启发式正确性：IsUsedDestination 的两个修正与复用交易缓存重置，共同让"地址复用检测"这一隐私相关机制的判定更准确、更保守。
3. 生命周期与关停顺序：#17897（索引在 ChainStateFlushed 之后停止）与 #17843（缓存重置）都属于状态机时序问题，修复后降低了异常关停/状态残留的概率。
4. 构建与 CI 现代化：VS2019 工具链、Boost 1.72 兼容、RISC-V 预编译二进制、macOS 预分配修复——0.19.1 显著扩大了可复现构建的覆盖面。

贡献者与致谢

发布说明完整列出了直接贡献者名单，此处照录以保留原始信息：Aaron Clauson、Adam Jonas、Andrew Chow、Fabian Jahr、fanquake、Gregory Sanders、Harris、Hennadii Stepanov、Jan Beich、Jim Posen、João Barbosa、Karl-Johan Alm、Luke Dashjr、MarcoFalke、Michael Chrostowski、Russell Yanofsky、Wladimir J. van der Laan；同时感谢所有通过 Transifex 参与翻译的贡献者。

小结与适用边界

• 0.19.1 是 0.19.x 系列的收尾修复版本，适用前提是当前部署的是 0.19.0；对已使用后续大版本（当前仓库源码为 31.x 时代代码）的节点没有直接意义，但其中的 PSBT 校验与索引关停时序设计在后续版本中继续演进，仍具参考价值。
• 兼容性以发布说明为准：Linux 内核系统、macOS 10.10+（因 Qt 5.9.x 限制，且深色模式外观不适配）、Windows 7+；RISC-V 为首次提供预编译二进制。
• 仓库内可进一步深入的资料：doc/release-notes/release-notes-0.19.0.md（前一版本说明，便于对照变更脉络）、doc/descriptors.md（scantxoutset 描述符语法）、doc/psbt.md（PSBT 协议）、src/rpc/blockchain.cpp（扫描类 RPC 实现）、src/psbt.cpp（PSBT 实现）。