简介《etcd实战及其原理分析》PDF面向分布式系统、云原生开发与运维人员围绕etcd v3.5构建从部署实操到核心原理的知识框架适合需要掌握服务发现、分布式锁、主备选举等场景的中高级读者。包内为1个PDF文件约4.55MB内容按“介绍—实战—原理”组织先说明etcd的定位、应用场景、与ZooKeeper的差异及分层架构再覆盖单实例、单机多实例、多节点集群搭建etcdctl常用命令与用户、角色、权限管理最后深入读请求与写请求执行流程、Raft的Leader选举、日志复制与安全性以及MVCC的treeIndex、更新、查询和删除机制。已有450人学习适合用来对照搭建实验环境、梳理面试考点或排查一致性、watch、租约与压缩等问题形成可落地的分布式协调组件认知。1. 三节点只有一台能运行一次端口冲突的教训去年帮一个做配置中心的团队搭测试环境对方拿来一个 etcd v3.5.5 的 tar 包说照着以前留下的笔记跑一下就行。解压、./etcd一把启动put username fox也能写进去看起来一切正常。可等到把三份 local-cluster-profile 写好、用 goreman 拉起来member list里只剩一个 member另外两个节点的日志反复只显示一行bind: address already in use。真正的问题出在端口规划没有提前处理并非 etcd 本身有问题——三个实例的--listen-peer-urls都写了 2380。这类事故在单机多实例或者小集群里非常常见。etcd 的 2379 端口负责客户端请求2380 端口负责节点之间的 Raft 通信只要这两个端口没有区分开再正确的参数也无法启动集群。而且它不会主动提示你“端口写重了”只会安静地少一个节点直到你member list时才发现异常。这套环境适合三类人本地要复现服务发现和分布式锁的后端开发、要给 K8s 之外的系统接一套一致性 KV 的运维以及只想把 etcd 原理读明白之前先亲手跑一遍的人。下面按“环境定版 → 单机跑通 → 集群搭起来 → 坏了怎么救 → 怎么验收”的顺序写每一步都有可以照抄的命令。2. 装前定版etcd v3.5 的二进制包、端口与数据目录etcd 的安装方式看起来非常简单解压一个压缩包就能用没有依赖也不需要编译。真正导致问题的是版本、端口和目录这三件事。如果安装之前不先把它们定下来后面安装、重启、扩容的每一步都要返工。2.1 v3.5.5 的包怎么选别拿错架构etcd 官方在 releases 页面提供编译好的二进制压缩包Linux 下常用的文件名形如etcd-v3.5.5-linux-amd64.tar.gz。这个包解压出来是三个可执行文件etcd、etcdctl、etcdutl。前两个是服务端和命令行客户端第三个是 v3.5 才从etcdctl里拆出来的运维工具专门用于快照备份和恢复。版本上有两个取舍要先说清。第一尽量不采用发行版软件源里的包。很多系统源里还是 3.3 或 3.4这些版本与 v3.5 在命令行为上有差异最典型的是快照命令3.5 里etcdctl snapshot save已经不再作为主入口统一移到etcdutl snapshot save。旧脚本迁移过来会直接报错新手很容易误以为包坏了。第二集群内的版本要尽量保持一致滚动升级也只能一台一台来不要出现一半 3.4、一半 3.5 的情况。还有一条经常被忽略的版本差异etcdctl在 3.4 之前默认使用 v2 API必须export ETCDCTL_API3才能读到 v3 写入的 key。3.5 默认已经是 v3所以如果你照着三四年前的笔记操作put成功之后get却返回空先不要怀疑数据丢了——八成是那份笔记里的环境变量和历史版本对不上。# 下载 v3.5.5 的 Linux amd64 二进制包 wget https://github.com/etcd-io/etcd/releases/download/v3.5.5/etcd-v3.5.5-linux-amd64.tar.gz # 解压并进入目录 tar -zxvf etcd-v3.5.5-linux-amd64.tar.gz cd etcd-v3.5.5-linux-amd64/ # 确认三个二进制都在版本号一致 ./etcd --version ./etcdctl version ./etcdutl version这段命令没有技术含量但建议把后面三行--version当作硬性动作执行。etcd --version输出里除了版本号还会带Git SHA和Go Version排查“明明换了包版本却没变”时这行输出比ls -l有用得多。三条版本号不一致说明你的PATH里还残留着旧版本后面的所有验证都不可信。2.2 端口、数据目录、运行账号先划清etcd 的默认端口是 2379 和 2380。2379 给客户端2380 给集群内部通信。单机单实例时这两个端口都够用一旦同一台机器上跑多个实例就必须成对地错开比如 12379/12380、22379/22380、32379/32380。这个对应关系一旦定下来后面所有配置文件都照着这个表来不要临时改。用途单实例默认多实例示例说明客户端监听237912379 / 22379 / 32379etcdctl、业务客户端连这里集群通信238012380 / 22380 / 32380节点之间复制日志、选主数据目录当前目录下${name}.etcd/data/etcd生产必须固定绝对路径日志文件无默认/var/log/etcd/etcd.log重定向或交给 systemd数据目录这里有一个容易忽略的问题etcd 不指定--data-dir时默认在当前工作目录下建一个以节点名命名的目录。这意味着你用cd /tmp启动一次、用cd /root再启动一次看到的就会是两套完全不同的数据。生产环境的常见做法是固定/var/lib/etcd或/data/etcd并且在启动命令或者 unit 文件里写死。运行账号也有讲究。不建议用 root 直接启动虽然能跑但数据目录的权限会被 root 独占后面想换成普通用户就得多绕几步。常见做法是先建一个专用账号把数据目录先 chown 过去再启动。# 建专用运行账号与目录生产环境建议 useradd -r -s /sbin/nologin etcd mkdir -p /data/etcd /var/log/etcd chown -R etcd:etcd /data/etcd /var/log/etcd # 定好端口归属检查有没有别的进程占着 ss -lntp | grep -E 2379|2380ss -lntp这一步建议在安装前做一次在每次启动失败时也做一次。它同时在听的进程一眼就能看到比翻日志快。很多人以为address already in use是因为 etcd 自己没退干净实际上往往是另一个测试实例还挂着。2.3 磁盘与文件句柄两个不显眼但会致命的前置条件etcd 所有写请求都要落 WAL 并 fsync对磁盘延迟极其敏感。磁盘慢不会让 etcd 直接报错而是表现为etcdserver: request timed out、心跳超时、频繁重新选主日志里看不出直接原因很容易让人找不到方向。测试环境用机械盘勉强能跑一旦压测或者节点多了问题就会冒出来。# 看一眼数据目录所在磁盘确认不是机械盘或网络盘 df -h /data/etcd lsblk -d -o NAME,ROTA # 临时放开文件句柄限制正式环境写进 /etc/security/limits.conf ulimit -n 65536lsblk输出里的ROTA列1 表示旋转盘机械0 表示 SSD。这个字段不绝对准但作为第一眼判断够用。文件句柄方面etcd 每个 watch 连接都要占资源句柄数太少时watch 会莫名断开客户端只能重连表现成“监听到了但偶尔丢事件”。ulimit -n只在当前 shell 生效生产环境要落到 limits.conf 或者 systemd 的LimitNOFILE。3. 单实例跑通etcd v3.5.5 部署与 etcdctl 常用命令实操单实例是整套环境的基础。它不只是“能启动”还要把读写、租约、权限三件事都成功执行一遍后面上集群时才知道每一步的预期是什么。3.1 解压启动与后台化最简启动就是解压后直接./etcd。前台跑能直观看到日志输出适合第一次确认端口监听和数据库路径。等确认没问题再用 nohup 或者 systemd 托管到后台。# 前台启动观察日志中的 listen 地址和># 设置或更新键值 etcdctl --endpointslocalhost:2379 put username fox # 读取指定键 etcdctl --endpointslocalhost:2379 get username # 半开区间读取左闭右开 etcdctl get /test/name /test/name3 # 按前缀读取并用 --limit 限制返回条数 etcdctl get --prefix /test --limit 3 # 按字典序从某个 key 开始读 etcdctl get --from-key name2 # 读取历史版本第 8 个全局 revision etcdctl get --rev8 /test/name # 以 JSON 输出便于看 revision 等元数据 etcdctl get username -wjson # 删除并带回被删除的值 etcdctl del --prev-kv username--endpoints这个参数在单实例时可以省略默认连 127.0.0.1:2379但建议一直显式写。上集群时它就是一个列表客户端会按轮询方式选择节点节点挂了自动换下一个。等到那时再补这个参数前面练的命令都得改。真正需要理解的是-wjson返回的那几个字段。revision是集群全局版本号任何一次 put 或 delete 都会让它加一create_revision是这条 key 创建时的全局版本mod_revision是最后一次修改的全局版本version是这条 key 自己被修改了多少次创建时为 1删除后重建又从 1 开始。这四个数字分不清MVCC 那块原理就只能死记硬背。raft_term是当前主节点的任期排查“是不是刚发生过选主”时看这个值有没有跳。3.3 watch 与 lease服务发现的两块基础watch 用于监听键值变化lease 用于给键设置存活期。这两个机制组合起来就是 etcd 做服务发现的标准做法服务启动时申请一个租约、把自己的地址写进去并绑定租约定期续约下线或崩溃后租约到期键自动消失调用方 watch 这个前缀实时感知上下线。# 终端 A监听某个 key 的变化 etcdctl watch /test/name # 终端 B修改这个 key终端 A 会立即输出新值 etcdctl put /test/name fox2 # 授予 30 秒的租约返回租约 ID etcdctl lease grant 30 # 把 key 绑定到租约上 etcdctl put --lease705b8474d1acd63b name fox # 保持租约存活前台持续续约 etcdctl lease keep-alive 705b8474d1acd63b # 查询租约剩余时间及关联的 key etcdctl lease timetolive --keys 705b8474d1acd63b # 主动撤销租约关联的 key 会被一并删除 etcdctl lease revoke 705b8474d1acd63blease grant返回的那串十六进制就是租约 ID后面put --lease和keep-alive都要用它建议先记下来。timetolive --keys是最实用的检查命令它一次告诉你租约还剩多久、绑了哪些键。服务发现调不通时先看这条租约已过期但键还在说明续约线程挂了键不在了但服务还活着说明注册逻辑根本没跑。watch的行为和 ZooKeeper 的临时节点、单次触发 watch 不一样它是持续的一次连接能收到后续所有变更。这个差异在迁移旧系统时容易出问题——按 ZooKeeper 的思维写完 watch 就不管了结果事件越积越多。3.4 权限管理user、role 与 auth enable 的顺序etcd 的权限模型是三级用户、角色、权限。用户绑角色角色绑 key 范围的读写权限。真正容易出错的是开启顺序。# 第一步必须先创建 root 用户 etcdctl user add root # 第二步root 存在之后才能开启认证 etcdctl auth enable # 第三步之后所有命令都要带上 root 凭据 etcdctl --userroot --password123456 user add fox etcdctl --userroot --password123456 role add test etcdctl --userroot --password123456 user grant-role fox test # 给角色赋权范围是 /name 的读写 etcdctl --userroot --password123456 role grant-permission test readwrite /name # 用普通用户访问只能操作被授权的范围 etcdctl --userfox --password123456 get /name顺序错了会把自己锁在外面先auth enable而没有 root 用户命令会失败root 用户建了但密码忘了就只能停服务、走--force-new-cluster那条恢复路径。我一般会在开启认证之前先把 root 密码写在密码管理器里并且立刻验证一次etcdctl --userroot --password... get /能通再继续后面的操作。role grant-permission的范围参数支持前缀匹配写/name时只对这一个键生效要覆盖整个目录得写/name/或者配合前缀语义。这个细节不弄清配完权限发现业务读不到自己的 key会以为是认证模块坏了。4. 起集群goreman 单机多实例与三节点静态、动态发现部署单实例验证完下一步是把多节点跑起来。本地用 goreman 模拟三节点最省事生产则用三台机器做静态配置或者动态发现。这两条路径的启动参数高度重合把参数吃透一次两边都能用。4.1 goreman 安装与 local-cluster-profile 写法goreman 是一个用 Go 写的进程管理工具读取一个 profile 文件按行启动多个进程还能单独停启某一个。它依赖 Go 环境装之前先确认go version有输出。# 安装 goreman需要本地有 Go 环境 go install github.com/mattn/goremanlatest # 确认可执行文件在 GOPATH/bin 下并加入 PATH ls $(go env GOPATH)/bin/goreman export PATH$PATH:$(go env GOPATH)/bin goreman helpprofile 文件的格式是每行一个进程写成进程名: 启动命令。注意每行必须是一条完整的命令goreman 不认反斜杠续行参数多的时候只能写成一长行。这也是很多人从别处复制配置过来后启动失败的原因——复制时被编辑器自动折行了。# local-cluster-profile三个实例端口成对错开 etcd1: etcd --name infra1 --listen-client-urls http://127.0.0.1:12379 --advertise-client-urls http://127.0.0.1:12379 --listen-peer-urls http://127.0.0.1:12380 --initial-advertise-peer-urls http://127.0.0.1:12380 --initial-cluster-token etcd-cluster-1 --initial-cluster infra1http://127.0.0.1:12380,infra2http://127.0.0.1:22380,infra3http://127.0.0.1:32380 --initial-cluster-state new etcd2: etcd --name infra2 --listen-client-urls http://127.0.0.1:22379 --advertise-client-urls http://127.0.0.1:22379 --listen-peer-urls http://127.0.0.1:22380 --initial-advertise-peer-urls http://127.0.0.1:22380 --initial-cluster-token etcd-cluster-1 --initial-cluster infra1http://127.0.0.1:12380,infra2http://127.0.0.1:22380,infra3http://127.0.0.1:32380 --initial-cluster-state new etcd3: etcd --name infra3 --listen-client-urls http://127.0.0.1:32379 --advertise-client-urls http://127.0.0.1:32379 --listen-peer-urls http://127.0.0.1:32380 --initial-advertise-peer-urls http://127.0.0.1:32380 --initial-cluster-token etcd-cluster-1 --initial-cluster infra1http://127.0.0.1:12380,infra2http://127.0.0.1:22380,infra3http://127.0.0.1:32380 --initial-cluster-state new三行配置里唯一的差别是--name和四个端口。--initial-cluster那一长串在三个实例里必须一模一样写错了就会变成“各自以为自己在一个集群里”。--initial-cluster-token是用来区分集群的同一台机器上要起多套集群时靠它隔离测试环境随便写生产环境建议用有意义的固定值。4.2 关键启动参数一条条拆etcd 的启动参数有几十个真正决定集群能不能组起来的就下面这几个。把它们记住比背文档有用。参数作用常见写错的地方--name本节点在集群中的名字与--initial-cluster里的名字不一致--initial-cluster集群所有成员的名字与 peer 地址列表某个节点的 peer 地址写成本机的 client 端口--initial-cluster-statenew表示新建集群existing表示加入已有集群重启时仍然写new--listen-client-urls本机监听的客户端地址只写 127.0.0.1外部连不进来--advertise-client-urls告诉客户端该用哪个地址访问自己与 listen 不一致导致客户端连到错误地址--listen-peer-urls节点之间通信的监听地址多实例全写 2380端口冲突--initial-advertise-peer-urls告诉其他节点该用哪个地址访问自己与--initial-cluster中的地址对不上--initial-cluster-state是最容易被复制粘贴带错的一个。首次引导必须写new集群已经建好、节点重启时应该写existing。如果数据目录已经有数据但参数里还写着newetcd 会尝试按全新集群引导轻则报错退出重则和其他节点握手失败日志里是一堆etcdserver: cluster ID mismatch。--listen-client-urls和--advertise-client-urls的关系也值得单独说一句前者是“我在这几个地址上接收请求”后者是“别人应该用哪个地址来找我”。单机测试时两个写一样没问题生产环境如果有多块网卡listen 可以同时写127.0.0.1和内网 IPadvertise 只写内网 IP。监听不代表通告这两个概念混用集群里会出现客户端连到回环地址的经典故障。4.3 生产三节点静态配置静态配置适用于节点数量已知、IP 已知的线下环境。三台机器的名字和地址在下表里固定下来之后所有命令都照这个来。节点名IPinfra0192.168.65.206infra1192.168.65.209infra2192.168.65.210# 在 192.168.65.206 上启动 infra0 etcd --name infra0 \ --data-dir /data/etcd \ --listen-client-urls http://192.168.65.206:2379,http://127.0.0.1:2379 \ --advertise-client-urls http://192.168.65.206:2379 \ --listen-peer-urls http://192.168.65.206:2380 \ --initial-advertise-peer-urls http://192.168.65.206:2380 \ --initial-cluster-token etcd-cluster-1 \ --initial-cluster infra0http://192.168.65.206:2380,infra1http://192.168.65.209:2380,infra2http://192.168.65.210:2380 \ --initial-cluster-state new另外两台只需要替换--name、IP 和端口--initial-cluster那一行原封不动。三台同时起或者逐台起都行只要--initial-cluster一致它们会自己完成选主。# 任意一台执行确认三个 member 都在且状态正常 etcdctl --endpoints192.168.65.206:2379 member list # 检查集群健康度 etcdctl --endpoints192.168.65.206:2379,192.168.65.209:2379,192.168.65.210:2379 endpoint healthmember list输出的STARTED列是判断关键三个都是 true 才算集群真正组建完成。如果有节点显示 false先看那台的日志九成是 peer 地址不通或者名字写错。这一步之前防火墙的 2379、2380 要放行三台机器的时钟要同步时间漂移大了会出现“选主来回切”的怪现象。4.4 动态发现一次性令牌与它的边界节点 IP 不固定的场景比如云上按需扩容用静态配置很别扭这时可以用已有的 etcd 服务做引导。官方提供一个 discovery 服务先申请一个令牌各节点带着同一个令牌启动就能互相发现。# 申请一个 size3 的发现令牌返回一串 URL curl https://discovery.etcd.io/new?size3 # 三台机器都用同一个令牌启动其余参数按本机实际情况写 etcd --name etcd1 --data-dir /data/etcd \ --initial-advertise-peer-urls http://192.168.65.206:2380 \ --listen-peer-urls http://192.168.65.206:2380 \ --listen-client-urls http://192.168.65.206:2379,http://127.0.0.1:2379 \ --advertise-client-urls http://192.168.65.206:2379 \ --discovery https://discovery.etcd.io/ef89922e093e9d5ff5ae5c8ec481f4e3这个令牌有两个硬性边界。第一一个令牌只能引导一个集群用过一次就作废哪怕中途失败也不能拿来重建。第二发现协议只在引导阶段生效不能用于运行时的成员变更加节点、删节点得走member add、member remove。把发现服务当成动态扩缩容手段是很多教程里容易误导人的地方。还有一条经验每个成员的--name必须不同。名字重复时发现服务直接把这次引导判为失败日志里写的是重复名称但很多人会误以为是令牌失效。5. 装坏了怎么救etcd 启动失败与集群异常的排查清单etcd 的报错普遍比较克制很多故障在日志里只有一两行剩下的全靠推理。下面五条是我这几年反复遇到的按“现象 → 原因 → 解决”记下来出问题时对着翻。5.1 只有自己一个 member其他节点起不来现象member list只返回一台另外两台的日志反复出现bind: address already in use或者进程直接退出。原因单机多实例时三个 profile 的--listen-peer-urls都写了 2380。etcd 不会因为端口冲突而智能地切换只会 bind 失败然后退出。另一种常见变体是--listen-client-urls撞了 2379表现是客户端连不上服务端日志里有监听失败。解决先把端口分配表列出来一个实例一行client 和 peer 成对错开12379/12380、22379/22380、32379/32380。启动前用ss -lntp | grep -E 2379|2380|12379|12380扫一遍确认没有残留进程。前一次没退干净的 etcd 是最大的干扰源pkill -f etcd之后再起。5.2 重启后数据“没了”现象服务能正常启动get之前写过的 key 返回空member list里节点名也变了。原因启动命令里没写--data-dir。etcd 默认在当前工作目录下建一个${name}.etcd目录换了工作目录就等于换了一套数据。这个行为在测试机上特别容易触发因为大家习惯在不同目录下敲./etcd。解决所有启动命令统一加--data-dir /data/etcd这种绝对路径systemd unit 里也写死。已经“丢”了的数据不是真的丢了去旧工作目录下找.etcd目录把member/snap和member/wal拷到新目录再启动就能恢复。从那以后我养成一个习惯看到--data-dir没写就把命令拦下来。5.3 开启认证后所有命令都报权限错误现象auth enable之后etcdctl get报etcdserver: user name is empty加--user又报authentication failed。原因两种可能。一是auth enable之前没建 root 用户认证开了但没有任何账号能通过等于把自己锁在门外二是密码在 shell 历史里被转义坏了比如!或者特殊字符没加引号。解决如果已经锁死停掉服务用--force-new-cluster单节点恢复一次重建 root 用户后再启动整个集群。预防办法是固定顺序先user add root、立即验证一次带凭据的get、再auth enable。另外把密码统一加单引号别让 shell 去解释。提示--force-new-cluster会以当前节点数据重建单节点集群适合用来恢复访问权限但不要在有其他节点在线时随意使用。5.4 集群健康但写入偶发超时现象endpoint health全部 healthy业务侧偶尔报etcdserver: request timed out压测时更明显日志里还有slow read或者成功了但延迟很高。原因磁盘 fsync 慢是头号嫌疑。etcd 每次写都要确保 WAL 落盘机械盘或者共享存储上延迟会上下波动。第二个原因是后端数据库接近配额上限默认--quota-backend-bytes是 2GB写满之后所有写请求直接返回etcdserver: mvcc: database space exceeded。解决先df和lsblk确认数据目录在 SSD 上把数据目录从网络盘挪到本地盘。再看配额etcdctl endpoint status -wjson里的dbSize和dbSizeInUse能看出实际占用确实接近上限就做一次compact加defrag。defrag 会阻塞该节点要一台一台做别三台同时来。5.5 节点日志刷cluster ID mismatch现象某个节点启动后反复重连日志里是etcdserver: cluster ID mismatch或者couldnt find local name in the initial cluster configuration。原因前者通常是这台机器上残留了旧集群的数据目录集群 ID 对不上后者是--name的取值和--initial-cluster里的名字不匹配比如节点叫infra1配置里写的是etcd1。解决先把--name和--initial-cluster里的字符串逐字比对包括大小写和连字符。确认无误仍报 cluster ID mismatch就是数据目录的问题——这个节点要么清空数据目录重新加入仅限无数据的新节点要么从健康节点做快照恢复。清空数据目录是破坏性操作动手前先确认这个节点上没有独有数据。6. 验证跑通三项检查加一次故障演练装完之后最怕的是“看起来能用”。etcd 尤其如此单节点读写正常不代表集群没问题集群健康也不代表故障切换能成立。我一般用三项检查收尾加一次人为故障演练。检查项命令通过标准成员完整性etcdctl member list -wtable三台都在STARTED全为 true端点健康etcdctl endpoint health --cluster每条都返回 healthy读写一致性写一台、读另外两台读到的值和 revision 一致# 一次性把三项都跑一遍 etcdctl --endpoints192.168.65.206:2379,192.168.65.209:2379,192.168.65.210:2379 member list -wtable etcdctl --endpoints192.168.65.206:2379,192.168.65.209:2379,192.168.65.210:2379 endpoint health --cluster # 向 206 写从 209 读确认数据同步 etcdctl --endpoints192.168.65.206:2379 put /verify/key hello etcdctl --endpoints192.168.65.209:2379 get /verify/key -wjson读回来的 JSON 里revision应该是写完之后的值mod_revision与它相同。如果两台读到的 revision 差一说明有一个节点还没应用完日志属于正常的一瞬间延迟等几秒再看如果一直不追平那就是那个节点的 apply 卡住了。最后一步是故障演练很多人跳过但它才是真正能证明集群可用的动作停掉 leader看剩下两台能不能在十几秒内选出新主读写是否恢复。# 找到当前 leaderendpoint status 输出里的 leader 字段 etcdctl --endpoints192.168.65.206:2379,192.168.65.209:2379,192.168.65.210:2379 endpoint status -wtable # 停掉 leader 所在的那台然后持续读观察恢复时间 etcdctl --endpoints192.168.65.209:2379,192.168.65.210:2379 get /verify/key etcdctl --endpoints192.168.65.209:2379,192.168.65.210:2379 endpoint status -wtable-wtable的输出里会多出RAFT TERM和RAFT INDEX两列。停掉 leader 之后RAFT TERM应该加一新 leader 的IS LEADER变成 true。三节点集群的情况下停一台还剩两台仍能满足仲裁人数读写正常。如果你把这个演练做成停两台那集群就该拒绝写入了——这不是 bug是 etcd 在保护一致性正好可以顺手验证一下预期行为。从那以后我每次搭完 etcd都强制走一遍“member list → endpoint health → 跨节点读写 → 停 leader”这四个动作一个都不跳。看起来是多花五分钟实际省下的是上线之后半夜被叫起来排查选主的时间。装环境这件事能跑通和能扛住故障中间差的就是这几步。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/11/2 17:39:50 · 阅读 1.2k etcd v3.5.5集群部署实战：端口冲突排查与三节点健康验证
简介《etcd实战及其原理分析》PDF面向分布式系统、云原生开发与运维人员围绕etcd v3.5构建从部署实操到核心原理的知识框架适合需要掌握服务发现、分布式锁、主备选举等场景的中高级读者。包内为1个PDF文件约4.55MB内容按“介绍—实战—原理”组织先说明etcd的定位、应用场景、与ZooKeeper的差异及分层架构再覆盖单实例、单机多实例、多节点集群搭建etcdctl常用命令与用户、角色、权限管理最后深入读请求与写请求执行流程、Raft的Leader选举、日志复制与安全性以及MVCC的treeIndex、更新、查询和删除机制。已有450人学习适合用来对照搭建实验环境、梳理面试考点或排查一致性、watch、租约与压缩等问题形成可落地的分布式协调组件认知。1. 三节点只有一台能运行一次端口冲突的教训去年帮一个做配置中心的团队搭测试环境对方拿来一个 etcd v3.5.5 的 tar 包说照着以前留下的笔记跑一下就行。解压、./etcd一把启动put username fox也能写进去看起来一切正常。可等到把三份 local-cluster-profile 写好、用 goreman 拉起来member list里只剩一个 member另外两个节点的日志反复只显示一行bind: address already in use。真正的问题出在端口规划没有提前处理并非 etcd 本身有问题——三个实例的--listen-peer-urls都写了 2380。这类事故在单机多实例或者小集群里非常常见。etcd 的 2379 端口负责客户端请求2380 端口负责节点之间的 Raft 通信只要这两个端口没有区分开再正确的参数也无法启动集群。而且它不会主动提示你“端口写重了”只会安静地少一个节点直到你member list时才发现异常。这套环境适合三类人本地要复现服务发现和分布式锁的后端开发、要给 K8s 之外的系统接一套一致性 KV 的运维以及只想把 etcd 原理读明白之前先亲手跑一遍的人。下面按“环境定版 → 单机跑通 → 集群搭起来 → 坏了怎么救 → 怎么验收”的顺序写每一步都有可以照抄的命令。2. 装前定版etcd v3.5 的二进制包、端口与数据目录etcd 的安装方式看起来非常简单解压一个压缩包就能用没有依赖也不需要编译。真正导致问题的是版本、端口和目录这三件事。如果安装之前不先把它们定下来后面安装、重启、扩容的每一步都要返工。2.1 v3.5.5 的包怎么选别拿错架构etcd 官方在 releases 页面提供编译好的二进制压缩包Linux 下常用的文件名形如etcd-v3.5.5-linux-amd64.tar.gz。这个包解压出来是三个可执行文件etcd、etcdctl、etcdutl。前两个是服务端和命令行客户端第三个是 v3.5 才从etcdctl里拆出来的运维工具专门用于快照备份和恢复。版本上有两个取舍要先说清。第一尽量不采用发行版软件源里的包。很多系统源里还是 3.3 或 3.4这些版本与 v3.5 在命令行为上有差异最典型的是快照命令3.5 里etcdctl snapshot save已经不再作为主入口统一移到etcdutl snapshot save。旧脚本迁移过来会直接报错新手很容易误以为包坏了。第二集群内的版本要尽量保持一致滚动升级也只能一台一台来不要出现一半 3.4、一半 3.5 的情况。还有一条经常被忽略的版本差异etcdctl在 3.4 之前默认使用 v2 API必须export ETCDCTL_API3才能读到 v3 写入的 key。3.5 默认已经是 v3所以如果你照着三四年前的笔记操作put成功之后get却返回空先不要怀疑数据丢了——八成是那份笔记里的环境变量和历史版本对不上。# 下载 v3.5.5 的 Linux amd64 二进制包 wget https://github.com/etcd-io/etcd/releases/download/v3.5.5/etcd-v3.5.5-linux-amd64.tar.gz # 解压并进入目录 tar -zxvf etcd-v3.5.5-linux-amd64.tar.gz cd etcd-v3.5.5-linux-amd64/ # 确认三个二进制都在版本号一致 ./etcd --version ./etcdctl version ./etcdutl version这段命令没有技术含量但建议把后面三行--version当作硬性动作执行。etcd --version输出里除了版本号还会带Git SHA和Go Version排查“明明换了包版本却没变”时这行输出比ls -l有用得多。三条版本号不一致说明你的PATH里还残留着旧版本后面的所有验证都不可信。2.2 端口、数据目录、运行账号先划清etcd 的默认端口是 2379 和 2380。2379 给客户端2380 给集群内部通信。单机单实例时这两个端口都够用一旦同一台机器上跑多个实例就必须成对地错开比如 12379/12380、22379/22380、32379/32380。这个对应关系一旦定下来后面所有配置文件都照着这个表来不要临时改。用途单实例默认多实例示例说明客户端监听237912379 / 22379 / 32379etcdctl、业务客户端连这里集群通信238012380 / 22380 / 32380节点之间复制日志、选主数据目录当前目录下${name}.etcd/data/etcd生产必须固定绝对路径日志文件无默认/var/log/etcd/etcd.log重定向或交给 systemd数据目录这里有一个容易忽略的问题etcd 不指定--data-dir时默认在当前工作目录下建一个以节点名命名的目录。这意味着你用cd /tmp启动一次、用cd /root再启动一次看到的就会是两套完全不同的数据。生产环境的常见做法是固定/var/lib/etcd或/data/etcd并且在启动命令或者 unit 文件里写死。运行账号也有讲究。不建议用 root 直接启动虽然能跑但数据目录的权限会被 root 独占后面想换成普通用户就得多绕几步。常见做法是先建一个专用账号把数据目录先 chown 过去再启动。# 建专用运行账号与目录生产环境建议 useradd -r -s /sbin/nologin etcd mkdir -p /data/etcd /var/log/etcd chown -R etcd:etcd /data/etcd /var/log/etcd # 定好端口归属检查有没有别的进程占着 ss -lntp | grep -E 2379|2380ss -lntp这一步建议在安装前做一次在每次启动失败时也做一次。它同时在听的进程一眼就能看到比翻日志快。很多人以为address already in use是因为 etcd 自己没退干净实际上往往是另一个测试实例还挂着。2.3 磁盘与文件句柄两个不显眼但会致命的前置条件etcd 所有写请求都要落 WAL 并 fsync对磁盘延迟极其敏感。磁盘慢不会让 etcd 直接报错而是表现为etcdserver: request timed out、心跳超时、频繁重新选主日志里看不出直接原因很容易让人找不到方向。测试环境用机械盘勉强能跑一旦压测或者节点多了问题就会冒出来。# 看一眼数据目录所在磁盘确认不是机械盘或网络盘 df -h /data/etcd lsblk -d -o NAME,ROTA # 临时放开文件句柄限制正式环境写进 /etc/security/limits.conf ulimit -n 65536lsblk输出里的ROTA列1 表示旋转盘机械0 表示 SSD。这个字段不绝对准但作为第一眼判断够用。文件句柄方面etcd 每个 watch 连接都要占资源句柄数太少时watch 会莫名断开客户端只能重连表现成“监听到了但偶尔丢事件”。ulimit -n只在当前 shell 生效生产环境要落到 limits.conf 或者 systemd 的LimitNOFILE。3. 单实例跑通etcd v3.5.5 部署与 etcdctl 常用命令实操单实例是整套环境的基础。它不只是“能启动”还要把读写、租约、权限三件事都成功执行一遍后面上集群时才知道每一步的预期是什么。3.1 解压启动与后台化最简启动就是解压后直接./etcd。前台跑能直观看到日志输出适合第一次确认端口监听和数据库路径。等确认没问题再用 nohup 或者 systemd 托管到后台。# 前台启动观察日志中的 listen 地址和># 设置或更新键值 etcdctl --endpointslocalhost:2379 put username fox # 读取指定键 etcdctl --endpointslocalhost:2379 get username # 半开区间读取左闭右开 etcdctl get /test/name /test/name3 # 按前缀读取并用 --limit 限制返回条数 etcdctl get --prefix /test --limit 3 # 按字典序从某个 key 开始读 etcdctl get --from-key name2 # 读取历史版本第 8 个全局 revision etcdctl get --rev8 /test/name # 以 JSON 输出便于看 revision 等元数据 etcdctl get username -wjson # 删除并带回被删除的值 etcdctl del --prev-kv username--endpoints这个参数在单实例时可以省略默认连 127.0.0.1:2379但建议一直显式写。上集群时它就是一个列表客户端会按轮询方式选择节点节点挂了自动换下一个。等到那时再补这个参数前面练的命令都得改。真正需要理解的是-wjson返回的那几个字段。revision是集群全局版本号任何一次 put 或 delete 都会让它加一create_revision是这条 key 创建时的全局版本mod_revision是最后一次修改的全局版本version是这条 key 自己被修改了多少次创建时为 1删除后重建又从 1 开始。这四个数字分不清MVCC 那块原理就只能死记硬背。raft_term是当前主节点的任期排查“是不是刚发生过选主”时看这个值有没有跳。3.3 watch 与 lease服务发现的两块基础watch 用于监听键值变化lease 用于给键设置存活期。这两个机制组合起来就是 etcd 做服务发现的标准做法服务启动时申请一个租约、把自己的地址写进去并绑定租约定期续约下线或崩溃后租约到期键自动消失调用方 watch 这个前缀实时感知上下线。# 终端 A监听某个 key 的变化 etcdctl watch /test/name # 终端 B修改这个 key终端 A 会立即输出新值 etcdctl put /test/name fox2 # 授予 30 秒的租约返回租约 ID etcdctl lease grant 30 # 把 key 绑定到租约上 etcdctl put --lease705b8474d1acd63b name fox # 保持租约存活前台持续续约 etcdctl lease keep-alive 705b8474d1acd63b # 查询租约剩余时间及关联的 key etcdctl lease timetolive --keys 705b8474d1acd63b # 主动撤销租约关联的 key 会被一并删除 etcdctl lease revoke 705b8474d1acd63blease grant返回的那串十六进制就是租约 ID后面put --lease和keep-alive都要用它建议先记下来。timetolive --keys是最实用的检查命令它一次告诉你租约还剩多久、绑了哪些键。服务发现调不通时先看这条租约已过期但键还在说明续约线程挂了键不在了但服务还活着说明注册逻辑根本没跑。watch的行为和 ZooKeeper 的临时节点、单次触发 watch 不一样它是持续的一次连接能收到后续所有变更。这个差异在迁移旧系统时容易出问题——按 ZooKeeper 的思维写完 watch 就不管了结果事件越积越多。3.4 权限管理user、role 与 auth enable 的顺序etcd 的权限模型是三级用户、角色、权限。用户绑角色角色绑 key 范围的读写权限。真正容易出错的是开启顺序。# 第一步必须先创建 root 用户 etcdctl user add root # 第二步root 存在之后才能开启认证 etcdctl auth enable # 第三步之后所有命令都要带上 root 凭据 etcdctl --userroot --password123456 user add fox etcdctl --userroot --password123456 role add test etcdctl --userroot --password123456 user grant-role fox test # 给角色赋权范围是 /name 的读写 etcdctl --userroot --password123456 role grant-permission test readwrite /name # 用普通用户访问只能操作被授权的范围 etcdctl --userfox --password123456 get /name顺序错了会把自己锁在外面先auth enable而没有 root 用户命令会失败root 用户建了但密码忘了就只能停服务、走--force-new-cluster那条恢复路径。我一般会在开启认证之前先把 root 密码写在密码管理器里并且立刻验证一次etcdctl --userroot --password... get /能通再继续后面的操作。role grant-permission的范围参数支持前缀匹配写/name时只对这一个键生效要覆盖整个目录得写/name/或者配合前缀语义。这个细节不弄清配完权限发现业务读不到自己的 key会以为是认证模块坏了。4. 起集群goreman 单机多实例与三节点静态、动态发现部署单实例验证完下一步是把多节点跑起来。本地用 goreman 模拟三节点最省事生产则用三台机器做静态配置或者动态发现。这两条路径的启动参数高度重合把参数吃透一次两边都能用。4.1 goreman 安装与 local-cluster-profile 写法goreman 是一个用 Go 写的进程管理工具读取一个 profile 文件按行启动多个进程还能单独停启某一个。它依赖 Go 环境装之前先确认go version有输出。# 安装 goreman需要本地有 Go 环境 go install github.com/mattn/goremanlatest # 确认可执行文件在 GOPATH/bin 下并加入 PATH ls $(go env GOPATH)/bin/goreman export PATH$PATH:$(go env GOPATH)/bin goreman helpprofile 文件的格式是每行一个进程写成进程名: 启动命令。注意每行必须是一条完整的命令goreman 不认反斜杠续行参数多的时候只能写成一长行。这也是很多人从别处复制配置过来后启动失败的原因——复制时被编辑器自动折行了。# local-cluster-profile三个实例端口成对错开 etcd1: etcd --name infra1 --listen-client-urls http://127.0.0.1:12379 --advertise-client-urls http://127.0.0.1:12379 --listen-peer-urls http://127.0.0.1:12380 --initial-advertise-peer-urls http://127.0.0.1:12380 --initial-cluster-token etcd-cluster-1 --initial-cluster infra1http://127.0.0.1:12380,infra2http://127.0.0.1:22380,infra3http://127.0.0.1:32380 --initial-cluster-state new etcd2: etcd --name infra2 --listen-client-urls http://127.0.0.1:22379 --advertise-client-urls http://127.0.0.1:22379 --listen-peer-urls http://127.0.0.1:22380 --initial-advertise-peer-urls http://127.0.0.1:22380 --initial-cluster-token etcd-cluster-1 --initial-cluster infra1http://127.0.0.1:12380,infra2http://127.0.0.1:22380,infra3http://127.0.0.1:32380 --initial-cluster-state new etcd3: etcd --name infra3 --listen-client-urls http://127.0.0.1:32379 --advertise-client-urls http://127.0.0.1:32379 --listen-peer-urls http://127.0.0.1:32380 --initial-advertise-peer-urls http://127.0.0.1:32380 --initial-cluster-token etcd-cluster-1 --initial-cluster infra1http://127.0.0.1:12380,infra2http://127.0.0.1:22380,infra3http://127.0.0.1:32380 --initial-cluster-state new三行配置里唯一的差别是--name和四个端口。--initial-cluster那一长串在三个实例里必须一模一样写错了就会变成“各自以为自己在一个集群里”。--initial-cluster-token是用来区分集群的同一台机器上要起多套集群时靠它隔离测试环境随便写生产环境建议用有意义的固定值。4.2 关键启动参数一条条拆etcd 的启动参数有几十个真正决定集群能不能组起来的就下面这几个。把它们记住比背文档有用。参数作用常见写错的地方--name本节点在集群中的名字与--initial-cluster里的名字不一致--initial-cluster集群所有成员的名字与 peer 地址列表某个节点的 peer 地址写成本机的 client 端口--initial-cluster-statenew表示新建集群existing表示加入已有集群重启时仍然写new--listen-client-urls本机监听的客户端地址只写 127.0.0.1外部连不进来--advertise-client-urls告诉客户端该用哪个地址访问自己与 listen 不一致导致客户端连到错误地址--listen-peer-urls节点之间通信的监听地址多实例全写 2380端口冲突--initial-advertise-peer-urls告诉其他节点该用哪个地址访问自己与--initial-cluster中的地址对不上--initial-cluster-state是最容易被复制粘贴带错的一个。首次引导必须写new集群已经建好、节点重启时应该写existing。如果数据目录已经有数据但参数里还写着newetcd 会尝试按全新集群引导轻则报错退出重则和其他节点握手失败日志里是一堆etcdserver: cluster ID mismatch。--listen-client-urls和--advertise-client-urls的关系也值得单独说一句前者是“我在这几个地址上接收请求”后者是“别人应该用哪个地址来找我”。单机测试时两个写一样没问题生产环境如果有多块网卡listen 可以同时写127.0.0.1和内网 IPadvertise 只写内网 IP。监听不代表通告这两个概念混用集群里会出现客户端连到回环地址的经典故障。4.3 生产三节点静态配置静态配置适用于节点数量已知、IP 已知的线下环境。三台机器的名字和地址在下表里固定下来之后所有命令都照这个来。节点名IPinfra0192.168.65.206infra1192.168.65.209infra2192.168.65.210# 在 192.168.65.206 上启动 infra0 etcd --name infra0 \ --data-dir /data/etcd \ --listen-client-urls http://192.168.65.206:2379,http://127.0.0.1:2379 \ --advertise-client-urls http://192.168.65.206:2379 \ --listen-peer-urls http://192.168.65.206:2380 \ --initial-advertise-peer-urls http://192.168.65.206:2380 \ --initial-cluster-token etcd-cluster-1 \ --initial-cluster infra0http://192.168.65.206:2380,infra1http://192.168.65.209:2380,infra2http://192.168.65.210:2380 \ --initial-cluster-state new另外两台只需要替换--name、IP 和端口--initial-cluster那一行原封不动。三台同时起或者逐台起都行只要--initial-cluster一致它们会自己完成选主。# 任意一台执行确认三个 member 都在且状态正常 etcdctl --endpoints192.168.65.206:2379 member list # 检查集群健康度 etcdctl --endpoints192.168.65.206:2379,192.168.65.209:2379,192.168.65.210:2379 endpoint healthmember list输出的STARTED列是判断关键三个都是 true 才算集群真正组建完成。如果有节点显示 false先看那台的日志九成是 peer 地址不通或者名字写错。这一步之前防火墙的 2379、2380 要放行三台机器的时钟要同步时间漂移大了会出现“选主来回切”的怪现象。4.4 动态发现一次性令牌与它的边界节点 IP 不固定的场景比如云上按需扩容用静态配置很别扭这时可以用已有的 etcd 服务做引导。官方提供一个 discovery 服务先申请一个令牌各节点带着同一个令牌启动就能互相发现。# 申请一个 size3 的发现令牌返回一串 URL curl https://discovery.etcd.io/new?size3 # 三台机器都用同一个令牌启动其余参数按本机实际情况写 etcd --name etcd1 --data-dir /data/etcd \ --initial-advertise-peer-urls http://192.168.65.206:2380 \ --listen-peer-urls http://192.168.65.206:2380 \ --listen-client-urls http://192.168.65.206:2379,http://127.0.0.1:2379 \ --advertise-client-urls http://192.168.65.206:2379 \ --discovery https://discovery.etcd.io/ef89922e093e9d5ff5ae5c8ec481f4e3这个令牌有两个硬性边界。第一一个令牌只能引导一个集群用过一次就作废哪怕中途失败也不能拿来重建。第二发现协议只在引导阶段生效不能用于运行时的成员变更加节点、删节点得走member add、member remove。把发现服务当成动态扩缩容手段是很多教程里容易误导人的地方。还有一条经验每个成员的--name必须不同。名字重复时发现服务直接把这次引导判为失败日志里写的是重复名称但很多人会误以为是令牌失效。5. 装坏了怎么救etcd 启动失败与集群异常的排查清单etcd 的报错普遍比较克制很多故障在日志里只有一两行剩下的全靠推理。下面五条是我这几年反复遇到的按“现象 → 原因 → 解决”记下来出问题时对着翻。5.1 只有自己一个 member其他节点起不来现象member list只返回一台另外两台的日志反复出现bind: address already in use或者进程直接退出。原因单机多实例时三个 profile 的--listen-peer-urls都写了 2380。etcd 不会因为端口冲突而智能地切换只会 bind 失败然后退出。另一种常见变体是--listen-client-urls撞了 2379表现是客户端连不上服务端日志里有监听失败。解决先把端口分配表列出来一个实例一行client 和 peer 成对错开12379/12380、22379/22380、32379/32380。启动前用ss -lntp | grep -E 2379|2380|12379|12380扫一遍确认没有残留进程。前一次没退干净的 etcd 是最大的干扰源pkill -f etcd之后再起。5.2 重启后数据“没了”现象服务能正常启动get之前写过的 key 返回空member list里节点名也变了。原因启动命令里没写--data-dir。etcd 默认在当前工作目录下建一个${name}.etcd目录换了工作目录就等于换了一套数据。这个行为在测试机上特别容易触发因为大家习惯在不同目录下敲./etcd。解决所有启动命令统一加--data-dir /data/etcd这种绝对路径systemd unit 里也写死。已经“丢”了的数据不是真的丢了去旧工作目录下找.etcd目录把member/snap和member/wal拷到新目录再启动就能恢复。从那以后我养成一个习惯看到--data-dir没写就把命令拦下来。5.3 开启认证后所有命令都报权限错误现象auth enable之后etcdctl get报etcdserver: user name is empty加--user又报authentication failed。原因两种可能。一是auth enable之前没建 root 用户认证开了但没有任何账号能通过等于把自己锁在门外二是密码在 shell 历史里被转义坏了比如!或者特殊字符没加引号。解决如果已经锁死停掉服务用--force-new-cluster单节点恢复一次重建 root 用户后再启动整个集群。预防办法是固定顺序先user add root、立即验证一次带凭据的get、再auth enable。另外把密码统一加单引号别让 shell 去解释。提示--force-new-cluster会以当前节点数据重建单节点集群适合用来恢复访问权限但不要在有其他节点在线时随意使用。5.4 集群健康但写入偶发超时现象endpoint health全部 healthy业务侧偶尔报etcdserver: request timed out压测时更明显日志里还有slow read或者成功了但延迟很高。原因磁盘 fsync 慢是头号嫌疑。etcd 每次写都要确保 WAL 落盘机械盘或者共享存储上延迟会上下波动。第二个原因是后端数据库接近配额上限默认--quota-backend-bytes是 2GB写满之后所有写请求直接返回etcdserver: mvcc: database space exceeded。解决先df和lsblk确认数据目录在 SSD 上把数据目录从网络盘挪到本地盘。再看配额etcdctl endpoint status -wjson里的dbSize和dbSizeInUse能看出实际占用确实接近上限就做一次compact加defrag。defrag 会阻塞该节点要一台一台做别三台同时来。5.5 节点日志刷cluster ID mismatch现象某个节点启动后反复重连日志里是etcdserver: cluster ID mismatch或者couldnt find local name in the initial cluster configuration。原因前者通常是这台机器上残留了旧集群的数据目录集群 ID 对不上后者是--name的取值和--initial-cluster里的名字不匹配比如节点叫infra1配置里写的是etcd1。解决先把--name和--initial-cluster里的字符串逐字比对包括大小写和连字符。确认无误仍报 cluster ID mismatch就是数据目录的问题——这个节点要么清空数据目录重新加入仅限无数据的新节点要么从健康节点做快照恢复。清空数据目录是破坏性操作动手前先确认这个节点上没有独有数据。6. 验证跑通三项检查加一次故障演练装完之后最怕的是“看起来能用”。etcd 尤其如此单节点读写正常不代表集群没问题集群健康也不代表故障切换能成立。我一般用三项检查收尾加一次人为故障演练。检查项命令通过标准成员完整性etcdctl member list -wtable三台都在STARTED全为 true端点健康etcdctl endpoint health --cluster每条都返回 healthy读写一致性写一台、读另外两台读到的值和 revision 一致# 一次性把三项都跑一遍 etcdctl --endpoints192.168.65.206:2379,192.168.65.209:2379,192.168.65.210:2379 member list -wtable etcdctl --endpoints192.168.65.206:2379,192.168.65.209:2379,192.168.65.210:2379 endpoint health --cluster # 向 206 写从 209 读确认数据同步 etcdctl --endpoints192.168.65.206:2379 put /verify/key hello etcdctl --endpoints192.168.65.209:2379 get /verify/key -wjson读回来的 JSON 里revision应该是写完之后的值mod_revision与它相同。如果两台读到的 revision 差一说明有一个节点还没应用完日志属于正常的一瞬间延迟等几秒再看如果一直不追平那就是那个节点的 apply 卡住了。最后一步是故障演练很多人跳过但它才是真正能证明集群可用的动作停掉 leader看剩下两台能不能在十几秒内选出新主读写是否恢复。# 找到当前 leaderendpoint status 输出里的 leader 字段 etcdctl --endpoints192.168.65.206:2379,192.168.65.209:2379,192.168.65.210:2379 endpoint status -wtable # 停掉 leader 所在的那台然后持续读观察恢复时间 etcdctl --endpoints192.168.65.209:2379,192.168.65.210:2379 get /verify/key etcdctl --endpoints192.168.65.209:2379,192.168.65.210:2379 endpoint status -wtable-wtable的输出里会多出RAFT TERM和RAFT INDEX两列。停掉 leader 之后RAFT TERM应该加一新 leader 的IS LEADER变成 true。三节点集群的情况下停一台还剩两台仍能满足仲裁人数读写正常。如果你把这个演练做成停两台那集群就该拒绝写入了——这不是 bug是 etcd 在保护一致性正好可以顺手验证一下预期行为。从那以后我每次搭完 etcd都强制走一遍“member list → endpoint health → 跨节点读写 → 停 leader”这四个动作一个都不跳。看起来是多花五分钟实际省下的是上线之后半夜被叫起来排查选主的时间。装环境这件事能跑通和能扛住故障中间差的就是这几步。希望帮到你。本文还有配套的精品资源点击获取