4. etcdctl 命令行工具：安装、配置与核心操作
etcdctl 是 etcd 的官方命令行客户端，是压测沙盘中执行数据写入、读取、监听和集群状态检查的核心工具。本章覆盖 etcdctl 的安装方式、版本对齐策略、常用命令语义以及安全连接验证，确保你在后续压测脚本中能准确调用。
4.1 安装与版本兼容性
etcdctl 与 etcd 服务端采用相同的版本号体系，但客户端二进制可独立下载。版本不匹配会导致协议握手失败或 API 字段解析异常，因此在沙盘构建中必须遵循“大版本一致、小版本 ≥ 服务端”的原则。
| 安装方式 | 适用场景 | 版本获取命令 |
|---|---|---|
| 从 etcd 发布包解压 | 单节点或集群快速部署 | etcdctl version |
| go install 编译安装 | 开发环境、自定义分支 | go install go.etcd.io/etcd/v3/etcdctl@latest |
| 容器镜像内自带 | Kubernetes 或 Docker 沙盘 | docker exec <container> etcdctl version |
版本兼容性红线：etcdctl v3.4.x 不能连接 etcd v3.5+ 集群（gRPC API 版本不匹配）。压测沙盘建议统一使用 etcd v3.5.x 系列，etcdctl 版本 ≥ 3.5.0。
4.2 常用命令：put / get / del / watch
etcdctl 的 v3 API 使用 etcdctl put、get、del、watch 四个原子操作构建所有数据流。下面以压测沙盘中最典型的键值操作为例，列出命令格式与关键参数。
| 命令 | 语法 | 压测常用参数 |
|---|---|---|
| put | etcdctl put <key> <value> |
--lease 绑定租约，--ignore-value 仅更新 key |
| get | etcdctl get <key> |
--prefix 前缀扫描，--limit 限制返回条数 |
| del | etcdctl del <key> |
--prefix 批量删除，--from-key 范围删除 |
| watch | etcdctl watch <key> |
--prefix 监听前缀，--rev 从指定版本开始 |
压测提示：使用
--prefix 进行范围操作时，etcd 内部会触发线性化读或串行化读。压测脚本中建议先通过 get --prefix 预热缓存，再执行 put 写入，避免读压力与写压力叠加导致延迟抖动。
4.3 TLS 连接测试
生产级压测沙盘必须启用 TLS 加密。etcdctl 通过 --cacert、--cert、--key 三个参数建立双向认证通道。测试 TLS 连接是否正常，推荐使用 etcdctl endpoint health 和 etcdctl member list 两条命令。
# 带 TLS 的健康检查
etcdctl --endpoints=https://192.168.1.10:2379 \
--cacert=/etc/etcd/ca.pem \
--cert=/etc/etcd/client.pem \
--key=/etc/etcd/client-key.pem \
endpoint health
# 输出示例
# https://192.168.1.10:2379 is healthy: successfully committed proposal: took = 2.345ms
排障要点：如果 TLS 连接失败，先检查证书 CN 是否匹配 endpoints 中的主机名或 IP。etcdctl 默认不跳过证书验证，
--insecure-skip-tls-verify 仅用于临时调试，压测沙盘不应使用。
4.4 配置持久化与端点管理
为避免每次命令重复输入 endpoints 和证书路径，etcdctl 支持环境变量和配置文件两种持久化方式。压测沙盘中推荐使用环境变量，便于脚本动态切换集群地址。
| 配置方式 | 示例 | 优先级 |
|---|---|---|
| 环境变量 | ETCDCTL_ENDPOINTS=https://10.0.0.1:2379 |
高（覆盖配置文件） |
| 命令行参数 | --endpoints=https://10.0.0.1:2379 |
最高（覆盖环境变量） |
| 配置文件 | ~/.etcdrc 或 /etc/etcd/etcdctl.conf |
低（默认值） |
# 压测沙盘推荐的环境变量配置模板
export ETCDCTL_ENDPOINTS="https://192.168.1.10:2379,https://192.168.1.11:2379,https://192.168.1.12:2379"
export ETCDCTL_CACERT="/etc/etcd/ca.pem"
export ETCDCTL_CERT="/etc/etcd/client.pem"
export ETCDCTL_KEY="/etc/etcd/client-key.pem"
export ETCDCTL_DIAL_TIMEOUT="5s"
export ETCDCTL_COMMAND_TIMEOUT="10s"
# 配置后可直接执行
etcdctl put /sandbox/key1 "value1"
etcdctl get /sandbox/key1
沙盘最佳实践：将上述环境变量写入
/etc/profile.d/etcdctl.sh，确保每次登录 shell 自动加载。压测脚本中通过 source /etc/profile.d/etcdctl.sh 继承配置，避免硬编码证书路径。
4.5 本章小结
- 版本对齐：etcdctl 与服务端大版本必须一致，推荐统一使用 v3.5.x。
- 核心命令：put/get/del/watch 构成压测数据平面的全部操作，
--prefix和--limit是范围操作的关键参数。 - TLS 验证：使用
endpoint health作为连接测试的黄金命令，证书链和主机名匹配是排障重点。 - 配置持久化：环境变量方式最适合沙盘动态切换，命令行参数用于临时覆盖。