2. etcd 存储引擎：BoltDB 与 bbolt 的关系、核心数据结构、页与桶概念
2.1 BoltDB 与 bbolt：从开源库到 CNCF 孵化项目
etcd 的持久化存储层最早基于 BoltDB（一个由 Ben Johnson 开发的纯 Go 语言嵌入式键值存储引擎）。BoltDB 的设计灵感来源于 LMDB（Lightning Memory-Mapped Database），采用 B+ 树和内存映射文件（mmap）实现高吞吐读写。
2017 年，etcd 团队发现 BoltDB 在长期运行场景下存在 文件锁竞争 和 事务并发限制 等问题，且原仓库已停止维护。因此 etcd 团队 fork 了 BoltDB，在 etcd 仓库内进行深度定制，形成了 bbolt（即 etcd 内部的 BoltDB 分支）。
| 对比维度 | BoltDB（原版） | bbolt（etcd 分支） |
|---|---|---|
| 维护状态 | 已归档，不再更新 | CNCF 孵化项目，持续维护 |
| 文件锁 | 全局文件锁，多进程互斥 | 优化锁粒度，支持更细粒度并发 |
| 事务模型 | 单写多读（读写互斥） | 保留单写多读，但减少锁持有时间 |
| 内存映射 | 固定 mmap 大小 | 支持动态 mmap 大小调整 |
| 数据完整性 | 基础校验和 | 增强 freepage 校验，防止数据损坏 |
| API 兼容性 | 原始 API | 完全向后兼容，新增辅助函数 |
go.etcd.io/bbolt 模块。升级 etcd 时需关注 bbolt 版本号，避免因底层存储引擎变更导致数据格式不兼容。
2.2 bbolt 核心数据结构：B+ 树与内存映射文件
bbolt 的底层存储结构围绕 B+ 树 和 内存映射文件（mmap） 两个核心机制构建。所有数据最终以页（page）为单位存储在磁盘文件中，通过 mmap 将文件映射到进程地址空间，实现零拷贝读取。
2.2.1 B+ 树节点类型
- Branch Page（分支页）：内部节点，存储子页的指针和分隔键。用于引导查询路径，不存储实际键值对。
- Leaf Page（叶子页）：叶子节点，存储实际键值对数据。所有叶子页通过链表指针串联，支持顺序遍历。
- Meta Page（元数据页）：固定位于文件第 0 页和第 1 页，存储数据库魔数、版本号、根页 ID、空闲页链表指针等关键元信息。
- Freelist Page（空闲页链表页）：记录所有已释放可复用的页 ID，bbolt 在写入时优先从 freelist 分配页。
2.3 页（Page）与桶（Bucket）概念
2.3.1 页（Page）—— 最小的存储单元
bbolt 将数据库文件划分为固定大小的 页，默认页大小为 4KB（可通过 bolt.PageSize 配置）。每个页由页头和数据区组成：
| 页字段 | 偏移量 | 大小 | 说明 |
|---|---|---|---|
| id | 0 | 8 字节 | 页 ID，从 0 开始递增 |
| flags | 8 | 2 字节 | 页类型标识（branch/leaf/meta/freelist） |
| count | 10 | 2 字节 | 页内元素数量（分支页为键数，叶子页为键值对数） |
| overflow | 12 | 4 字节 | 溢出页数量（当数据超过单页大小时使用） |
| ptr | 16 | 可变 | 数据区起始指针 |
当单个键值对超过页大小时，bbolt 会分配 溢出页（overflow page），通过页头的 overflow 字段记录连续溢出页的数量。溢出页会显著增加 I/O 开销，是容量水位评估中需要重点关注的异常场景。
2.3.2 桶（Bucket）—— 逻辑命名空间
桶（Bucket） 是 bbolt 提供的逻辑数据隔离单元，类似于关系数据库中的“表”。每个桶内部拥有一棵独立的 B+ 树，桶之间通过 根页 ID 区分。etcd 使用多个桶来存储不同类型的数据：
| 桶名称 | 存储内容 | 键格式 | 容量特征 |
|---|---|---|---|
key |
用户存储的键值对 | 原始 key 字节 | 随用户数据线性增长 |
history |
历史版本记录（MVCC） | revision + key | 随写操作和压缩策略波动 |
meta |
集群元数据（成员、租约等） | 固定键 | 相对稳定，少量增长 |
lease |
租约信息 | 租约 ID | 与租约数量成正比 |
2.3.3 桶的嵌套与容量影响
bbolt 支持 嵌套桶（nested bucket），即桶内可以再创建子桶。etcd 并未使用嵌套桶，所有数据直接存储在顶层桶中。但理解嵌套桶机制有助于分析容量水位：
- 每个桶的根页 ID 存储在父桶的叶子页中，占用额外的键值对空间。
- 嵌套桶的创建和删除会导致父桶 B+ 树的分裂与合并，产生临时页碎片。
- 在容量评估时，若发现大量嵌套桶，需额外计算桶元数据开销（每个桶约 40 字节 + 根页指针）。
2.4 页分配与回收机制
bbolt 的页分配策略直接影响存储容量和写入性能：
| 操作 | 页分配行为 | 容量影响 |
|---|---|---|
| 写入新键值对 | 从 freelist 获取空闲页，若无则追加到文件末尾 | 文件大小增长 |
| 更新键值对 | 若新数据大于旧数据，分配新页，旧页加入 freelist | 产生碎片，文件大小可能不变或增长 |
| 删除键值对 | 叶子页变空后释放回 freelist，B+ 树可能合并 | 文件大小不缩小，空闲页被复用 |
| 事务提交 | 将脏页写入文件，更新 meta page | 写放大（脏页可能多于实际数据页） |
etcdctl check datascale 或直接读取 bbolt 的 DB.Stats() 方法，可以获取当前数据库的页总数、空闲页数、溢出页数等关键指标。空闲页占比超过 30% 时，建议执行 etcdctl defrag 进行碎片整理，回收空闲页空间。