etcd 分布式 KV¶

一句话概述：etcd 是 Kubernetes 的核心存储组件，一个强一致性的分布式键值存储，用 Raft 共识算法保证数据一致，适合存储配置数据和服务发现。

核心知识点¶

概念	白话解释
Raft	共识算法 = 多个节点如何就数据达成一致
Leader/Follower	领导者/跟随者 = 集群中的角色分工
Watch	监听 = 实时监听键值变化
Lease	租约 = 给键设置有效期（过期自动删除）
Transaction	事务 = 原子性地执行多个操作
MVCC	多版本并发控制 = 保留数据的历史版本

安装配置¶

# Docker
docker run -d --name etcd \
  -p 2379:2379 -p 2380:2380 \
  gcr.io/etcd-development/etcd:v3.5.12 \
  etcd --advertise-client-urls http://0.0.0.0:2379 \
  --listen-client-urls http://0.0.0.0:2379

# 安装 etcdctl 命令行工具
brew install etcd  # macOS

基本使用¶

# 基本操作
etcdctl put mykey "myvalue"          # 写入
etcdctl get mykey                     # 读取
etcdctl get --prefix "config/"        # 按前缀读取
etcdctl del mykey                     # 删除
etcdctl watch mykey                   # 监听变化（实时推送）

# 租约（自动过期）
etcdctl lease grant 60                # 创建60秒租约
etcdctl put --lease=<ID> temp "data"  # 带租约的键（60秒后自动删除）
etcdctl lease keep-alive <ID>         # 续约

# 事务
etcdctl txn --interactive
# compares: value("key") = "old"
# success: put key "new"
# failure: get key

Python 客户端¶

import etcd3

client = etcd3.client()  # 连接

client.put('/config/db_host', 'localhost')  # 写入
value, metadata = client.get('/config/db_host')  # 读取
print(value.decode())

# 监听变化
for event in client.watch_prefix('/config/'):
    print(f"变化: {event}")

常见报错¶

报错信息	原因	解决方法
`no leader`	集群没有 Leader	确保多数节点在线
`mvcc: database space exceeded`	磁盘空间不足	`etcdctl compact` + `defrag`
`context deadline exceeded`	请求超时	检查网络和集群健康状态

速查表¶

etcdctl put key value             # 写入
etcdctl get key                   # 读取
etcdctl get --prefix "prefix/"    # 前缀读取
etcdctl del key                   # 删除
etcdctl watch key                 # 监听
etcdctl member list               # 集群成员
etcdctl endpoint health           # 健康检查
etcdctl snapshot save backup.db   # 备份

# etcd 主要用途：Kubernetes 集群数据存储、服务发现、分布式锁、配置中心

参考：etcd 文档 | 更新于 2026 年