etcdctl 命令速查

本篇按使用场景分表收录 etcdctl 的高频命令，默认针对 etcd 3.5，路径和地址按实际环境替换。

全局参数与环境变量

先设环境变量，后面命令可以省略一长串参数：

export ETCDCTL_ENDPOINTS=https://10.0.0.11:2379,https://10.0.0.12:2379,https://10.0.0.13:2379
export ETCDCTL_CACERT=/etc/etcd/certs/ca.crt
export ETCDCTL_CERT=/etc/etcd/certs/client.crt
export ETCDCTL_KEY=/etc/etcd/certs/client.key

参数 / 变量	作用
`--endpoints` / `ETCDCTL_ENDPOINTS`	端点列表，多个用逗号分隔
`--cacert` / `ETCDCTL_CACERT`	校验服务端的 CA
`--cert` / `ETCDCTL_CERT`	客户端证书
`--key` / `ETCDCTL_KEY`	客户端私钥
`--dial-timeout`	建连超时，默认 2s
`--command-timeout`	单条命令超时，默认 5s
`--write-out` / `-w`	输出格式：`simple`、`json`、`table`、`fields`
`--consistency`	读一致性：`l` 线性读（默认），`s` 串行读
`--debug`	打印 gRPC 调试日志

KV 操作

命令	说明
`etcdctl put KEY VALUE`	写入单个 key
`etcdctl put KEY VALUE --prev-kv`	写入并返回旧值
`etcdctl put KEY VALUE --lease=LEASE_ID`	绑定租约写入
`etcdctl get KEY`	读取单个 key
`etcdctl get KEY --print-value-only`	只输出 value
`etcdctl get KEY -w json`	输出完整 JSON，含 revision 元数据
`etcdctl get PREFIX --prefix`	前缀范围查询
`etcdctl get PREFIX --prefix --keys-only`	只列 key
`etcdctl get PREFIX --prefix --count-only -w fields`	只统计数量，必须配合 `-w fields`
`etcdctl get PREFIX --prefix --limit=100`	限制返回条数
`etcdctl get PREFIX --from-key --limit=100`	从 key 开始向后遍历
`etcdctl get KEY --rev=REV`	读指定 revision 的历史值
`etcdctl get KEY --consistency=s`	串行读，可能读到旧值
`etcdctl del KEY`	删除单个 key
`etcdctl del PREFIX --prefix`	按前缀批量删除
`etcdctl del PREFIX --prefix --prev-kv`	删除并返回旧值

常用示例：

# 写入并查看元数据
etcdctl put /app/config/env prod --prev-kv
etcdctl get /app/config/env -w json | jq '.kvs[0]'

# 统计某个前缀下有多少 key
etcdctl get /registry/pods/ --prefix --count-only -w fields

# 读历史版本
REV=$(etcdctl get /app/config/env -w json | jq -r '.header.revision')
etcdctl get /app/config/env --rev=$((REV - 1))

租约与 watch

命令	说明
`etcdctl lease grant 60`	创建 60 秒租约，输出 lease ID
`etcdctl lease timetolive LEASE_ID`	查剩余 TTL
`etcdctl lease timetolive LEASE_ID --keys`	查 TTL 和绑定的 key
`etcdctl lease keep-alive LEASE_ID`	持续续期，前台阻塞
`etcdctl lease keep-alive LEASE_ID --once`	只续期一次
`etcdctl lease list`	列出所有租约
`etcdctl lease revoke LEASE_ID`	撤销租约，绑定 key 立即删除
`etcdctl watch KEY`	监听单个 key
`etcdctl watch PREFIX --prefix`	监听前缀下所有变更
`etcdctl watch PREFIX --prefix --rev=REV`	从指定 revision 开始补事件
`etcdctl watch PREFIX --prefix -w json`	输出 JSON 事件
`etcdctl watch PREFIX --prefix --prev-kv`	事件带变更前的值

# 创建租约并把 key 绑上去
LEASE_ID=$(etcdctl lease grant 300 | awk '{print $2}')
etcdctl put /services/api/10.0.0.11:8080 up --lease=$LEASE_ID

# 续期（另开终端）
etcdctl lease keep-alive $LEASE_ID

# 监听前缀，JSON 输出
etcdctl watch --prefix /services/api/ -w json

集群维护

命令	说明
`etcdctl endpoint health`	单端点健康检查
`etcdctl endpoint health --cluster`	所有成员健康检查
`etcdctl endpoint status -w table`	成员状态、db 大小、raft 进度
`etcdctl endpoint status -w json`	JSON 格式，脚本解析用
`etcdctl member list -w table`	成员列表和 peer 地址
`etcdctl member add NAME --peer-urls=URL`	添加成员
`etcdctl member remove MEMBER_ID`	移除成员
`etcdctl member update MEMBER_ID --peer-urls=URL`	更新成员 peer 地址
`etcdctl move-leader MEMBER_ID`	把 leader 迁到指定成员
`etcdctl alarm list`	查看 NOSPACE / CORRUPT 告警
`etcdctl alarm disarm`	解除告警
`etcdctl compact REV`	压缩历史版本
`etcdctl defrag`	整理当前成员碎片
`etcdctl defrag --cluster`	依次整理所有成员
`etcdctl endpoint hashkv`	计算成员数据 hash，做一致性比对
`etcdctl snapshot status FILE -w table`	查看快照 revision、hash、大小

常用组合：

# 当前 revision
REV=$(etcdctl endpoint status -w json | jq -r '.[0].Status.header.revision')

# db 大小、实际使用量
etcdctl endpoint status -w json | jq '.[0].Status | {dbSize, dbSizeInUse}'

# 按来源统计 2379 连接数
ss -tn state established '( sport = :2379 )' | tail -n +2 | wc -l

# 压缩到当前 revision
etcdctl compact $REV

# 单成员碎片整理，超时放宽到 10 分钟
etcdctl defrag --command-timeout=600s

备份恢复

命令	说明
`etcdctl snapshot save FILE`	在线保存快照
`etcdctl snapshot status FILE -w table`	校验快照完整性
`etcdutl snapshot restore FILE --data-dir DIR`	从快照恢复数据目录
`etcdctl snapshot restore FILE --data-dir DIR`	3.5 兼容写法，已不推荐

完整备份示例：

sudo mkdir -p /var/backups
sudo etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/healthcheck-client.crt \
  --key=/etc/kubernetes/pki/etcd/healthcheck-client.key \
  snapshot save /var/backups/etcd-$(date +%F-%H%M).db

etcdctl snapshot status /var/backups/etcd-2026-10-25-1200.db -w table

恢复示例（三节点集群，每个成员都执行，只改 name、data-dir 和 peer URL）：

sudo etcdutl snapshot restore /var/backups/etcd-2026-10-25-1200.db \
  --name etcd-01 \
  --data-dir /var/lib/etcd-restore \
  --initial-cluster etcd-01=https://10.0.0.11:2380,etcd-02=https://10.0.0.12:2380,etcd-03=https://10.0.0.13:2380 \
  --initial-advertise-peer-urls https://10.0.0.11:2380 \
  --initial-cluster-token etcd-cluster-restored

恢复后把配置文件里的 data-dir 和 initial-cluster-token 改成新值，再启动成员。

避坑提示

get --prefix 的前缀最好带结尾斜杠，避免 /app 命中 /application。
-w json 里的 key/value 是 base64，解码后再用。
--rev 不能早于压缩点，否则报 required revision has been compacted。
compact 只释放逻辑空间，磁盘回收必须再做 defrag。
defrag 会阻塞当前成员读写，生产逐台执行，leader 最后做。
加了 --client-cert-auth 后，所有 etcdctl 命令都必须带证书。
3.6 起快照相关操作用 etcdutl，etcdctl snapshot 逐步退场。
跨版本升级前先看官方 upgrade 文档，不要直接跳大版本。

全局参数与环境变量​

KV 操作​

租约与 watch​

集群维护​

备份恢复​

避坑提示​

全局参数与环境变量

KV 操作

租约与 watch

集群维护

备份恢复

避坑提示