机房断电后 etcd 启动失败的排查与快速恢复实录

[机房断电后 etcd 启动失败的排查与快速恢复实录](#机房断电后 etcd 启动失败的排查与快速恢复实录)

背景与问题起因

报错分析

[解决方案：删除 member 数据重新初始化](#解决方案：删除 member 数据重新初始化)

[步骤 1：停止 etcd 容器或服务](#步骤 1：停止 etcd 容器或服务)

[步骤 2：删除 member 目录](#步骤 2：删除 member 目录)

[步骤 3：重启 etcd 服务](#步骤 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 定期备份机制，避免数据丢失风险。