Bitcoin Core 0.7.2 升级指南：-detachdb、Berkeley DB 日志兼容与优雅停机机制的修复解析

本篇技术文章以 doc/release-notes/release-notes-0.7.2.md 为骨架，解读 Bitcoin Core 0.7.2 这一补丁发布（bug-fix minor release）的升级方法、-detachdb 选项背后的 Berkeley DB 双文件存储原理、以及当时引入的 "stop true" RPC 停机机制。读者读完可掌握该版本升级时的完整操作与注意事项，理解为什么跨 Berkeley DB 版本升级必须预先分离日志，并通过当前仓库源码了解 RPC stop 与 legacy 钱包 BDB 存储的现代演化位置。

---

版本定位：聚焦稳定性与平台兼容的补丁发布

0.7.2 是 Bitcoin Core（当时仍沿用 Bitcoin 项目名）在 0.7.0 / 0.7.1 系列基础上的维护型补丁版本，其正文开篇即定性为 "This is a bug-fix minor release"，不引入任何新的用户级功能，主要工作是修复死锁、内存生命周期（use-after-free）、竞态条件与平台兼容问题。原文档通过官方下载渠道对外发布（正文给出 SourceForge 文件下载地址与 GitHub issue 追踪入口）。

从 doc/release-notes 目录看，本版本位于 0.7.x 生命周期末端：紧随 release-notes-0.7.1.md、release-notes-0.7.0.md 之后，下一个大版本为 0.8.0，而 0.8.x 起链上索引存储发生了重要架构替换（当前仓库 src/txdb.cpp 与 src/leveldb/ 即该演化的最终形态）。因此 0.7.2 可视为 "Berkeley DB 时期" 最后一次收尾式稳定化发布。

---

如何升级：完整操作步骤

原文档给出了三个层次的升级指引，逐条还原如下。

1. 先关闭旧版本并等待完全退出

If you are running an older version, shut it down. Wait until it has completely shut down (which might take a few minutes for older versions)…

升级的第一步不是直接覆盖文件，而是干净地关闭运行中的节点：

• 停止 bitcoind / Bitcoin-Qt 进程，必须等待其完全退出；
• 旧版本因数据库收尾工作量大，完整退出可能需要数分钟，不能凭进程消失即认定结束，否则数据库可能仍处于中间状态。

从现代实现看，这一 "完全退出后再替换" 的原则依然成立：当前源码中 stop RPC 的注释明确写到，事件循环会在"当前 HTTP 请求处理完毕之后"退出（见 src/rpc/server.cpp），即停机是一个内部先收尾、后放行的异步过程，客户端不应假定返回即退出完成。

2. 按平台替换可执行文件

关闭并确认退出后：

平台	操作
Windows	运行安装包（installer）覆盖升级
macOS	拷贝覆盖 /Applications/Bitcoin-Qt
Linux	拷贝覆盖 bitcoind / bitcoin-qt（按启动方式二选一或同时替换）

3. Linux 场景：注意 Berkeley DB 编译版本差异

这是原文档中最关键的升级提示，原文提示了一个会直接导致启动失败的错误路径：

If you were running on Linux with a version that might have been compiled with a different version of Berkeley DB (for example, if you were using an Ubuntu PPA version), then run the old version again with the -detachdb argument and shut it down; if you do not, then the new version will not be able to read the database files and will exit with an error.

典型反例是 Ubuntu PPA 打包版本：不同打包方可能使用不同的 Berkeley DB 库版本编译，若不做任何处理直接替换新二进制，新版本将无法读取数据库文件并直接报错退出。正确流程是：

# 1. 仍使用旧版本二进制启动一次，仅为了执行数据库分离
bitcoind -detachdb

# 2. 等待其完整关闭（此过程明显变慢，属正常现象）
# 3. 之后再替换为 0.7.2 二进制并正常启动

该段文本在 0.7.1 与 0.7.2 两份发布说明中逐字重复，说明这是一个被官方确认过的、具有普遍性的真实迁移陷阱，而非个例。

---

深入 -detachdb：Berkeley DB 的双文件存储与跨版本兼容模型

为什么会出现"读不了数据库"这类问题？原文档用一段专门的 Explanation 详细交代了机制，这是理解整个升级注意事项的核心。

Berkeley DB 的一致性保障：.dat 数据文件 + log 日志文件

The Berkeley DB database library stores data in both ".dat" and "log" files, so the database is always in a consistent state, even in case of power failure or other sudden shutdown.

即 Berkeley DB 采用"数据页 + 预写式日志"的经典存储布局：

• .dat 文件存放数据库主体内容；
• log 文件记录已提交事务的重做信息，用于在断电、进程崩溃等突发停机后把数据库回滚/前滚到一致状态。

因此只要 .dat 与 log 配套完整，数据库在任意时刻都能被恢复为一致状态——这也是当时节点敢于直接落盘的根本保障。

兼容性不对称：.dat 可移植，log 不可移植

The format of the ".dat" files is portable between different versions of Berkeley DB, but the "log" files are not-- even minor version differences may have incompatible "log" files.

这是本发布说明信息密度最高的一句：

• .dat 文件的格式在不同 Berkeley DB 版本间保持可移植；
• log 文件的内部格式则不具备跨版本兼容性，即便是 minor 版本差异也可能互不兼容。

于是升级场景中矛盾出现：新版本能读旧 .dat，但旧 log 文件可能已无法被新版本的 BDB 库解析，节点自然报错退出。这正是上一节"先跑旧版 -detachdb"建议存在的根本原因。

-detachdb 做什么：把 pending 变更写回 .dat

The -detachdb option moves any pending changes from the "log" files to the "blkindex.dat" file for maximum compatibility, but makes shutdown much slower.

-detachdb 的作用是强制把 log 文件中尚未落盘到数据文件的待定（pending）变更全部迁移写入 blkindex.dat，使数据库在关闭时处于"可脱离日志、单靠数据文件即可完整读取"的状态，从而换取最大化的跨版本兼容性。代价则是停机变慢——因为关闭阶段要多做一次全量日志冲刷。

这一点与 release-notes-0.6.2.md 中的相关改动一脉相承：0.6.2 实现了更快的常规停机（默认不再分离数据库），但"如果你需要可移植的 blkindex.dat，请以新的 -detachdb=1 选项运行"，0.7.x 系列把该能力完整继承下来。

两类数据的差异化处理

Note that the "wallet.dat" file is always detached, and versions prior to 0.6.0 detached all databases at shutdown.

原文档补充了两个重要事实：

• wallet.dat 与链数据不同，在每次关闭时都会执行分离（always detached）——钱包文件较小且对可移植性要求高，因此被特殊对待；
• 0.6.0 之前的版本则对所有数据库都在关闭时执行分离，这也是旧版本停机较慢的历史原因（后来 0.6.2 才引入默认快速停机 + 可选 -detachdb 的机制）。

由此可以理解，升级说明中反复强调的 -detachdb 主要服务于**区块索引数据（当时的 blkindex.dat）**与 Linux 异构 BDB 编译环境，而钱包数据本身已默认保证分离。

从当前仓库看这一存储模型的演化

在当下 master 分支的源码中，-detachdb 已不再出现在 src 代码（仅在 doc/release-notes 的历史发布说明中保留），可以推断该选项随 0.8 起链上索引改用 LevelDB 而退出历史舞台：

• 当前区块/链索引数据由 src/txdb.cpp 与 src/leveldb 承担，不再依赖 Berkeley DB；
• 但 legacy 钱包仍然使用 Berkeley DB：在 src/wallet/db.cpp 中可看到 BDBDataFile() 会识别"目录下同时含 BDB 数据文件与 log 文件的路径"，IsBDBFile() 依据文件头判断是否为 BDB 格式。这说明 BDB 的 .dat/log 双文件模型作为钱包层遗产保留至今，仅在需要迁移到 descriptor 钱包时（见 src/wallet/migrate.cpp）才被系统性地读写与转换。

换言之，0.7.2 升级说明所揭示的"Berkeley DB 日志不可跨版本移植"这一规律，对今天仍在使用 legacy BDB 钱包的用户依然具备现实参考价值——理解它，就理解了为什么钱包升级往往伴随备份、分离与迁移工具链。

---

"stop true"：通过 RPC 触发带数据库收尾的停机

在说明 -detachdb 的同时，原文档特别点名了 新的 "stop true" RPC 命令。这实际上是 release-notes-0.7.1.md 中新增功能的延续——0.7.1 为 RPC stop 命令增加了布尔参数，文档原文为：

Added a boolean argument to the RPC 'stop' command, if true sets -detachdb to create standalone database .dat files before shutting down.

历史用法

# 不带参数：快速停机（默认，等价于快速关闭）
bitcoin-cli stop

# 传 true：停机前执行 -detachdb 语义，生成可独立移植的数据库 .dat 文件
bitcoin-cli stop true

其业务价值非常直观：运维人员无须重启进程加入命令行参数，即可在远程 RPC 层面对停机行为做一次性控制，从而把"升级前置的数据库分离"纳入自动化脚本——例如：

# 升级 Linux 节点前的推荐脚本：先分离数据库，再干净停机
bitcoin-cli stop true
# 等待进程完全退出
# 替换为新版二进制并启动

现代实现：stop 命令在 src/rpc/server.cpp 中的演化

当代仓库中 stop 命令的实现在功能语义上一脉相承，但参数已由布尔值演化为可选的毫秒级等待参数。核心代码（节选）：

static RPCMethod stop()
{
    static const std::string RESULT{CLIENT_NAME " stopping"};
    return RPCMethod{
        "stop",
    // Also accept the hidden 'wait' integer argument (milliseconds)
    // For instance, 'stop 1000' makes the call wait 1 second before returning
    // to the client (intended for testing)
        "Request a graceful shutdown of " CLIENT_NAME ".",
                {
                    {"wait", RPCArg::Type::NUM, RPCArg::Optional::OMITTED, "how long to wait in ms", RPCArgOptions{.hidden=true}},
                },
                RPCResult{RPCResult::Type::STR, "", "A string with the content '" + RESULT + "'"},
                RPCExamples{""},
        [](const RPCMethod& self, const JSONRPCRequest& jsonRequest) -> UniValue
{
    // Event loop will exit after current HTTP requests have been handled, so
    // this reply will get back to the client.
    CHECK_NONFATAL((CHECK_NONFATAL(EnsureAnyNodeContext(jsonRequest.context).shutdown_request))());
    if (jsonRequest.params[0].isNum()) {
        UninterruptibleSleep(std::chrono::milliseconds{jsonRequest.params[0].getInt<int>()});
    }
    return RESULT;
},
    };
}

要点与 0.7.2 时代的对照：

• 方法名 stop 与"请求优雅停机"（Request a graceful shutdown）的定位从 0.7.x 沿用至今；
• 现代的 wait 参数单位是毫秒，且被标记为隐藏参数、主要用于测试（"intended for testing"），与 0.7.x 的布尔语义不同——这说明该参数设计意图从"控制数据库分离"迁移到了"控制客户端等待时长"；
• 底层停机仍是"事件循环在当前 HTTP 请求处理完后退出"的优雅流程，回复会先送回客户端；
• 参数转换表位于 src/rpc/client.cpp：{ "stop", 0, "wait" }，即客户端把 stop 的位置 0 参数按数值类型转换后传给服务端。

因此，如果你在今天尝试 bitcoin-cli help stop，会看到 "Request a graceful shutdown" 的说明——这正是 0.7.1/0.7.2 发布说明中 "stop true" 命令的血脉延续。

---

0.7.2 Bug 修复清单逐条解读

原文档 Bug fixes 一节共列出七类修复，逐条还原并结合工程背景解读：

1. 修复 RPC move 的死锁

Prevent RPC 'move' from deadlocking. This was caused by trying to lock the database twice.

move 是当时钱包层在账户（account）间转移余额的 RPC。其死锁根因被官方直接给出：实现中对同一数据库尝试了两次加锁。在 Berkeley DB 环境里，数据库锁并非可重入语义，嵌套获取同一写锁会造成自我阻塞，最终表现为 RPC 调用挂死、钱包相关操作全部卡住。该修复即把对数据库的访问路径收敛为单次持锁。

2. 修复初始化和关闭阶段的 use-after-free

Fix use-after-free problems in initialization and shutdown, the latter of which caused Bitcoin-Qt to crash on Windows when exiting.

这类问题属于典型的 C++ 内存生命周期缺陷：初始化/关闭路径中对象析构顺序错误，使代码在对象释放后仍访问其内存。其中关闭阶段的 use-after-free 是 Windows 上 Bitcoin-Qt 退出即崩溃的直接原因——GUI 组件与后台线程的销毁顺序需要严格保证"先停消费者、再释放被共享对象"。

3. 修正库链接，使 Windows 原生构建可用

Correct library linking so building on Windows natively works.

0.7.x 时期官方推荐在 Windows 使用跨平台构建；本次修复同时保证了在 Windows 上进行原生（native）构建的可用性，属于构建系统层面的链接顺序/依赖声明修正。

4. 规避区块创建/挖矿代码中的竞态与越界读

Avoid a race condition and out-of-bounds read in block creation/mining code.

区块模板构建（CreateNewBlock 路径）需要并发读取内存池并组装交易，若在内存池变更与模板读取之间缺少同步，既可能读到已释放或半更新的条目（竞态），也可能在按索引访问交易数组时越界。这类问题在高负载、高并发下随机暴露，正是补丁版优先处理的稳定性隐患。

5. 改善平台兼容怪癖，包括 FreeBSD 9 的 100% CPU 占用

Improve platform compatibility quirks, including fix for 100% CPU utilization on FreeBSD 9.

修复了 FreeBSD 9 上节点空转却占满单个 CPU 内核的问题。这类平台怪癖通常源于对操作系统定时器、信号或 socket 事件的误判（例如忙等而非阻塞等待），导致主循环空转。

6. 若干错误处理小修正与翻译更新

A few minor corrections to error handling, and updated translations.

属于低风险收尾改动：错误分支返回码/报错文案修正，以及多语言翻译字符串同步更新（对应 src/qt 中 *.ts 翻译文件体系，该机制至今保留）。

7. 重新支持 OSX 10.5

OSX 10.5 supported again

与 release-notes-0.7.1.md 中 "Mac OSX 10.5 is no longer supported" 形成呼应：0.7.1 曾宣布放弃对 OSX 10.5（Leopard）的支持，而 0.7.2 通过兼容性修复收回了这一决定，重新支持该系统。

---

致谢与相关历史发布说明

原文档在末尾向本版本贡献者致谢，保留如下：

Alex、dansmith、Gavin Andresen、Gregory Maxwell、Jeff Garzik、Luke Dashjr、Philip Kaufmann、Pieter Wuille、Wladimir J. van der Laan、grimd34th。

其中多数贡献者后来成为 Bitcoin Core 的长期维护者，可在当前仓库的 CONTRIBUTING.md 与 COPYING 中了解项目协作与许可背景。

如需追溯本版本相关机制的前后脉络，建议继续阅读以下位于 doc/release-notes 的相邻发布说明：

• release-notes-0.6.2.md：快速停机改造与 -detachdb=1 选项的引入源头；
• release-notes-0.7.0.md：0.7 主版本功能基线，首次出现跨 BDB 版本升级提示；
• release-notes-0.7.1.md："stop true" RPC 布尔参数与 -salvagewallet、bootstrap.dat 自动导入等新功能。

---

结语：从一份补丁说明看数据库工程

0.7.2 这份发布说明篇幅不长，但浓缩了当时节点存储层最核心的一条工程经验："数据文件格式可移植，日志文件格式不可移植"。围绕它展开的 -detachdb 升级前置流程、"stop true" 远程停机控制，以及本版修复的 DB 双重加锁死锁、关闭路径 use-after-free、挖矿竞态等问题，共同构成了早期比特币节点在"崩溃一致性 + 跨版本升级 + 优雅停机"三角约束下的工程解法。理解这段历史，也有助于你读懂当前仓库中 legacy 钱包 BDB 存储（src/wallet/db.cpp）为何仍保留 .dat 与 log 文件的识别与迁移逻辑。