etcdctl 使用说明

认证与权限管理

命令	功能描述	常用参数/示例
auth enable	启用集群的身份认证功能	etcdctl auth enable
auth disable	禁用集群的身份认证功能	etcdctl auth disable
user add	创建新用户	etcdctl user add <用户名>[:密码]
user passwd	修改用户密码	etcdctl user passwd <用户名>(交互式输入新密码)
user grant-role	为用户授予角色	etcdctl user grant-role <用户名> <角色名>
user revoke-role	撤销用户的角色	etcdctl user revoke-role <用户名> <角色名>
user get	获取用户的详细信息（含角色）	etcdctl user get <用户名>
user list	列出所有用户	etcdctl user list
user delete	删除用户	etcdctl user delete <用户名>
role add	创建新角色	etcdctl role add <角色名>
role grant-permission	为角色授予针对键或键范围的权限	etcdctl role grant-permission <角色名> read <键前缀> etcdctl role grant-permission <角色名> readwrite --prefix <键前缀>
role revoke-permission	撤销角色对特定键的权限	etcdctl role revoke-permission <角色名> <键>
role get	获取角色的详细信息（含权限）	etcdctl role get <角色名>
role list	列出所有角色	etcdctl role list
role delete	删除角色	etcdctl role delete <角色名>

键值对操作 (KV Operations)

命令	功能描述	常用参数/示例
put	写入或更新一个键值对	etcdctl put /test/key1 "Hello etcd"
get	获取一个键或一个范围的值	etcdctl get /test/key1 etcdctl get /test/ --prefix(前缀查询) etcdctl get / --prefix --limit=5(限制数量) etcdctl get /test/key1 --hex(十六进制输出)
del	删除一个键或一个范围	etcdctl del /test/key1 etcdctl del /test/ --prefix(删除前缀下所有键)
watch	监听一个键或一个范围的变更	etcdctl watch /test/key1 etcdctl watch /test/ --prefix(监听前缀)
txn	在单个事务中执行多个操作（支持条件判断）	从标准输入或文件读取事务内容，用于复杂原子操作。

租约与锁 (Leases & Locks)

命令	功能描述	常用参数/示例
lease grant	创建一个具有生存时间(TTL)的租约	etcdctl lease grant 60(创建一个60秒后过期的租约，返回ID)
lease keep-alive	周期性保活一个租约，防止其过期	etcdctl lease keep-alive <租约ID>
lease revoke	撤销一个租约，其关联的所有键将被删除	etcdctl lease revoke <租约ID>
lease timetolive	获取租约的剩余TTL信息	etcdctl lease timetolive <租约ID> etcdctl lease timetolive <租约ID> --keys(同时查看绑定的键)
lease list	列出所有活跃的租约	etcdctl lease list
lock	获取一个具名的分布式锁	etcdctl lock my-lock(阻塞直到获得锁，输出一个解锁密钥)
elect	观察并参与一个领导者选举	etcdctl elect my-election

集群成员管理 (Cluster Membership)

命令	功能描述	常用参数/示例
member list	列出集群中的所有成员及其信息	etcdctl member list -w table
member add	向集群中添加一个新成员	etcdctl member add <新成员名> --peer-urls="http://<新成员IP>:2380"
member remove	从集群中移除一个成员	etcdctl member remove <成员ID>
member update	更新一个成员的 Peer URL 地址	etcdctl member update <成员ID> --peer-urls="http://<新IP>:2380"
member promote	将一个非投票成员提升为投票成员	etcdctl member promote <成员ID>
move-leader	将领导权转移给指定成员（用于维护）	etcdctl move-leader <新领导者成员ID>

监控、健康检查与运维 (Monitoring, Health & Maintenance)

命令	功能描述	常用参数/示例
endpoint health	检查指定端点的健康状态	etcdctl --endpoints=ep1,ep2 endpoint health
endpoint status	获取指定端点的详细状态（DB大小、领导者、版本等）	etcdctl endpoint status -w table
endpoint hashkv	打印每个端点的KV历史哈希，用于一致性校验	etcdctl endpoint hashkv
check perf	检查etcd集群的性能（负载测试）	etcdctl check perf
check datascale	预估不同数据模型下的内存占用量	etcdctl check datascale
alarm list	列出所有活跃的警报（如空间不足NOSPACE）	etcdctl alarm list
alarm disarm	解除所有警报	etcdctl alarm disarm
defrag	对指定端点上的 etcd 成员存储进行碎片整理 –cluster[=false] 使用集群成员列表中的所有端点 –data-dir=“” 可选。如果提供，则对未被 etcd 使用的数据目录进行碎片整理	etcdctl defrag --endpoints=<单个成员端点>
compaction	压缩etcd的事件历史，回收存储空间	etcdctl compaction <修订版本号> 需先get键时使用--write-out=fields查看当前修订版。
snapshot save	创建集群的快照备份到文件	etcdctl snapshot save backup.db
snapshot status	检查快照文件的详细信息	etcdctl snapshot status backup.db -w table
snapshot restore	从快照文件恢复一个新集群	etcdctl snapshot restore backup.db --data-dir /var/lib/etcd-new
make-mirror	将本地集群的键镜像到另一个集群	etcdctl make-mirror --dest-prefix=/mirror/ target-endpoint
migrate	将v2格式的存储迁移到v3 (mvcc) 存储	用于旧版本迁移。

其他

命令	功能描述
version	打印etcdctl和API的版本信息  3.4.13
help	查看帮助信息

---

关键全局选项 (OPTIONS) 详解

选项	说明	示例与应用场景
连接与发现选项​
--endpoints	指定要连接的etcd集群端点，用逗号分隔。最常用。	--endpoints=10.0.1.1:2379,10.0.1.2:2379,10.0.1.3:2379
--discovery-srv	使用DNS SRV记录进行服务发现。	--discovery-srv=etcd.example.com
安全与认证选项​
--cacert	用于验证服务器的CA证书文件路径。	--cacert=/etc/etcd/ca.pem
--cert	客户端使用的TLS证书文件路径。	--cert=/etc/etcd/client.pem
--key	客户端使用的TLS私钥文件路径。	--key=/etc/etcd/client-key.pem
--user, -u	指定用户名和密码（格式user:pass）进行认证。	--user=root:complexpassword
--password	单独指定密码（通常与--user不含密码时配合使用）。	--user=root --password(交互输入)
--insecure-skip-tls-verify	警告：跳过服务器证书验证，仅用于测试。	--insecure-skip-tls-verify=true
--insecure-transport	禁用传输层安全，不推荐生产使用。	--insecure-transport=false
输出与格式选项​
-w, --write-out	指定输出格式，极大影响可读性。	-w table(表格，适合member list, endpoint status) -w json(JSON，用于脚本处理) -w fields(提取特定字段) -w simple(默认，简单格式)
--hex	以十六进制格式显示键和值。	etcdctl get mykey --hex
超时与性能选项​
--dial-timeout	建立连接的超时时间。	--dial-timeout=3s
--command-timeout	命令执行的超时时间（不包含连接时间）。	--command-timeout=5s
--keepalive-time	客户端ping服务器的间隔。	--keepalive-time=2s
--keepalive-timeout	等待keepalive响应的超时时间。	--keepalive-timeout=6s
其他选项​
--debug	启用客户端调试日志。	--debug=true

---

日常运维检查清单

# 1. 检查集群健康
etcdctl endpoint health
# 2. 查看成员和领导者状态
etcdctl member list -w table
etcdctl endpoint status -w table
# 3. 检查是否有告警
etcdctl alarm list
# 4. 查看数据库大小
etcdctl endpoint status -w fields | grep dbSize

备份与恢复

# 备份（从任一健康节点执行）
etcdctl snapshot save /var/backup/etcd-snapshot-$(date +%Y%m%d).db
# 查看备份状态
etcdctl snapshot status /var/backup/etcd-snapshot-20231027.db -w table
# 恢复（到一个全新的数据目录）
etcdctl snapshot restore /var/backup/etcd-snapshot-20231027.db \
  --name infra1 \
  --initial-cluster infra1=https://new.ip.1:2380 \
  --initial-advertise-peer-urls https://new.ip.1:2380 \
  --data-dir /var/lib/etcd-restored

键空间操作技巧

# 使用前缀进行批量操作
etcdctl get /services/ --prefix --keys-only
# 在watch时从某个历史版本开始监听
etcdctl watch /key --rev=1000
# 将键值对绑定到租约实现自动过期
lease_id=$(etcdctl lease grant 300 | awk '{print $2}')
etcdctl put /temp/session "data" --lease=$lease_id