备份前须确认 etcd 启用 v3 API，验证 endpoint health；用 go-etcd/v3 的 SnapshotSave 可控备份；恢复时需匹配版本、清空 data-dir、设置正确启动参数；快照不含运行时状态和缓存。
备份前必须确认 etcd 是否启用了 v3 API
Kubernetes 1.6+ 默认使用 etcd v3，而 etcdctl 的 v2 和 v3 命令不兼容。若误用 v2 模式备份，etcdctl backup 会静默失败或生成空快照。执行前务必验证：
ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \ --cacert=/etc/kubernetes/pki/etcd/ca.crt \ --cert=/etc/kubernetes/pki/etcd/server.crt \ --key=/etc/kubernetes/pki/etcd/server.key \ endpoint health
返回 healthy 才代表 v3 接口可用。否则需检查 ETCDCTL_API 环境变量是否被覆盖、证书路径是否拼写错误（如把 server.crt 写成 peer.crt）。
用 go-etcd/v3 客户端直接调用 SnapshotSave 实现可控备份
纯 shell 调用 etcdctl snapshot save 难以嵌入 Go 应用逻辑中。改用官方 go.etcd.io/etcd/client/v3 的 SnapshotSave 方法更可靠，支持超时控制与错误分类：
-
ctx必须带 timeout，避免因网络抖动卡死（建议5 * time.Minute） - 目标文件需提前创建并设置
0600权限，防止备份中途被其他进程截断 - 不要复用已有 client 连接做备份——
SnapshotSave是独立 HTTP 请求，与 KV 操作隔离
cli, _ := clientv3.New(clientv3.Config{
Endpoints: []string{"https://127.0.0.1:2379"},
DialTimeout: 5 * time.Second,
TLS: &tls.Config{
Certificates: []tls.Certificate{cert},
RootCAs: caPool,
},
})
f, _ := os.Create("/backup/etcd-snapshot-$(date +%s).db")
defer f.Close()
if err := cli.SnapshotSave(context.WithTimeout(context.Background(), 5*time.Minute), f); err != nil {
log.Fatal("snapshot save failed:", err) // 注意：err 可能是 io.EOF 或 tls handshake timeout
}恢复时 etcd 启动参数必须匹配原集群版本与数据目录权限
从快照恢复不是简单替换文件。常见失败点：
立即学习“go语言免费学习笔记（深入）”；
-
--initial-cluster和--initial-advertise-peer-urls必须与原集群完全一致，否则启动后无法加入集群 -
--data-dir目录必须为空，且属主为运行 etcd 的用户（如etcd:etcd），否则报permission denied on lock file - 若原集群使用
etcd v3.5.x备份，不能用v3.4.x的etcdctl snapshot restore恢复，会提示unsupported version
正确流程是先停掉所有 etcd 成员，清空 --data-dir，再执行：
ETCDCTL_API=3 etcdctl --write-out=table snapshot restore /backup/etcd-snapshot-1712345678.db \ --data-dir=/var/lib/etcd-restored \ --name=etcd-node-1 \ --initial-cluster="etcd-node-1=https://10.0.0.1:2380,etcd-node-2=https://10.0.0.2:2380" \ --initial-cluster-token=etcd-cluster-1 \ --initial-advertise-peer-urls=https://10.0.0.1:2380
备份内容不含 kube-apiserver 状态缓存和节点本地资源
etcd 快照只保存 Kubernetes 的声明式状态（Pod、Service、Secret 等对象），但以下内容不会被还原：
- 节点上的
containerd或docker运行时状态（如正在运行的容器、临时卷挂载） -
kube-apiserver的 watch 缓存、openapi schema 缓存 -
Node对象的Status.Addresses可能过期，需等 kubelet 重连后自动更新 - 外部存储（如 S3 中的
VolumeSnapshotContent）需单独备份，etcd 不存其二进制数据
这意味着恢复后需等待所有节点重新上报状态，并手动验证 DaemonSet 是否在全部节点上重建成功——这步容易被忽略，但直接影响业务可用性。
