Bitcoin Core 28.1 版本详解：升级指南、兼容性说明与关键技术变更（含 -port 洋葱端口推导规则）

导读

本文围绕 Bitcoin Core 28.1 版本的官方发布说明展开，系统梳理该维护版本的升级流程、系统兼容性边界，以及本版本中的 P2P、密钥处理、构建、测试、文档与 CI 等方向的技术变更。作为从 v28.0 演化而来的维护版本，28.1 修复了 v28.0 在多本地节点 + 自定义 -port 场景下的启动失败问题，并对地址管理器内部计数、扩展密钥解码的敏感数据清理做了强化。阅读本文后，你将理解 28.1 的新行为（尤其是默认 Tor 洋葱监听端口如何随 -port 推导）、正确完成跨版本升级与 macOS 自签名操作，并能定位到对应源码中的实现位置加以验证。

---

一、版本总览：维护版本的本质与发布渠道

Bitcoin Core 28.1 属于 v28 系列的一个维护版本（maintenance release）。这类版本通常不会引入新的共识规则或全新的用户界面特性，而是以修复缺陷、改进性能、更新翻译、优化测试与构建基础设施为主。发布说明将其内容概括为：

• 若干新特性（notable features）；
• 各类 Bug 修复；
• 性能改进；
• 更新的多语言翻译（updated translations）。

从官方发布说明的惯例看，正式二进制版本会随发布公告分发，而本仓库（Bitcoin Core integration/staging tree）本身就是构建这些版本号的源码主干。若需从源码自行构建，可参考仓库内的 INSTALL.md、doc/INSTALL_linux.md 与 doc/build 相关文档，并使用 src/CMakeLists.txt 描述的 CMake 构建体系（根目录另见 CMakeLists.txt 与 CMakePresets.json）。

提示：发布说明面向所有使用旧版本的用户，升级路径与兼容性部分为通用操作说明；「Notable changes」小节则逐一对应合并入主干的 GitHub PR 编号，这些编号可在后续章节与仓库源码中交叉验证。

---

二、如何升级（How to Upgrade）

升级步骤

如果正在运行较旧版本，升级前请先完整关停节点：

1. 关闭正在运行的 Bitcoin Core 进程（对守护进程执行优雅关闭，或在 GUI 中退出）；
2. 等待进程完全退出——在某些情况下可能需要几分钟，切勿在数据目录仍被占用时强行覆盖；
3. 按平台完成程序替换：
   • Windows：运行新版安装程序即可；
   • macOS：直接覆盖 /Applications/Bitcoin-Qt；
   • Linux：覆盖 bitcoind / bitcoin-qt 可执行文件。

从 EOL 版本直接升级

发布说明明确指出：直接从已达生命周期终点（EOL）的旧版本升级是可行的，但如果数据目录需要迁移，启动耗时可能变长。同时，旧版本的钱包通常仍然受支持（old wallet versions of Bitcoin Core are generally supported），即低版本创建的旧格式钱包一般无需手工转换即可被新版本加载。

macOS 自签名要求

自 Bitcoin Core 26.0 起，在 macOS 上运行二进制需要先去除隔离属性并完成本地自签名（self signing）。28.1 的说明要求在解包后的二进制目录中执行：

cd /path/to/bitcoin-28.x/bin
xattr -d com.apple.quarantine bitcoin-cli bitcoin-qt bitcoin-tx bitcoin-util bitcoin-wallet bitcoind test_bitcoin
codesign -s - bitcoin-cli bitcoin-qt bitcoin-tx bitcoin-util bitcoin-wallet bitcoind test_bitcoin

xattr -d com.apple.quarantine 移除从网络下载文件时系统附加的隔离标记，而 codesign -s -（签名身份为 -，即临时 ad-hoc 签名）使二进制在本地可运行。注意该操作需针对全部可执行目标逐一执行：bitcoin-cli、bitcoin-qt、bitcoin-tx、bitcoin-util、bitcoin-wallet、bitcoind 以及测试二进制 test_bitcoin。

---

三、兼容性说明（Compatibility）

Bitcoin Core 官方支持并经过广泛测试的操作系统如下：

系统	支持范围
Linux	Kernel 3.17+
macOS	11.0+
Windows	Windows 7 及更新版本

其他类 UNIX 系统（如各 BSD、Solaris 等）通常也能运行，但测试频度较低。官方建议不要在不受支持的系统上使用 Bitcoin Core，以避免潜在的数据完整性与安全问题。

对应源码层面，跨平台构建支持逻辑集中在 depends 目录，其中 depends/hosts/（darwin、mingw32、linux、freebsd、netbsd、openbsd 等）定义了各宿主工具链参数，depends/builders/ 定义了平台差异处理。28.1 中对 NetBSD 构建的修正（见下文 Build 章节）正落在这套 depends 体系中。

---

四、核心变更详解（Notable Changes）

4.1 P2P：默认洋葱监听端口随 -port 推导（修复 v28.0 端口冲突）

这是 28.1 中最值得关注的行为变更（PR #31223）。变更内容可概括为一句话：

当使用 -port 配置选项时，默认的 Tor 洋葱（onion）监听端口将推导为 -port + 1，而不再固定为 8334（主网）。

背景：v28.0 引入的回归

在 v28.0 中，若用户在同一台机器上运行多个本地节点，各节点使用不同的 -port 但不使用 -bind，会由于默认洋葱端口全部固定为同一数值（主网 8334）而产生端口冲突，导致节点启动失败。因为无论 P2P 主监听端口如何设置，所有节点的内嵌 Tor 隐藏服务仍会尝试绑定同一个本地洋葱转发端口。

新规则：-port = x → 洋葱端口 x + 1

28.1 将默认洋葱端口改为跟随 -port：

• 若 -port 取标准默认值（主网 8333），洋葱端口仍为 8334，行为与过去一致；
• 若 -port 取非标准值（如 -port=5555），洋葱监听端口将落在 127.0.0.1:5556，即 -port 加一。

发布说明给出了该场景的完整对照示例：

假设使用非标准值 -port=5555 且未使用 -bind=...=onion：

• 旧行为（≤ v28.0）：Bitcoin Core 在 127.0.0.1:8334 监听入站 Tor 连接；
• 新行为（v28.1）：改为监听 127.0.0.1:5556（即 -port + 1）。

如果你在 torrc 中手工配置了隐藏服务，则需要相应调整。以该示例而言，需将：

HiddenServicePort 8333 127.0.0.1:8334

改为：

HiddenServicePort 8333 127.0.0.1:5556

或者，为恢复旧行为，可显式用 -bind=127.0.0.1:8334=onion 配置 bitcoind。

源码级验证

该推导逻辑可追溯到 src/init.cpp：

// Port to bind to if `-bind=addr` is provided without a `:port` suffix.
const uint16_t default_bind_port =
    static_cast<uint16_t>(args.GetIntArg("-port", Params().GetDefaultPort()));

const uint16_t default_bind_port_onion = default_bind_port + 1;

随后在解析 -bind=<addr>=onion 时（src/init.cpp），不带端口的洋葱绑定参数会以 default_bind_port_onion 作为缺省端口进行地址解析；当用户完全没有提供 -bind/-whitebind 时，则通过 DefaultOnionServiceTarget(default_bind_port_onion) 构造默认洋葱服务目标并加入 onion_binds（src/init.cpp），再交给 src/torcontrol.cpp 的 TorController 完成自动创建洋葱服务。

同时，-port 与 -bind 的参数帮助文本也已同步更新，明确标注「If set to a value x, the default onion listening port will be set to x+1」（见 src/init.cpp），而 -bind 的帮助文本则列出各网络默认洋葱绑定地址为默认端口 + 1（主网 127.0.0.1:8334=onion、testnet3/testnet4 与 signet、regtest 各自遵循同样规则，见 src/init.cpp）。

实践建议

• 只跑单节点且使用默认端口：无需任何改动；
• 单机多节点、各自使用不同 -port 且不用 -bind：这是本修复的主要受益场景，升级后应能正常启动；
• 在 torrc 中手工维护 HiddenServicePort：升级到 28.1 后需检查并同步更新为目标端口（-port + 1），否则 Tor 流量将无法正确转发到节点；
• 希望保持旧监听地址：显式指定 -bind=127.0.0.1:8334=onion 即可。

4.2 P2P/addrman：内部 id 计数改为 int64_t（#30568）

地址管理器（addrman）用于持久化并管理已知对等节点地址。本次变更将其内部 id 计数类型从窄类型提升为 int64_t，消除极长期运行或极端地址规模下计数溢出的风险，也统一了各索引容器所存 id 的整数类型。

在源码中，该类型通过别名统一定义：

// src/addrman_impl.h
//! User-defined type for the internally used nIds
using nid_type = int64_t;

随后 nIdCount、mapInfo、mapAddr、随机化数组 vRandom、vvTried/vvNew 桶及冲突集合 m_tried_collisions 全部改用该类型（见 src/addrman_impl.h）。这一改动属纯内部重构，不影响网络协议或磁盘格式，但对地址表容量上限的语义更稳健。

4.3 Key：DecodeExtKey 清除残留密钥数据（#31166）

BIP32 扩展私钥字符串（xprv 系列）经 Base58Check 解码后会在内存中产生中间字节缓冲，若该缓冲未显式清零，可能成为侧信道或内存取证的风险点。28.1 在 DecodeExtKey 返回路径上对解码缓冲做了确定性擦除。

对应实现位于 src/key_io.cpp：解码流程先 DecodeBase58Check(str, data, 78)，校验扩展密钥前缀（CChainParams::EXT_SECRET_KEY）与长度（BIP32_EXTKEY_SIZE）后调用 key.Decode(...) 填充密钥结构；在函数返回前：

if (!data.empty()) {
    memory_cleanse(data.data(), data.size());
}

memory_cleanse 保证即使编译器优化也不会被消除（相比普通 memset 在内存被复用前可能被优化掉）。同时 CKey 本身以 secure_unique_ptr<KeyType> 持有密钥字节，并暴露 ClearKeyData()（置空智能指针，见 src/key.h），在 src/key.cpp 的析构与复制等路径中均会触发清理，共同构成「中间解码缓冲 + 密钥对象」双层的敏感数据清除策略。

4.4 Build：跨平台编译修正

两个与构建基础设施相关的修复：

• #31013 depends：mingw 交叉编译使用 -gcc-posix 防止库冲突 面向 Windows 的 MinGW-w64 工具链存在 win32 与 posix 两套线程模型。本次修正为交叉编译环境显式选用 -gcc-posix，避免因线程模型不匹配导致链接期库冲突。相关宿主配置见 depends/hosts/mingw32.mk，构建框架见 depends/Makefile 与 depends/funcs.mk。

• #31502 depends：修复 NetBSD 的 CXXFLAGS 对 NetBSD 宿主下 C++ 编译标志的处理做了修正，使 depends/builders/netbsd.mk 给出的标志组合能正确生效，改善 NetBSD 交叉/本机构建一致性。

4.5 Test：测试健壮性与覆盖完善

PR	内容	说明
#31016	feature_fee_estimation.py 增加缺失的同步	修复费用估算功能测试中的竞态，相关脚本见 test/functional/feature_fee_estimation.py
#31448	fuzz：FuzzedDataProvider 引入 <cstdlib>	补充模糊测试基础设施缺失的标准库头文件包含
#31419	test：修复 MIN 宏重定义	规避不同头文件对通用宏 MIN 的重复定义告警
#31563	rpc：扩展 generateblock 中校验互斥锁作用域	在 src/rpc/ 区块生成相关 RPC 中扩大 validation mutex 的持有范围，消除并发安全疑点

这些改动大多不改变用户可见行为，而是提升 CI 环境的稳定性与回归检测能力。

4.6 Doc：配置文件补充 testnet4 分区（#31007）

28.1 为配置文件示例/文档新增 testnet4 分区标题（section header），与仓库对 testnet4 网络的逐步支持相配套。Testnet4 的网络参数（默认端口等）定义于 src/chainparams.cpp（testnet4ChainParams），其默认端口也在 src/init.cpp 的 -port 帮助文本中被显式列出。仓库内完整示例配置由 contrib/devtools/gen-bitcoin-conf.sh 生成（模板入口见 contrib/devtools/README.md），其中 testnet4 分区可按 [testnet4] 的节头语法统一设置网络专属参数。

4.7 CI：Valgrind fuzz 任务注入 LLVM 符号化器（#30961）

CI 基础设施中，针对 Valgrind 模糊测试任务新增 LLVM_SYMBOLIZER_PATH 环境变量，使 sanitizer 栈回溯在 Valgrind 环境下也能正确符号化。对应任务脚本见 ci/test/00_setup_env_native_fuzz_with_valgrind.sh，容器驱动入口为 ci/test/02_run_container.py，任务编排参考 ci/test_run_all.sh。

4.8 Misc：代码卫生与类型安全清理

• #31267 refactor：移除 operator""_mst 中被弃用的空格 对自定义字面量运算符（毫秒时间单位 _mst）的书写形式做规范化整理，消除随 C++ 标准演进被标记为 deprecated 的空白写法，属纯重构；
• #31431 util：MultiIntBitSet::Fill() 使用显式类型转换 在 src/util 的位集合实现中，以显式 cast 取代隐式转换，规避潜在截断告警并提升可读性。

---

五、致谢与翻译

发布说明向直接贡献本版本的所有开发者致谢（fanquake、Hennadii Stepanov、laanwj、MarcoFalke、Martin Zumsande、Marnix、Sebastian Falbesoner），并感谢通过 Transifex 平台参与翻译的社区成员。这也说明本版本包含大量的界面与文档翻译更新，属于维护版本的常规组成部分。

---

六、总结：升级前必读清单

升级到 Bitcoin Core 28.1 前，建议对照以下清单逐项确认：

1. 操作系统是否受支持（Linux Kernel 3.17+ / macOS 11.0+ / Windows 7+）；
2. 先完全关闭旧节点，等待数据目录释放后再替换二进制；
3. macOS 用户记得执行 xattr -d com.apple.quarantine 与 codesign -s - 自签名；
4. 使用自定义 -port + Tor 隐藏服务（含手工 torrc 配置）的用户：核对洋葱端口是否已按 -port + 1 更新 HiddenServicePort，或改用 -bind=127.0.0.1:8334=onion 保持旧行为；
5. 单机多节点场景：v28.0 中因固定洋葱端口导致的启动失败已由 #31223 修复，升级后应可恢复多实例运行；
6. 钱包与数据兼容：EOL 版本可直升级，旧钱包格式一般仍受支持；数据目录若需迁移，请预留额外启动时间。

如需在源码层面复核上述任何变更，本文已给出对应文件的相对路径与关键代码片段，可据此在仓库内继续深入阅读验证。