Docker Compose搭建etcd集群：参数详解、健康检查与故障演练实战

如果你跟我一样，过去习惯用裸进程或者脚本去拉 etcd 集群，第一次看到完整的三节点配置时一定会觉得有点乱：每个节点要同时处理 name、IP、客户端端口和节点间通信端口，还有一串看起来像“身份证号”的 initial-cluster 参数。这篇文章就围绕 docker-compose 搭建 etcd 集群这件事，把我最近的完整实操过程梳理一遍，包含可以直接复制的 compose 文件、每个启动参数背后的作用、启动后的健康检查、故障演练，以及平时不容易查到的排查经验。适合刚接触 etcd、打算把单点改成集群的朋友，也适合已经搭过但还没彻底弄懂参数细节的运维同路人。

1. 项目拆解：etcd 集群到底在解决什么问题

1.1 单点部署是所有事故的源头

很多团队最先接触 etcd，都是因为某个配置中心、服务注册表或者分布式锁需要一致性存储。开发环境里跑一个单节点，看起来没什么问题，等流量上来或者机器重启一下就露馅了。

单节点 etcd 意味着没有副本，数据只有一份。磁盘故障、误删数据目录、机器无法启动，任何一个意外都可能导致配置数据永久丢失。更麻烦的是，raft 算法需要多数派才能完成日志提交，单节点虽然自身可以工作，但没有“容错”可言：它不是受保护的状态，而是全量风险。

所以搭建集群的第一个动机，就是把“一个节点挂了全部不可用”变成“两个节点挂了我还在线”。etcd 的复制模型是 raft，三节点集群最多容忍一台机器故障，五节点集群最多容忍两台。这也是为什么更多人愿意在 etcd 上多花几个节点数，而不是单点裸奔。

1.2 为什么选择 docker-compose 而不是裸机或 k8s

裸机部署 etcd 并不难，下载二进制、写 systemd 单元、启动三个进程，但真正麻烦的是后续维护：日志轮转、进程守护、多节点环境差异、网络地址变更，这些都得自己处理。docker-compose 把这些配套问题打包成一份 YAML，数据卷、网络、健康检查、重启策略都能声明式管理，对中小规模集群和本地开发环境非常友好。

在另一头，Kubernetes 自带 etcd 管理能力，但如果你的业务只用 etcd 做配置中心或分布式锁，完全不值得为此引入整套容器编排平台。docker-compose 的定位刚好卡在中间：比裸脚本更规范，比 k8s 更轻量。尤其是本地起三节点验证 raft 行为、测试客户端故障切换时，一条命令就能完成整个环境的搭建和销毁，性价比非常高。

1.3 环境和前置条件

我建议使用较新的 Docker Compose v2，也就是docker compose子命令。老版本的docker-compose也能运行，但在命令写法上有细微差别。Docker 引擎建议 20.10 以上，避免旧版本在网络自定义方面的一些已知问题。

理论上，三节点可以全部跑在一台宿主机上，通过容器内固定 IP 模拟三个独立节点。这只适合学习验证，不适合生产。生产环境尽量让每个 etcd 节点落在不同宿主机，否则一台物理机挂掉，三个容器同时消失，集群照样瘫痪。后面演示基于单台宿主机做三容器集群，方便你复现。

2. 动手之前：集群拓扑与关键参数设计

2.1 选几个节点：奇偶数的真相

有人会觉得四节点比三节点多一个，应该更稳。实际上从 raft 的容错公式看，四节点的多数派是 3，和五节点的多数派也是 3，但四节点和五节点容错的节点数不一样？这里容易记错，让我直接说结论：一个 N 节点 etcd 集群，最多容忍(N-1)/2向下取整的节点故障。三节点容忍 1 个，四节点也是容忍 1 个，五节点才升到 2 个。

所以说，四节点集群比三节点多花一份资源，容错能力却没有提升，反而增加边缘网络和成员管理的复杂度。这就是 etcd 集群推荐 3、5、7 这种奇数的原因。三节点是绝大多数业务的最佳起点，对配置中心来说足够；五节点通常给关键基础设施或需要跨可用区场景使用，七节点以上很少见。

2.2 静态发现 vs 动态发现

etcd 集群节点互相发现的机制有静态配置和 DNS 动态发现两类。静态配置就是在启动参数里把三个节点的地址和名字写死，例如etcd1=http://172.20.0.11:2380...。这种方式的优势很直接：所有成员都清晰可见，配置即事实，任何节点启动时都知道应该联系谁。

DNS 动态发现则依赖 SRV 记录，节点变化时只需要调整 DNS，不需要挨个改配置。听起来优雅，但坑也更多：DNS 缓存策略、解析顺序、服务记录格式，一旦排查起来非常绕。对于 docker-compose 管理的固定节点，静态配置完全是更好的选择。只有当你做动态扩缩容平台、节点频繁上下线时，才值得认真考虑 discovery 方案。

2.3 端口和网段规划

etcd 有两个重要端口：2379 是客户端端口，面向业务服务；2380 是 peer 端口，用于节点间 raft 通信和心跳。部署集群前要先规划网段，我下面统一用 172.20.0.0/24 示例网段，三个节点分别取 11、12、13。

宿主机端口映射也需要提前定。容器间通过自定义网络内的固定 IP 通信，所以 peer 端口 2380 不一定暴露到宿主机。客户端端口 2379 一般需要暴露给应用，三个节点可以分别映射成宿主机 23791、23792、23793。如果你只有一套应用需要访问 etcd，甚至可以只映射第一个节点的 2379，但为了故障切换方便，建议三个节点的客户端端口都暴露出来，客户端配置里写三个地址做负载。

下面是这次部署的地址规划：

3. 完整配置与参数逐个拆解

3.1 一个可以直接使用的 docker-compose.yml

我使用的 etcd 镜像来自公共镜像仓库的官方发布版本，版本号锁定为 v3.5.4。如果你在部署时发现版本较旧，可以换成同系列更新的 patch 版本，但三个节点最好保持一致。

version: "3.9" services: etcd1: image: quay.io/coreos/etcd:v3.5.4 container_name: etcd1 hostname: etcd1 restart: unless-stopped networks: etcd-net: ipv4_address: 172.20.0.11 ports: - "23791:2379" command: - etcd - --name=etcd1 - --data-dir=/etcd-data - --listen-client-urls=http://0.0.0.0:2379 - --listen-peer-urls=http://0.0.0.0:2380 - --advertise-client-urls=http://172.20.0.11:2379 - --initial-advertise-peer-urls=http://172.20.0.11:2380 - --initial-cluster=etcd1=http://172.20.0.11:2380,etcd2=http://172.20.0.12:2380,etcd3=http://172.20.0.13:2380 - --initial-cluster-state=new - --initial-cluster-token=etcd-cluster-01 - --logger=zap - --log-level=info volumes: - etcd1_data:/etcd-data healthcheck: test: ["CMD", "etcdctl", "endpoint", "health", "--endpoints=http://127.0.0.1:2379"] interval: 30s timeout: 10s retries: 5 start_period: 20s etcd2: image: quay.io/coreos/etcd:v3.5.4 container_name: etcd2 hostname: etcd2 restart: unless-stopped networks: etcd-net: ipv4_address: 172.20.0.12 ports: - "23792:2379" command: - etcd - --name=etcd2 - --data-dir=/etcd-data - --listen-client-urls=http://0.0.0.0:2379 - --listen-peer-urls=http://0.0.0.0:2380 - --advertise-client-urls=http://172.20.0.12:2379 - --initial-advertise-peer-urls=http://172.20.0.12:2380 - --initial-cluster=etcd1=http://172.20.0.11:2380,etcd2=http://172.20.0.12:2380,etcd3=http://172.20.0.13:2380 - --initial-cluster-state=new - --initial-cluster-token=etcd-cluster-01 - --logger=zap - --log-level=info volumes: - etcd2_data:/etcd-data healthcheck: test: ["CMD", "etcdctl", "endpoint", "health", "--endpoints=http://127.0.0.1:2379"] interval: 30s timeout: 10s retries: 5 start_period: 20s etcd3: image: quay.io/coreos/etcd:v3.5.4 container_name: etcd3 hostname: etcd3 restart: unless-stopped networks: etcd-net: ipv4_address: 172.20.0.13 ports: - "23793:2379" command: - etcd - --name=etcd3 - --data-dir=/etcd-data - --listen-client-urls=http://0.0.0.0:2379 - --listen-peer-urls=http://0.0.0.0:2380 - --advertise-client-urls=http://172.20.0.13:2379 - --initial-advertise-peer-urls=http://172.20.0.13:2380 - --initial-cluster=etcd1=http://172.20.0.11:2380,etcd2=http://172.20.0.12:2380,etcd3=http://172.20.0.13:2380 - --initial-cluster-state=new - --initial-cluster-token=etcd-cluster-01 - --logger=zap - --log-level=info volumes: - etcd3_data:/etcd-data healthcheck: test: ["CMD", "etcdctl", "endpoint", "health", "--endpoints=http://127.0.0.1:2379"] interval: 30s timeout: 10s retries: 5 start_period: 20s volumes: etcd1_data: etcd2_data: etcd3_data: networks: etcd-net: ipam: driver: default config: - subnet: 172.20.0.0/24

这个文件省去了很多人的重复劳动，但直接抄之前，你需要理解一件事：为什么每个节点都要重复写一遍完整的 initial-cluster。因为 etcd 启动时，节点本身并不知道集群里有多少成员，它只能从自己拿到的配置列表里发现其他节点。三份配置内容相同，但每个节点的 announce 地址不同，这样任何一个节点先启动，它都会去尝试联系另外两个地址，等待多数派出现后选主。

3.2 每个启动参数都在干什么

先从最容易误解的--listen-*和--advertise-*说起。listen是进程监听在哪个地址，容器里一般写0.0.0.0，表示容器内所有网卡都提供服务。advertise是告诉其他节点和客户端“你来访问我时用哪个地址”，这个必须写成实际可达地址，不能写0.0.0.0。

以 etcd2 为例，容器内固定 IP 是 172.20.0.12，所以--advertise-client-urls=http://172.20.0.12:2379。如果你错误地写成http://etcd2:2379，依赖 DNS 解析，虽然容器名在 compose 网络里可解析，但容易引入不确定因素。直接写固定 IP 最稳。

--initial-cluster-state=new表示这是一次全新创建。如果后面某个节点数据目录崩溃、需要重新加入旧集群，就要用existing模式，否则新旧集群 ID 对不上会产生冲突。

--initial-cluster-token相当于给这个集群打了一个唯一标签，所有节点必须一致。它的作用是防止某个节点误加入一个数据集不同但地址相同的集群。恢复集群、跨环境迁移时，这个 token 也要跟着走。

--logger=zap是我强烈建议开启的。etcd 默认日志是 capnslog，字段格式和可读性远不如 zap，排查问题时不方便。换成 zap 后会输出结构化 JSON 日志，日志里能直接看到 raft term、节点 ID、提案信息等。

3.3 数据卷隐藏的坑

每个节点背后的数据卷，我特意用了 named volume 而不是 bind mount。原因很直接：etcd 容器内部的进程往往以非 root 用户运行，bind mount 宿主机目录时经常遇到目录权限不匹配的问题，表现为permission denied或者failed to lock file。named volume 由 Docker 管理，初始权限能自动与容器镜像期望对齐，踩坑概率低很多。

不过 named volume 也有麻烦：数据卷不直观，备份时要通过docker cp或者卷快照工具导出。我的习惯是日常测试无所谓，跑起来就行；如果是最小化生产环境，还是用 bind mount 并在宿主机手动调整目录属主，保证可审计性。

还有一点必须强调：etcd 数据目录不要放在 Docker 容器层。容器重建后数据丢失，这谁都懂，但真正容易忽略的是 Docker 默认的 storage driver 写性能和 fsync 开销。etcd 对磁盘延迟敏感，留给它一个独立数据卷，别和其他日志文件混在同一个 volume。

4. 实操记录：启动、验证、故障演练

4.1 启动集群与健康检查

配置文件准备好后，先在同一目录执行：

docker compose up -d docker compose ps

第一次启动时，三个容器会同时进入启动流程。日志里可能出现某些节点短暂地“联系不到其他成员”，这是正常的，etcd 启动时会带有重试逻辑，等多数派出现后自动收敛。我习惯先等十秒左右，再看一次健康状态：

docker compose exec etcd1 sh -c "etcdctl member list --write-out=table" docker compose exec etcd1 sh -c "etcdctl endpoint health --cluster --write-out=table"

如果看到三行healthy，集群已经进入正常状态。这里要注意，member list只能看到成员信息，不代表 leader 已经选好；endpoint health --cluster才是真正逐个检查可用性的命令。有一个很容易踩的坑：直接在新版镜像里跑etcdctl，可能因为环境变量ETCDCTL_API未设置而进入 v2 模式，只要你有任何输出异常，可以先显式指定：

docker compose exec etcd1 sh -c "ETCDCTL_API=3 etcdctl endpoint health --cluster"

4.2 写入读取验证

集群健康不代表读写链路正常，我习惯做一次最小验证：

docker compose exec etcd1 sh -c "etcdctl put /demo hello" docker compose exec etcd2 sh -c "etcdctl get /demo"

如果从 etcd2 能读到 etcd1 写入的值，说明 raft 日志同步、提交和本地 apply 都在正常工作。这个环节我见过太多人跳过，结果等真正接入应用时才发现客户端配置里少了某个地址或者证书没配对。

4.3 故障演练：停掉一个节点

三节点集群的核心价值是容忍单节点故障，所以一定要亲自做一次故障演练。模拟故障最简单的方式是：

docker compose stop etcd2

现在集群还剩 etcd1 和 etcd3，它们仍然能组成多数派。再执行：

docker compose exec etcd1 sh -c "etcdctl endpoint health --cluster --write-out=table"

你会看到 etcd2 显示unreachable，但 as long as 另外两个端点是 healthy，集群依然可读可写。这就是 raft 的多数派机制在起作用。实际业务客户端如果配了三个地址，遇到 etcd2 不可达时会自动转而请求其他节点。

恢复节点同样直接：

docker compose start etcd2 docker compose exec etcd2 sh -c "etcdctl endpoint health --cluster --write-out=table"

etcd2 重新加入后，会主动从 leader 那里追赶日志，最终回到 healthy 状态。这个过程不需要人工干预，也不用改配置，前提是 etcd2 的数据目录还保留着原来的数据。如果你把数据目录删空再恢复，就会变成一个新节点，反而需要用 member add 的方式加回集群。

4.4 如果必须扩容，怎么做

虽然静态配置模式下的扩容有点绕，但方法并不复杂。核心步骤是：先通过etcdctl member add把新节点注册进现有集群，再去启动新容器。

假设要加 etcd4，先执行：

docker compose exec etcd1 sh -c "etcdctl member add etcd4 --peer-urls=http://172.20.0.14:2380"

命令会返回一段提示，告诉你新节点需要使用的启动参数。之后在 compose 文件里新增 etcd4 服务，注意initial-cluster要包含所有四个节点的地址，并且--initial-cluster-state=existing，因为是对已有集群做成员变更，不是重新初始化。

启动新节点后，用etcdctl member list确认 leader 跟上、日志追上。缩容则相反：先etcdctl member remove <node-id>，再从 compose 里移除对应服务并停止容器。顺序乱掉会出问题，反过来操作可能导致旧节点重新连接僵尸成员。

4.5 备份、恢复和灾难演练

再稳的集群也可能遇到双节点同时故障。三节点集群一次损失两个节点，就无法形成多数派，此时理论上是“不可用但数据未丢”，恢复也很麻烦。提前做备份就显得特别重要。

备份用 etcd 自带的 snapshot 功能：

docker compose exec etcd1 sh -c "etcdctl snapshot save /etcd-data/snapshot.db" docker cp etcd1:/etcd-data/snapshot.db ./etcd-snapshot.db

snapshot 保存的是某一时刻的完整数据快照。恢复演练时，最好在一套干净的目录里进行：

etcdctl snapshot restore ./etcd-snapshot.db \ --name etcd-restored \ --data-dir /tmp/etcd-restored \ --initial-cluster etcd-restored=http://127.0.0.1:2380 \ --initial-cluster-token restored-cluster

然后启动一个单节点验证数据，确认后再考虑是否接入原集群。这里有一个我踩过的坑：恢复的新节点和旧成员会持有完全不同的集群 ID，如果直接把恢复节点混入原集群，会看到各种成员冲突和日志报错。正确思路是恢复出来的节点先自己单独运行，验证无误后，通过 member add 的方式重新把其他节点拉进来，或者直接把原集群所有数据目录清理掉，用恢复节点作为唯一起点重建。

5. 常见问题与排查技巧

5.1 问题速查表

下面这张表可以贴在运维手册里，遇到问题先按行对号入座。

5.2 时间不同步带来的麻烦

etcd 的 raft 选举对节点间时钟差非常敏感么？准确说，raft 本身不要求强时钟同步，但网络延迟和时钟偏移会让心跳超时和选举超时乱掉。常见症状是日志里频繁出现 leader 切换、请求超时，严重时客户端会拿到不一致的状态。

容器通常继承宿主机的时钟，所以主要保证宿主机 NTP 正常。一次部署前我遇到两个节点时间差了十几秒，结果集群一直选不出稳定的 leader，每次请求都要等超时。配置好 NTP 后问题立刻消失。现在我做任何集群前都会先跑一条命令确认所有节点时间误差在 100ms 以内。

5.3 节点起不来的三块绊脚石

第一块是数据目录残留。如果你之前用initial-cluster-state=new启动过集群，后来觉得不对想重新初始化，但没清空容器数据卷，就会出现成员ID冲突。解决办法是清除对应节点的数据目录，让它以一个“全新节点”的身份加入。

第二块是端口没放行。容器内互访一般没问题，但从宿主机或外部访问时，2380 和 2379 都要在防火墙和安全组放行。特别要注意，如果容器是在云主机上，安全组规则和宿主机防火墙是两个独立层次，只改一处不会生效。

第三块是镜像版本不一致。三个节点如果分别用了 3.4 和 3.5，有可能在协议细节上有差异，导致一个节点始终无法追日志。同一集群严格锁定相同版本，升级时先升级 follower 再滚动到 leader，避免跨大版本。

5.4 生产环境必须养成的几个习惯

第一，不要把 2379 直接暴露到公网。etcd 默认没有任何加密认证，裸奔就意味着任何人可以读取甚至覆盖数据。要么限制网络访问，要么启用 TLS，两者都要做。

第二，开启监控。etcd 暴露的/metrics接口可以接到监控系统，重点看etcd_server_has_leader、etcd_server_leader_changes_seen_total和etcd_server_proposals_failed_total这几个指标。磁盘 IO 和内存也要盯，etcd 对资源抖动非常敏感。

第三，变更之前先备份。无论是改成员、升级版本还是会话参数，都先把 snapshot 保存下来。etcd 不像普通数据库可以直接复制数据目录，最简单可靠的兜底就是 snapshot。

6. 最后分享一点个人经验

搭建 docker-compose 版的 etcd 集群，真正的难点不是敲命令，而是理解集群行为。我在做迁移演练时反复验证过同一件事：节点宕机后的自动恢复不是魔法，而是多数派、日志复制、心跳超时这些机制协同工作的结果。只有亲手停掉一个节点、观察日志、确认读写仍正常，再把它恢复回来，才能真正理解 etcd 为什么说自己是“为可靠而设计”。

建议你拿到这份 compose 文件后，别急着投进生产，先在本地把故障演练完整走几遍，特别是停节点、恢复、加成员、备份恢复这四个动作。我开始也会觉得这些动作多余，直到一次真的遇到双节点同时离线，脑子里没有预案的时候，才意识到演练的价值。多踩几次坑，你对 etcd 的信任感和掌控感会完全不一样。