etcdctl v2 客户端实战指南：配置参数、键值操作、事件监控与退出码全解

本文基于 etcd 仓库中的 etcdctl v2 文档，系统讲解 etcd v2 API 命令行客户端 etcdctl 的全套配置参数、键值增删查改与目录管理操作、事件监听机制、Endpoint 与 DNS 发现配置、认证方式以及退出码约定，并结合当前仓库源码补充参数默认值的来源与环境变量映射机制，帮助你在脚本和日常运维中可靠地操作 etcd 集群。

一、etcdctl 与 v2 API：定位、获取方式与适用前提

etcdctl 是 etcd 的官方命令行客户端，既可以用于自动化脚本，也适合管理员交互式地探索 etcd 集群。本文对应的文档 READMEv2.md 专门描述其 v2 API 模式下的行为与命令集。

需要注意一个重要的适用前提：当前仓库的 etcdctl 默认使用 v3 API。根据 etcdctl/README.md 第 8 行的说明，若要以 v2 API 方式调用，需设置环境变量 ETCDCTL_API=2（反之，使用早于 v3.4 的发布版本时则需设置 ETCDCTL_API=3）。也就是说，下文的 set、get、ls、rm、watch、mk、mkdir 等 v2 风格命令，运行在 v2 兼容模式下；仓库中 v3 默认模式的命令集（put、del、txn、lease 等）则由 etcdctl/ctlv3/ctl.go 中的命令注册代码定义。

获取 etcdctl 的两种方式：

• 发布二进制：随 etcd 官方 Release 一并提供（原文档所述）；
• 源码构建：使用仓库父目录下的构建脚本，即顶层 Makefile，从 etcdctl/main.go 入口编译。

版本策略上，etcdctl 遵循语义化版本（Semantic Versioning），并与 etcd 主发布周期锁定同步（lockstep）发布；仓库中的版本常量定义在 api/version/version.go 中（例如 Version、MinClusterVersion）。etcdctl 采用 Apache 2.0 许可证，详见仓库根目录的 LICENSE 文件。

二、全局配置参数详解

v2 模式下的全局参数决定了 etcdctl 如何连接集群、以什么格式输出、如何认证与限流。下表汇总原文档列出的全部参数及其默认值与环境变量：

参数	短选项	作用	默认值	环境变量
--debug		输出可用于复现请求的 cURL 命令	关闭	-
--no-sync		发送请求前不同步集群信息，用于访问未发布的客户端端点	关闭	-
--output	-o	指定响应输出格式（simple、extended 或 json）	simple	-
--discovery-srv	-D	用于查询描述集群端点 SRV 记录的域名	无	ETCDCTL_DISCOVERY_SRV
--peers		集群中机器地址的逗号分隔列表	http://127.0.0.1:2379	ETCDCTL_PEERS
--endpoint		集群中机器地址的逗号分隔列表	http://127.0.0.1:2379	ETCDCTL_ENDPOINT
--cert-file		用于标识 HTTPS 客户端的 SSL 证书文件	无	ETCDCTL_CERT_FILE
--key-file		用于标识 HTTPS 客户端的 SSL 密钥文件	无	ETCDCTL_KEY_FILE
--ca-file		用于校验启用 HTTPS 的服务端证书的 CA 包	无	ETCDCTL_CA_FILE
--username	-u	提供 username[:password]；未提供密码时交互式提示	无	ETCDCTL_USERNAME
--timeout		单次请求的连接超时	1s	-
--total-timeout		命令执行的总超时（watch 除外）	5s	-

两点值得结合实现细节理解：

1. --endpoint 与 --no-sync 的交互：不带 --no-sync 时，etcdctl 会先向集群做内部同步（sync），同步结果会覆盖 --endpoint 传入的值；因此要访问集群未发布的客户端端点，必须同时使用 --no-sync。
2. --debug 的排障价值：开启后 etcdctl 会把请求翻译成可复现的 cURL 命令输出，便于把客户端问题与服务端行为对照分析。

环境变量的映射规则

除表中明确列出的环境变量外，etcdctl 支持一套通用的 ETCDCTL_ 前缀规则：把参数名转大写、以 ETCDCTL_ 为前缀、并将连字符 - 替换为下划线 _。例如：

ETCDCTL_ENDPOINT="http://10.0.28.1:4002" etcdctl get /foo/bar

从源码结构看，这一机制由 pkg/flags/flag.go 中的 FlagToEnv 函数实现（prefix + "_" + 大写(连字符转下划线)），并在每个命令构建客户端配置时通过 etcdctl/ctlv3/command/global.go 中的 flags.SetPflagsFromEnv(lg, "ETCDCTL", fs) 调用生效。该实现还包含一个保护逻辑：如果命令行显式设置了某参数、环境中又存在对应的 ETCDCTL_ 变量（二者冲突），客户端会直接报错退出；未识别的 ETCDCTL_ 变量会打印告警日志。因此使用这些变量时应确保与命令行参数不重复。

超时参数的参考来源

原文档给出的 --timeout（默认 1s）与 --total-timeout（默认 5s）是 v2 模式下的取值。作为对照，当前 v3 模式的对应默认值定义在 etcdctl/ctlv3/ctl.go：defaultDialTimeout = 2s、defaultCommandTimeOut = 5s（另有 keepalive 时间与超时各 2s/6s）。可见短命令的总超时在两个时代均为 5 秒，而拨号超时从 v2 的 1 秒放宽到 v3 的 2 秒。

三、键值操作实战

3.1 设置键值

为 /foo/bar 设置值：

$ etcdctl set /foo/bar "Hello world"
Hello world

附带 60 秒 TTL（到期自动删除）设置：

$ etcdctl set /foo/bar "Hello world" --ttl 60
Hello world

条件更新——仅当前一个值为 "Hello world" 时写入（值 CAS）：

$ etcdctl set /foo/bar "Goodbye world" --swap-with-value "Hello world"
Goodbye world

条件更新——仅当前一个 etcd index 为 12 时写入（索引 CAS）：

$ etcdctl set /foo/bar "Goodbye world" --swap-with-index 12
Goodbye world

--swap-with-value 与 --swap-with-index 构成了 v2 API 的原子比较-交换语义，是实现分布式协调（如防止并发覆盖配置）的关键手段。

3.2 创建键与目录

仅当键不存在时创建（原子操作）：

$ etcdctl mk /foo/new_bar "Hello world"
Hello world

在目录 /fooDir 下创建按序排列的新键（自动生成递增的有序子键名）：

$ etcdctl mk --in-order /fooDir "Hello world"

仅当不存在时创建目录：

$ etcdctl mkdir /fooDir

仅当键已存在时更新：

$ etcdctl update /foo/bar "Hola mundo"
Hola mundo

创建或更新目录（等价于 mkdir -p 的宽松语义）：

$ etcdctl setdir /mydir

3.3 读取与列表

读取单个键的当前值：

$ etcdctl get /foo/bar
Hello world

以可解析的扩展格式读取，附带元数据：

$ etcdctl -o extended get /foo/bar
Key: /foo/bar
Modified-Index: 72
TTL: 0
Etcd-Index: 72
Raft-Index: 5611
Raft-Term: 1

Hello World

输出格式由全局参数 -o 控制：simple（默认，纯值）、extended（键、修改索引、TTL、etcd 索引、raft 索引与任期等元数据）、json（结构化输出，便于脚本用 jq 等工具处理）。

用 ls 浏览键空间：

$ etcdctl ls
/akey
/adir
$ etcdctl ls /adir
/adir/key1
/adir/key2

加 --recursive 递归列出所有子键：

$ etcdctl ls --recursive
/akey
/adir
/adir/key1
/adir/key2

加 -p 让目录在输出中以 / 结尾，便于区分目录与键：

$ etcdctl ls -p
/akey
/adir/

3.4 删除键

删除单个键：

$ etcdctl rm /foo/bar

删除空目录（两种等价写法）：

$ etcdctl rmdir /path/to/dir

$ etcdctl rm /path/to/dir --dir

递归删除键及其全部子键：

$ etcdctl rm /path/to/dir --recursive

条件删除——仅当当前值为 "Hello world" 时删除：

$ etcdctl rm /foo/bar --with-value "Hello world"

条件删除——仅当当前 etcd index 为 12 时删除：

$ etcdctl rm /foo/bar --with-index 12

四、事件监听：watch 与 exec-watch

4.1 基本监听

只监听键的下一次变更：

$ etcdctl watch /foo/bar
Hello world

持续监听（--forever），进程挂起直到 Ctrl+C，期间按键变更打印值：

$ etcdctl watch /foo/bar --forever
Hello world
.... client hangs forever until ctrl+C printing values as key change

从指定 etcd index 开始持续监听：

$ etcdctl watch /foo/bar --forever --index 12
Hello world
.... client hangs forever until ctrl+C printing values as key change

4.2 exec-watch：把变更事件变成程序执行

exec-watch 在每次事件发生时执行指定程序，并把事件信息通过 ETCD_WATCH_* 环境变量传递给子进程：

$ etcdctl exec-watch /foo/bar -- sh -c "env | grep ETCD"
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My configuration stuff
ETCD_WATCH_MODIFIED_INDEX=1999
ETCD_WATCH_KEY=/foo/bar
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My new configuration stuff
ETCD_WATCH_MODIFIED_INDEX=2000
ETCD_WATCH_KEY=/foo/bar

加 --recursive 后，前缀下任意子键的变更都会触发执行（注意下面第二次事件的键为 /foo/barbar）：

$ etcdctl exec-watch --recursive /foo -- sh -c "env | grep ETCD"
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My configuration stuff
ETCD_WATCH_MODIFIED_INDEX=1999
ETCD_WATCH_KEY=/foo/bar
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My new configuration stuff
ETCD_WATCH_MODIFIED_INDEX=2000
ETCD_WATCH_KEY=/foo/barbar

这个机制的典型用途是把 etcd 作为配置中心：进程启动时 get 一次初始值，随后用 exec-watch 常驻监听，配置一变就重新加载。事件携带的四个变量含义如下：

• ETCD_WATCH_ACTION：事件类型（如 set、delete）；
• ETCD_WATCH_VALUE：事件对应的值；
• ETCD_WATCH_MODIFIED_INDEX：该键的最新修改索引；
• ETCD_WATCH_KEY：发生变更的键名。

五、Endpoint 配置与 DNS 发现

5.1 指定集群端点

当集群不在默认的 http://127.0.0.1:2379 时，通过 --endpoint 标志或 ETCDCTL_ENDPOINT 环境变量指定；可以写单个端点，也可以写逗号分隔的多个端点。注意：若同时提供了 --discovery-srv 选项，--endpoint 会被忽略。

ETCDCTL_ENDPOINT="http://10.0.28.1:4002" etcdctl set my-key to-a-value
ETCDCTL_ENDPOINT="http://10.0.28.1:4002,http://10.0.28.2:4002,http://10.0.28.3:4002" etcdctl set my-key to-a-value
etcdctl --endpoint http://10.0.28.1:4002 my-key to-a-value
etcdctl --endpoint http://10.0.28.1:4002,http://10.0.28.2:4002,http://10.0.28.3:4002 etcdctl set my-key to-a-value

多端点列表的价值在于：当某一个成员不可达时，请求可切换到其他端点，脚本无需自行处理主从切换。

5.2 DNS SRV 服务发现

在域名 SRV 记录中维护集群端点时，使用 --discovery-srv 标志或 ETCDCTL_DISCOVERY_SRV 环境变量，该选项优先级高于 --endpoint：

ETCDCTL_DISCOVERY_SRV="some-domain" etcdctl set my-key to-a-value
etcdctl --discovery-srv some-domain set my-key to-a-value

对于集群成员频繁变更的环境，SRV 记录可以由服务编排工具自动维护，etcdctl 每次执行时查询最新的端点集合，从而免去了手工维护端点列表的负担。

六、认证与 TLS

6.1 用户名密码认证

当 etcd 集群启用了认证时，用 --username 标志或 ETCDCTL_USERNAME 环境变量提供凭据；若只给用户名不带密码，etcdctl 会以交互模式提示输入密码：

ETCDCTL_USERNAME="root:password" etcdctl set my-key to-a-value

从源码结构看，这一“无密码则交互提示”的行为由 etcdctl/ctlv3/command/global.go 中的 authCfgFromCmd 实现：它以第一个冒号为界拆分 username:password，拆分不出两段时调用交互式询问函数 speakeasy.Ask("Password: ") 读取密码。

6.2 TLS 证书参数

对启用 TLS 的集群，使用三个证书参数构成完整的双向校验链路：

etcdctl --cert-file=/path/client.crt \
        --key-file=/path/client.key \
        --ca-file=/path/ca.crt \
        get /foo/bar

• --cert-file / ETCDCTL_CERT_FILE：客户端证书，向服务端证明客户端身份；
• --key-file / ETCDCTL_KEY_FILE：客户端私钥；
• --ca-file / ETCDCTL_CA_FILE：CA 证书包，用于验证服务端证书。

七、退出码（Return Codes）

etcdctl v2 模式按如下约定返回退出码，便于脚本用 $? 精确区分失败类型：

0    Success
1    Malformed etcdctl arguments
2    Failed to connect to host
3    Failed to auth (client cert rejected, ca validation failure, etc)
4    400 error from etcd
5    500 error from etcd

脚本中的典型用法：

etcdctl get /foo/bar
case $? in
  0) echo "读取成功" ;;
  1) echo "参数错误，检查命令行" ;;
  2) echo "无法连接 etcd，检查网络与 endpoint" ;;
  3) echo "认证失败，检查证书或用户名密码" ;;
  4|5) echo "etcd 服务端错误，查看 etcd 日志" ;;
esac

值得注意的是，这一退出码体系在当前仓库的 v3 模式代码中仍有对应：pkg/cobrautl/error.go 定义了 ExitError（1）、ExitBadConnection（2）、ExitServerError（4）、ExitClusterNotHealthy（5）等常量，与 v2 文档中 1/2/4/5 的语义（参数错误、连接失败、服务端 400/500 错误）一脉相承；v3 模式另有 ExitBadArgs = 128 等扩展码。编写兼容脚本时应以所用模式对应的退出码为准。

八、总结与延伸阅读

本文完整覆盖了 etcdctl/READMEv2.md 的全部技术内容：12 个全局配置参数（含默认值与环境变量）、键值设置/读取/列表/删除的完整命令集（包括 TTL、条件 CAS、有序键、递归操作）、watch 与 exec-watch 的事件监听模型、多端点与 DNS SRV 发现、认证与 TLS 配置，以及 0–5 的退出码约定。再结合仓库源码补充了环境变量映射的实现（pkg/flags/flag.go）、认证交互提示的实现（etcdctl/ctlv3/command/global.go）与 v3 模式的默认超时和退出码定义（etcdctl/ctlv3/ctl.go、pkg/cobrautl/error.go）。

最后重申适用边界：上述 v2 风格命令需要 ETCDCTL_API=2 环境变量的配合，且依赖服务端对 v2 API 的支持；在较新的 etcd 版本中 v3 API 是默认且持续演进的主线，生产脚本建议优先使用 v3 命令集（参考 etcdctl/README.md），本文内容则适用于维护与理解 v2 生态中的存量脚本和配置系统。