【etcd】运维与升级：member change、backup/restore 与 3.5→3.6/3.7 门

etcd 运维事故里有两类「不可逆」：一类是 quorum 丢失后没有近期 snapshot；另一类是 全集群 minor 升级完成后才发现配置仍依赖已删除的 --experimental-* 或 v2 路径——此时不能靠换回旧二进制 rollback，只能从升级前 snapshot restore。member replace 与 learner promote 若跳步骤，则表现为 Raft 轴 no leader 或 WAL 轴 corrupt member。

本文钉 etcd v3.5.33 生产栈上的运维动作：成员变更、备份恢复、滚动升级，以及官方文档对 3.5→3.6→3.7 的门禁项。3.6/3.7 独有特性不在正文当 v3.5.33 事实写；升级门只列文档已钉的检查项。无真实集群则不粘贴伪造 etcdctl endpoint status 输出。

本篇在系列中的位置

篇目核心内容

第 13 篇 · K8s 控制面耦合 apiserver、resourceVersion、Node Lease

第 14 篇 · 运维与升级 member change、backup/restore、升级门

第 15 篇 · 排障五轴 Raft/WAL/MVCC/Watch/Lease 口令表

系列目录全部篇目

篇目	核心内容
第 13 篇 · K8s 控制面耦合	apiserver、resourceVersion、Node Lease
第 14 篇 · 运维与升级	member change、backup/restore、升级门
第 15 篇 · 排障五轴	Raft/WAL/MVCC/Watch/Lease 口令表
系列目录	全部篇目

版本锚定：正文机制 etcd v3.5.33（tag v3.5.33）。3.6/3.7 升级指南引用 etcd.io/docs/v3.6/upgrades 与 v3.7/upgrades/upgrade_3_7——开升级前须再核当前 live 文档与 CHANGELOG，本篇不冒充最新 patch 矩阵。

一、运维总原则

原则	依据
升级前必 snapshot	Disaster recovery（A）
一次只升一个 minor	3.5 → 3.6 → 3.7；不可 3.5 直跳 3.7
滚动：逐 member 替换	每步确认 cluster health
混合版本窗口可回滚二进制	全部升到新 minor 后则只能 restore
K8s 控制面 restore 考虑 revision bump	避免 informer cache 与 rev 回退

Raft 与 WAL 细节见第 2–3 篇；Learner 角色见第 2 篇。排障口令见第 15 篇。

二、member change：add、remove、replace

etcd 集群成员信息存在 etcd 自身中，通过 Raft 配置变更提交。常见操作：

操作	典型场景	风险轴
member add	扩缩容到 5 节点	Raft 配置变更期间无 quorum
member remove	永久下线机器	不可删到丧失 quorum
member update / replace	机器名/IP 变但身份延续	WAL 与 peer URL 不一致
learner add → promote	先同步后投票	Learner 未 catch-up 即 promote

2.1 推荐 replace 路径（v3.5）

官方 Member migration 流程（Run etcd clusters，A 级）核心步骤：

用 etcdctl member add 添加 新 member（learner 或 voting，视版本与策略）；
在新节点用 --initial-cluster-state=existing 启动，不要误用 new 格式化旧数据；
确认新节点 Raft index catch-up；
member remove 旧 member ID；
全集群 etcdctl endpoint health / endpoint status 一致。

Learner 路径（v3.5 已支持 non-voting member）：先以 learner 加入，待日志追平后再 promote 为 voting member——降低新节点拖慢 quorum commit 的概率（Raft 轴）。

2.2 检查单（member 变更）

[ ] 变更前 snapshot（见 §三）
[ ] 集群仍有 quorum（(N-1)/2 容错未超）
[ ] 新节点 `--name` / `--initial-advertise-peer-urls` 与 member add 输出一致
[ ] 未对已有 member 误跑 `etcdutl snapshot restore` 覆盖 live data
[ ] K8s 栈：apiserver `--etcd-servers` 列表与现 member 对齐
[ ] 变更后 committed index 与 applied index 差距收敛（Apply 轴）

force-new-cluster：--force-new-cluster 可在灾难时保留数据但重写成员——官方强烈不推荐在有旧 member 存活时使用（会 panic）。优先 restore from snapshot + 新 initial-cluster（§三）。

三、backup 与 restore

3.1 在线 snapshot

ETCDCTL_API=3 etcdctl --endpoints=$ENDPOINT snapshot save snapshot.db

从 live member 做逻辑 snapshot（A 级推荐路径）。
直接拷贝 member/snap/db 可能丢 尚未 snap 进 db 的 WAL 数据（recovery 文档）。

查看 snapshot 元数据：

etcdutl snapshot status snapshot.db -w table

输出字段 REVISION、TOTAL KEYS、TOTAL SIZE 用于核对备份点——本站不粘贴具体数字（无环境）。

3.2 restore 集群

etcdutl snapshot restore 为每个 member 生成新 data-dir，会覆盖 member ID / cluster ID——这是新逻辑集群，不是「原地复活」。

Kubernetes 语境下官方额外警告（A 级）：

restore 后 Revision 可能大幅回退；
controller/informer 本地缓存若仍记住更高 resourceVersion，会出现不一致行为；
建议使用 --bump-revision 与 --mark-compacted（见 recovery · Restoring with revision bump）。

--bump-revision 接受 64 位整数，使新 Revision 单调高于旧缓存；--mark-compacted 终止旧 rev 上的 Watch，迫使客户端全量 List。 bump 量级应覆盖「snapshot 年龄 × 写入速率」——文档示例：一周旧 snapshot、<1500 writes/s 时可考虑 \(10^9\) 量级；须按你的写入速率工程估算，非固定常数。

3.3 K8s 控制面 restore 顺序（概要）

停止 apiserver 与依赖 etcd 的控制面组件；
对每个 etcd member 用同一 snapshot restore（或按 disaster 流程重建 member 集）；
启动 etcd 集群，确认 quorum + health；
启动 apiserver；
观察 controller 是否触发大规模 resync——必要时按运维 runbook 滚动重启 controller。

Events 分集群（第 13 篇）应对每个 etcd 后端分别 backup/restore。

四、3.5.33 补丁线

本系列正文钉 v3.5.33（2026-07-23 补丁线）。在 3.5 系列内滚动升级 patch：

逐 member 替换二进制/镜像；
混合 patch 版本通常可接受，但 K8s 发行版可能钉死镜像 digest——以发行版 matrix 为准；
升级前仍应 snapshot。

3.5.33 已包含的运维相关能力（相对早期 3.5，不逐条 CHANGELOG）：Learner、Lease checkpoint（稳定路径）、auto-compaction、quota alarm——机制见前序篇。

若目标是 3.6/3.7：3.5.33 满足官方「升级 3.6 前先 ≥3.5.32」的 patch 前置（upgrade_3_6 文档，2026 年 live 文档写 3.5.32+；3.5.33 在其后）。

五、3.5 → 3.6 升级门

依据 Upgrade etcd from v3.5 to v3.6（A 级；开写时核 live 页）。门禁摘要：

门禁项	要求	失败后果
3.5 patch 基线	全部 member ≥ 3.5.32（文档当前表述）	升级 blocker
v2 API	移除 `--enable-v2` / `ETCD_ENABLE_V2`	3.6 不支持
v2store 检查	每节点 `etcdutl check v2store`（etcdutl ≥3.5.32）	有 custom v2 数据则阻塞
升级前 snapshot	必须	全量升 3.6 后无法二进制回滚
滚动方式	逐 member 停 3.5 → 启 3.6	混合版本期间集群仍以最低 common 协议运行

v2store 清理：若从未启用 v2，文档称可直接升级。否则按检查输出走 migration 或 --v2-deprecation=write-only-skip-check（有风险，需 3.5.32+）。WAL 中 v2 记录可能需等待下次 v2 snapshot 或临时 --snapshot-count=1 强制快照（见官方文档 §WAL has custom v2 data）。

混合版本回滚窗口：只要仍有 member 在 3.5，可用旧二进制或 snapshot restore；全部 member 升到 3.6 后，回滚必须走 downgrade 指南或 restore——不能假设换镜像即可。

3.6 行为变化（选型相关，非 v3.5.33 正文）：feature gate 替代部分 --experimental-*；集群协议在全员 3.6 前保持 3.5 协议——具体 flag 映射以 upgrade 文档表格为准，升级窗口内再核。

六、3.6 → 3.7 升级门

依据 Upgrade etcd from v3.6 to v3.7 与 Announcing etcd v3.7.0（A/B）。在 3.5.33 生产栈上，本节是规划门，不是当前事实：

门禁项	要求
3.6 patch 基线	全部 member ≥ 3.6.11（文档当前表述）
`--experimental-*`	3.7 已删除；须在 3.6 先迁到 feature gate 或稳定 flag
v2 全路径	3.7 移除 v2 store/API/client/discovery
滚动	同样逐 member；全员 3.7 前协议为 common version

3.7 公告中的机制变化（引用，非 v3.5.33 能力）：RangeStream、纯 v3store 启动、protobuf 迁移、bbolt v1.5.1 / raft v3.7.0 等——是否进入你的 K8s 版本以 SIG etcd 与 K8s release notes 为准，不在此写「默认已上 3.7」。

Kubernetes 矩阵：K8s 小版本与 etcd 版本的耦合由发行版维护——升级 etcd minor 前必须查你的 K8s 文档/support matrix，不能只看 etcd 官方「可以 rolling upgrade」。

七、与五轴的对应

运维动作	主要轴	成功信号
member add/replace	Raft	quorum 稳定；无 election storm
snapshot save	WAL/MVCC	文件可 `snapshot status`
restore	WAL + MVCC + Watch	health；K8s 需 bump rev
rolling upgrade	Raft + WAL	混合版本日志预期；health 连续
v2store 未清理就升 3.6	—	进程拒绝启动或数据风险
defrag / compact	MVCC	见第 12 篇；与升级窗口错开

升级窗口避免与 defrag、大规模 compaction 同屏——两者都占磁盘与 Apply 路径（第 12 篇）。

八、本篇边界

题目	归属
etcd-druid / Operator 全书	Gardener 生态
云厂商托管 etcd 点击路径	厂商文档
3.6/3.7 新特性机制深读	未来补丁；须钉新 tag 再写
跨版本性能对比	禁止（无实测）

参考资料

规范 / 官方文档（A）

源码（A）

etcd-io/etcd tag v3.5.33：etcdctl/ctlv3/command/snapshot_command.go；etcdutl/snapshot/

站内

实验台账

member change / restore / 升级：未在本环境执行；命令与门禁来自官方文档。

上一篇：Kubernetes 控制面耦合

下一篇：排障五轴

读完这篇，下一步读什么

优先读同系列或同问题的下一篇，把单篇消费变成主题集群。

2026-08-26 · distributed / kubernetes