机房断电后 etcd 启动失败的排查与快速恢复实录
目录
机房断电后 etcd 启动失败的排查与快速恢复实录
背景与问题起因
报错分析
解决方案：删除 member 数据重新初始化
步骤 1：停止 etcd 容器或服务
步骤 2：删除 member 目录
步骤 3：重启 etcd 服务
附加提醒
总结与后续建议
机房断电后 etcd 启动失败的排查与快速恢复实录
背景与问题起因
在一次突发的 机房断电事件 后，我们所在的 Kubernetes 集群节点在重启过程中，发现 Milvus 无法正常启动。进一步排查发现，根因来自底层的 etcd 服务启动失败。etcd 是 Milvus 中关键的元数据协调组件，若其无法启动，会直接导致整个 Milvus 服务不可用。
启动 etcd 时出现如下典型日志输出：
starting an etcd server
etcd-version: 3.5.18
...
panic: freepages: failed to get all reachable pages (page 15493: multiple references (stack: [10971 15493]))
这类错误通常意味着 etcd 数据库文件损坏，可能是由于非正常关机导致写入中断、页索引混乱等原因。
报错分析
etcd 报错的关键信息：
panic: freepages: failed to get all reachable pages ...
这是一个由底层 BoltDB（etcd 存储引擎）在启动时进行页表校验时报出的 数据页引用错误，即同一页被多个地方引用，属于数据结构严重损坏的一种表现，无法通过常规手段自动修复。
解决方案：删除 member 数据重新初始化
经过快速评估和容灾权衡，我们采取了 “删除损坏 member 数据并重新初始化” 的方式进行恢复。操作步骤如下：
步骤 1：停止 etcd 容器或服务
docker stop etcd
# 或者 systemctl stop etcd
步骤 2：删除 member 目录
rm -rf /etcd/member
该目录下是 etcd 的成员节点数据（包含 WAL 日志和 snapshot 快照），此操作将等同于清空当前节点的全部 etcd 元数据。
⚠️ 风险提示： 本方法适用于非集群 / 单节点开发测试环境，或有其他节点或外部备份可用的情况下。生产环境建议先尝试
etcdctl snapshot restore等官方推荐方式。
步骤 3：重启 etcd 服务
docker start etcd
# 或者 systemctl start etcd
观察日志，可以发现 etcd 成功初始化并以 initial-cluster-state=new 模式重新创建了一个新的集群。
附加提醒
日志中另有一条 check file permission 警告：
directory "/etcd" exist, but the permission is "drwxr-xr-x". The recommended permission is "-rwx------"
虽然这不会直接导致启动失败，但为确保 etcd 数据目录的安全性，建议将其权限调整为：
chmod 700 /etcd
总结与后续建议
-
问题根因： 非正常断电导致 etcd 数据库损坏；
-
恢复方式： 删除
/etcd/member目录，强制重新初始化； -
风险控制： 未尝试恢复数据，适用于开发或非核心环境；
-
建议： 生产环境应启用 etcd snapshot 定期备份机制，避免数据丢失风险。