“msg“:“server error“,“error“:“the member has been permanently removed from the cluster“

---

🧩 etcd 节点异常分析报告

一、问题概述

该节点的 etcd 成员已被永久从集群中移除，但仍试图以旧身份启动，导致容器反复重启并进入 Exited 状态。

从日志中可见的关键报错信息：

"msg":"server error","error":"the member has been permanently removed from the cluster"
"msg":"data-dir used by this member must be removed"

这表明该节点对应的 etcd 数据目录仍保留了旧成员的元信息，而该成员 ID 已不再属于当前集群。

---

二、详细原因分析

1. 成员已被移除

• 节点 IP：172.x.x.137
• 成员 ID：f3497c0b0464423d
• 此成员已被永久性地从 etcd 集群中移除（可能通过 etcdctl member remove 操作或自动剔除机制实现）。
• 但该节点本地仍保留旧数据目录 /opt/qfusion/etcd，导致 etcd 进程在启动时读取到无效成员信息。

2. 启动冲突

• etcd 容器尝试加载旧的数据目录和成员 ID 启动。
• 集群检测到该成员 ID 已被标记为“已移除（removed）”，拒绝其重新加入。
• 因此进程启动失败并重复崩溃，形成容器的 CrashLoopBackOff / Exited 状态。

3. 数据不一致迹象

• 日志中出现警告：

  "error":"etcdserver: mvcc: required revision has been compacted"
  

• 表明该节点本地数据版本（revision）落后于当前集群的 compact 版本，数据已不可追溯，无法通过正常同步恢复。

---

三、可能的触发原因

1. 节点长期离线

   • 若 etcd 成员长时间未心跳上报，可能被其他成员标记并移除。

2. 手动维护操作

   • 管理员执行了 etcdctl member remove 删除该节点。

3. 集群清理或迁移操作

   • 在节点替换、缩容或集群维护时误操作。

4. 节点硬件或系统故障

   • 存储或网络异常导致该节点不可用，从而被剔除。

---

四、故障影响

• 该节点无法参与集群共识（Raft）投票；
• kube-apiserver 与 etcd 通信中断时可能触发短暂的 API 不可用；
• 若集群规模较小（如 3 节点），此问题可能导致 丧失 quorum（法定多数），影响集群写入功能；
• 若为非关键节点，则仅表现为 etcd 实例单点不可用。

---

五、恢复与解决方案

步骤一：停止异常容器

docker stop <etcd_container_id>  # 或通过 Kubernetes 删除异常 Pod

步骤二：清理旧数据目录

rm -rf /opt/qfusion/etcd/member

⚠️ 注意：此操作将删除旧成员的本地存储数据，无法恢复，请确认集群中其他成员数据完整。

步骤三：重新添加该节点到 etcd 集群

• 在集群健康节点上执行：

  etcdctl member add <new-node-name> --peer-urls=https://172.30.30.137:2380
  

• 记录输出的 initial-cluster 参数，用于该节点启动配置。

步骤四：重新初始化并启动 etcd

如果是第一台的etcd，需要修改–initial-cluster-state 和 --initial-cluster

• 更新该节点 etcd 的环境变量或配置文件（包含新 member ID）

• 启动 etcd 容器或 Pod，让其以新身份加入集群：

  systemctl restart kubelet  # 若由 kubelet 管理
  # 或：
  docker start <etcd_container_id>
  

步骤五：验证状态

• 在任意健康节点执行：

  etcdctl member list
  etcdctl endpoint health
  

• 确认新成员状态为 started，并能正常同步数据。

---

六、预防建议

1. 建立成员状态监控

   • 通过 etcdctl endpoint status 定期检测各节点健康。
   • 配合 Prometheus + Alertmanager 设置 member down 告警。

2. 节点离线前先移除成员

   • 若计划维护节点，应先通过 etcdctl member remove 正式移除，避免集群误判。

3. 持久化备份

   • 保持每日自动快照，使用 etcdctl snapshot save 存档，防止数据一致性问题时无法恢复。

4. 统一管理操作入口

   • 禁止在单节点上直接执行删除命令，应通过集群管理工具或 CI/CD 平台统一操作。

---

七、结论

该节点 etcd 启动失败的根本原因是：

已被永久移除的成员仍保留旧数据目录并尝试以旧身份加入集群。

通过清理旧数据、重新添加成员并初始化，可使节点以新身份重新加入集群，恢复正常运行。

---