Go bbolt 怎么从只读事务导出一致性备份

Go 项目使用 bbolt 时，备份的关键不是在数据库文件旁边随手复制一份，而是让导出动作绑定到一个一致的只读事务。bbolt 的 DB.View 会提供事务开始时的数据视图，Tx.WriteTo 可以把这个视图写入任意 io.Writer，而 Tx.CopyFile 适合直接写成另一个备份文件。这样既能在服务继续提供读写时导出，也能避免把不同时间点的数据拼在同一份备份里。

官方地址：https://github.com/etcd-io/bbolt

本文只解决一个问题：如何从 bbolt 的只读事务导出一致性备份。示例分别覆盖 HTTP 流式下载和本地文件归档，不把备份接口扩展成完整的权限系统、对象存储或恢复平台。

先把一致性边界放在 DB.View 里面

bbolt 的数据库是一个单文件数据库，事务负责提供一致视图。读写事务和只读事务的并发规则不同，但对备份来说最重要的是：导出动作必须在同一个 View 回调中完成。不要先打开一个事务读取元数据，再在事务关闭后复制文件；也不要在回调里只计算文件大小，回调结束后才真正导出。

下面的关系可以概括成一条边界：DB 创建 View 只读事务，事务持有 Tx 一致视图，导出 API 再把这个视图写到目标。图中的箭头表示对象关系，不表示已经在本机执行过的结果。

准备打开方式、文件权限和请求边界

数据库打开时要明确文件权限。官方 README 的基础示例使用 0600，表示只有当前用户可以读写数据库文件。备份文件通常包含完整业务数据，权限不应比数据库本身更宽。服务端 HTTP 入口还需要给请求设置超时，避免客户端中断后长期占用只读事务。

package backup

import (
    "context"
    "fmt"
    "net/http"
    "time"

    bolt "go.etcd.io/bbolt"
)

// Open 打开 bbolt 数据库；权限和打开超时都由调用方明确传入。
func Open(path string) (*bolt.DB, error) {
    // Timeout 防止数据库文件被其他进程占用时无限等待。
    return bolt.Open(path, 0600, &bolt.Options{Timeout: 3 * time.Second})
}

// requestContext 将 HTTP 请求的取消信号传给备份入口的上层代码。
// bbolt 的 WriteTo 本身接收 Writer，取消后的处理仍由 Writer 和调用方负责。
func requestContext(r *http.Request) context.Context {
    return r.Context()
}

// contentDisposition 返回一个固定的下载文件名，避免把用户输入直接拼进响应头。
func contentDisposition() string {
    return `attachment; filename="backup.db"`
}

var _ = fmt.Sprintf
var _ = http.MethodGet

这个片段只展示准备阶段的约束：路径来自受控配置，权限使用窄范围模式，打开数据库设置了等待上限。实际导出仍要在 DB.View 回调中完成。

用 Tx.WriteTo 把一致视图流式写给 HTTP

当备份需要从服务端下载，或者需要交给对象存储 SDK 的 Writer 时，Tx.WriteTo 更合适。它不要求你把整个数据库先读进内存，而是直接把事务视图写入响应体或其他实现了 io.Writer 的目标。

package backup

import (
    "net/http"

    bolt "go.etcd.io/bbolt"
)

// Handler 将 bbolt 的一致快照写入 HTTP 响应；错误交给 HTTP 层记录和处理。
func Handler(db *bolt.DB) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // 只允许 GET，避免把备份动作混入写请求语义。
        if r.Method != http.MethodGet {
            http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
            return
        }

        err := db.View(func(tx *bolt.Tx) error {
            // 响应头描述下载内容；文件名不来自请求参数。
            w.Header().Set("Content-Type", "application/octet-stream")
            w.Header().Set("Content-Disposition", `attachment; filename="backup.db"`)
            w.Header().Set("Content-Length", fmt.Sprintf("%d", tx.Size()))

            // WriteTo 在当前只读事务视图内写入响应体，保持导出边界一致。
            _, err := tx.WriteTo(w)
            return err
        })
        if err != nil {
            // 头部可能已经写出，此处至少记录真实错误并结束请求。
            http.Error(w, "backup failed", http.StatusInternalServerError)
        }
    }
}

上面的示例需要补充 fmt 导入：

import "fmt" // 用事务大小填充响应长度，避免手写一个可能过期的数字。

实际项目中可以在进入 View 前完成权限判断和审计记录。进入回调后，响应头要尽早设置，但不要在事务外读取 tx.Size()。如果客户端断开，底层 Writer 可能返回错误；这个错误应保留在日志中，不能把它改写成“备份成功”。

用 Tx.CopyFile 直接生成本地备份

定时任务、发布前归档和单机维护通常不需要 HTTP 流，此时可使用 Tx.CopyFile。它仍然应该从只读事务中调用，因为一致性来自事务视图，而不是方法名里是否包含 Copy。

package backup

import (
    "fmt"
    "path/filepath"
    "time"

    bolt "go.etcd.io/bbolt"
)

// CopyToFile 将数据库快照写入备份目录，返回最终备份路径和错误。
func CopyToFile(db *bolt.DB, dir string, now time.Time) (string, error) {
    // 时间戳只用于归档文件名，不参与事务内容。
    name := fmt.Sprintf("backup-%s.db", now.UTC().Format("20060102T150405Z"))
    target := filepath.Join(dir, name)

    err := db.View(func(tx *bolt.Tx) error {
        // CopyFile 必须在只读事务内调用，目标文件由 bbolt 负责写入。
        return tx.CopyFile(target, 0600)
    })
    if err != nil {
        return "", fmt.Errorf("copy bbolt backup: %w", err)
    }
    return target, nil
}

这里的 0600 是目标备份文件的权限参数。目标目录应由部署配置创建并限制访问；不要直接把目录拼接到用户输入，也不要让多个任务同时写同一个固定文件名。若要覆盖固定文件，先设计好并发锁、临时文件和替换策略，避免读者把半成品当成可恢复备份。

WriteTo 和 CopyFile 应该怎么选

两种 API 的一致性来源相同，区别在于输出边界。可以按下面的规则选择：

不要把 Tx.WriteTo 和 Tx.CopyFile 当成“导出部分字段”的接口。它们导出的是事务视图对应的数据库内容，和遍历 bucket 后导出业务 JSON 不是同一件事。如果业务需求是脱敏、筛选或跨版本迁移，应另写明确的数据转换流程。

发布到生产前检查事务与失败路径

企业环境更容易出问题的地方，往往不是 API 名称，而是备份过程的边界没有写清。发布前至少要把以下规则固化到配置和日志中：

• 备份调用从 DB.View 进入，并在回调返回后结束事务，不把事务对象保存到异步 goroutine。
• HTTP 备份入口有鉴权、访问审计和请求超时；下载路径不接受任意文件名。
• 本地备份目录与业务进程的写权限分离，备份文件使用窄权限，目录空间不足时保留真实错误。
• 备份任务不与写事务互相嵌套；bbolt 官方说明长时间只读事务可能影响写事务重新映射文件，因此应避免在 Writer 已经阻塞时无限保持事务。
• 成功日志记录目标类型、目标路径或请求标识、耗时和字节数；失败日志记录错误，不用一个固定的“完成”消息覆盖所有情况。

最后要区分“导出完成”和“可恢复”。这篇文章解决的是从一致只读视图生成备份文件，真正的恢复演练、密钥管理、异地保存和保留策略仍需由项目自己的灾备方案负责。

常见问题

只读事务真的能在数据库继续读写时导出吗？

可以，bbolt 官方文档把从只读事务调用 Tx.WriteTo 描述为热备份场景，并说明它不会阻塞其他数据库读写。实际部署仍要给 Writer 设置合理的超时和失败处理，避免导出请求长期悬挂。

为什么不能先关闭 View 再调用 WriteTo？

Tx 及其对象只在事务生命周期内有效。关闭 View 后再导出，既失去一致视图，也违反事务对象的使用边界。正确做法是把完整的 WriteTo 或 CopyFile 调用放进回调。

CopyFile 生成的文件还需要自己再复制一遍吗？

通常不需要。Tx.CopyFile 的用途就是把当前事务视图写到另一个文件；如果还要上传对象存储，可以在文件生成成功后再由独立上传步骤处理，并保留上传失败状态。