4. etcdctl 命令行工具：安装、常用命令与租约操作
etcdctl 是 etcd 官方提供的命令行客户端工具，支持 v2 和 v3 API。在压测沙盘课程中，我们统一使用 v3 API 模式。etcdctl 不仅是日常运维的瑞士军刀，更是理解 etcd 核心机制（Watch、Lease）最直接的交互入口。本章将围绕安装、核心命令、Watch 机制和租约操作展开，为后续编写压测脚本打下坚实基础。
4.1 安装与版本确认
etcdctl 通常随 etcd 二进制一起发布，也可单独下载。推荐使用与 etcd 服务端相同的大版本（如 v3.5.x）。
| 安装方式 | 命令 / 步骤 | 说明 |
|---|---|---|
| 从 etcd 发布包获取 | wget https://github.com/etcd-io/etcd/releases/download/v3.5.15/etcd-v3.5.15-linux-amd64.tar.gztar -xzf etcd-v3.5.15-linux-amd64.tar.gzsudo cp etcdctl /usr/local/bin/ | 包含 etcd、etcdctl、etcdutl |
| Go 安装（需 Go 环境） | go install go.etcd.io/etcd/v3/etcdctl@latest | 自动安装最新稳定版 |
| 包管理器（macOS） | brew install etcd | 附带 etcdctl |
版本对齐检查： 执行
etcdctl version 确认输出包含 api version: 3。若显示 api version: 2，需设置环境变量 export ETCDCTL_API=3。
4.2 常用命令：put / get / del
etcd v3 采用扁平键值存储，所有操作通过 gRPC 完成。以下为最核心的三个数据操作命令。
| 命令 | 语法示例 | 关键参数 | 说明 |
|---|---|---|---|
| put | etcdctl put /app/config/key1 "value1" | --lease 绑定租约；--ignore-value 仅更新租约 | 写入或更新键值对 |
| get | etcdctl get /app/config/key1 | --prefix 前缀扫描；--limit 限制返回条数；--rev 指定历史版本 | 读取单个键或范围 |
| del | etcdctl del /app/config/key1 | --prefix 批量删除；--range 范围删除 | 删除键值对 |
压测关注点： put 操作在 etcd 中为线性一致写入，延迟敏感；get 操作可通过
--consistency=s（串行化）降低延迟，适合高吞吐读压测。
4.3 Watch 机制：从命令行到原理
Watch 是 etcd 实现事件驱动架构的核心。etcdctl 的 watch 命令允许客户端监听键的变化，并在变化发生时实时推送事件。
# 监听单个键
etcdctl watch /app/config/key1
# 监听前缀（监控整个目录）
etcdctl watch /app/config/ --prefix
# 从指定版本开始监听（历史回放）
etcdctl watch /app/config/key1 --rev=100Watch 机制的工作流程如下：
Watch 压测陷阱： 大量 Watch 连接会占用服务端内存和 goroutine。在压测脚本中，应复用 Watch 连接（前缀监听）而非为每个键创建独立 Watch。同时注意 Watch 响应中的
CompactRevision，避免因历史版本压缩导致 Watch 中断。
4.4 租约（Lease）操作
租约是 etcd 实现键值自动过期和心跳保活的机制。etcdctl 提供完整的租约生命周期管理命令。
| 命令 | 语法示例 | 说明 |
|---|---|---|
| 租约授予 | etcdctl lease grant 60 | 创建一个 60 秒 TTL 的租约，返回 Lease ID |
| 租约续期 | etcdctl lease keep-alive 694d7c6b7c8a1f2e | 持续续约（阻塞），保持租约存活 |
| 租约绑定 | etcdctl put /key val --lease=694d7c6b7c8a1f2e | 将键绑定到指定租约，租约过期则键自动删除 |
| 租约查询 | etcdctl lease timetolive 694d7c6b7c8a1f2e | 查看租约剩余 TTL 及绑定的键列表 |
| 租约撤销 | etcdctl lease revoke 694d7c6b7c8a1f2e | 立即撤销租约，所有绑定键被删除 |
租约与键的绑定关系如下图所示：
压测场景应用： 租约常用于模拟分布式锁、服务注册与发现中的会话过期。在压测脚本中，可通过批量创建短 TTL 租约（如 5s）并配合 Watch 监听，验证 etcd 在大量租约并发过期场景下的清理性能与事件推送能力。
4.5 综合操作示例：Watch + Lease 组合
以下示例展示如何通过 etcdctl 模拟一个带自动过期的配置监听场景：
# 终端 1：创建租约并绑定键
LEASE_ID=$(etcdctl lease grant 10 | grep -oP '0x[0-9a-f]+')
etcdctl put /app/config/db-url "postgres://localhost:5432" --lease=$LEASE_ID
# 终端 2：监听该键的变化
etcdctl watch /app/config/db-url
# 终端 1：续约（模拟心跳）
etcdctl lease keep-alive $LEASE_ID
# 终端 1：撤销租约（模拟故障清理）
etcdctl lease revoke $LEASE_ID
# 终端 2 将收到 DELETE 事件，键被自动移除
压测脚本设计启示： 上述组合操作可直接映射为压测脚本中的事务步骤：
1. 创建租约 → 2. 写入键并绑定 → 3. 启动 Watch → 4. 等待租约过期或主动撤销 → 5. 验证 Watch 事件到达。
通过控制 TTL 长度和并发数，可精准评估 etcd 在 Lease 过期风暴下的 Watch 事件吞吐与延迟。
1. 创建租约 → 2. 写入键并绑定 → 3. 启动 Watch → 4. 等待租约过期或主动撤销 → 5. 验证 Watch 事件到达。
通过控制 TTL 长度和并发数，可精准评估 etcd 在 Lease 过期风暴下的 Watch 事件吞吐与延迟。