bbolt 嵌入式键值数据库完整使用指南——从 ACID 事务到 B+树原理，兼谈 Grafana Mimir 中的工程实践

时序数据库后端数据存储可观测性云原生【免费下载链接】mimirGrafana Mimir provides horizontally scalable, highly available, multi-tenant, long-term storage for Prometheus.项目地址https://gitcode.com/gh_mirrors/mimir/mimir点击查看免费下载本篇技术指南以本仓库 vendor 目录下随项目一起交付的 bboltvendor/go.etcd.io/bbolt/README.md文档为骨架系统讲解这款纯 Go 实现的嵌入式键值数据库从安装、打开数据库、四种事务模式到 Bucket 管理、键迭代、备份与统计再到它与 Postgres、LevelDB、LMDB 的取舍以及其内部 B树与两阶段提交的实现原理。文中还结合 Grafana Mimir 的 compactor-scheduler 组件源码展示 bbolt 在真实分布式系统中的持久化工程实践。读完本文你将掌握 bbolt 的全部核心 API 用法、关键限制并能理解它在 Mimir 中承担的角色。一、认识 bbolt从 Bolt 到 etcd 社区维护版bbolt 是 Ben Johnson 所写 Bolt 键值存储的官方分支。创建这一 fork 的目的是为 Go 社区提供一个持续维护与开发的目标bbolt 在保持与 Bolt API 向后兼容的同时吸收了 Bug 修复、性能增强与新增特性目标是更高的可靠性与稳定性。Bolt即 bbolt 的前身本身是受 Howard Chu 的 LMDB 项目启发的纯 Go 键值存储。它的设计目标是为那些不需要 Postgres 或 MySQL 这样完整数据库服务器的项目提供一个简单、快速、可靠的嵌入式数据库。由于 Bolt 定位为底层存储组件简洁是它的第一原则API 规模很小只聚焦于取值和设值两件事。正如包文档 vendor/go.etcd.io/bbolt/doc.go 所概括的bbolt 是一个纯 Go 实现的低层键值存储支持完全可串行化fully serializable的事务、ACID 语义以及单写多读的无锁 MVCC它是单层、零拷贝的 B树数据存储针对快速读取优化系统崩溃时无需恢复——未提交完成的事务在崩溃时会直接回滚。项目状态与版本策略稳定性Bolt 已经稳定API 固定、文件格式固定。项目通过完整的单元测试覆盖和随机化黑盒测试来保证数据库一致性与线程安全并被广泛用于高负载生产环境。版本管理bbolt 遵循语义化版本semantic versioning。patch 与 minor 版本之间 API 不应变动新的 minor 版本可能为 API 增加新功能。二、安装、命令行工具与导入安装库使用go get获取最新版本的 bbolt 库该命令会自动更新项目的go.mod与go.sum文件$ go get go.etcd.io/bboltlatest运行命令行工具bbolt 自带一个命令行工具可以通过go run直接执行$ go run go.etcd.io/bbolt/cmd/bboltlatest也可以使用go install将bbolt命令行工具安装到$GOBIN路径下默认是$GOPATH/bin如果未设置GOPATH环境变量则为$HOME/go/bin$ go install go.etcd.io/bbolt/cmd/bboltlatest在 Go 代码中导入以嵌入库的方式使用 bboltimport bolt go.etcd.io/bbolt db, err : bolt.Open(path, 0600, nil) if err ! nil { return err } defer db.Close()注当前 Mimir 仓库通过 go.mod 锁定依赖版本为go.etcd.io/bbolt v1.5.0。三、打开数据库DB、文件锁与 Optionsbbolt 的顶层对象是DB。它在磁盘上表现为单个文件代表着数据的一致快照consistent snapshot。package main import ( log bolt go.etcd.io/bbolt ) func main() { // 打开当前目录下的 my.db 数据文件。 // 如果文件不存在会自动创建。 db, err : bolt.Open(my.db, 0600, nil) if err ! nil { log.Fatal(err) } defer db.Close() // ... }文件锁与超时需要注意Bolt 会对数据文件加文件锁因此多个进程不能同时打开同一个数据库。尝试打开一个已被打开的 Bolt 数据库会一直阻塞直到持有它的进程关闭为止。为了避免无限等待可以给Open()传入带Timeout的 Optionsdb, err : bolt.Open(my.db, 0600, bolt.Options{Timeout: 1 * time.Second})Options 选项详解Options结构定义在 vendor/go.etcd.io/bbolt/db.go除Timeout外还包含以下关键字段字段说明Timeout time.Duration获取文件锁的等待时间为零时无限期等待NoGrowSync bool设置DB.NoGrowSync标志后再做内存映射NoFreelistSync bool不将 freelist空闲页表同步到磁盘可提升常规写性能但恢复时需对整库做一次同步PreLoadFreelist bool打开文件时是否预加载空闲页写模式下 bbolt 总是会加载FreelistType FreelistTypefreelist 后端类型FreelistArrayType默认实现简单但库大且碎片多时性能急剧下降或 hashmap 类型绝大多数场景更快ReadOnly bool以只读模式打开数据库UNIX 下使用flock(..., LOCK_SH \| LOCK_NB)获取共享锁MmapFlags int内存映射标志InitialMmapSize int初始 mmap 大小字节。足够大时读事务不会阻塞写事务Windows 平台打开时会立即将文件大小调整为该值非 Windows 平台则随实际写入数据动态增长PageSize int覆盖操作系统默认页大小MaxSize int数据文件的最大大小0表示无限制NoSync bool设置DB.NoSync的初始值OpenFile func(...)自定义文件打开函数常用于编写封闭式hermetic测试Mlock bool将数据库文件锁进内存避免页错误但已用内存无法回收仅 UNIXLogger Loggerbbolt 使用的日志器NoStatistics bool关闭统计收集高并发只读事务下可提升性能此后Stats()返回空结构如果传入nil作为 Options则使用默认值{Timeout: 0, NoGrowSync: false, FreelistType: FreelistArrayType}见 db.go。四、事务模型串行化 ACID 的核心Bolt同一时刻只允许一个读-写事务但可以同时存在任意多个只读事务。每个事务都拥有一个一致性的数据视图——看到的是事务开始那一刻的数据。事务本身以及由它创建的所有对象如 Bucket、Key不是线程安全的要在多个 goroutine 中操作数据必须为每个 goroutine 开启各自的事务或用加锁保证同一时刻只有一个 goroutine 访问某个事务。但从DB创建事务本身是线程安全的。死锁警示事务之间不应相互依赖也不建议在同一 goroutine 中同时打开多个事务。读-写事务需要周期性重新映射数据文件而任何只读事务未关闭时它都无法完成重映射即使是嵌套的只读事务也可能造成死锁子事务会阻塞父事务释放资源。读-写事务DB.Update()err : db.Update(func(tx *bolt.Tx) error { // ... return nil })在闭包内你拥有一致的数据视图。返回nil即提交事务在任何位置返回 error 即回滚事务。读-写事务内允许所有数据库操作。务必检查返回值它会报告任何可能导致事务未完成的磁盘故障闭包内返回的 error 也会原样透传。只读事务DB.View()err : db.View(func(tx *bolt.Tx) error { // ... return nil })同样拥有一致视图但只读事务内不允许任何修改操作只能获取 Bucket、读取值以及在只读事务内复制数据库。批量读-写事务DB.Batch()每次DB.Update()都会等待磁盘提交写入这个开销可以通过DB.Batch()将多次更新合并来最小化err : db.Batch(func(tx *bolt.Tx) error { // ... return nil })并发的Batch调用会被机会式地合并成更大的事务。只有多个 goroutine 同时调用时Batch才有意义。权衡Batch可能在事务部分失败时多次调用传入的函数。因此该函数必须幂等副作用只能在DB.Batch()成功返回后生效。例如不要在函数内部打印消息而是在外层作用域设置变量var id uint64 err : db.Batch(func(tx *bolt.Tx) error { // 在 bucket 中找到最后一个 key按 bigendian uint64 解码加一 // 重新编码为 []byte 并作为新 key 写入。 // ... id newValue return nil }) if err ! nil { return ... } fmt.Println(Allocated ID %d, id)手动管理事务DB.Begin()DB.View()与DB.Update()都是对DB.Begin()的封装启动事务、执行函数、出错时安全关闭事务。这是推荐的用法。但如果确实需要手动控制事务生命周期可以直接调用DB.Begin()务必记得关闭事务// 启动一个可写事务。 tx, err : db.Begin(true) if err ! nil { return err } defer tx.Rollback() // 使用该事务... _, err : tx.CreateBucket([]byte(MyBucket)) if err ! nil { return err } // 提交事务并检查错误。 if err : tx.Commit(); err ! nil { return err }DB.Begin()的第一个参数是布尔值表示事务是否可写。五、Bucket 管理Bucket 是数据库内键值对的集合同一 Bucket 内的所有 key 必须唯一。创建 Bucket 使用Tx.CreateBucket()db.Update(func(tx *bolt.Tx) error { b, err : tx.CreateBucket([]byte(MyBucket)) if err ! nil { return fmt.Errorf(create bucket: %s, err) } return nil })获取已存在的 Bucket 使用Tx.Bucket()db.Update(func(tx *bolt.Tx) error { b : tx.Bucket([]byte(MyBucket)) if b nil { return errors.New(bucket does not exist) } return nil })Tx.CreateBucketIfNotExists()则只在 Bucket 不存在时创建。一种常见模式是打开数据库后对所有顶层 Bucket 都调用一次该函数以保证它们在未来事务中必然存在。删除 Bucket 只需调用Tx.DeleteBucket()。遍历所有顶层 Bucket 用Tx.ForEach()db.View(func(tx *bolt.Tx) error { tx.ForEach(func(name []byte, b *bolt.Bucket) error { fmt.Println(string(name)) return nil }) return nil })六、键值对读写写入键值对使用Bucket.Put()db.Update(func(tx *bolt.Tx) error { b : tx.Bucket([]byte(MyBucket)) err : b.Put([]byte(answer), []byte(42)) return err })读取使用Bucket.Get()db.View(func(tx *bolt.Tx) error { b : tx.Bucket([]byte(MyBucket)) v : b.Get([]byte(answer)) fmt.Printf(The answer is: %s\n, v) return nil })Get()不返回 error因为它的操作被保证可以工作除非发生系统级故障。key 存在则返回其字节切片值不存在则返回nil。注意key 可以对应一个零长度值这与 key 不存在是两种不同的状态。删除 key 使用Bucket.Delete()db.Update(func (tx *bolt.Tx) error { b : tx.Bucket([]byte(MyBucket)) err : b.Delete([]byte(answer)) return err })重要Get()返回的值只在事务打开期间有效。如果要在事务外使用该值必须用copy()复制到另一个字节切片。这是因为 bbolt 直接返回内存映射文件或内存节点中的引用事务结束后底层内存可能被复用或解除映射详见下文注意事项。七、为 Bucket 生成自增整数 ID通过NextSequence()可以让 Bolt 自动维护一个序列值用作键值对的唯一标识。以下示例展示了一个简单的用户存储// CreateUser 将 u 保存到 store数据持久化后新的用户 ID 会被设置到 u 上。 func (s *Store) CreateUser(u *User) error { return s.db.Update(func(tx *bolt.Tx) error { // 获取 users bucket。 // 该 bucket 应在 DB 首次打开时创建。 b : tx.Bucket([]byte(users)) // 为用户生成 ID。 // 仅当 Tx 已关闭或不可写时才返回错误 // 在 Update() 调用中不可能发生因此忽略错误检查。 id, _ : b.NextSequence() u.ID int(id) // 将用户数据 marshal 成字节。 buf, err : json.Marshal(u) if err ! nil { return err } // 将字节持久化到 users bucket。 return b.Put(itob(u.ID), buf) }) } // itob 返回 v 的 8 字节大端序表示。 func itob(v int) []byte { b : make([]byte, 8) binary.BigEndian.PutUint64(b, uint64(v)) return b } type User struct { ID int // ... }八、键的迭代Cursor、前缀扫描、范围扫描与 ForEachBolt 在 Bucket 内部按字节排序存储 key因此顺序迭代非常快。迭代使用Cursordb.View(func(tx *bolt.Tx) error { // 假设 bucket 存在且有 key b : tx.Bucket([]byte(MyBucket)) c : b.Cursor() for k, v : c.First(); k ! nil; k, v c.Next() { fmt.Printf(key%s, value%s\n, k, v) } return nil })Cursor 允许你移动到 key 列表中的特定位置并一次一步地向前或向后移动。可用的函数First() 移动到第一个 key。 Last() 移动到最后一个 key。 Seek() 移动到指定 key。 Next() 移动到下一个 key。 Prev() 移动到上一个 key。每个函数的返回签名都是(key []byte, value []byte)。调用Next()或Prev()之前必须先通过First()、Last()或Seek()定位否则会返回nilkey。迭代到末尾时Next()返回nilkey若有最后一个元素cursor 仍指向它迭代到开头时Prev()返回nilkeycursor 仍指向第一个元素。迭代时若删除键值对cursor 可能自动移到当前节点中的下一个位置此时再调用c.Next()可能跳过一对键值——需要留意这一行为详见本仓库 README 引用的 bbolt pull/611 讨论。迭代时如果 key 非nil但 value 为nil说明该 key 指向的是一个子 Bucket而不是值应使用Bucket.Bucket()访问该子 bucket。前缀扫描将Seek()与bytes.HasPrefix()结合即可遍历某个 key 前缀db.View(func(tx *bolt.Tx) error { // 假设 bucket 存在且有 key c : tx.Bucket([]byte(MyBucket)).Cursor() prefix : []byte(1234) for k, v : c.Seek(prefix); k ! nil bytes.HasPrefix(k, prefix); k, v c.Next() { fmt.Printf(key%s, value%s\n, k, v) } return nil })范围扫描另一个常见场景是按范围扫描例如时间范围。如果使用可排序的时间编码如 RFC3339就可以按日期范围查询db.View(func(tx *bolt.Tx) error { // 假设 events bucket 存在且 key 为 RFC3339 编码的时间。 c : tx.Bucket([]byte(Events)).Cursor() // 时间范围覆盖 90 年代。 min : []byte(1990-01-01T00:00:00Z) max : []byte(2000-01-01T00:00:00Z) // 遍历 90 年代。 for k, v : c.Seek(min); k ! nil bytes.Compare(k, max) 0; k, v c.Next() { fmt.Printf(%s: %s\n, k, v) } return nil })注意RFC3339 是可排序的但 Go 实现的RFC3339Nano在小数点后位数不固定因此不可排序。ForEach()如果确定要遍历一个 Bucket 的全部 key可以使用ForEach()db.View(func(tx *bolt.Tx) error { // 假设 bucket 存在且有 key b : tx.Bucket([]byte(MyBucket)) b.ForEach(func(k, v []byte) error { fmt.Printf(key%s, value%s\n, k, v) return nil }) return nil })ForEach()中的 key 和 value同样只在事务打开期间有效事务外使用需要copy()。九、嵌套 Bucket可以在 key 上存储一个 Bucket 来创建嵌套 BucketAPI 与DB层级的 Bucket 管理 API 相同func (*Bucket) CreateBucket(key []byte) (*Bucket, error) func (*Bucket) CreateBucketIfNotExists(key []byte) (*Bucket, error) func (*Bucket) DeleteBucket(key []byte) error典型场景是多租户应用根级 Bucket 是账户 Bucket内部是一系列账户每个账户本身也是 Bucket账户 Bucket 内又可挂多个属于该账户自身的 BucketUsers、Notes 等把信息隔离到逻辑分组中// createUser 在指定账户下创建一个新用户。 func createUser(accountID int, u *User) error { // 启动事务。 tx, err : db.Begin(true) if err ! nil { return err } defer tx.Rollback() // 获取账户的根 bucket。 // 假设在账户创建时已经建立。 root : tx.Bucket([]byte(strconv.FormatUint(accountID, 10))) // 建立 users bucket。 bkt, err : root.CreateBucketIfNotExists([]byte(USERS)) if err ! nil { return err } // 为新用户生成 ID。 userID, err : bkt.NextSequence() if err ! nil { return err } u.ID userID // 序列化并保存编码后的用户。 if buf, err : json.Marshal(u); err ! nil { return err } else if err : bkt.Put([]byte(strconv.FormatUint(u.ID, 10)), buf); err ! nil { return err } // 提交事务。 if err : tx.Commit(); err ! nil { return err } return nil }十、数据库备份Bolt 是单文件备份很容易。用Tx.WriteTo()把数据库的一致视图写入任意io.Writer。如果从只读事务中调用它就构成一次热备份hot backup不会阻塞其他数据库读写。默认情况下它使用常规文件句柄会利用操作系统页缓存。一种常见做法是通过 HTTP 暴露备份接口用cURL等工具拉取func BackupHandleFunc(w http.ResponseWriter, req *http.Request) { err : db.View(func(tx *bolt.Tx) error { w.Header().Set(Content-Type, application/octet-stream) w.Header().Set(Content-Disposition, attachment; filenamemy.db) w.Header().Set(Content-Length, strconv.Itoa(int(tx.Size()))) _, err : tx.WriteTo(w) return err }) if err ! nil { http.Error(w, err.Error(), http.StatusInternalServerError) } }随后即可通过命令备份$ curl http://localhost/backup my.db或直接在浏览器打开http://localhost/backup自动下载。如果想备份到另一个文件可以使用Tx.CopyFile()辅助函数其实现见 vendor/go.etcd.io/bbolt/tx.go。十一、运行统计信息数据库会持续统计其内部执行的许多操作帮助了解运行情况。通过获取两个时间点的快照并求差可以看到这段时间内的操作量。例如可以启动一个 goroutine 每 10 秒记录一次统计go func() { // 获取初始统计。 prev : db.Stats() for { // 等待 10 秒。 time.Sleep(10 * time.Second) // 获取当前统计并与上次求差。 stats : db.Stats() diff : stats.Sub(prev) // 编码为 JSON 打印到 STDERR。 json.NewEncoder(os.Stderr).Encode(diff) // 保存供下一轮比较。 prev stats } }()也可以把这些统计导入 statsd 之类监控服务或提供一个 HTTP 端点做固定时长的采样。Stats结构定义于 vendor/go.etcd.io/bbolt/db.go包含空闲页数FreePageN、挂起页数PendingPageN、事务数TxN等字段其Sub()方法专门用于计算两时间点间的差值db.go。十二、只读模式有时需要创建一个可共享的、只读的 Bolt 数据库。为此在打开数据库时设置Options.ReadOnly标志。只读模式使用共享锁允许多个进程同时读取数据库但会阻止任何进程以读-写模式打开它db, err : bolt.Open(my.db, 0600, bolt.Options{ReadOnly: true}) if err ! nil { log.Fatal(err) }十三、移动端使用iOS/Android借助 gomobile 工具的绑定binding功能Bolt 可以运行在移动设备上。做法是创建一个包裹结构体内部持有*bolt.DB引用并提供接收数据库文件路径的初始化构造函数。Android 与 iOS 都不需要为此申请额外权限或清理工作func NewBoltDB(filepath string) *BoltDB { db, err : bolt.Open(filepath/demo.db, 0600, nil) if err ! nil { log.Fatal(err) } return BoltDB{db} } type BoltDB struct { db *bolt.DB // ... } func (b *BoltDB) Path() string { return b.db.Path() } func (b *BoltDB) Close() { b.db.Close() }数据库逻辑应定义为该包裹结构体的方法。从原生语言初始化时两个平台现在都会把本地存储同步到云端下面的代码片段针对数据库文件禁用了该功能AndroidJavaString path; if (android.os.Build.VERSION.SDK_INT android.os.Build.VERSION_CODES.LOLLIPOP){ path getNoBackupFilesDir().getAbsolutePath(); } else{ path getFilesDir().getAbsolutePath(); } Boltmobiledemo.BoltDB boltDB Boltmobiledemo.NewBoltDB(path)iOSObjective-C- (void)demo { NSString* path [NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES) objectAtIndex:0]; GoBoltmobiledemoBoltDB * demo GoBoltmobiledemoNewBoltDB(path); [self addSkipBackupAttributeToItemAtPath:demo.path]; //Some DB Logic would go here [demo close]; } - (BOOL)addSkipBackupAttributeToItemAtPath:(NSString *) filePathString { NSURL* URL [NSURL fileURLWithPath: filePathString]; assert([[NSFileManager defaultManager] fileExistsAtPath: [URL path]]); NSError *error nil; BOOL success [URL setResourceValue: [NSNumber numberWithBool: YES] forKey: NSURLIsExcludedFromBackupKey error: error]; if(!success){ NSLog(Error excluding % from backup %, [URL lastPathComponent], error); } return success; }十四、与其他数据库的对比与 Postgres、MySQL 等关系型数据库关系型数据库把数据组织为行只能通过 SQL 访问。这种方式在存储和查询上灵活但也带来了 SQL 解析与查询计划的额外开销。Bolt 通过字节切片 key 访问所有数据按 key 读写很快但不提供内建的关联join能力。此外多数关系型数据库SQLite 除外是独立于应用运行的服务器可以灵活地让多个应用服务器连接同一个数据库但带来了网络序列化与传输开销。Bolt 作为库内嵌在应用中所有数据访问都经过应用进程数据离应用更近但限制了多进程访问。与 LevelDB、RocksDBLevelDB 及其衍生品RocksDB、HyperLevelDB同样是内嵌库但底层结构是日志结构合并树LSM tree通过预写日志WAL和多层有序的 SSTable 文件优化随机写。Bolt 内部使用B树并且只有单个文件。两种方案各有取舍如果需要很高的随机写吞吐10,000 写/秒或必须使用机械磁盘LevelDB 可能是更好选择如果应用是读密集型或做了大量范围扫描Bolt 可能更合适。另一个重要差异LevelDB 没有事务。它支持批量写键值对和读快照但不能安全地执行 compare-and-swap 操作。Bolt 则支持完全可串行化的 ACID 事务。与 LMDBBolt 最初是 LMDB 的移植因此架构相似两者都用 B树都有 ACID 语义与完全可串行化的事务都支持单写多读的无锁 MVCC。两者也出现了一些分化LMDB 高度聚焦原始性能而 Bolt 聚焦简单易用。例如 LMDB 允许若干不安全操作如为性能直接写文件Bolt 则选择禁止任何可能把数据库置入损坏状态的操作——唯一例外是DB.NoSync。API 上也有差异LMDB 打开mdb_env时需要指定最大 mmap 大小Bolt 会自动增量调整 mmap 大小LMDB 用多种 flag 重载 getter/setterBolt 则把这些特例拆分为独立函数。十五、注意事项与限制Caveats Limitations选对工具很重要以下是评估和使用 Bolt 时需要留意的要点读写特性Bolt 适合读密集型工作负载顺序写也很快但随机写较慢。可用DB.Batch()或自行加预写日志缓解。随机页访问Bolt 内部使用 B树随机页访问较多SSD 相对机械磁盘能带来显著性能提升。避免长只读事务Bolt 使用写时复制copy-on-write旧事务仍在使用时旧页面无法被回收。字节切片生命周期Bolt 返回的字节切片只在事务期间有效。事务提交或回滚后它们指向的内存可能被新页面复用或从虚拟内存中解除映射访问时会触发unexpected fault addresspanic。单进程独占Bolt 对数据库文件使用排他写锁不能被多进程共享。Bucket.FillPercent慎用对随机插入的 Bucket 设置过高的 fill percent 会导致极差的页面利用率。使用较大的 Bucket过小的 Bucket 一旦超过页面大小通常 4KB会导致页面利用率差。批量随机写入向新 Bucket 批量加载大量随机写入可能很慢因为页面在事务提交前不会分裂。不建议在单个事务中向单个新 Bucket 随机插入超过 100,000 个键值对。内存映射与缓存Bolt 使用内存映射文件由操作系统处理数据缓存。OS 通常会尽量多缓存并按需释放内存给其他进程。因此操作大数据库时 Bolt 可能显示很高的内存占用这是预期行为Bolt 可以处理远大于物理 RAM 的数据库只要其内存映射能放进进程虚拟地址空间即可——在 32 位系统上可能有问题。字节序endiannessBolt 数据库的数据结构是内存映射的因此数据文件与字节序相关不能把小端机器上的 Bolt 文件拷到大端机器上直接使用。对多数用户无影响因为现代 CPU 大多是小端。空间不回收由于页面在磁盘上的布局方式Bolt不能截断数据文件把空闲页还给磁盘。它会在数据文件内维护一个空闲页列表freelist空闲页可被后续事务复用。删除大块数据后无法回收这部分磁盘空间数据库整体趋势是增长的场景下通常没问题。迭代中删除键值对在 cursor 迭代 Bucket 时删除键值对可能无法正确工作——每次删除后 cursor 可能自动移到下一个位置再调用c.Next()可能跳过一对键值对。初始化阶段掉电损坏bbolt 数据库在首次初始化阶段数据库中还没有任何数据时因突然断电可能损坏。该问题只在首次初始化阶段可复现正常生产环境很难复现一旦数据库文件完成初始化就不会再发生详见 etcd 仓库 issue 16596 的讨论。十六、阅读源码核心入口与两阶段提交Bolt 是一个相对较小的代码库不到 5K 行却实现了嵌入式、可串行化、事务性键值数据库是学习数据库原理的好起点。源码中最重要的几个入口点Open()初始化数据库引用。负责在文件不存在时创建文件、获取文件排他锁、读取 meta 页、以及内存映射整个文件。DB.Begin()根据writable参数启动只读或读-写事务。需要短暂获取 meta 锁以跟踪打开的事务读-写事务在同一时刻只能有一个因此 rwlock 在读-写事务存活期间被持有。Bucket.Put()向 Bucket 写入键值对。校验参数后用 cursor 在 B树中定位到页面及要写入的位置定位后Bucket 把底层页面及其父页面物化为内存中的 nodes。这些 nodes 是读-写事务期间发生变更的地方变更在提交时刷盘。Bucket.Get()从 Bucket 取键值对。用 cursor 定位。只读事务中key 和 value 以 mmap 文件的直接引用返回零分配开销读-写事务中可能引用 mmap 文件或内存 node 中的值。Cursor用于在磁盘页面或内存 nodes 组成的 B树中遍历。可以 seek 到特定 key、移到第一个/最后一个值或前后移动它对用户透明地处理 B树中的上下移动。Tx.Commit()实现见 vendor/go.etcd.io/bbolt/tx.go把内存中的脏 nodes 与空闲页列表转换为待写盘的页面。写盘分两个阶段第一阶段脏页写入磁盘并执行一次fsync()第二阶段写入一个事务 ID 递增的新 meta 页再执行一次fsync()。这种两阶段写入确保崩溃时由于指向它们的 meta 页从未写入部分写入的数据页会被忽略部分写入的 meta 页因带校验和checksum而被判定无效。十七、已知问题Linux ext4 fast commit 数据损坏风险当 Linux 内核版本 v5.10 引入的 [ext4 fast commit] 特性被启用时bbolt 可能遇到数据损坏问题。相关修复已合入稳定版 LTS 补丁级别 5.10.94 与 5.15.17ftruncate 追踪以及 5.15.27ineligible-commit 回退Linux 5.17 也包含这些修复但 5.17 不是 LTS 版本。若在生产使用 ext4请关注内核补丁级别。零长度值写入长度为 0 的值读取回来时总是空的[]byte{}值。十八、实战延伸bbolt 在 Grafana Mimir 中的应用上文已完整覆盖 bbolt 的 API 与原理最后回到当前仓库本身看看 bbolt 在 Grafana Mimir 中的真实工程实践——这能让上面的知识立刻落地。compactor-scheduler 的作业持久化Grafana Mimir 的compactor-scheduler组件架构说明见 docs/sources/mimir/references/architecture/components/compactor-scheduler/index.md负责把压缩作业调度给各 compactor worker。为了在重启、故障转移后不丢失作业状态它把作业信息持久化到本地磁盘的 bbolt 数据库中。该实现位于 pkg/compactor/scheduler/persistence_bbolt.go核心结构如下配置项BboltConfig包含Dirbbolt 分片数据库文件存放目录与ShardCountbbolt 数据库分片数。分片策略状态被分片到多个 bbolt 数据库文件中默认 16 个分片文件按bbolt_shard_000、bbolt_shard_001等命名每个租户通过xxhash jump hash 一致性哈希映射到某个分片见 shardForTenant。每个租户一个 Bucket租户名即 Bucket 名作业信息存放在该 Bucket 的键值对中此外还有一个名为.的特殊 bucket 存放元数据PersistenceMetadata记录分片数与创建时间。启动恢复scheduler 启动时通过RecoverAll遍历所有分片数据库的每个 Bucket重建各租户的JobTracker并清理无效租户 Bucket 与反序列化失败的 key——这一段完整用到了本文讲到的tx.Update、tx.View、tx.ForEach、Cursor迭代、CreateBucket、DeleteBucket、b.Put、b.Get、b.Delete等全部核心 API。分片数变更迁移修改-compactor-scheduler.bbolt.shard-count后下次启动会自动触发状态迁移扩缩分片迁移过程同样基于 bbolt 的跨库读写事务实现runMigration并先写元数据再删多余分片文件以保证崩溃安全。配置参数在scheduler.Config中pkg/compactor/scheduler/scheduler.go通过如下 CLI 标志与配置项控制 bbolt 持久化compactor_scheduler: # (experimental) compactor scheduler 使用的持久化类型。合法值none, bbolt # CLI flag: -compactor-scheduler.persistence-type [persistence_type: string | default bbolt] bbolt: # (experimental) compactor scheduler 的 bbolt 分片数据库文件存放目录。 # CLI flag: -compactor-scheduler.bbolt.dir [dir: string | default ./data-compactor-scheduler] # (experimental) compactor scheduler 的 bbolt 数据库分片目标数量。 # CLI flag: -compactor-scheduler.bbolt.shard-count [shard_count: int | default 16]上述参数说明与默认值同步记录在 docs/sources/mimir/configure/configuration-parameters/index.md。校验逻辑要求dir非空且shard_count 1见 persistence_bbolt.go并支持通过persistence_type: none关闭持久化pkg/compactor/scheduler/persistence.go。从 Mimir 用法看 bbolt 设计取舍Mimir 选择 bbolt 而非关系型数据库正契合本文前面提到的定位compactor scheduler 的作业状态是单进程可独占、按租户隔离、以键排序遍历按租户名与作业 ID的小型状态集bbolt 的 B树顺序遍历、零拷贝读取、单文件易备份、以及强一致 ACID 事务都恰到好处而单进程排他锁限制在这种本地持久化场景下并不构成问题。同时Mimir 用多文件分片 一致性哈希缓解了 bbolt 单文件、单写者的约束并通过启动时自动迁移实现分片数的在线调整——这是一个值得借鉴的把嵌入式 KV 用到分布式组件本地状态的工程范式。小结bbolt 以不足 5K 行的代码实现了单文件、零拷贝、B树、ACID 可串行化事务的嵌入式键值存储API 简洁但功能完备Update/View/Batch/Begin四种事务入口、Bucket 与嵌套 Bucket、基于 Cursor 的前缀/范围扫描、热备份、统计与只读模式一应俱全。它的限制同样明确单写者、单进程独占、随机写偏慢、空间不回收。理解这些特性之后再回看 Grafana Mimir 中 compactor-scheduler 用租户即 Bucket 一致性哈希分片 启动迁移的方式使用 bbolt就能真正体会选对工具的工程含义。赞分享时序数据库后端数据存储可观测性云原生【免费下载链接】mimirGrafana Mimir provides horizontally scalable, highly available, multi-tenant, long-term storage for Prometheus.项目地址https://gitcode.com/gh_mirrors/mimir/mimir点击查看免费下载相关推荐bbolt 嵌入式键值数据库完全指南从 B 树事务原理到 Loki 中的生产级应用bbolt 嵌入式键值数据库完全指南从 B 树事务原理到 Loki 中的生产级应用 bbolt go.etcd.io/bbolt 是一个纯 Go 实现的可观测性日志分析后端微服务对象存储云原生bbolt 嵌入式键值数据库完整实战指南纯 Go 实现的 B 树存储引擎与 ACID 事务bbolt 嵌入式键值数据库完整实战指南纯 Go 实现的 B 树存储引擎与 ACID 事务 本文以 bboltgo.etcd.io/bbolt官方 REKV存储嵌入式数据库bbolt 嵌入式键值数据库实战指南从 Bolt API 到事务与 B树原理解析bbolt 嵌入式键值数据库实战指南从 Bolt API 到事务与 B树原理解析 bbolt 是 Ben Johnson 所著 Bolt 键值存储的社区维护云原生容器编排集群管理微服务上一篇番茄小说下载器构建个人离线数字图书馆的终极指南下一篇番茄小说下载器架构深度解析与高级配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考