etcd集群搭建教程：三节点高可用部署与验证

知识分享

2026-10-11 19:40

8 阅读

etcd 是 Kubernetes 等分布式系统的关键组件，用来保存集群的所有配置和状态数据。
如果你正准备搭建一个高可用的 etcd 集群，这篇教程会从零开始，用三台服务器完成一套可用的 etcd 集群部署，并给出验证和排错方法。

准备三台机器和基础环境

etcd 集群通常使用奇数个节点，3 节点是最小的高可用生产规格。
你需要准备三台可以互相通过内网通信的 Linux 服务器，推荐使用 CentOS 7/8 或 Ubuntu 20.04 以上版本。

假设三台机器的 IP 和主机名如下：

192.168.1.101 etcd-1
192.168.1.102 etcd-2
192.168.1.103 etcd-3

开始前先确认几件事：

所有机器时间同步，可用 chrony 或 ntpd 保证时间一致。
关闭防火墙或放行 etcd 使用的端口：2379（客户端通信）和 2380（节点间通信）。
如果开启了 SELinux，建议临时设为宽容模式或正确配置策略，避免权限问题。
为每台机器配置好主机名和 hosts 解析，方便后续使用域名。

随后从 etcd 官方 GitHub Release 页面下载对应架构的二进制包，例如 etcd-v3.5.x-linux-amd64.tar.gz。
解压后将 etcd 和 etcdctl 两个可执行文件复制到 /usr/local/bin/。

tar -zxvf etcd-v3.5.*-linux-amd64.tar.gz
cd etcd-v3.5.*-linux-amd64
sudo cp etcd etcdctl /usr/local/bin/

执行 etcd --version 和 etcdctl version 能正常输出版本号，说明二进制已就绪。

生成 TLS 证书（可选但推荐）

生产环境建议启用 TLS 加密通信。
如果你只是在测试环境快速验证，可以跳过证书部分，直接使用 HTTP 启动集群。
下面给出使用 cfssl 生成自签名证书的简要步骤。

首先安装 cfssl 工具，然后创建 CA 配置文件 ca-config.json：

{
  "signing": {
    "default": { "expiry": "87600h" },
    "profiles": {
      "etcd": {
        "usages": ["signing", "key encipherment", "server auth", "client auth"],
        "expiry": "87600h"
      }
    }
  }
}

创建 CA 证书签名请求 ca-csr.json：

{
  "CN": "etcd-ca",
  "key": { "algo": "rsa", "size": 2048 },
  "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "etcd", "OU": "etcd" }]
}

生成 CA 证书：

cfssl gencert -initca ca-csr.json | cfssljson -bare ca

然后为每台 etcd 节点生成证书，注意 hosts 字段要包含该节点的 IP 和主机名。
以 etcd-1 为例，创建 etcd-1-csr.json：

{
  "CN": "etcd-1",
  "hosts": ["192.168.1.101", "etcd-1", "127.0.0.1", "localhost"],
  "key": { "algo": "rsa", "size": 2048 },
  "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "etcd", "OU": "etcd" }]
}

使用 CA 签发证书：

cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=etcd etcd-1-csr.json | cfssljson -bare etcd-1

对 etcd-2、etcd-3 重复同样操作，注意替换 IP 和主机名。
最后把 ca.pem、对应节点的 .pem 和 -key.pem 文件放到每台机器的 /etc/etcd/ssl/ 目录下。

编写 systemd 服务并启动集群

etcd 官方推荐使用 systemd 管理服务。
在每台机器上创建 /etc/etcd/etcd.conf 配置文件。
以 etcd-1 为例：

ETCD_NAME="etcd-1"
ETCD_DATA_DIR="/var/lib/etcd"
ETCD_LISTEN_PEER_URLS="https://192.168.1.101:2380"
ETCD_LISTEN_CLIENT_URLS="https://192.168.1.101:2379,https://127.0.0.1:2379"
ETCD_INITIAL_ADVERTISE_PEER_URLS="https://192.168.1.101:2380"
ETCD_ADVERTISE_CLIENT_URLS="https://192.168.1.101:2379"
ETCD_INITIAL_CLUSTER="etcd-1=https://192.168.1.101:2380,etcd-2=https://192.168.1.102:2380,etcd-3=https://192.168.1.103:2380"
ETCD_INITIAL_CLUSTER_STATE="new"
ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster"
ETCD_CERT_FILE="/etc/etcd/ssl/etcd-1.pem"
ETCD_KEY_FILE="/etc/etcd/ssl/etcd-1-key.pem"
ETCD_TRUSTED_CA_FILE="/etc/etcd/ssl/ca.pem"
ETCD_PEER_CERT_FILE="/etc/etcd/ssl/etcd-1.pem"
ETCD_PEER_KEY_FILE="/etc/etcd/ssl/etcd-1-key.pem"
ETCD_PEER_TRUSTED_CA_FILE="/etc/etcd/ssl/ca.pem"

etcd-2 和 etcd-3 的配置按同样格式修改 IP、名称和证书路径。
注意 ETCD_INITIAL_CLUSTER 在三台机器上必须完全一致，ETCD_INITIAL_CLUSTER_STATE 首次启动时保持 new。

接着创建 systemd 单元文件 /etc/systemd/system/etcd.service：

[Unit]
Description=etcd key-value store
Documentation=https://github.com/etcd-io/etcd
After=network.target

[Service]
Type=notify
EnvironmentFile=-/etc/etcd/etcd.conf
ExecStart=/usr/local/bin/etcd
Restart=always
RestartSec=10s
LimitNOFILE=40000

[Install]
WantedBy=multi-user.target

在每台机器上按顺序执行：

sudo mkdir -p /var/lib/etcd
sudo systemctl daemon-reload
sudo systemctl enable etcd
sudo systemctl start etcd

三个节点都启动后，集群会自动完成选举和成员同步。
这里要特别注意：必须三台机器都启动后，集群才会进入健康状态，只启动一台或两台时查询可能超时，属于正常现象。

检查集群状态与读写验证

集群启动后，用 etcdctl 验证成员和健康状态。
如果启用了 TLS，需要带上证书参数。
下面命令在任意一台节点上执行：

export ETCDCTL_API=3
export ETCDCTL_CACERT=/etc/etcd/ssl/ca.pem
export ETCDCTL_CERT=/etc/etcd/ssl/etcd-1.pem
export ETCDCTL_KEY=/etc/etcd/ssl/etcd-1-key.pem
export ETCDCTL_ENDPOINTS=https://192.168.1.101:2379,https://192.168.1.102:2379,https://192.168.1.103:2379
export ETCDCTL_DIAL_TIMEOUT=3s

etcdctl member list -w table
etcdctl endpoint health -w table
etcdctl endpoint status -w table

endpoint health 应显示所有节点 true，endpoint status 中能看到 leader 和 raft term 信息。
接着做一次读写测试：

etcdctl put /test/key "hello-etcd"
etcdctl get /test/key

能正确写入并读回，说明集群工作正常。
你还可以用 etcdctl member list 确认三个成员都在列表中。

常见报错与避坑提醒

搭建过程中容易遇到几个典型问题：

集群一直选不出 leader：检查 ETCD_INITIAL_CLUSTER 是否三台完全一致，ETCD_INITIAL_CLUSTER_STATE 是否误设为 existing。
连接被拒绝：确认防火墙放行了 2379 和 2380 端口，且 ETCD_LISTEN_CLIENT_URLS 监听的 IP 正确。
证书错误：检查证书里的 hosts 是否包含当前节点 IP 和主机名，系统时间是否准确，证书路径是否可读。
数据目录权限：etcd 进程需要对 /var/lib/etcd 有读写权限，权限不足会导致启动失败。
重启后无法加入：如果只是单节点重启，不要修改 ETCD_INITIAL_CLUSTER_STATE，保持 new 即可；只有整个集群重建时才需要调整。

如果修改了配置文件，执行 sudo systemctl daemon-reload && sudo systemctl restart etcd 后再次用 endpoint health 确认。
需要强调：不要随意删除 /var/lib/etcd 下的数据，除非你确定要重建整个集群。

写在最后

这篇 etcd 集群搭建教程覆盖了三节点高可用部署的核心流程：环境准备、证书生成、配置编写、systemd 启动和状态验证。
对于测试环境，你可以先不启用 TLS 快速跑通；
生产环境则建议按文中步骤启用证书并做好端口和权限管理。
完成搭建后，建议定期用 etcdctl endpoint health 检查集群状态，并关注磁盘 I/O 和网络延迟，这两个因素对 etcd 稳定性影响较大。
如果在操作中遇到其他报错，可以优先回看避坑部分，逐步排查配置、证书和网络三个方向。

RocketMQ部署教程：Linux单机环境从零搭建与验证

Zookeeper集群搭建：三节点伪分布式到生产环境的配置与排错