《Kubernetes 分布式系统原理深入解析》9.3 etcd 压缩策略、碎片整理与 defrag

etcd 的压缩是三层递进的:Raft 日志压缩(snapshot)只管协议层的日志,mvcc 历史版本压缩(auto-compaction,按 period 或 revision)管键值的历史版本,而存储碎片整理(defrag)才是真正把磁盘空间还给文件系统的一步。本节先讲清楚这三层的边界与默认值(--snapshot-count=100000、--auto-compaction-mode 与 --auto-compaction-retention、--quota-backend-bytes 默认 2GB),再解释为什么 mvcc 压缩后空间未必立即释放——bolt 数据库的碎片;然后给出 etcdctl defrag 与在线 defrag 的用法与代价。K8s 运维实践部分覆盖常见的 8h 保留配置、磁盘告警与逐台 defrag。最后梳理两类压缩故障:mvcc 压缩过快丢 watch 历史(ErrCompacted),以及 defrag 期间的性能下降,并预告 12 章 mvcc 的深入衔接。lab 用 snapshot.go 的 Compact 与 Install、以及 TestSnapshotCompaction 与 TestInstallSnapshot 联合验证「日志压缩→快照」与「落后节点从快照恢复」两个方向。

9.3 etcd 压缩策略、碎片整理与 defrag

9.1 与 9.2 把 Raft 日志压缩讲清楚了:日志压成快照,落后节点靠 InstallSnapshot 对齐。但 etcd 的存储不止日志一层——它把键值放进 mvcc 后端,每个键保留多个历史 revision,文件系统上的库文件是 bbolt。于是 etcd 的压缩其实是三层递进:Raft 日志压缩、mvcc 历史版本压缩、存储碎片整理。前两层只是「在逻辑上删掉数据」,第三层才是「把磁盘空间真正还回来」。

本节把这三层的边界、默认值、运维命令和故障场景逐一讲清楚。压缩做不好,K8s 控制面的第一个报警通常是 etcdserver: mvcc: database space exceeded——而它往往不是因为没做压缩,而是因为压缩少了第三层。

三层压缩的边界与职责分工

先给一张总览表,三层分别处理什么、由什么触发、默认值是多少:

层处理对象触发/配置默认
第一层 Raft 日志压缩日志条目--snapshot-count100000
第二层 mvcc 版本压缩键的历史 revision--auto-compaction-mode + --auto-compaction-retentionperiodic + 0(关闭)
第三层 碎片整理bolt 文件内的空闲页etcdctl defrag(手动)——

三层的分工可以这样记:snapshot 管「日志」,auto-compaction 管「revision」,defrag 管「文件」。前两层删的是逻辑数据,第三层删的是物理碎片。遗漏任何一层,都会在某个时刻以磁盘空间的方式反弹回来。

为什么是三层而不是一层?因为三者的生命周期与回收单位完全不同:日志以「条」为单位、按快照批次回收;revision 以「版本号」为单位、按压缩点回收;文件页以「页」为单位、按 defrag 重写回收。三者各自独立演进,任何一个环节慢下来,都在自己的维度积累债务。这也决定了运维上不能只配一个参数了事——三层要分别检查、分别调优。

第一层:Raft 日志压缩(snapshot)

这一层是 9.1/9.2 的内容,这里只从「三层之一」的角度补充定位:它处理的是 Raft 日志条目,目标是让 WAL 与内存日志有界。已应用条目数超过 --snapshot-count(默认 100000)就生成快照、截断日志;落后 follower 靠 InstallSnapshot 对齐。

这一层不碰 mvcc 的 revision:快照的 data 虽然是一份库拷贝,但它只是「当时的库」,压缩日志并不删除库里的旧 revision。换句话说,日志压缩让 Raft 层干净了,但 mvcc 层的历史版本还在占用后端空间。这就是为什么只做 snapshot 还不够——它解决的是日志问题,不是数据版本问题。

第二层:mvcc 历史版本压缩(auto-compaction)

etcd 的键值存储是版本化的:每个键的每次变更都产生一个新的 revision——一次 put 写入新值并推进 revision,一次 delete 不立即删数据,而是写入一个墓碑(tombstone)并在删除处推进 revision。于是后端库里堆积的不只是「当前值」,还有每个键的全部历史版本。对 K8s 来说,这意味着同一个对象的几十次 status 更新在库里保留了几十个 revision。

mvcc 压缩就是删除「压缩点之前」的旧 revision,只保留最新值。它由 --auto-compaction-mode 与 --auto-compaction-retention 控制:

  • periodic 模式(默认):retention 是时间长度,如 8h,etcd 保留最近 8 小时的 revision,更旧的周期性压缩掉;
  • revision 模式:retention 是一个 revision 数量,如 10000,etcd 保留最近 10000 个 revision;
  • --auto-compaction-retention 默认 0,即自动压缩默认关闭——这是 K8s 场景一定要显式打开的原因。

除了自动压缩,还有手动命令 etcdctl compact <revision>:直接把压缩点推到指定 revision。手动压缩通常用于「已知某个关键时刻之前的版本都没用了」,而自动压缩用于持续保护。

auto-compaction 的两种模式怎么选

periodic 与 revision 两种模式各有适用场景:

  • periodic(按时间):retention 是时长,语义直观——「保留最近 8 小时的 revision」。它最匹配运维直觉,也是 K8s 场景的主流选择。缺点是如果写入速率波动大,同样的时长在不同时段保留的 revision 数量差别很大:写入高峰的一小时可能产生平时十倍的 revision。
  • revision(按数量):retention 是 revision 数量——「保留最近 10000 个 revision」。它把库的增长控制在一个绝对数量上,适合写入速率极不均匀、更关心「库别超过某个体积」的场景。缺点是不直观,很难估算「10000 个 revision 对应多久」。

选哪种没有绝对答案,但对 K8s 控制面,periodic + 8h 是社区验证过的默认组合:watch 客户端(informer)的重试窗口通常远小于 8 小时,8h 足够覆盖绝大多数 watch 断连重连场景。改用 revision 模式时,一个可参考的起点是把 retention 设在「8 小时写入量」对应的 revision 数上。

压缩点能推到哪:revision 的边界

压缩点本身是一个 revision 号,它有明确的边界约束,理解这些边界能避免很多误操作:

  • 压缩点必须 ≤ 当前最大 revision——不能压缩「还不存在的版本」;etcdctl compact 传一个超出现有范围的 revision 会报错或退化成 no-op;
  • 压缩点只能前进不能后退——已经压缩过的 revision 再重复压缩是无效操作;
  • 压缩点以下的 revision 会被删除,因此 watch 从压缩点以下开始必然收到 ErrCompacted——这决定了 retention 必须大于「最长的 watch 存活窗口」;
  • 手动 etcdctl compact 之后立即 etcdctl defrag,是一套完整的「手动清理历史版本 + 回收磁盘」组合拳,常用于大维护前的一次性清理。

这四条边界在 12 章 mvcc 会从存储模型层面重新推导一遍,本节先记住结论:压缩点永远只删「过去的版本」,绝不碰「当前版本」。

第三层:存储碎片整理(defrag)

第二层压缩在逻辑上删掉了旧 revision,但 bolt 文件不会自动缩容。bbolt 是 COW(copy-on-write)的 B+ 树文件:每次事务写都创建新页,旧页并不立即回收,而是留作空闲页供后续写入复用。mvcc 压缩把旧 revision 标记删除后,这些页在文件内部变成 free 页,但文件长度不变。

defrag 把库文件重写一遍,把空闲页压缩掉,空间才还给文件系统。这是唯一直接作用于磁盘占用的步骤。--quota-backend-bytes(默认 2GB)衡量的是文件大小,所以只要不 defrag,文件就可能撞上限——哪怕逻辑上数据已经删干净了。

为什么 mvcc 压缩后空间未必立即释放

这是 etcd 运维里最容易踩的坑:etcdctl compact 或 auto-compaction 执行后,du 看库文件还是那么大,甚至告警还在。原因就是上一节说的 COW 模型。

bbolt 的空闲页管理是「先留着给后续写复用」:新写入优先使用 free 页,而不是从文件尾部追加。所以:

  • 压缩后立即 defrag,文件大幅缩水;
  • 不 defrag 继续运行,free 页会被后续写入逐渐消化,文件大小可能横盘甚至继续增长;
  • 删除速度持续高于写入速度时,空洞率持续上升,文件最终撞上 2GB 配额。

实测量级:一个库文件 1.6GB 的 etcd,其中 1.2GB 可能是删除后残留的空闲页,etcdctl defrag 之后文件可能降到 400MB。这也是为什么 K8s 运维手册把 defrag 写成一个周期性动作——auto-compaction 只是第一步,defrag 才是收尾。

etcdctl defrag 与在线 defrag:命令与代价

defrag 的命令是 etcdctl defrag,不带端点时对本地默认端点执行,多成员集群要对每个成员分别执行:

etcdctl defrag --endpoints=http://10.0.0.1:2379
etcdctl defrag --endpoints=http://10.0.0.2:2379
etcdctl defrag --endpoints=http://10.0.0.3:2379

etcd 3.4 起支持在线 defrag:成员进程不停,etcdctl defrag 通过 maintenance 端点的 Defragment RPC 把库重写一遍。但要清醒认识它的代价——defrag 期间该成员会阻塞写请求,因为 bbolt 要求独占访问来重写文件;对 apiserver 来说就是写 etcd 超时。因此生产实践有一条固定流程:

  1. 逐台执行,一次只 defrag 一个成员,绝不并发;
  2. defrag 前先确认该成员不是 Leader(必要时转移 leader),降低阻塞面;
  3. defrag 安排在低峰期,预留该成员短暂不可写的窗口;
  4. 注意磁盘余量:defrag 重写期间需要额外的临时空间,库越大要求越高。

如果不做 defrag 会怎样?当删除速度持续高于写入速度,空洞率持续上升,库文件最终撞上 --quota-backend-bytes 上限,etcd 进入只读保护,整个 K8s 控制面停止写入。这类故障解不掉的原因通常是只做了 auto-compaction、没做 defrag。

K8s 的 etcd 运维实践:8h、告警与轮转

K8s 控制面的 etcd 推荐配置里,auto-compaction 几乎必开。常见配置是保留最近 8 小时的历史版本:

--auto-compaction-mode=periodic
--auto-compaction-retention=8h

历史文档里常见裸写 --auto-compaction-retention=8,在老版本 etcd 中同样表示 8 小时;新版显式加 8h 单位后语义更明确,写配置时以目标 etcd 版本文档为准。为什么是 8 小时而不是更长?保留太久意味着 mvcc 库更大、defrag 更慢、内存里的索引更多;保留太短则 watch 客户端容易撞上 ErrCompacted(见下)。8 小时是一个「让绝大多数在线 watch 存活」与「库不至于失控」之间的经验平衡点。

K8s 文档对 etcd 还有两个常规要求:数据目录放在性能足够的盘上(fsync 延迟直接决定写延迟),以及持续监控磁盘用量。对应的 Prometheus 指标是 etcd_mvcc_db_total_size_in_bytes 与 etcd_server_slow_apply_total,前者反映库文件大小与配额的距离,后者反映 apply 是否因为磁盘慢而堆积。日志轮转同样属于运维的一部分:/var/log/ 下的 etcd 日志由系统轮转管理,而 member/wal/ 与 member/snap/ 的清理节奏由 --max-wal-files(默认 5)与 --max-snapshots(默认 5)约束——配置过大会让这两个目录缓慢膨胀,与 defrag 属于同一类「磁盘空间管理」问题。

K8s 特有的大 revision 场景

理解 K8s 为什么会产生远超「键数量」的 revision,有三个典型场景:

  • Event 对象:K8s 把事件也存进 etcd(事件 key 带 time-based lease)。一次故障期间数百个事件涌入,每个事件都是一个新 revision;旧事件过期删除后留下墓碑,直到压缩才真正回收——这是 revision 堆积最快的来源之一。
  • ConfigMap/Secret 轮转:控制器常以「新名字创建新对象」的方式轮转配置,旧对象不会被删除而是被替换引用,键数量随时间累积,revision 数随之增长。
  • 批处理与 CronJob:每次 Job 创建一批 Pod,每个 Pod 的创建、调度、容器状态更新都是一系列 revision;短时间内容器反复重启会把同一 Pod 的 revision 数推到几十。

这些场景共同的特点是:revision 的增长速率由「对象变更事件」决定,而不是由「键的当前数量」决定。所以 K8s 集群的 etcd 需要 auto-compaction 是必然的,不是可选项。判断 retention 是否够用,可以观察一个指标:etcd_mvcc_db_total_size_in_bytes 是否在一个窗口内被异常抬高——如果是,先看是不是上述三类 churn 之一在作祟。

另一个更直接的估算法:观察几小时内的最大 revision 增长,算出每小时新增 revision 数,再乘以 retention 时长,就能估算 auto-compaction 生效后库的稳定量级。例如每小时 20 万 revision、retention 8h,那么库里的活跃 revision 大致稳定在 160 万左右,乘以单 revision 的平均体积,就是 etcd 库的预期规模。

压缩不当的两类故障

第一类故障是 mvcc 压缩过快导致 watch 历史丢失。watch 是按 revision 订阅的:客户端从某个 revision 开始 watch,如果该 revision 已经被 compact 掉,就会收到 ErrCompacted(错误信息为 etcdserver: mvcc: required revision has been compacted)。K8s 的 informer 收到这个错误会强制 relist 全量对象再重建 watch——功能上能自愈,但一次全量 relist 对大型集群是数千个对象的下载,成本不小。auto-compaction-retention 设置过短(比如几十分钟)会频繁触发这种 relist;另一个触发点是某些控制面组件长时间不 watch(比如节点离线很久),恢复时恰好踩在压缩点之后。

第二类故障是 defrag 期间的性能下降。前面说过 defrag 会阻塞成员;在低峰期逐台执行、错开 leader 的情况下通常无感,但在高峰期硬做 defrag,会出现 apiserver 写超时、控制器重试风暴。教训是:defrag 要计划,不能等配额告警响了才临时补做——告警状态下的库已经很大,defrag 更慢、阻塞更久,形成「越急越慢」的恶性循环。合理的节奏是定期(比如每月)检查 etcd_mvcc_db_total_size_in_bytes 的空洞率,接近告警阈值之前就安排一次低峰期的逐台 defrag。

压缩与配额告警的排查路径

遇到 etcdserver: mvcc: database space exceeded 时,不要急着调大 --quota-backend-bytes(那只是把崩溃点往后推),按三层顺序排查:

  1. 看第一层:Raft 日志是否在正常压缩——--snapshot-count 是否保持默认、member/wal/ 是否异常膨胀。若 WAL 目录持续增长,快照生成可能被卡住。
  2. 看第二层:auto-compaction 是否真的开着——--auto-compaction-retention 为 0 就什么都没做;确认模式与 retention 已生效。
  3. 看第三层:库文件的空洞率——比较两个指标:etcd_mvcc_db_total_size_in_bytes(文件总大小)与 etcd_mvcc_db_total_size_in_use_in_bytes(实际使用字节)。前者远大于后者就是碎片化严重,此时 defrag 是唯一解。

实际排障里最常见的组合是「第一层、第二层都正常,但库文件依然逼近 2GB」——原因几乎总是第三层没做:mvcc 压缩删了数据,bbolt 文件没有缩容。正确动作是低峰期逐台 etcdctl defrag,而不是调大配额。记住一句话:配额是上限不是目标,健康的状态是库文件长期稳定在一个明显低于配额的量级。

与 mvcc 的衔接

本节的第二层压缩(revision 压缩)依赖一个尚未展开的模型:etcd 的 mvcc 用 revision 作为全局单调版本号,每个键的每次变更都产生新 revision,watch、lease、事务都建立在这个模型上。为什么压缩点是一个 revision 号、为什么墓碑要保留到压缩之后、为什么 ErrCompacted 的判断逻辑是这样——这些问题的完整答案在第 12 章 mvcc 里。本节先把运维视角的三层压缩讲完,等 12 章再补上存储模型本身。到那时再看三层压缩,你会明白 snapshot、auto-compaction、defrag 其实是同一个存储模型的三道闸门:日志闸、版本闸、文件闸。

一个值得提前记住的对应关系是:本节的「压缩点是一个 revision」与 9.1 节的「压缩点是 applyIndex」并不冲突——applyIndex 是 Raft 日志层的下标,revision 是 mvcc 层的版本号,两者由 etcd 在 apply 时一一对齐。Raft 层压到哪,mvcc 层就能安全地压到对应的 revision;这正是两层压缩能叠起来而不互相破坏的原因。

本节 lab

本节验证的是 9.1/9.2 两个方向的联合:日志压缩成快照,落后节点从快照恢复。代码在 private/labs/k8s-etcd-lab/raft/snapshot.go 的 Compact 与 Install,测试在 replication_test.go:

cd private/labs/k8s-etcd-lab
go test ./raft -run 'TestSnapshotCompaction|TestInstallSnapshot' -v

TestSnapshotCompaction 验证「日志压缩→快照」方向:集群提交 4 条命令并全部 apply 后,Compact(3) 生成快照,快照保留 set:c=3 与 set:d=4 的已应用状态,日志条数从 4 降到 ≤1。TestInstallSnapshot 验证「落后节点从快照恢复」方向:Leader 压缩到 ApplyIndex 后生成快照,新建空日志节点 Install 该快照,状态机直接包含 set:b=2,CommitIndex 对齐到 Leader 的 ApplyIndex。

两个测试覆盖的正是本节三层压缩里第一层的完整闭环:压缩点必须选在已应用位置(Raft 日志压缩的前提),快照作为传播载体让落后节点一步到位(InstallSnapshot 的目标)。

mvcc 的 revision 压缩与 defrag 属于 etcd 存储层行为,不在这个 Raft lab 的范围内——它们在 12 章 mvcc 配套的 lab 中验证。

运行 go test ./raft -run 'TestSnapshotCompaction|TestInstallSnapshot' -v 通过即表示两个方向都符合语义。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图