Etcd v3 API 增删改查详解：从基础命令到Kubernetes存储实战

在介绍 Etcd 数据库的增删改查操作之前，我们有必要先了解其两个核心 API 版本：V2 和 V3。它们是设计理念与底层实现都显著不同的两代接口，目前主流的生产环境使用的是 V3 版本。

版本演进与核心差异

etcd 从 3.4 版本 开始，将命令行工具 etcdctl 的默认 API 版本正式从 v2 改为了 v3。如果你使用的是 etcd 3.0 到 3.3 版本，则需要手动指定 ETCDCTL_API=3 才能使用 v3 API，否则默认仍会使用 v2。

一个关键的理解是：v2 和 v3 可以看作是两个独立的数据存储库。使用 v2 API 写入的数据和使用 v3 API 写入的数据在底层是相互隔离的，两个存储区之间没有 自动同步 或 关联查询 的机制。这意味着，如果你需要让一份数据同时在基于 v2 和 v3 的旧新应用中都可用，就必须分别用两个版本的客户端各写入一次，或者借助官方迁移工具进行一次性的数据拷贝。

下图清晰地展示了 etcd 服务器内部如何处理不同版本的 API 请求：

数据结构：树形目录

与 ZooKeeper 类似，Etcd 也采用了树形目录结构来组织数据。所有的键（Key）都像文件系统中的路径，例如 /project/database/host。这种结构非常直观，便于按“目录”进行归类和管理。在 Kubernetes 中，这种结构被用来存储集群内所有资源对象的定义。

下图以 Kubernetes 的资源存储为例，展示了这种树形路径的典型形态：

理解了这个基础模型后，我们就可以开始进行具体的 CRUD 操作了。本文所有操作均基于 v3 API。

开始前的关键设置

在进行任何操作之前，必须确保你的环境使用的是 v3 API。否则，命令会默认使用 v2 API，导致操作失败或写入错误的数据存储区。

export ETCDCTL_API=3
# 或者在每次执行 etcdctl 命令时显式指定
ETCDCTL_API=3 etcdctl get /some/key

增 / 改 (Put)

put 命令是幂等的，即无论执行多少次，只要键和值相同，最终结果都一样。如果指定的键不存在，则创建它；如果已存在，则用新值覆盖旧值。

# 基本写入：将值 “192.168.1.100” 写入键 `/project/database/host`
etcdctl put /project/database/host “192.168.1.100”

# 带租约写入：键将在租约过期后自动删除
LEASE_ID=$(etcdctl lease grant 60)  # 创建一个有效期为60秒的租约，并获取其ID
etcdctl put /tmp/session_token “abc123” --lease=$LEASE_ID

查 (Get)

get 命令的查询方式非常灵活，可以根据不同需求获取数据。

# 1. 精确获取：获取指定键的值
etcdctl get /project/database/host

# 2. 范围获取：获取键在字节序区间 [/project/database/a, /project/database/z) 内的所有键值对
etcdctl get /project/database/a /project/database/z

# 3. 前缀获取（最常用）：模拟列出目录下的所有内容
etcdctl get /project/database/ --prefix
# 输出示例:
# /project/database/host
# 192.168.1.100
# /project/database/port
# “3306”

# 4. 获取历史版本：需要启用 MVCC 功能，查看指定修订版本时的数据
etcdctl get /project/database/host --rev=5  # 获取该键在全局修订版本5时的值

# 5. 只获取键名或仅统计数量
etcdctl get /project/database/ --prefix --keys-only
etcdctl get /project/database/ --prefix --count-only

删 (Del)

删除操作同样支持精确删除和基于前缀的范围删除。

# 1. 精确删除：删除指定的键
etcdctl del /project/database/host

# 2. 前缀删除：模拟删除整个目录及其下所有子键
etcdctl del /project/database/ --prefix

# 3. 删除并返回被删除的键值对数据
etcdctl del /project/database/ --prefix --prev-kv

总结

掌握 Etcd 的 v3 API 基本命令是管理和运维现代分布式系统，特别是 Kubernetes 集群的必备技能。从简单的 put 和 get，到利用 --prefix 进行目录式操作，再到结合租约（Lease）实现临时节点，这些操作构成了使用 Etcd 的基石。在实际生产环境中，理解其树形数据模型并结合具体的业务场景（如服务发现、配置存储、分布式锁）来设计键的命名空间，将更能发挥出这个强大键值存储系统的威力。如果想了解更多关于分布式存储或系统架构的深入讨论，欢迎来 云栈社区 交流。