etcd 持久化存储文件

本文介绍了 etcd 持久化存储格式：命名规则、内容结构以及可供开发者用于检查存储内容的工具。后续应随着存储模型的变更持续扩展本文内容。本文面向 etcd 开发者，旨在帮助其满足数据恢复需求。

先决条件

以下文章为本文提供了有益的背景信息：

• etcd 数据模型概述
• Raft 概述 （特别是“5.3 日志复制”节）。

概述

长期存在的文件

./member/snap/db

./member/snap/0000000000000002-0000000000049425.snap
./member/snap/0000000000000002-0000000000061ace.snap

/member/snap/000000000007a178.snap.db

./member/wal/000000000000000f-00000000000b38c7.wal
./member/wal/000000000000000e-00000000000a7fe3.wal
./member/wal/000000000000000d-000000000009c70c.wal

./member/wal/0.tmp (or .../1.tmp)

临时文件

在 etcd 内部处理过程中，可能会遇到多个生命周期较短的文件：

./member/snap/0000000000000002-000000000007a178.snap.broken

./member/snap/tmp071677638 (random suffix)

/member/snap/db.tmp.071677638 (random suffix)

bbolt B+ 树：member/snap/db

该文件包含已应用至 Raft 日志某个特定位置的 etcd 主要内容（参见 consistent_index ）。

物理组织结构

Bolt 存储系统在物理上按 B+树 组织。B+树的物理页永远不会原地修改¹。相反，内容会被复制到新页（从空闲页列表中回收）中，一旦没有正在运行的事务可能访问该旧页，该旧页即被加入空闲页列表。得益于这一机制，打开的只读（RO）事务可观察到存储系统一致的历史状态。读写（RW）事务具有排他性，会阻塞其他所有读写事务。 大值存储在多个连续页上。页回收过程与需分配不同大小的连续页区域的需求相结合，可能导致 bbolt 存储系统出现日益严重的碎片化。

bbolt 文件不会自行缩小。只有在执行碎片整理过程中，文件才能被重写为一个新的文件，该文件末尾保留了一定数量的空闲页，并且大小已被截断。

逻辑组织

bbolt 存储系统划分为多个桶。每个桶中以字典序存储键（byte[]→value byte[] 键值对）。下表列出了 etcd（截至版本 3.5）所使用的桶及其使用的键。

{
  "target-version": "3.4.0"
  "enabled": true/false
}

{
  "id":10276657743932975437,
  "peerURLs":[
  "http://localhost:2380"],
  "name":"default",
  "clientURLs": ["http://localhost:2379"]
}

工具

bbolt

bbolt 提供了一个命令行工具，可用于检查文件内容。

使用示例：

列出给定 bbolt 文件中的所有桶：

% go run go.etcd.io/bbolt/cmd/bbolt buckets ./default.etcd/member/snap/db

读取特定键值对：

% go run go.etcd.io/bbolt/cmd/bbolt get ./default.etcd/member/snap/db cluster clusterVersion

etcd-dump-db

etcd-dump-db 可用于列出 v3 etcd 后端数据库（bbolt）的内容。

% go run go.etcd.io/etcd/v3/tools/etcd-dump-db  list-bucket default.etcd
alarm
auth
...

更多示例请参见：https://github.com/etcd-io/etcd/tree/master/tools/etcd-dump-db

WAL：预写日志

预写日志（Write Ahead Log）是 Raft 协议的持久化存储，用于存储提案。首先，领导者将提案写入其日志，然后（并发地）通过 Raft 协议将提案复制到跟随者。每个跟随者在向领导者确认复制之前，会先将其提案持久化到自身的 WAL 中。

etcd 中使用的 WAL 日志与标准 Raft 模型存在两方面的差异：

• 它不仅持久化索引条目，还持久化 Raft 快照（轻量级）和硬状态。因此，仅通过 WAL 日志即可恢复成员的完整 Raft 状态。
• WAL 只支持追加写入。条目不会原地覆盖；后续追加到文件中的同索引条目会取代先前的条目。

文件名

WAL 日志文件的命名遵循以下模式：

"%016x-%016x.wal", seq, index

示例：./member/wal/0000000000000010-00000000000bf1e6.wal

因此，文件名包含十六进制编码：

• WAL 日志文件的顺序编号
• 文件中第一条条目或快照的索引。 特别地，第一个文件“0000000000000000-0000000000000000.wal”包含索引为 0 的初始快照记录。

物理内容

WAL 日志文件由一系列“帧 ”组成。每个帧包含：

1. 使用 LittleEndian ² 编码的 uint64，表示序列化后 walpb.Record 的长度（3）。
2. 填充：若干个 0 字节，使整个帧的大小按 8 字节对齐。
3. 序列化后的 walpb.Record 数据：
   1. type - 以整数编码的枚举，用于决定如何解释下述 data 字段
   2. data - 由类型决定，通常是序列化后的 Protocol Buffers 数据
   3. crc - 自 WAL 日志创建以来，该副本上所有日志记录中所有“data”字段（不包含 type）的 RC-32 校验和。请注意，CRC 计算包含所有记录（即使它们未被 Raft 提交）。

当当前文件超过 64*10^6 字节时，会将其切分并开始写入新文件。

逻辑内容

预写日志文件在逻辑层包含：

• Raftpb.Entry: 由 Raft 领导者复制的最近提案。其中部分提案被视为“已提交”，其余提案可能被逻辑覆盖。
• Raftpb.HardState(term,commit,vote): 关于日志条目索引的周期性（非常频繁）信息，该索引表示条目已“提交”（复制到多数服务器），因此保证不会被更改或覆盖，并可应用于后端（v2、v3）。该信息还包含“任期”（指示是否存在与选举相关的变更）以及投票信息——当前副本在当前任期中投给的成员。
• walpb.Snapshot(term, index): Raft 状态的周期性快照（不包含数据库内容，仅包含快照日志索引和 Raft 任期）
  • v2 存储内容存储在独立的 *.store 文件中。
  • v3 存储内容保存在 bbolt 文件中，一旦条目被应用，该文件即成为隐式快照。
• crc32 校验和记录（位于每个文件开头），用于恢复对文件剩余部分的 CRC 检查。
• etcdserverpb.Metadata(node_id, cluster_id) —— 用于标识日志所代表的集群与副本。

每个 WAL 日志文件按以下顺序构建：

1. CRC-32 帧（从之前所有文件延续的 CRC；第一个文件为 0）。

2. 元数据帧（集群 ID 与副本 ID）。

3. 仅初始 WAL 文件包含：

   • 空快照帧（索引：0，任期：0）。 此帧用于维持一个不变量：所有条目之前均有一个快照。

   对于非初始（第 2 个及后续）WAL 文件：

   • HardState 帧。

4. 条目、硬状态与快照记录的混合

WAL 日志可能包含同一索引的多个条目。这种情况可能出现在 Raft 论文 图 7 所描述的场景中。etcd 的 WAL 日志仅支持追加写入，因此当新条目以相同索引写入时，原有条目会被覆盖。

特别是在读取 WAL 时，逻辑会用新条目覆盖旧条目 。因此，仅当条目索引 entry.index <= HardState.commit 时，才可视为最终版本。索引大于 HardState.commit 的条目可能发生变化。

WAL 日志中的“任期”应保持单调递增。

WAL 日志中的“索引”预期满足以下要求：

1. 从某个快照开始
2. 在该任期期间，索引应持续递增
3. 若任期发生变化，索引可能减少，但必须大于最新的 HardState.commit 值
4. 任意索引大于等于 HardState.commit 的新快照都可能发生，从而开启新的索引序列

工具

etcd-dump-logs

etcd 的 WAL 日志可使用 etcd-dump-logs 工具读取：

% go install go.etcd.io/etcd/v3/tools/etcd-dump-logs@latest

% go run go.etcd.io/etcd/v3/tools/etcd-dump-logs --start-index=0 aname.etcd

请注意：

• 该工具仅显示条目，而不显示 WAL 日志文件中的所有记录（如快照、HardState）。
• 该工具会自动应用“覆盖”规则。若某条目被同一索引下更新的条目覆盖，则工具仅输出最终值。
• 该工具还会输出未提交的条目（来自日志尾部），但不包含 HardState.commitIndex 信息，因此无法判断条目是否为最终值。

Store V2 快照：member/snap/{term}-{index}.snap

文件名：

member/snap/{term}-{index}.snap

文件名在 此处 ("%016x-%016x.snap") 生成，采用 2 个十六进制编码的组合形式：

• term -> 快照生成时的 Raft 任期（两次选举之间的时段）
• index -> 快照生成时最后一个已应用提案的索引

创建

*.snap 文件由 Snapshotter.SaveSnap 方法创建。

有两个触发器控制这些文件的创建：

• 每处理大约 –snapshotCount=（默认为 100'000）个已应用提案，就会创建一个新文件。这只是近似值：提案可能分批到达，而系统只会在一批处理结束时考虑生成快照，最终的快照过程还会异步调度。 标志名 –snapshotCount 容易产生误解：它控制最后一次快照索引与最后一次已应用提案索引之间的索引差 。
• Raft 请求副本从快照恢复。副本通过网络接收快照（msgSnap 消息）时，也会将其以轻量方式记录到 WAL 日志中。这可确保 WAL 日志尾部始终存在一个后接日志条目的有效快照，从而避免 WAL 日志中可能出现的不连续。

目前，这些文件大致³与 WAL 日志中的 Snapshot 条目一一对应。随着 v2 存储系统停用，预计将彻底停止写入这些文件（3.5.x 可选启用，3.6.x 强制执行）。

内容

该文件包含序列化后的 snapdb.snapshot proto (uint32 crc, bytes data)，

其中 data 字段包含 Raftpb.Snapshot ：

（字节数据，SnapshotMetadata{index, term, conf } 元数据），

最后，嵌套数据包含序列化为 JSON 格式的 存储 v2 内容 。

特别是存在：

• 任期
• 索引
• 成员数据：
  • /0/members/8e9e05c52164694d/attributes -> {"name":"default","clientURLs":["http://localhost:2379"]}
  • /0/members/8e9e05c52164694d/RaftAttributes -> "{"peerURLs":["http://localhost:2380"]}"
• 存储版本：/0/version -> 3.5.0

工具

protoc

以下命令可在 etcd 根目录下执行，用于查看文件内容：

cat default.etcd/member/snap/0000000000000002-0000000000049425.snap |
  protoc --decode=snappb.snapshot \
    server/etcdserver/api/snap/snappb/snap.proto \
    -I $(go list -f '{{.Dir}}' github.com/gogo/protobuf/proto)/.. \
    -I . \
    -I $(go list -m -f '{{.Dir}}' github.com/gogo/protobuf)/protobuf

类似地，可以提取 data 字段，并将其解码为 Raftpb.Snapshot 。

etcd 3.4 *.snap 文件中示例 JSON 序列化存储 v2 内容：

{
  "Root":{
    "Path":"/",
    "CreatedIndex":0,
    "ModifiedIndex":0,
    "ExpireTime":"0001-01-01T00:00:00Z",
    "Value":"",
    "Children":{
      "0":{
        "Path":"/0",
        "CreatedIndex":0,
        "ModifiedIndex":0,
        "ExpireTime":"0001-01-01T00:00:00Z",
        "Value":"",
        "Children":{
          "members":{
            "Path":"/0/members",
            "CreatedIndex":1,
            "ModifiedIndex":1,
            "ExpireTime":"0001-01-01T00:00:00Z",
            "Value":"",
            "Children":{
              "8e9e05c52164694d":{
                "Path":"/0/members/8e9e05c52164694d",
                "CreatedIndex":1,
                "ModifiedIndex":1,
                "ExpireTime":"0001-01-01T00:00:00Z",
                "Value":"",
                "Children":{
                  "attributes":{
                    "Path":"/0/members/8e9e05c52164694d/attributes",
                    "CreatedIndex":2,
                    "ModifiedIndex":2,
                    "ExpireTime":"0001-01-01T00:00:00Z",
                    "Value":"{\"name\":\"default\",\"clientURLs\":[\"http://localhost:2379\"]}",
                    "Children":null
                  },
                  "RaftAttributes":{
                    "Path":"/0/members/8e9e05c52164694d/RaftAttributes",
                    "CreatedIndex":1,
                    "ModifiedIndex":1,
                    "ExpireTime":"0001-01-01T00:00:00Z",
                    "Value":"{\"peerURLs\":[\"http://localhost:2380\"]}",
                    "Children":null
                  }
                }
              }
            }
          },
          "version":{
            "Path":"/0/version",
            "CreatedIndex":3,
            "ModifiedIndex":3,
            "ExpireTime":"0001-01-01T00:00:00Z",
            "Value":"3.5.0",
            "Children":null
          }
        }
      },
      "1":{
        "Path":"/1",
        "CreatedIndex":0,
        "ModifiedIndex":0,
        "ExpireTime":"0001-01-01T00:00:00Z",
        "Value":"",
        "Children":{


        }
      }
    }
  },
  "WatcherHub":{
    "EventHistory":{
      "Queue":{
        "Events":[
          {
            "action":"create",
            "node":{
              "key":"/0/members/8e9e05c52164694d/RaftAttributes",
              "value":"{\"peerURLs\":[\"http://localhost:2380\"]}",
              "modifiedIndex":1,
              "createdIndex":1
            }
          },
          {
            "action":"set",
            "node":{
              "key":"/0/members/8e9e05c52164694d/attributes",
              "value":"{\"name\":\"default\",\"clientURLs\":[\"http://localhost:2379\"]}",
              "modifiedIndex":2,
              "createdIndex":2
            }
          },
          {
            "action":"set",
            "node":{
              "key":"/0/version",
              "value":"3.5.0",
              "modifiedIndex":3,
              "createdIndex":3
            }
          }
        ]
      }
    }
  }
}

变更记录

本节用于描述不同 etcd 版本之间引入的文件格式变更。