4. etcd 运维基础：常用 etcdctl 命令、集群健康检查、成员管理、数据目录结构
在生产环境中，etcd 作为 Kubernetes 和分布式系统的“状态中枢”，其运维能力直接决定了集群的可靠性与灾备恢复速度。本章聚焦 etcd 运维的四个核心维度：etcdctl 命令行工具、集群健康检查、成员管理以及数据目录结构。掌握这些基础操作，是后续实现增量备份与蓝绿发布灾备自动化的前提。
前置条件：确保 etcdctl 版本与 etcd 服务端版本一致（建议 v3.5+），并已设置
ETCDCTL_API=3 环境变量。使用 TLS 证书的集群需在命令中追加 --cacert、--cert、--key 参数。
4.1 常用 etcdctl 命令速查
etcdctl 是与 etcd 交互的主要 CLI 工具，覆盖键值操作、租约管理、快照、用户权限等场景。以下表格列出生产环境最常用的命令及其用途：
| 分类 | 命令示例 | 说明 |
|---|---|---|
| 键值写入 | etcdctl put /app/config '{"port":8080}' |
写入键值，支持 JSON 字符串 |
| 键值读取 | etcdctl get /app/config |
读取指定键的值 |
| 前缀查询 | etcdctl get /app/ --prefix |
获取 /app/ 前缀下的所有键值对 |
| 键值删除 | etcdctl del /app/config |
删除指定键 |
| 租约创建 | etcdctl lease grant 60 |
创建 60 秒 TTL 租约，返回租约 ID |
| 租约绑定 | etcdctl put /app/session value --lease=694d7c |
将键绑定到指定租约，租约过期则键自动删除 |
| 快照保存 | etcdctl snapshot save /backup/snapshot.db |
创建集群一致性快照，用于全量备份 |
| 快照恢复 | etcdctl snapshot restore /backup/snapshot.db |
从快照恢复新集群（需指定新成员名称） |
| 端点状态 | etcdctl endpoint status --cluster -w table |
以表格形式显示所有成员端点状态 |
| 端点健康 | etcdctl endpoint health --cluster |
检查所有成员端点的健康状态 |
| 告警列表 | etcdctl alarm list |
列出集群中的告警（如存储空间不足） |
生产技巧：使用
-w table 或 -w json 参数格式化输出，便于脚本解析。快照操作建议在业务低峰期执行，并配合 --endpoints 参数指定本地节点以减少网络开销。
4.2 集群健康检查体系
etcd 集群的健康状态需要从多个维度综合判断，单一指标不足以反映真实情况。以下流程图为标准健康检查步骤：
健康检查的五个关键步骤及其对应命令：
- 端点健康检查：执行
etcdctl endpoint health --cluster，确认所有端点返回is healthy: true。 - 成员状态检查：执行
etcdctl member list -w table，确认成员数量与预期一致，且所有成员处于unstarted或started状态。 - Raft 领导者确认：执行
etcdctl endpoint status --cluster -w table，检查IS_LEADER列，确保集群有且仅有一个领导者。 - 告警与存储检查：执行
etcdctl alarm list，检查是否存在NOSPACE告警；同时查看DB_SIZE是否接近配额限制（默认 2GB）。 - 数据一致性校验：使用
etcdctl check perf测试读写延迟，或通过etcdctl get / --prefix --keys-only对比不同节点的键集合。
常见陷阱：仅依赖
endpoint health 是不够的——一个节点可能健康但网络分区导致数据不同步。务必结合 endpoint status 中的 RAFT_TERM 和 COMMITTED_INDEX 判断一致性。
4.3 成员管理操作
etcd 集群的成员管理包括添加、移除、更新成员，以及处理成员故障。以下表格总结了核心操作命令与适用场景：
| 操作 | 命令示例 | 适用场景 |
|---|---|---|
| 列出成员 | etcdctl member list -w table |
查看当前集群成员 ID、名称、地址、状态 |
| 添加成员 | etcdctl member add node3 --peer-urls=https://10.0.0.3:2380 |
集群扩容或替换故障节点 |
| 移除成员 | etcdctl member remove 8e9e05c52164694d |
节点永久下线或缩容 |
| 更新成员 | etcdctl member update 8e9e05c52164694d --peer-urls=https://10.0.0.4:2380 |
更改节点 IP 或端口 |
| 领导者转移 | etcdctl move-leader 8e9e05c52164694d |
手动触发领导者选举（运维维护时使用） |
成员管理的关键原则：
- 奇数成员原则：生产集群建议使用 3、5、7 个成员，确保 Raft 多数派（quorum）可用。3 节点集群容忍 1 个故障，5 节点容忍 2 个故障。
- 添加成员流程：先通过
member add注册新节点，再启动新 etcd 进程加入集群。新节点会从领导者同步全量数据。 - 移除成员注意：移除前确保该节点已停止服务，且移除后剩余成员数仍满足多数派要求。移除操作不可逆，需谨慎。
蓝绿发布场景：在蓝绿发布灾备方案中，成员管理用于“绿集群”的快速组建——通过
member add 将备份节点加入临时集群，验证数据一致性后再切换流量。
4.4 数据目录结构详解
理解 etcd 数据目录结构是进行增量备份和灾备恢复的基础。etcd 默认数据目录为 /var/lib/etcd/（或通过 --data-dir 指定），其内部结构如下：
数据目录各组成部分的详细说明：
| 目录/文件 | 作用 | 备份关注点 |
|---|---|---|
member/snap/ |
存储 Raft 快照（.snap 文件），用于快速恢复集群到某个一致状态 | 快照文件是增量备份的基准点，需定期归档旧快照以节省空间 |
member/wal/ |
预写日志（.wal 文件），记录所有 Raft 日志条目，保证数据持久性 | WAL 文件是增量备份的核心——通过归档 WAL 实现时间点恢复（PITR） |
member/backend/ |
BoltDB 数据库文件（db），存储所有键值数据、元数据、事务索引 | 全量备份时需使用 etcdctl snapshot save 而非直接复制 db 文件 |
member/snap.db |
临时快照文件，在快照压缩过程中生成 | 通常无需单独备份，压缩完成后自动删除 |
重要：切勿在 etcd 运行时直接复制
backend/db 文件作为备份——这会导致数据损坏。始终使用 etcdctl snapshot save 或基于 WAL 的增量备份工具。
4.5 实战：一键健康检查脚本
以下脚本整合了本章的核心检查命令，可用于日常巡检或灾备演练前的环境验证：
#!/bin/bash
# etcd_health_check.sh - 集群健康检查脚本
ETCDCTL_API=3
ENDPOINTS="https://10.0.0.1:2379,https://10.0.0.2:2379,https://10.0.0.3:2379"
CERT_FLAGS="--cacert=/etc/etcd/ca.pem --cert=/etc/etcd/client.pem --key=/etc/etcd/client-key.pem"
echo "=== 1. 端点健康检查 ==="
etcdctl --endpoints=$ENDPOINTS $CERT_FLAGS endpoint health --cluster
echo -e "\n=== 2. 成员列表 ==="
etcdctl --endpoints=$ENDPOINTS $CERT_FLAGS member list -w table
echo -e "\n=== 3. 端点状态（含领导者信息） ==="
etcdctl --endpoints=$ENDPOINTS $CERT_FLAGS endpoint status --cluster -w table
echo -e "\n=== 4. 告警检查 ==="
etcdctl --endpoints=$ENDPOINTS $CERT_FLAGS alarm list
echo -e "\n=== 5. 数据库大小 ==="
etcdctl --endpoints=$ENDPOINTS $CERT_FLAGS endpoint status --cluster -w table | awk '{print $1, $4}'
扩展建议：将上述脚本集成到 Prometheus 告警规则或 CronJob 中，实现自动化健康巡检。在蓝绿发布切换前，务必对“蓝集群”执行此脚本，确保数据源一致。