命令行操作

中间件

etcd

命令行操作

etcdctl 完整命令参考：键值操作、Watch、Lease、事务、集群管理、快照备份/恢复、用户/角色管理，以及环境变量配置。

适用 etcd 版本: v3.5+（本文使用 v3 API，ETCDCTL_API=3）

快速配置

# v3 API 为默认（推荐）
export ETCDCTL_API=3

# 连接指定端点
export ETCDCTL_ENDPOINTS=localhost:2379

# 或者每次指定
etcdctl --endpoints=localhost:2379,localhost:22379 get /foo

键值操作

Put（写入）

# 基本写入
etcdctl put /config/db/host "192.168.1.100"

# 带租约写入（60s 后自动删除）
etcdctl put /service/host1 "10.0.0.1" --lease=<lease-id>

# 返回之前的 value
etcdctl put /foo "new" --prev-kv
# OK
# /foo
# old       ← 旧值

Get（读取）

# 精确获取
etcdctl get /config/db/host
# /config/db/host
# 192.168.1.100

# 只显示值
etcdctl get /config/db/host --print-value-only
# 192.168.1.100

# 前缀查询
etcdctl get /config --prefix

# 范围查询（左闭右开 [start, end)）
etcdctl get /config/a /config/z

# 按 Key 字典序从指定位置开始取所有
etcdctl get /config/ --from-key

# 只取 Key（不取 Value）
etcdctl get /config --prefix --keys-only

# 读取指定数量的 Key
etcdctl get /config --prefix --limit=10

# 按 revision 读取历史版本
etcdctl get /foo --rev=5

# 按版本排序（ASCEND / DESCEND）
etcdctl get /config --prefix --order=ASCEND --sort-by=CREATE

Get 输出格式说明：

<key>
<value>
<key>
<value>
...

Del（删除）

# 精确删除
etcdctl del /obsolete/key

# 前缀删除
etcdctl del /config --prefix

# 范围删除
etcdctl del /config/a /config/z

# 返回被删除的键值
etcdctl del /foo --prev-kv
# 1
# /foo
# bar

Watch（监听）

# 监听单个 Key（阻塞，直到 Ctrl+C）
etcdctl watch /config/db/host

# 前缀监听
etcdctl watch /service --prefix

# 从指定 revision 开始监听（避免丢失事件）
etcdctl watch /foo --rev=42

# 交互式多次 watch
etcdctl watch -i
# watch /foo
# watch /bar --prefix

💡 最佳实践：每次 watch 建立一个独立的 gRPC 双向流。用 --rev=<last_rev+1> 可从已知位置恢复监听。

Lease（租约）

# 创建租约（TTL 秒）
etcdctl lease grant 60
# lease 694d8b5d49adad0b granted with TTL(60s)

# 查看租约信息
etcdctl lease timetolive 694d8b5d49adad0b
# lease 694d8b5d49adad0b granted with TTL(60s), remaining(55s)

# 查看租约绑定的 Key
etcdctl lease timetolive 694d8b5d49adad0b --keys

# 续约一次
etcdctl lease keep-alive once 694d8b5d49adad0b
# lease 694d8b5d49adad0b keepalived with TTL(60s)

# 持续续约（阻塞）
etcdctl lease keep-alive 694d8b5d49adad0b

# 吊销租约（立即删除绑定 Key）
etcdctl lease revoke 694d8b5d49adad0b

事务（Txn）

# 原子比较与交换：如果 /foo 的值是 "a"，则改为 "b"
etcdctl txn <<EOF
compare value("/foo") = "a"
success request put /foo "b"
EOF

# 如果 /lock 不存在，则创建（获得锁）
etcdctl txn <<EOF
compare create("/lock") = 0
success request put /lock "owner"
failure request get /lock
EOF

Compare 类型：value, create（CreateRevision）, mod（ModRevision）, version

Compare 操作符：=, !=, >, <

集群管理

# 查看集群成员
etcdctl member list
# 8e9e05c52164694d, started, etcd1, http://10.0.0.1:2380, http://10.0.0.1:2379, false

# 添加成员
etcdctl member add etcd4 --peer-urls=http://10.0.0.4:2380

# 移除成员
etcdctl member remove 8e9e05c52164694d

# 更新成员 peer URLs
etcdctl member update 8e9e05c52164694d --peer-urls=http://new-host:2380

# Learner 提升为 Voter
etcdctl member promote <learner-id>

端点状态

# 查看端点健康
etcdctl endpoint health
# 127.0.0.1:2379 is healthy: successfully committed proposal: took = 2.1ms

# 详细状态（DB 大小、Leader、Raft 索引等）
etcdctl endpoint status
# 127.0.0.1:2379, 8e9e05c52164694d, 3.5.16, 25 MB, true, false, 15, 1024, ...

# 查看当前 Leader
etcdctl endpoint status | grep true | awk -F',' '{print $2}'

快照备份与恢复

# 创建快照
etcdctl snapshot save backup.db
# Snapshot saved at backup.db

# 查看快照状态
etcdctl snapshot status backup.db
# backup.db: rev=1024, 25MB, 3 files

# 恢复快照（启动新集群）
etcdctl snapshot restore backup.db \
  --name etcd-new \
  --data-dir /var/lib/etcd-new \
  --initial-cluster etcd-new=http://localhost:2380 \
  --initial-advertise-peer-urls http://localhost:2380

# 然后以恢复后的 data-dir 启动 etcd
etcd --data-dir /var/lib/etcd-new ...

💡 最佳实践：定期创建快照（建议 cron 每天一次），并备份到异地。恢复时注意 --initial-cluster-state 应为 new。

认证与 RBAC

# 启用认证
etcdctl auth enable

# 关闭认证
etcdctl auth disable

# 查看认证状态
etcdctl auth status

# 用户管理
etcdctl user add myuser          # 交互式输入密码
etcdctl user add myuser --new-user-password="pwd123"  # 非交互式
etcdctl user get myuser
etcdctl user list
etcdctl user delete myuser

# 修改密码
etcdctl user passwd myuser

# 授予/撤销角色
etcdctl user grant-role myuser admin
etcdctl user revoke-role myuser admin

# 角色管理
etcdctl role add myrole
etcdctl role get myrole
etcdctl role list
etcdctl role delete myrole

# 角色权限管理
# 授予对 /foo 前缀的读写权限
etcdctl role grant-permission myrole readwrite /foo --prefix
# 授予只读权限
etcdctl role grant-permission myrole read /config --prefix
# 授予写入权限
etcdctl role grant-permission myrole write /data --prefix

# 撤销权限
etcdctl role revoke-permission myrole /foo --prefix

详见 09-认证与安全.md

维护操作

# 压缩历史版本（保留到 revision 1000）
etcdctl compact 1000

# 碎片整理（节点级别，释放空间给操作系统）
etcdctl defrag

# 集群级别碎片整理
etcdctl defrag --cluster

# 查看告警
etcdctl alarm list

# 解除告警（如 NOSPACE）
etcdctl alarm disarm

# 强制转移 Leader
etcdctl move-leader <target-node-id>

# 检查 Hash（校验数据一致性）
etcdctl hashkv /var/lib/etcd

环境变量速查

export ETCDCTL_API=3                        # API 版本（必须）
export ETCDCTL_ENDPOINTS=localhost:2379      # 集群地址（逗号分隔）
export ETCDCTL_CACERT=/path/to/ca.pem        # CA 证书
export ETCDCTL_CERT=/path/to/client.pem      # 客户端证书
export ETCDCTL_KEY=/path/to/client-key.pem   # 客户端私钥
export ETCDCTL_USER=myuser:password          # 用户认证
export ETCDCTL_DIAL_TIMEOUT=2s               # 连接超时
export ETCDCTL_COMMAND_TIMEOUT=5s            # 命令超时

核心概念 Go 客户端