Etcd on Liangweidong's blog

etcd 3.5 集群二进制部署与 TLS 证书签发

Fri, 15 Mar 2024 00:00:00 +0800

为什么 etcd 必须独立部署

etcd 是 K8s 唯一的状态存储后端，所有 Pod/Service/ConfigMap 状态都写在 etcd 里。生产环境对 etcd 的要求：

3 节点或 5 节点集群（raft 多数派容错）
所有通信必须 TLS（peer + client）
必须与 kube-apiserver 分开部署（不要复用 master 节点或用容器化 etcd）

本文用 cfssl 工具签发全套证书，部署 3 节点 etcd 集群。

适用版本：etcd v3.5.11 / cfssl 1.6.4 / Ubuntu 22.04 部署位置：master1、master2、master3 各一份

1. 安装 cfssl 工具

1
2
3
4
5
6
7
8


cd /data/softs
cp cfssl_1.6.4_linux_amd64 /usr/local/bin/cfssl
cp cfssljson_1.6.4_linux_amd64 /usr/local/bin/cfssljson
cp cfssl-certinfo_1.6.4_linux_amd64 /usr/local/bin/cfssl-certinfo
chmod +x /usr/local/bin/cfssl /usr/local/bin/cfssljson /usr/local/bin/cfssl-certinfo

ls /usr/local/bin
# cfssl cfssl-certinfo cfssljson containerd ...

2. etcd 证书生成

所有证书的生成操作只在 master1 上做，然后 scp 到其他 master。

2.1 创建证书目录

1
2


mkdir -p /etc/etcd/ssl
mkdir -p /data/softs/pki && cd /data/softs/pki

需要的 11 个 JSON 配置文件（生产里通常从运维仓库分发）：

1
2
3
4


admin-csr.json apiserver-csr.json ca-config.json
ca-csr.json etcd-ca-csr.json etcd-csr.json
front-proxy-ca-csr.json front-proxy-client-csr.json
kube-proxy-csr.json manager-csr.json scheduler-csr.json

2.2 生成 etcd CA 与证书

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 生成 CA 根证书
cfssl gencert -initca etcd-ca-csr.json | cfssljson -bare /etc/etcd/ssl/etcd-ca

# 生成 etcd server 证书（hostname 和 IP 必须包含所有 3 个节点）
cfssl gencert \
 -ca=/etc/etcd/ssl/etcd-ca.pem \
 -ca-key=/etc/etcd/ssl/etcd-ca-key.pem \
 -config=ca-config.json \
 -hostname=127.0.0.1,master1,master2,master3,<master1-ip>,<master2-ip>,<master3-ip> \
 -profile=kubernetes \
 etcd-csr.json | cfssljson -bare /etc/etcd/ssl/etcd

生成结果：

1
2
3


ls /etc/etcd/ssl/
# etcd-ca.csr etcd-ca-key.pem etcd-ca.pem
# etcd.csr etcd-key.pem etcd.pem

2.3 把证书复制到其他 master

1
2
3
4
5
6


for NODE in master2 master3; do
 ssh $NODE "mkdir -p /etc/etcd/ssl"
 for FILE in etcd-ca-key.pem etcd-ca.pem etcd-key.pem etcd.pem; do
 scp /etc/etcd/ssl/${FILE} $NODE:/etc/etcd/ssl/${FILE}
 done
done

内网 IP 用占位符 <master1-ip> 等替代；实际操作换成真实 IP。

3. etcd 二进制安装

1
2
3
4
5
6
7
8
9


cd /data/softs
tar -xf etcd-v3.5.11-linux-amd64.tar.gz
mv etcd-v3.5.11-linux-amd64/etcd /usr/local/bin/
mv etcd-v3.5.11-linux-amd64/etcdctl /usr/local/bin/
mv etcd-v3.5.11-linux-amd64/etcdutl /usr/local/bin/

etcdctl version
# etcdctl version: 3.5.11
# API version: 3.5

推送到 master2 / master3：

1
2
3


for NODE in master2 master3; do
 scp /usr/local/bin/etcd* $NODE:/usr/local/bin/
done

4. etcd 配置文件

4.1 etcd.config.yml（master1 示例）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


name: 'master1'
data-dir: /var/lib/etcd
wal-dir: /var/lib/etcd/wal
snapshot-count: 5000
heartbeat-interval: 100
election-timeout: 1000
quota-backend-bytes: 0
listen-peer-urls: 'https://<master1-ip>:2380'
listen-client-urls: 'https://<master1-ip>:2379,http://127.0.0.1:2379'
max-snapshots: 3
max-wals: 5
initial-advertise-peer-urls: 'https://<master1-ip>:2380'
advertise-client-urls: 'https://<master1-ip>:2379'
initial-cluster: 'master1=https://<master1-ip>:2380,master2=https://<master2-ip>:2380,master3=https://<master3-ip>:2380'
initial-cluster-token: 'etcd-k8s-cluster'
initial-cluster-state: 'new'
strict-reconfig-check: false
enable-v2: true
enable-pprof: true
client-transport-security:
 cert-file: '/etc/etcd/ssl/etcd.pem'
 key-file: '/etc/etcd/ssl/etcd-key.pem'
 client-cert-auth: true
 trusted-ca-file: '/etc/etcd/ssl/etcd-ca.pem'
 auto-tls: true
peer-transport-security:
 cert-file: '/etc/etcd/ssl/etcd.pem'
 key-file: '/etc/etcd/ssl/etcd-key.pem'
 peer-client-cert-auth: true
 trusted-ca-file: '/etc/etcd/ssl/etcd-ca.pem'
 auto-tls: true

master2 / master3 的配置只需要改 name 字段、listen-peer-urls 里的 IP。

4.2 etcd.service 单元

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


[Unit]
Description=Etcd Service
Documentation=https://coreos.com/etcd/docs/latest/
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/etcd --config-file=/etc/etcd/etcd.config.yml
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
Alias=etcd3.service

5. 启动与验证

5.1 启动

1
2
3


systemctl daemon-reload
systemctl enable --now etcd.service
systemctl status etcd.service

5.2 验证集群状态

1
2
3
4
5
6
7


export ETCDCTL_API=3

etcdctl --endpoints="<master1-ip>:2379,<master2-ip>:2379,<master3-ip>:2379" \
 --cacert=/etc/etcd/ssl/etcd-ca.pem \
 --cert=/etc/etcd/ssl/etcd.pem \
 --key=/etc/etcd/ssl/etcd-key.pem \
 endpoint status --write-out=table

预期输出：

1
2
3
4
5
6
7


+------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS |
+------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
| <master1-ip>:2379 | b55511e3290daa2b | 3.5.11 | 20 kB | true | false | 2 | 8 | 8 | |
| <master2-ip>:2379 | 64aba84b878707bb | 3.5.11 | 20 kB | false | false | 2 | 8 | 8 | |
| <master3-ip>:2379 | 3eafefedb1462a99 | 3.5.11 | 20 kB | false | false | 2 | 8 | 8 | |
+------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+

只要 IS LEADER 有一个 true，RAFT TERM 都一致，ERRORS 都为空，集群就是健康的。

5.3 etcd 性能压测

1

etcdctl check perf

5.4 备份与恢复

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 备份
etcdctl snapshot save /tmp/etcd-snapshot.db
etcdctl snapshot status /tmp/etcd-snapshot.db --write-out=table

# 恢复（停 etcd 后）
etcdctl snapshot restore /tmp/etcd-snapshot.db \
 --name master1 \
 --initial-cluster master1=https://...,master2=...,master3=... \
 --initial-advertise-peer-urls https://<master1-ip>:2380 \
 --data-dir /var/lib/etcd-restore

6. 排错速查

现象	原因	解决
`etcdctl: command not found`	旧版本客户端	`export ETCDCTL_API=3`
`certificate verify failed`	CA 不匹配	检查 `trusted-ca-file`
raft term 不增长	集群未选主	检查 `initial-cluster` 是否 3 节点都在
`db size exceeds quota`	默认 2GB	调大 `quota-backend-bytes`
peer URL 改后无法加入	老的 peer 还在	删 data-dir 重启

7. 小结

etcd 集群是 K8s 状态的"心脏"：

必须 3 节点或 5 节点（raft 多数派）
所有通信必须 TLS（peer + client 都要）
证书 hostname 列表必须包含所有 3 节点
定期备份（etcdctl snapshot save）

下一步：K8s 1.28 核心组件二进制部署：apiserver/scheduler/controller-manager。

注册中心镜像实战：Nacos / Consul / etcd / ZooKeeper 部署、集群、配置与坑点

Wed, 20 Sep 2023 00:00:00 +0800

微服务架构里，“服务 A 怎么知道服务 B 的地址"这个问题被反复解决。最早大家用硬编码 IP（127.0.0.1:8080），后来用负载均衡（Nginx upstream），再后来才有了注册中心——服务启动时把自己注册上去，调用方从注册中心拉。

这篇文章把 Nacos / Consul / etcd / ZooKeeper 四款主流注册中心的 docker 部署、集群、客户端接入、坑点整理成一份实战清单。和之前 0.4 批次的 CI 工具对比 / 0.4 批次的 Java 全家桶不同，本文只聚焦"镜像实战”——拉哪个镜像、怎么配集群、客户端怎么连。

阅读对象：需要从零搭一套注册中心，或在生产环境做注册中心选型的开发者、运维
覆盖范围：四款组件的核心特性对比、Nacos 2.2.2 单机/集群部署、Consul 集群部署、etcd 3.4 单机/多机集群部署、ZooKeeper 3.8 部署 + WebUI、客户端 Spring Cloud 接入、常见排错

一、四款注册中心对比

维度	Nacos	Consul	etcd	ZooKeeper
语言	Java	Go	Go	Java
服务发现	✅	✅	✅（弱）	✅（弱）
配置中心	✅（核心）	✅（KV）	✅（KV）	❌（需自己实现）
健康检查	✅	✅	❌	❌
一致性协议	自研（AP/CP 可切）	Raft	Raft	ZAB
多数据中心	❌	✅	❌	❌
镜像大小	250 MB	130 MB	50 MB	300 MB
内存占用	1 GB~	200 MB~	100 MB~	500 MB~
启动时间	30 秒	5 秒	3 秒	30 秒
客户端语言支持	Java、Go、Node、Python	多语言	多语言	多语言
适用场景	Spring Cloud Alibaba 一站式	多语言 + 多数据中心	K8s 内部（kube-apiserver）	大数据生态（Hadoop、Kafka）

When to use：

Spring Cloud Alibaba 全家桶 → Nacos（一站式服务发现 + 配置中心）

多语言微服务 + 多数据中心 → Consul

K8s 内部 / 强一致性 KV → etcd

大数据组件依赖（Hadoop、Kafka、HBase） → ZooKeeper

二、Nacos 部署

2.1 镜像选择

镜像	版本	备注
`nacos/nacos-server:v2.0.3`	2.0 LTS	老版本，没有 gRPC 端口（只用 8848）
`nacos/nacos-server:v2.2.2`	2.2 LTS	推荐——修复了 2.2.0/2.2.1 的鉴权 bug
`nacos/nacos-server:latest`	2.x latest	跟随最新 dev 版，生产慎用

2.2 关键变化：Nacos 2.x 端口

Nacos 客户端升级到 2.x 后，新增了 gRPC 通信方式——这意味着除了主端口 8848，还要开两个 gRPC 端口：

端口	偏移量	用途
8848	—	HTTP（API + 控制台）
9848	1000	客户端 gRPC 请求服务端
9849	1001	服务间 gRPC 同步

坑 1：Nacos 2.x 部署时必须同时开 8848/9848/9849 三个端口——少一个客户端就连不上。只开 8848 会报 “9848 port is unavailable”。

2.3 单机部署（MySQL 后端）

前置：先准备一个 MySQL 库 nacos-config：

1
2
3


# nacos-db.sql 是 Nacos 官方提供的初始化脚本
# 包含 config_info / config_info_gray / config_tags_relation / his_config_info / config_info_beta 等表
mysql -u root -p < nacos-db.sql

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


docker run -d \
 --name nacos \
 --restart=always \
 -p 8848:8848 \
 -p 9848:9848 \
 -p 9849:9849 \
 -e NACOS_AUTH_ENABLE=true \
 -e NACOS_AUTH_IDENTITY_KEY=nacos \
 -e NACOS_AUTH_IDENTITY_VALUE=nacos \
 -e PREFER_HOST_MODE=ip \
 -e MODE=standalone \
 -e SPRING_DATASOURCE_PLATFORM=mysql \
 -e MYSQL_SERVICE_HOST=<INTERNAL_HOST> \
 -e MYSQL_SERVICE_PORT=3306 \
 -e MYSQL_SERVICE_USER=root \
 -e MYSQL_SERVICE_PASSWORD=<REDACTED> \
 -e MYSQL_SERVICE_DB_NAME=nacos-config \
 -e MYSQL_SERVICE_DB_PARAM="characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai" \
 nacos/nacos-server:v2.2.2

访问 http://<HOST>:8848/nacos，默认账号 nacos/nacos。

2.4 Nacos 2.2.0/2.2.1 鉴权坑

Nacos 2.2.0.1 和 2.2.1 移除了 3 个鉴权默认值（token.secret.key / nacos.core.auth.server.identity.key / nacos.core.auth.server.identity.value），避免用户部署时因未修改而引入撞库风险。但这导致：

不开启鉴权时，控制台 UI 登录要求被强制依赖 token.secret.key → 启动失败
开启鉴权时，用户必须自定义设置这三个值 → 否则节点无法启动

Nacos 2.2.2 的修复：

不开启鉴权 → 取消控制台 UI 登录要求
开启鉴权 → 用户自定义设置（启动时用环境变量传）：

1
2
3


-e NACOS_AUTH_ENABLE=true \
-e NACOS_AUTH_IDENTITY_KEY=nacos \
-e NACOS_AUTH_IDENTITY_VALUE=nacos

坑 2：2.2.2 之前（2.2.0/2.2.1）的"无鉴权启动失败"问题是2.2.2 解决的——别在 2.2.0/2.2.1 上踩坑，直接用 2.2.2。

2.5 关键 application.properties

容器内 /home/nacos/conf/application.properties：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# spring
server.servlet.contextPath=/nacos
server.contextPath=/nacos
server.port=8848

# 数据库
spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://<INTERNAL_HOST>:3306/nacos-config?serverTimezone=GMT%2B8&characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true
db.user=root
db.password=<REDACTED>

# 鉴权
nacos.core.auth.enabled=true
nacos.core.auth.server.identity.key=nacos
nacos.core.auth.server.identity.value=nacos
nacos.core.auth.system.type=nacos
nacos.core.auth.default.token.expire.seconds=18000
nacos.core.auth.default.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789

# 关闭鉴权缓存（开发环境）
nacos.core.auth.caching.enabled=false

# 性能调优（naming 模块）
nacos.naming.distro.taskDispatchThreadCount=10
nacos.naming.distro.taskDispatchPeriod=200
nacos.naming.distro.batchSyncKeyCount=1000
nacos.naming.distro.initDataRatio=0.9
nacos.naming.distro.syncRetryDelay=5000
nacos.naming.data.warmup=true

2.6 命名空间

真实场景：开发 / 测试 / 生产三套环境用同一个 Nacos 集群，靠 namespace 隔离。

Web 端：命名空间 → 新建命名空间 → 拿到 namespaceId

客户端（Spring Cloud）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


spring:
 cloud:
 nacos:
 discovery:
 server-addr: <INTERNAL_HOST>:8848
 namespace: <NAMESPACE_ID>  # 命名空间 ID
 config:
 server-addr: <INTERNAL_HOST>:8848
 namespace: <NAMESPACE_ID>
 file-extension: yaml

坑 3：namespace ID 一定要用生成的 UUID，不要用命名空间名（如 dev）——客户端按 UUID 匹配，写错就报 “namespace not found”。

2.7 集群部署

Nacos 集群需要 3 节点 + MySQL 后端（至少 3 节点保证 Raft 一致性）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


# docker-compose-nacos-cluster.yml
version: '3'
services:
 nacos1:
 image: nacos/nacos-server:v2.2.2
 container_name: nacos1
 restart: always
 ports:
 - "8848:8848"
 - "9848:9848"
 - "9849:9849"
 environment:
 - NACOS_SERVERS=nacos1:8848 nacos2:8848 nacos3:8848
 - MYSQL_SERVICE_HOST=<INTERNAL_HOST>
 - MYSQL_SERVICE_DB_NAME=nacos-config
 - MYSQL_SERVICE_USER=root
 - MYSQL_SERVICE_PASSWORD=<REDACTED>
 - SPRING_DATASOURCE_PLATFORM=mysql
 - JVM_XMS=512m
 - JVM_XMX=512m

 nacos2:
 image: nacos/nacos-server:v2.2.2
 container_name: nacos2
 restart: always
 ports:
 - "8849:8848"
 - "9850:9848"
 - "9851:9849"
 environment:
 - NACOS_SERVERS=nacos1:8848 nacos2:8848 nacos3:8848
 - MYSQL_SERVICE_HOST=<INTERNAL_HOST>
 - MYSQL_SERVICE_DB_NAME=nacos-config
 - MYSQL_SERVICE_USER=root
 - MYSQL_SERVICE_PASSWORD=<REDACTED>
 - SPRING_DATASOURCE_PLATFORM=mysql
 - JVM_XMS=512m
 - JVM_XMX=512m

 nacos3:
 image: nacos/nacos-server:v2.2.2
 container_name: nacos3
 restart: always
 ports:
 - "8850:8848"
 - "9852:9848"
 - "9853:9849"
 environment:
 - NACOS_SERVERS=nacos1:8848 nacos2:8848 nacos3:8848
 - MYSQL_SERVICE_HOST=<INTERNAL_HOST>
 - MYSQL_SERVICE_DB_NAME=nacos-config
 - MYSQL_SERVICE_USER=root
 - MYSQL_SERVICE_PASSWORD=<REDACTED>
 - SPRING_DATASOURCE_PLATFORM=mysql
 - JVM_XMS=512m
 - JVM_XMX=512m

坑 4：Nacos 集群节点之间用容器名互通——nacos1:8848 是 Docker 网络里的 hostname。如果跨主机部署（多台物理机），要把 nacos1:8848 换成 10.8.x.x:8848 这种宿主机 IP。

三、Consul 部署

3.1 镜像

1

docker pull consul:1.9.5

3.2 单机模式

1
2
3


docker run -d \
 -e CONSUL_BIND_INTERFACE=eth0 \
 consul agent -dev -join=172.17.0.2

坑 5：dev 模式是开发用的，不能用于生产。Consul dev 模式没有持久化、所有数据存内存、重启丢。

3.3 集群部署

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


# docker-compose-consul-cluster.yml
version: '3.7'
services:
 consul-server-1:
 image: consul:1.9.5
 container_name: consul-server-1
 restart: always
 command:
 - "agent"
 - "-server"
 - "-bootstrap-expect=3"
 - "-ui"
 - "-data-dir=/consul/data"
 - "-bind=0.0.0.0"
 - "-client=0.0.0.0"
 - "-advertise=<NODE1_IP>"
 - "-retry-join=<NODE2_IP>"
 - "-retry-join=<NODE3_IP>"
 ports:
 - "8500:8500" # WebUI
 - "8600:8600/udp" # DNS
 - "8300:8300" # Server RPC
 - "8301:8301" # Serf LAN
 - "8302:8302" # Serf WAN
 volumes:
 - "/data/consul/server1:/consul/data"

 consul-server-2:
 image: consul:1.9.5
 container_name: consul-server-2
 # 同上, advertise=<NODE2_IP>

 consul-server-3:
 image: consul:1.9.5
 container_name: consul-server-3
 # 同上, advertise=<NODE3_IP>

3 节点各启动一次：

1

docker-compose -f docker-compose-consul-cluster.yml up -d

WebUI：http://<NODE_IP>:8500/

3.4 客户端注册

Spring Cloud：

1
2
3
4
5
6
7
8
9


spring:
 cloud:
 consul:
 host: <INTERNAL_HOST>
 port: 8500
 discovery:
 prefer-ip-address: true
 health-check-interval: 10s
 instance-id: ${spring.application.name}:${server.port}

Go：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


import "github.com/hashicorp/consul/api"

config := api.DefaultConfig()
config.Address = "<INTERNAL_HOST>:8500"
client, _ := api.NewClient(config)

// 注册服务
reg := &api.AgentServiceRegistration{
 ID: "my-service-1",
 Name: "my-service",
 Port: 8080,
 Check: &api.AgentServiceCheck{
 HTTP: "http://<HOST>:8080/health",
 Interval: "10s",
 },
}
client.Agent().ServiceRegister(reg)

坑 6：Consul 默认会做"健康检查 HTTP"——如果服务还没起来就报健康检查失败。解决：先启动服务再注册，或者把 Check.HTTP 改成 Check.TCP（更轻量）。

四、etcd 部署

4.1 镜像

1
2
3


docker pull bitnami/etcd:3
# 或
docker pull quay.io/coreos/etcd:v3.4.16

4.2 单机部署

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# docker-compose.yml
version: '3.7'
services:
 etcd:
 image: bitnami/etcd:3
 container_name: etcd-single
 restart: always
 environment:
 - ALLOW_NONE_AUTHENTICATION=yes
 - ETCD_ADVERTISE_CLIENT_URLS=http://<INTERNAL_HOST>:2379
 - ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
 ports:
 - "2379:2379"
 volumes:
 - "/data/etcd:/bitnami/etcd/data"

启动后验证：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 复制 etcdctl 客户端
docker cp etcd-single:/usr/local/bin/etcdctl /home/docker/etcd
sudo mv /home/docker/etcd/etcdctl /usr/local/bin/

# 让 etcdctl 使用 v3 API
echo 'export ETCDCTL_API=3' >> ~/.zshrc
source ~/.zshrc

# 查看版本
etcdctl version

# 查看成员
etcdctl member list

4.3 多机集群部署

前置：3 个节点（192.168.3.101、192.168.3.102、192.168.3.103），IP 可达。

每个节点的 docker-compose.yml 结构一样，只有 3 个参数不同（--name、--initial-advertise-peer-urls、--advertise-client-urls）：

192.168.3.101 节点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


version: '3.7'
services:
 etcd:
 image: quay.io/coreos/etcd
 container_name: my-etcd
 restart: always
 environment:
 - ETCDCTL_API=3
 command:
 - etcd
 - --name=etcd1
 - --data-dir=/etcd-data
 - --listen-peer-urls=http://0.0.0.0:2380
 - --listen-client-urls=http://0.0.0.0:2379
 - --initial-advertise-peer-urls=http://192.168.3.101:2380
 - --advertise-client-urls=http://192.168.3.101:2379
 - --initial-cluster-token=cluster-token
 - --initial-cluster=etcd1=http://192.168.3.101:2380,etcd2=http://192.168.3.102:2380,etcd3=http://192.168.3.103:2380
 - --initial-cluster-state=new
 volumes:
 - $PWD/etcd-data:/etcd-data
 ports:
 - 2379:2379
 - 2380:2380
 network_mode: "host"

192.168.3.102 / 192.168.3.103 节点：把 etcd1 改为 etcd2 / etcd3，URL 改对应 IP 即可。

1
2
3
4
5
6
7
8
9


# 3 个节点分别启动
docker-compose up -d

# 查看集群成员
export ENDPOINTS=192.168.3.101:2379,192.168.3.102:2379,192.168.3.103:2379
etcdctl --endpoints=$ENDPOINTS member list

# 查看成员状态
etcdctl --write-out=table --endpoints=$ENDPOINTS endpoint status

4.4 常见排错

症状：retrying of unary invoker failed

原因：--advertise-client-urls 和 --initial-advertise-peer-urls 设成了 0.0.0.0 或 localhost——必须是具体 IP 或 hostname。

解决：把两个 URL 改成节点实际 IP。

4.5 客户端使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 写
etcdctl put /config/db/url "jdbc:mysql://<HOST>:3306/test"
etcdctl put /config/db/user "root"

# 读
etcdctl get /config/db/url
etcdctl get /config --prefix

# 删
etcdctl del /config/db/url

# 监听变更
etcdctl watch /config/db/url

五、ZooKeeper 部署

5.1 镜像

1

docker pull zookeeper:3.8.0

5.2 单机部署

1

docker run -d -p 2181:2181 --name zookeeper --restart always zookeeper:3.8.0

5.3 客户端使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 进入容器
docker exec -it zookeeper /bin/bash
cd bin
./zkCli.sh -server 127.0.0.1:2181

# zkCli 命令
ls /
create /test "hello"
get /test
set /test "world"
delete /test

5.4 WebUI 部署

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


docker pull tobilg/zookeeper-webui:latest

docker run -d \
 -p 8098:8080 \
 -e ZK_DEFAULT_NODE=<INTERNAL_HOST>:2181/ \
 -e USER=admin \
 -e PASSWORD=<REDACTED> \
 --name zk-web-ui \
 --restart always \
 -t tobilg/zookeeper-webui

访问 http://<HOST>:8098/。

5.5 集群部署

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


# docker-compose.yml
version: '3'
services:
 zk1:
 image: zookeeper:3.8.0
 container_name: zk1
 restart: always
 environment:
 - ZOO_MY_ID=1
 - ZOO_SERVERS=server.1=zk1:2888:3888;2181 server.2=zk2:2888:3888;2181 server.3=zk3:2888:3888;2181
 ports:
 - "2181:2181"
 - "8081:8080"
 networks:
 - zk-net

 zk2:
 image: zookeeper:3.8.0
 container_name: zk2
 restart: always
 environment:
 - ZOO_MY_ID=2
 - ZOO_SERVERS=server.1=zk1:2888:3888;2181 server.2=zk2:2888:3888;2181 server.3=zk3:2888:3888;2181
 ports:
 - "2182:2181"
 - "8082:8080"
 networks:
 - zk-net

 zk3:
 image: zookeeper:3.8.0
 container_name: zk3
 restart: always
 environment:
 - ZOO_MY_ID=3
 - ZOO_SERVERS=server.1=zk1:2888:3888;2181 server.2=zk2:2888:3888;2181 server.3=zk3:2888:3888;2181
 ports:
 - "2183:2181"
 - "8083:8080"
 networks:
 - zk-net

networks:
 zk-net:
 driver: bridge

坑 7：ZooKeeper 集群节点数 必须为奇数（3、5、7）——ZAB 协议要求多数派，奇数能容忍 n/2 节点故障。4 节点集群和 3 节点集群的容错能力是一样的，但 4 节点更耗资源。

六、四款组件的 Spring Cloud 接入

6.1 Nacos

1
2
3
4
5
6
7
8


<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


spring:
 application:
 name: order-service
 cloud:
 nacos:
 discovery:
 server-addr: <INTERNAL_HOST>:8848
 namespace: <NAMESPACE_ID>
 config:
 server-addr: <INTERNAL_HOST>:8848
 namespace: <NAMESPACE_ID>
 file-extension: yaml

6.2 Consul

1
2
3
4
5
6
7
8


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-consul-discovery</artifactId>
</dependency>
<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-consul-config</artifactId>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


spring:
 cloud:
 consul:
 host: <INTERNAL_HOST>
 port: 8500
 discovery:
 prefer-ip-address: true
 health-check-interval: 10s
 config:
 format: yaml
 prefix: config
 default-context: order-service

6.3 etcd

1
2
3
4


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-etcd-discovery</artifactId>
</dependency>

坑 8：Spring Cloud Etcd 已经被官方弃用——推荐用 Kubernetes Service 做服务发现（K8s 内部 etcd 自动做）。如果是非 K8s 环境用 etcd 做服务发现，建议直接用 Nacos。

6.4 ZooKeeper

1
2
3
4


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-zookeeper-discovery</artifactId>
</dependency>

1
2
3
4


spring:
 cloud:
 zookeeper:
 connect-string: <INTERNAL_HOST>:2181,<INTERNAL_HOST>:2182,<INTERNAL_HOST>:2183

七、常见排错

7.1 Nacos 客户端报 “9848 port is unavailable”

症状：Spring Boot 启动时报 failed to req API:127.0.0.1:9848 或 9848 port is unavailable

解决：

服务端要开放 9848 端口（不只是 8848）
客户端 → 服务端的网络是通的

7.2 Consul 健康检查失败导致服务被踢

症状：服务注册到 Consul 后，30 秒后被自动剔除。

解决：

检查 Check.HTTP 路径是否真的存在（如 /actuator/health）
Spring Boot 加 management.endpoints.web.exposure.include: health
调长 deregister-critical-service-after 时间

7.3 etcd 集群脑裂

症状：etcdctl member list 显示 3 个节点都是 leader。

解决：

强制重置集群：停所有节点 → 删 --data-dir 目录 → 重新 --initial-cluster-state=new
加 --election-timeout 避免偶发切换

7.4 ZooKeeper 启动失败 “Cannot open channel to X at election address”

症状：ZooKeeper 容器日志反复报 Cannot open channel to 2 at election address /xx:3888

解决：

3888 端口是否开放
容器名（zk1 / zk2 / zk3）和 ZOO_SERVERS 配置是否一致
ZOO_MY_ID 是否和 server.X 中的 X 一致

八、写在最后

注册中心选型没有银弹——四款组件定位不同：

Nacos：Spring Cloud Alibaba 一站式，国内中小团队首选
Consul：多语言、多数据中心场景的"多面手"
etcd：K8s 内部组件、非 K8s 场景慎用
ZooKeeper：大数据生态依赖、传统微服务可用

下一步建议：

Nacos 2.x 集群 + MySQL 后端高可用（MySQL 主从 + Keepalived VIP）
Nacos + Sentinel 做流量控制和熔断
Consul Connect 做服务间 mTLS 加密

参考资料

Nacos 官方文档：https://nacos.io/zh-cn/docs/quick-start.html
Consul 官方文档：https://www.consul.io/docs
etcd 官方文档：https://etcd.io/docs/
ZooKeeper 官方文档：https://zookeeper.apache.org/doc/current/
Nacos Docker 镜像：https://hub.docker.com/r/nacos/nacos-server
Nacos 2.2.2 release notes：https://github.com/alibaba/nacos/releases/tag/2.2.2

etcd 集群部署：3 节点高可用与 Raft 选举详解

Tue, 15 Sep 2020 00:00:00 +0800

写于 2020-09，背景：etcd v3.4 时代，K8s 1.19 仍以 3 节点 etcd 集群为生产推荐。本文聚焦 etcd 集群原理 + 实战部署。

一、etcd 是什么

etcd 是一个分布式键值数据库，天生为集群化设计：

数据模型：扁平 key-value，类比 redis 但走磁盘（强一致）
一致性算法：Raft（保证多节点数据强一致）
API：gRPC + HTTP/JSON，对 K8s 友好
应用场景：服务发现、配置中心、K8s/calico/Docker Swarm 后端存储

etcd 是 CNCF 毕业项目，与 K8s 同源（都来自 Borg 系统的设计哲学）。

二、Raft 算法与集群规模

Raft 在做决策时需要超半数节点投票，所以 etcd 集群推荐奇数节点（3/5/7）：

节点数	最大容忍故障	备注
1	0	单实例，无集群意义
2	0	双节点能启动，但挂一台就选不出主，不要用
3	1	生产最低推荐
4	1	跟 3 一样，浪费一台
5	2	中型集群推荐
6	2	跟 5 一样，浪费一台
7	3	大型集群（>100 节点）

为什么不能是偶数？ 4 节点和 3 节点都是容忍 1 台故障，但 4 节点多一台机器成本；6 节点和 5 节点同理。Raft 选举只看"过半"，不看你有几个备份。

三、集群规划

3 master 节点同时跑 etcd（etcd 与 apiserver 同节点部署是 K8s 官方推荐）：

主机名	IP	角色
master1	`192.168.139.133`	etcd-1 + apiserver
master2	`192.168.139.134`	etcd-2 + apiserver
master3	`192.168.139.135`	etcd-3 + apiserver

端口约定：

2379：客户端 API（kube-apiserver 调 etcd）
2380：节点间 peer 通信（Raft 选举 + 数据同步）

四、生成 etcd 证书

K8s 集群里 etcd 走双向 TLS，证书前置在 2020-03-15《K8s 二进制部署》已签发。关键步骤回顾：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


# ca-config.json
cat > ca-config.json << EOF
{
 "signing": {
 "default": { "expiry": "876000h" },
 "profiles": {
 "kubernetes": {
 "usages": ["signing", "key encipherment", "server auth", "client auth"],
 "expiry": "876000h"
 }
 }
 }
}
EOF

# etcd CA
cat > etcd-ca-csr.json << EOF
{
 "CN": "etcd",
 "key": { "algo": "rsa", "size": 2048 },
 "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "etcd", "OU": "Etcd Security" }],
 "ca": { "expiry": "876000h" }
}
EOF

cfssl gencert -initca etcd-ca-csr.json | cfssljson -bare /etc/etcd/ssl/etcd-ca

# etcd server 证书（注意 hostname + IP 全列）
cat > etcd-csr.json << EOF
{
 "CN": "etcd",
 "key": { "algo": "rsa", "size": 2048 },
 "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "etcd", "OU": "Etcd Security" }]
}
EOF

cfssl gencert \
 -ca=/etc/etcd/ssl/etcd-ca.pem \
 -ca-key=/etc/etcd/ssl/etcd-ca-key.pem \
 -config=ca-config.json \
 -hostname=127.0.0.1,master1,master2,master3,192.168.139.133,192.168.139.134,192.168.139.135 \
 -profile=kubernetes \
 etcd-csr.json | cfssljson -bare /etc/etcd/ssl/etcd

五、安装 etcd 二进制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 解压
wget https://github.com/etcd-io/etcd/releases/download/v3.5.11/etcd-v3.5.11-linux-amd64.tar.gz
tar -xf etcd-v3.5.11-linux-amd64.tar.gz
mv etcd-v3.5.11-linux-amd64/etcd /usr/local/bin/
mv etcd-v3.5.11-linux-amd64/etcdctl /usr/local/bin/
mv etcd-v3.5.11-linux-amd64/etcdutl /usr/local/bin/

# 验证
etcd --version
etcdctl version
# etcdctl version: 3.5.11
# API version: 3.5

六、etcd 配置文件

每个 master 节点单独写一份 /etc/etcd/etcd.config.yml，注意 name、listen URL、advertise URL 都不同。

6.1 master1 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


name: 'master1'
data-dir: /var/lib/etcd
wal-dir: /var/lib/etcd/wal
snapshot-count: 5000
heartbeat-interval: 100
election-timeout: 1000
quota-backend-bytes: 0
listen-peer-urls: 'https://192.168.139.133:2380'
listen-client-urls: 'https://192.168.139.133:2379,http://127.0.0.1:2379'
max-snapshots: 3
max-wals: 5
initial-advertise-peer-urls: 'https://192.168.139.133:2380'
advertise-client-urls: 'https://192.168.139.133:2379'
initial-cluster: 'master1=https://192.168.139.133:2380,master2=https://192.168.139.134:2380,master3=https://192.168.139.135:2380'
initial-cluster-token: 'etcd-k8s-cluster'
initial-cluster-state: 'new'
strict-reconfig-check: false
enable-v2: true
enable-pprof: true
proxy: 'off'
client-transport-security:
 cert-file: '/etc/kubernetes/pki/etcd/etcd.pem'
 key-file: '/etc/kubernetes/pki/etcd/etcd-key.pem'
 client-cert-auth: true
 trusted-ca-file: '/etc/kubernetes/pki/etcd/etcd-ca.pem'
 auto-tls: true
peer-transport-security:
 cert-file: '/etc/kubernetes/pki/etcd/etcd.pem'
 key-file: '/etc/kubernetes/pki/etcd/etcd-key.pem'
 peer-client-cert-auth: true
 trusted-ca-file: '/etc/kubernetes/pki/etcd/etcd-ca.pem'
 auto-tls: true
debug: false
log-outputs: [default]
force-new-cluster: false

6.2 master2 / master3 配置

只改 name 和 listen/advertise URL 的 IP，其他保持一致。

七、systemd 单元文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


[Unit]
Description=Etcd Service
Documentation=https://coreos.com/etcd/docs/latest/
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/etcd --config-file=/etc/etcd/etcd.config.yml
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
Alias=etcd3.service

K8s 默认从 /etc/kubernetes/pki/etcd/ 找 etcd 证书，加软链：

1
2


mkdir -p /etc/kubernetes/pki/etcd
ln -s /etc/etcd/ssl/* /etc/kubernetes/pki/etcd/

八、启动与验证

1
2
3
4


# 所有 master 节点
systemctl daemon-reload
systemctl enable --now etcd.service
systemctl status etcd.service

关键验证（master1 执行）：

1
2
3
4
5
6
7
8


# 注意 v2/v3 API 切换
export ETCDCTL_API=3

etcdctl --endpoints="https://192.168.139.133:2379,https://192.168.139.134:2379,https://192.168.139.135:2379" \
 --cacert=/etc/kubernetes/pki/etcd/etcd-ca.pem \
 --cert=/etc/kubernetes/pki/etcd/etcd.pem \
 --key=/etc/kubernetes/pki/etcd/etcd-key.pem \
 endpoint status --write-out=table

预期输出：

1
2
3
4
5
6
7


+----------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+
| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
+----------------------+------------------+---------+---------+-----------+------------+
| 192.168.139.133:2379 | 67214e12874d646b | 3.5.11 | 29 kB | false | 2 | 8 |
| 192.168.139.134:2379 | a6947d51f82bebc4 | 3.5.11 | 29 kB | false | 2 | 8 |
| 192.168.139.135:2379 | f0598e5ca7a8066f | 3.5.11 | 29 kB | true | 2 | 8 |
+----------------------+------------------+---------+---------+-----------+------------+

关键字段：

IS LEADER：true 表示该节点是当前 leader（Raft 选举结果）
RAFT TERM：选举轮次，term 越大说明发生过越多次选举
DB SIZE：etcd 数据库占磁盘大小

九、故障模拟

9.1 模拟 master1 宕机

1
2


# 在 master1 上
systemctl stop etcd

观察其他节点：

1
2


# 观察 5~10 秒
watch -n 1 "etcdctl endpoint status --cluster --write-out=table"

预期：master1 不可达，master3 仍为 leader（因为 3 节点允许挂 1 台）。

9.2 模拟 master2 也宕机

1
2


# master2
systemctl stop etcd

此时只剩 master1，集群不可用（写操作会失败），但 etcd 不会自动重启——必须人工恢复至少 2 节点。

9.3 恢复

1
2
3


# master2 / master3 启动
systemctl start etcd
# 集群自动重新选主（5~10 秒内）

9.4 灾难恢复：强制重建集群

如果 3 台都挂，etcd 数据还在，但需要 --force-new-cluster 强制单节点启动：

1
2
3
4
5
6


# 改配置
echo "initial-cluster-state: 'existing'" >> /etc/etcd/etcd.config.yml
# 注意 force-new-cluster=true 只能用于一台

# 重启
systemctl start etcd

十、etcdctl 常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 列成员
etcdctl member list

# 健康检查
etcdctl endpoint health --cluster

# 写读测试
etcdctl put /test/foo "hello"
etcdctl get /test/foo

# 备份
etcdctl snapshot save /tmp/etcd-backup.db
etcdctl snapshot status /tmp/etcd-backup.db --write-out=table

# 碎片整理（v3.4 之前需要）
etcdctl defrag

# 告警
etcdctl alarm list
etcdctl alarm disarm

十一、性能调优

参数	含义	默认	调优建议
`heartbeat-interval`	心跳间隔（ms）	100	高延迟网络调大到 200~500
`election-timeout`	选举超时（ms）	1000	至少 5 倍 heartbeat
`quota-backend-bytes`	后端存储限额	2GB	集群 > 8GB 数据调大
`snapshot-count`	触发快照的事务数	100000	写多场景调小到 10000
`max-snapshots`	保留快照数	5	视磁盘空间

关键监控指标：

etcd_disk_wal_fsync_duration_seconds（p99 < 10ms，否则 IO 瓶颈）
etcd_network_peer_round_trip_time_seconds（p99 < 50ms）
etcd_server_has_leader（必须 = 1）
etcd_server_proposals_committed_total / etcd_server_proposals_applied_total（差值 = pending，>5 要警惕）

十二、常见坑

证书 hostname/IP 漏配：peer 通信报 “x509: certificate is valid for …” 错误
firewalld 没关：节点间 2380 端口不通，选举失败
initial-cluster-state: 'new' 重复使用：第二次启动报 “member already exists”，改成 'existing'
etcd 与 apiserver 时钟不同步：证书验证失败，先 ntpdate time1.aliyun.com 对齐
snapshot 备份恢复后集群 ID 变了：用 etcdctl snapshot restore 时记得加 --initial-cluster 和 --initial-advertise-peer-urls

十三、前置知识 / 下一步

前置：

证书签发（cfssl，参考 2020-03-15《K8s 二进制部署》）
K8s 架构基础

下一步：

API Server 高可用（2021-03-15）—— Nginx 四层 + Keepalived VIP
K8s 集群管理（2021-12-15）—— 升级、节点隔离、备份恢复

参考资料

2024+ 视角

etcd 在 2024-2026 年依然是 K8s 数据底座，但生态发生了几个关键变化：

etcd v3.5 全面稳定：v3.5.x 引入的 etcdutl（替代旧 etcdctl 快照管理）、Raft ReadIndex 优化、Learner 节点都已 GA。生产推荐 v3.5.10+（修复了多个 Raft 性能回退问题）。
K8s 1.30+ 的 etcd 管理变更：自 K8s 1.30 起，kubeadm 默认 etcd 容器镜像从 k8s.gcr.io/etcd 切到 registry.k8s.io/etcd，并支持 etcd Learner 节点用于接入已有 etcd 集群（适合 etcd 单独运维团队）。
etcd 性能与碎片整理：v3.4 之前的 defrag 命令在 v3.5 已不再是必须的——v3.5 后端实现了在线碎片回收（QuotaBackendBytes + AutoCompactionMode=periodic）。但 DB Size 超过 quota-backend-bytes 仍会触发告警。
可观测性增强：社区推荐 etcd-dashboard（来自 RedHat）+ Prometheus 抓取 etcd_disk_wal_fsync_duration_seconds、etcd_server_has_leader 等 20+ 关键指标。K8s SIG-Instrumentation 提供官方 kube-etcd-monitor Helm Chart。
替代方案的边界：Kine（将 etcd API 翻译成 SQL）让 MySQL/PostgreSQL 可作为 K8s 后端，但生产级 etcd 仍不可替代——Raft 协议下的强一致 + 低延迟（p99 < 10ms）是 etcd 的护城河。
运维注意：2024 年起，多个 K8s 重大故障源于 etcd 时钟漂移（节点间 NTP 偏差 > 1s 触发 leader 选举）。建议在所有 master 节点部署 chrony 而非 ntpd，并监控 node_timex_offset_seconds。

总之，这篇 2020 年的 etcd 部署骨架至今仍可作为新集群起点，主要补全是：升级到 v3.5.x、用 etcdutl 管理快照、补 Prometheus 监控。