简介etcd分布式存储系统 v3.5.12.zip 面向分布式系统学习者、云原生开发者及毕业设计研究者提供一份可直接研读的稳定版源码。etcd 基于 Raft 一致性算法实现可靠的键值对存储常用于共享配置与服务发现是 Kubernetes 等容器编排系统的状态管理核心。压缩包共 1457 个文件约 4.75MB以 1035 个 Go 源文件为主体辅以 proto 接口定义、json 配置、sh 脚本、crt 证书、md 文档及 Dockerfile 等构建文件完整覆盖服务端、客户端与部署工具链。已有 168 人学习下载。通过分析源码读者可深入理解 Go 并发模型、gRPC 接口设计与 Raft 算法的工程实现并借助说明文档掌握集群安装、配置与故障恢复流程适合作为分布式一致性研究与项目实践的参考素材。1. etcd v3.5.12 部署前先搞清楚它到底存什么很多团队第一次接触 etcd是因为 Kubernetes 集群起不来报错指向 etcd 健康检查失败。于是有人把 etcd 当成一个键值数据库随手装上了结果集群是恢复了但过两周发现磁盘写满、leader 频繁切换、watch 事件堆积。问题不在 etcd 本身而在于没搞清楚它到底承担什么角色。etcd 是一个基于 Raft 一致性算法实现的分布式键值存储它的核心价值不是存数据而是让多个节点对同一份数据达成一致。Kubernetes 的所有集群状态——Pod 调度结果、Service 端点、ConfigMap、Secret、RBAC 规则——全部存在 etcd 里。它同时也是服务发现和分布式锁的常用底座。v3.5.12 是 v3.5 系列的一个补丁版本主要修了稳定性和安全问题适合生产环境直接使用。这篇文章面向需要在 Linux 上从零部署 etcd 集群、或者正在排查 etcd 性能问题的工程师从二进制部署讲到参数调优和踩坑排查每一步都能照着复现。2. etcd v3.5.12 集群部署从单机验证到三节点落地2.1 为什么生产环境至少三个节点etcd 用 Raft 协议做共识集群里必须有过半数节点存活才能选出 leader 并继续写入。一个节点没有容错能力两个节点更糟——一旦挂掉一个剩下一个无法凑齐多数派集群直接不可写。三个节点可以容忍一个节点故障五个节点可以容忍两个。超过五个节点后Raft 的写入延迟会随节点数增加而上升因为 leader 需要把日志复制到更多 follower。所以生产环境的常见选择是 3 节点或 5 节点3 节点是性价比最高的方案。节点规格上etcd 对 CPU 要求不高但对磁盘 IO 延迟极其敏感。官方建议使用 SSD因为 etcd 每次写入都要 fsync 到磁盘。如果磁盘 fsync 延迟超过 10ms就会出现apply 等待时间过长的告警进而触发 leader 选举。内存方面etcd 把整个键空间缓存在内存里默认配额是 2GB超过就会触发 NOSPACE 告警并拒绝写入。对于大多数 Kubernetes 集群8GB 内存、4 核 CPU、SSD 磁盘足够。网络延迟同样关键。Raft 的 heartbeat 间隔默认是 100ms选举超时是 1000ms。如果节点间网络 RTT 超过 50ms就很容易出现 follower 来不及响应 heartbeat 导致重新选举。所以三个节点最好在同一个机房或同一个可用区不要跨地域部署。2.2 下载与安装 etcd v3.5.12etcd 官方发布的是静态编译的二进制包不依赖特定 Linux 发行版的库。下载后解压即可使用。以下命令在三台机器上分别执行假设节点 IP 为 10.0.0.1、10.0.0.2、10.0.0.3。# 下载 etcd v3.5.12 二进制包 # 注意实际下载地址以官方发布页为准此处用变量代替 ETCD_VERv3.5.12 DOWNLOAD_URLhttps://github.com/etcd-io/etcd/releases/download curl -L ${DOWNLOAD_URL}/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz -o /tmp/etcd.tar.gz # 解压并安装到 /usr/local/bin tar xzvf /tmp/etcd.tar.gz -C /tmp cp /tmp/etcd-${ETCD_VER}-linux-amd64/etcd /usr/local/bin/ cp /tmp/etcd-${ETCD_VER}-linux-amd64/etcdctl /usr/local/bin/ chmod x /usr/local/bin/etcd /usr/local/bin/etcdctl # 验证版本 etcd --version etcdctl version这段脚本做了三件事下载指定版本的压缩包、解压后把 etcd 和 etcdctl 两个二进制文件复制到系统 PATH 下、验证版本号。etcdctl 是命令行客户端后续所有操作都靠它。注意 etcd 和 etcdctl 的版本要一致否则可能出现 API 不兼容。参数说明ETCD_VER控制版本号改成其他 v3.5.x 版本也可以DOWNLOAD_URL是官方发布地址如果网络受限可以提前下载好再传到目标机器。/usr/local/bin是标准路径确保所有用户都能调用。2.3 三节点集群配置文件与启动etcd 支持命令行参数和配置文件两种方式。生产环境建议用 systemd 管理配置文件放在/etc/etcd/etcd.conf.yml。以下以 10.0.0.1 节点为例另外两个节点只需改name、initial-advertise-peer-urls、listen-peer-urls、listen-client-urls、advertise-client-urls这几项。# /etc/etcd/etcd.conf.yml name: etcd-1>[Unit] Descriptionetcd key-value store Documentationhttps://etcd.io/docs/ Afternetwork.target [Service] Typenotify ExecStart/usr/local/bin/etcd --config-file/etc/etcd/etcd.conf.yml Restartalways RestartSec5 LimitNOFILE65536 [Install] WantedBymulti-user.target然后执行systemctl daemon-reload systemctl enable etcd systemctl start etcd systemctl status etcd三个节点都启动后在任意一台机器上验证集群健康状态# 设置 API 版本为 v3 export ETCDCTL_API3 # 查看集群成员列表 etcdctl --endpointshttp://10.0.0.1:2379,http://10.0.0.2:2379,http://10.0.0.3:2379 member list # 查看端点健康状态 etcdctl --endpointshttp://10.0.0.1:2379,http://10.0.0.2:2379,http://10.0.0.3:2379 endpoint health # 查看端点状态关注 leader 和 raftIndex etcdctl --endpointshttp://10.0.0.1:2379,http://10.0.0.2:2379,http://10.0.0.3:2379 endpoint status --write-outtablemember list会输出三个成员的 ID、状态、peer 地址和客户端地址。endpoint health对每个端点发一次健康检查返回healthy或unhealthy。endpoint status是最有用的诊断命令输出里IS LEADER列标记当前 leaderRAFT INDEX是已提交的日志索引RAFT TERM是当前任期号DB SIZE是后端数据库大小。如果三个节点的 RAFT INDEX 差距很大说明有节点同步落后。参数说明quota-backend-bytes设为 8GB 是因为默认 2GB 对中等规模集群偏小但也不要设太大否则 etcd 内存占用会很高。auto-compaction-retention设为 1 小时意味着每小时压缩一次历史版本Kubernetes 场景下这个值可以设短一些比如 10 分钟因为 K8s 写入频繁。initial-cluster-token是集群标识同一个 token 的节点才会组成集群不同集群要用不同 token。3. etcdctl 日常操作读写、watch 与 lease 的实操命令3.1 键值读写与版本机制etcd v3 的 API 和 v2 完全不同v3 用 gRPC键值支持多版本。每次 put 一个 keyetcd 不会覆盖旧值而是追加一个新版本旧版本仍然可读直到被压缩。这是 etcd 实现 watch 和事务的基础。export ETCDCTL_API3 ENDPOINTShttp://10.0.0.1:2379,http://10.0.0.2:2379,http://10.0.0.3:2379 # 写入一个键 etcdctl --endpoints$ENDPOINTS put /app/config/db_host 10.0.0.100 # 读取键值 etcdctl --endpoints$ENDPOINTS get /app/config/db_host # 读取键值并显示详细信息版本号、创建 revision、修改 revision etcdctl --endpoints$ENDPOINTS get /app/config/db_host -w json # 按前缀读取所有键 etcdctl --endpoints$ENDPOINTS get /app/config/ --prefix # 只读取 key 不读 value etcdctl --endpoints$ENDPOINTS get /app/config/ --prefix --keys-only # 删除键 etcdctl --endpoints$ENDPOINTS del /app/config/db_hostput返回的OK不带额外信息但get -w json会返回一个 JSON 结构里面revision是全局递增的版本号create_revision是这个 key 第一次被创建时的版本mod_revision是最后一次修改的版本version是这个 key 被修改的次数。理解这几个字段很重要因为 etcd 的乐观锁就是基于 revision 比较实现的。参数说明--prefix表示按前缀匹配--keys-only只返回 key 列表适合快速查看有哪些配置项。-w json指定输出格式还支持table、fields等。--limit可以限制返回条数配合--prefix使用避免一次拉取太多数据。3.2 watch 机制与事件流watch 是 etcd 最核心的能力之一。Kubernetes 的 controller 就是通过 watch 感知资源变化的。etcdctl 也支持 watch可以用来调试。# 监听单个 key 的变化 etcdctl --endpoints$ENDPOINTS watch /app/config/db_host # 监听前缀下所有 key 的变化 etcdctl --endpoints$ENDPOINTS watch /app/config/ --prefix # 从指定 revision 开始监听用于补偿历史事件 etcdctl --endpoints$ENDPOINTS watch /app/config/ --prefix --rev100 # 只监听一次事件后退出 etcdctl --endpoints$ENDPOINTS watch /app/config/ --prefix --rev100watch 命令会阻塞终端每当被监听的 key 发生变化就输出一个事件包含事件类型PUT 或 DELETE、key、value 和 revision。--rev参数指定从哪个 revision 开始监听如果指定的 revision 已经被压缩掉了etcd 会返回一个ErrCompacted错误这时候需要重新做一次全量 get 再继续 watch。这是实际开发中很容易踩的坑watch 断连后如果直接用旧 revision 重连可能因为压缩而失败。参数说明--prev-kv可以在事件里带上变化前的值方便做 diff。--progress-notify会定期发送进度通知用于确认 watch 连接还活着。生产环境的客户端一般会设置较长的超时并实现自动重连。3.3 lease 与分布式锁lease 是 etcd 实现 TTL 和分布式锁的基础。一个 lease 有一个 TTL客户端需要定期续约否则 lease 过期后关联的所有 key 会被自动删除。# 创建一个 TTL 为 60 秒的 lease返回 lease ID etcdctl --endpoints$ENDPOINTS lease grant 60 # 假设返回的 lease ID 是 694d8a7c1f2b3e4f # 把 key 关联到这个 lease etcdctl --endpoints$ENDPOINTS put /app/lock/worker1 alive --lease694d8a7c1f2b3e4f # 查看 lease 信息 etcdctl --endpoints$ENDPOINTS lease timetolive 694d8a7c1f2b3e4f # 续约 etcdctl --endpoints$ENDPOINTS lease keep-alive 694d8a7c1f2b3e4f # 撤销 lease关联的 key 会被删除 etcdctl --endpoints$ENDPOINTS lease revoke 694d8a7c1f2b3e4f分布式锁的典型做法是多个客户端竞争创建同一个 key谁创建成功谁拿到锁创建时绑定一个 lease客户端定期续约。如果客户端崩溃lease 过期后 key 自动删除锁释放。etcd 官方提供了 concurrency 包封装了这个逻辑但理解底层机制对排查锁不释放的问题很有帮助。参数说明lease grant的 TTL 单位是秒最小可以设 1 秒但生产环境不建议设太短否则网络抖动就容易导致 lease 过期。lease keep-alive会持续续约直到终端中断。lease timetolive返回剩余 TTL 和已授权的 key 列表。4. etcd 性能调优磁盘、压缩与 defrag 的参数怎么设4.1 磁盘 IO 是 etcd 性能的第一瓶颈etcd 的写入路径是客户端请求 → leader 追加 WAL 日志 → fsync 到磁盘 → 复制到 follower → follower fsync → leader 提交 → apply 到 boltdb。整个链路里最慢的环节就是 fsync。如果磁盘 fsync 延迟高写入吞吐直接下降。用fio可以测磁盘的 fsync 延迟# 测试随机写和 fsync 延迟 fio --nameetcd-test --ioenginelibaio --direct1 --rwrandwrite \ --bs4k --size1G --numjobs1 --fsync1 --runtime60 \ --time_based --group_reporting关注输出里的fsync/fdatasync/sync_file_range的avg和p99。如果 p99 超过 10msetcd 的写入延迟就会明显上升。解决办法是换 SSD 或者 NVMe不要用网络存储NFS、Ceph RBD 等因为网络存储的 fsync 延迟通常很高。etcd 自身也暴露了磁盘相关的指标。通过--listen-metrics-urls开启 metrics 端点后可以抓取etcd_disk_wal_fsync_duration_seconds和etcd_disk_backend_commit_duration_seconds两个直方图。前者是 WAL fsync 耗时后者是 boltdb 提交耗时。如果 WAL fsync 的 p99 超过 25ms或者 backend commit 的 p99 超过 100ms就需要检查磁盘了。4.2 压缩与 defrag 的正确姿势etcd 的多版本机制意味着每次修改都会保留旧版本如果不压缩数据库会无限增长。压缩compaction是删除某个 revision 之前的所有历史版本但压缩只是标记删除磁盘空间不会立即释放。defrag 才是真正回收空间的操作。# 查看当前 revision etcdctl --endpoints$ENDPOINTS endpoint status --write-outtable # 手动压缩到指定 revision 之前 etcdctl --endpoints$ENDPOINTS compact 1000 # 对某个端点做 defrag注意defrag 会阻塞该节点的读写 etcdctl --endpointshttp://10.0.0.1:2379 defrag # 查看 defrag 后的 DB SIZE 变化 etcdctl --endpoints$ENDPOINTS endpoint status --write-outtable压缩和 defrag 有几个关键点。第一压缩是集群级别的操作只需要在一个节点执行但所有节点都会执行压缩。第二defrag 是节点级别的必须逐个节点执行而且 defrag 期间该节点会阻塞读写所以要在低峰期做。第三defrag 不要频繁做一般一周一次或者 DB SIZE 增长明显时做一次。第四如果开启了auto-compaction-retentionetcd 会自动压缩但不会自动 defragdefrag 仍然需要手动或通过定时任务触发。参数说明compact的 revision 参数要选一个比当前最新 revision 小的值通常用当前 revision 减去一个安全窗口。如果压缩的 revision 太新正在 watch 的客户端可能收到ErrCompacted。defrag没有参数直接对目标端点执行。4.3 关键性能参数对照表参数默认值生产建议作用quota-backend-bytes2GB8GB后端数据库配额超过触发 NOSPACEauto-compaction-retention0关闭1h 或 10m自动压缩保留时长auto-compaction-modeperiodicperiodic压缩模式periodic 按时间revision 按版本heartbeat-interval100ms100msleader 向 follower 发心跳的间隔election-timeout1000ms1000ms选举超时必须是 heartbeat 的 5-10 倍snapshot-count100000100000触发快照的日志条数max-request-bytes1.5MB1.5MB单个请求最大字节数grpc-keepalive-min-time5s5sgRPC 最小 keepalive 时间这张表里的参数不要随意改。heartbeat-interval和election-timeout如果调小对网络抖动更敏感调大则故障切换变慢。snapshot-count调小会增加快照频率增加磁盘 IO调大则 WAL 日志增长快恢复时间长。max-request-bytes如果调大单个请求占用内存更多可能触发 OOM。5. etcd 集群避坑排查5 个血泪教训5.1 NOSPACE 告警后集群只读现象Kubernetes 创建资源失败etcd 日志出现etcdserver: mvcc: database space exceededendpoint status显示DB SIZE接近配额上限集群进入只读模式。原因quota-backend-bytes设得太小或者没有开启自动压缩历史版本堆积导致数据库膨胀。etcd 在超过配额后会触发 NOSPACE 告警并拒绝所有写入请求只允许读取和删除。解决先压缩到最新 revision然后对每个节点执行 defrag 释放空间最后用etcdctl alarm disarm解除告警。具体命令# 查看当前告警 etcdctl --endpoints$ENDPOINTS alarm list # 压缩到最新 revision REV$(etcdctl --endpoints$ENDPOINTS endpoint status --write-outjson | grep -o revision:[0-9]* | head -1 | cut -d: -f2) etcdctl --endpoints$ENDPOINTS compact $REV # 逐个节点 defrag etcdctl --endpointshttp://10.0.0.1:2379 defrag etcdctl --endpointshttp://10.0.0.2:2379 defrag etcdctl --endpointshttp://10.0.0.3:2379 defrag # 解除告警 etcdctl --endpoints$ENDPOINTS alarm disarm事后要把quota-backend-bytes调大并开启auto-compaction-retention。5.2 leader 频繁切换现象endpoint status里RAFT TERM不断增大日志里频繁出现leadership changed客户端写入超时。原因通常是网络延迟或磁盘 IO 延迟导致 follower 来不及响应 heartbeat。也可能是某个节点 CPU 被其他进程占满etcd 进程被调度延迟。解决先检查节点间网络 RTT用ping和traceroute确认没有跨机房。然后检查磁盘 fsync 延迟用iostat -x 1看%util和await。如果磁盘是瓶颈换 SSD。如果 CPU 被占满给 etcd 进程设置 CPU 亲和性或提高优先级。另外检查heartbeat-interval和election-timeout是否被改过恢复默认值。5.3 watch 断连后 ErrCompacted现象客户端 watch 报etcdserver: mvcc: required revision has been compacted无法继续接收事件。原因客户端断连后从旧 revision 重新 watch但那个 revision 已经被压缩掉了。压缩是定期执行的如果客户端断连时间超过压缩窗口就会遇到这个问题。解决客户端在 watch 失败后不要直接用旧 revision 重试而是先做一次全量 get 获取当前最新 revision然后从最新 revision 开始 watch。同时把auto-compaction-retention设长一些给客户端留出重连窗口。在 Kubernetes 场景下client-go 已经处理了这个逻辑但自研客户端要注意。5.4 节点重启后无法加入集群现象某个节点重启后etcd 进程起不来日志报etcdserver: member ... has been removed from the cluster或cannot fetch cluster information from peer。原因节点重启时如果initial-cluster-state还是newetcd 会尝试重新初始化集群但集群已经存在导致冲突。或者节点被误删出集群member list 里已经没有它。解决对于已加入集群的节点initial-cluster-state应该设为existing。如果节点被删除了需要先用member add重新加入然后更新配置。注意member add会返回新的initial-cluster配置要把它更新到所有节点的配置文件里。5.5 数据目录权限问题现象etcd 启动失败日志报cannot access data directory: mkdir /var/lib/etcd: permission denied。原因systemd 服务默认以 root 运行但如果配置了Useretcd而/var/lib/etcd目录的属主不是 etcd 用户就会权限不足。解决创建 etcd 用户和组把数据目录属主改成 etcd并在 systemd 里指定Useretcd和Groupetcd。命令如下useradd -r -s /sbin/nologin etcd mkdir -p /var/lib/etcd chown -R etcd:etcd /var/lib/etcd chmod 700 /var/lib/etcd然后在 systemd 的[Service]段加上Useretcd和Groupetcd。6. 用 etcd 自带工具做健康巡检与快照恢复etcd 自带了一个etcdutl工具v3.5 之后从 etcdctl 里拆出来的可以做快照备份和恢复。生产环境一定要配置定期快照否则数据损坏时没有后悔药。# 创建快照 etcdutl snapshot save /backup/etcd-snapshot-$(date %Y%m%d%H%M).db \ --endpointshttp://10.0.0.1:2379 # 查看快照状态 etcdutl snapshot status /backup/etcd-snapshot-202401011200.db --write-outtable # 恢复快照到新数据目录注意恢复时要停掉 etcd 进程 etcdutl snapshot restore /backup/etcd-snapshot-202401011200.db \ --data-dir/var/lib/etcd-restore \ --nameetcd-1 \ --initial-clusteretcd-1http://10.0.0.1:2380,etcd-2http://10.0.0.2:2380,etcd-3http://10.0.0.3:2380 \ --initial-advertise-peer-urlshttp://10.0.0.1:2380快照恢复的逻辑是从快照文件里读出一个新的数据目录这个目录里的成员信息和集群配置是快照时刻的状态。恢复后要把 etcd 的>#!/bin/bash # etcd 日常巡检脚本 ENDPOINTShttp://10.0.0.1:2379,http://10.0.0.2:2379,http://10.0.0.3:2379 export ETCDCTL_API3 # 健康检查 etcdctl --endpoints$ENDPOINTS endpoint health # 告警检查 ALARMS$(etcdctl --endpoints$ENDPOINTS alarm list) if [ -n $ALARMS ]; then echo WARNING: etcd alarms detected: $ALARMS fi # DB SIZE 检查 etcdctl --endpoints$ENDPOINTS endpoint status --write-outtable这个脚本可以放到 cron 里每天跑一次输出重定向到日志文件。如果健康检查有 unhealthy 或者有告警就触发通知。最后说一个我自己的习惯每次升级 etcd 版本之前一定先做一次快照然后在测试环境用同样的数据量跑一遍恢复流程。etcd 的版本升级不像普通软件那样无脑替换二进制就行跨小版本升级一般没问题但跨大版本比如 v3.4 到 v3.5需要先确认 API 兼容性。v3.5.12 作为补丁版本升级风险较低但仍然建议先快照再操作。希望帮到你。本文还有配套的精品资源点击获取