4. etcd集群基础部署：二进制安装etcd、静态配置与动态发现、TLS证书生成与配置

etcd集群的部署质量直接决定压测沙盘Federation环境的稳定性与性能基线。本章围绕二进制安装、静态配置与动态发现、TLS证书生成与配置三个核心环节展开，确保学员能够从零搭建一个生产级etcd集群，并为后续压测与瓶颈分析奠定基础。

4.1 二进制安装etcd

推荐使用官方预编译二进制包进行安装，避免包管理器版本滞后或依赖冲突。以下步骤适用于Linux amd64/arm64环境。

4.1.1 下载与解压

# 获取最新稳定版本（以v3.5.15为例）
wget https://github.com/etcd-io/etcd/releases/download/v3.5.15/etcd-v3.5.15-linux-amd64.tar.gz

# 解压并进入目录
tar -xzf etcd-v3.5.15-linux-amd64.tar.gz
cd etcd-v3.5.15-linux-amd64

# 将二进制文件复制到系统路径
sudo cp etcd etcdctl etcdutl /usr/local/bin/

4.1.2 验证安装

etcd --version
etcdctl version
etcdutl version
版本一致性提示：集群内所有节点的etcd版本必须一致，否则可能导致Raft协议兼容性问题。建议在压测沙盘Federation环境中统一使用同一版本。

4.2 静态配置与动态发现

etcd集群成员发现机制分为静态配置和动态发现两种模式。静态配置适用于节点IP固定的场景，动态发现适用于IP不固定的云原生环境。

4.2.1 静态配置（Static Bootstrap）

静态配置需要在启动时通过--initial-cluster参数明确列出所有节点的名称与地址。以下是一个3节点集群的配置示例：

节点名称 节点IP Client端口 Peer端口
etcd-1 192.168.1.101 2379 2380
etcd-2 192.168.1.102 2379 2380
etcd-3 192.168.1.103 2379 2380 
# 节点 etcd-1 启动命令示例
etcd \
  --name etcd-1 \
  --initial-advertise-peer-urls http://192.168.1.101:2380 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --advertise-client-urls http://192.168.1.101:2379 \
  --listen-client-urls http://0.0.0.0:2379 \
  --initial-cluster- etcd-cluster-1 \
  --initial-cluster etcd-1=http://192.168.1.101:2380,etcd-2=http://192.168.1.102:2380,etcd-3=http://192.168.1.103:2380 \
  --initial-cluster-state new
关键参数说明：
  • --initial-cluster-state new：首次启动必须设为new，后续重启需改为existing。
  • --initial-cluster-：同一集群的所有节点必须使用相同的，用于防止跨集群混淆。
  • --listen-peer-urls：建议绑定0.0.0.0，但--initial-advertise-peer-urls必须使用实际可达IP。

4.2.2 动态发现（Discovery Service）

动态发现依赖etcd自带的discovery服务或自定义discovery URL。适用于节点IP动态分配的场景（如Kubernetes Pod）。

# 生成discovery （在任意一台机器执行）
DISCOVERY_URL=$(curl -s https://discovery.etcd.io/new?size=3)
echo $DISCOVERY_URL

# 所有节点使用相同的discovery URL启动
etcd \
  --name etcd-1 \
  --initial-advertise-peer-urls http://192.168.1.101:2380 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --advertise-client-urls http://192.168.1.101:2379 \
  --listen-client-urls http://0.0.0.0:2379 \
  --discovery https://discovery.etcd.io/<>
静态 vs 动态发现对比：
  • 静态配置：配置明确，启动速度快，适合压测沙盘Federation环境中的固定节点集群。
  • 动态发现：灵活性高，但依赖外部discovery服务，存在单点故障风险。生产环境建议自建discovery服务。

4.3 TLS证书生成与配置

etcd集群在生产环境中必须启用TLS加密，防止中间人攻击和数据泄露。证书体系包含CA根证书、服务端证书、客户端证书以及Peer证书。

4.3.1 使用cfssl生成证书

推荐使用cfssl工具链，支持JSON配置化生成，便于批量管理。

# 安装cfssl
wget -q --show-progress https://github.com/cloudflare/cfssl/releases/download/v1.6.5/cfssl_1.6.5_linux_amd64
wget -q --show-progress https://github.com/cloudflare/cfssl/releases/download/v1.6.5/cfssljson_1.6.5_linux_amd64
chmod +x cfssl_* cfssljson_*
sudo mv cfssl_* /usr/local/bin/cfssl
sudo mv cfssljson_* /usr/local/bin/cfssljson

# 创建CA配置文件
cat > ca-config.json <<EOF
{
  "signing": {
    "default": {
      "expiry": "87600h"
    },
    "profiles": {
      "server": {
        "expiry": "87600h",
        "usages": ["signing", "key encipherment", "server auth"]
      },
      "client": {
        "expiry": "87600h",
        "usages": ["signing", "key encipherment", "client auth"]
      },
      "peer": {
        "expiry": "87600h",
        "usages": ["signing", "key encipherment", "server auth", "client auth"]
      }
    }
  }
}
EOF

# 生成CA证书和私钥
cat > ca-csr.json <<EOF
{
  "CN": "etcd CA",
  "key": {
    "algo": "rsa",
    "size": 2048
  },
  "names": [
    {
      "C": "CN",
      "L": "Beijing",
      "O": "etcd",
      "OU": "SRE"
    }
  ]
}
EOF

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

4.3.2 生成节点证书（以etcd-1为例）

# 创建节点证书请求
cat > etcd-1.json <<EOF
{
  "CN": "etcd-1",
  "key": {
    "algo": "rsa",
    "size": 2048
  },
  "hosts": [
    "192.168.1.101",
    "127.0.0.1",
    "localhost",
    "etcd-1.example.com"
  ],
  "names": [
    {
      "C": "CN",
      "L": "Beijing",
      "O": "etcd",
      "OU": "SRE"
    }
  ]
}
EOF

# 生成服务端+Peer双用途证书
cfssl gencert \
  -ca=ca.pem \
  -ca-key=ca-key.pem \
  -config=ca-config.json \
  -profile=peer \
  etcd-1.json | cfssljson -bare etcd-1
hosts字段填写规则：
  • 必须包含节点的所有可达IP和DNS名称。
  • 建议包含127.0.0.1和localhost，便于本地调试。
  • 如果使用Kubernetes Service名称，也需要加入hosts列表。

4.3.3 配置etcd启用TLS

etcd \
  --name etcd-1 \
  --initial-advertise-peer-urls https://192.168.1.101:2380 \
  --listen-peer-urls https://0.0.0.0:2380 \
  --advertise-client-urls https://192.168.1.101:2379 \
  --listen-client-urls https://0.0.0.0:2379 \
  --cert-file=/etc/etcd/ssl/etcd-1.pem \
  --key-file=/etc/etcd/ssl/etcd-1-key.pem \
  --peer-cert-file=/etc/etcd/ssl/etcd-1.pem \
  --peer-key-file=/etc/etcd/ssl/etcd-1-key.pem \
  --peer-client-cert-auth \
  --peer-trusted-ca-file=/etc/etcd/ssl/ca.pem \
  --client-cert-auth \
  --trusted-ca-file=/etc/etcd/ssl/ca.pem \
  --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 \
  --initial-cluster- etcd-cluster-tls \
  --initial-cluster-state new
证书路径权限：etcd进程以etcd用户运行时，证书文件权限必须设置为600，目录权限为700，否则启动会报权限错误。

4.4 集群启动验证

启动所有节点后，使用etcdctl验证集群健康状态：

# 使用TLS访问
etcdctl \
  --endpoints=https://192.168.1.101:2379,https://192.168.1.102:2379,https://192.168.1.103:2379 \
  --cacert=/etc/etcd/ssl/ca.pem \
  --cert=/etc/etcd/ssl/etcd-1.pem \
  --key=/etc/etcd/ssl/etcd-1-key.pem \
  endpoint health --cluster

# 查看成员列表
etcdctl member list --write-out=table

预期输出显示所有节点均为healthy状态，成员列表包含3个节点且Leader已选举成功。

4.5 本章知识结构

以下SVG图展示了etcd集群部署的完整流程与TLS证书体系关系：

etcd集群部署流程与TLS证书体系 二进制安装 静态配置 动态发现 CA根证书生成 服务端/客户端证书 Peer证书 etcd集群启动（--initial-cluster-state new） 集群健康检查 & member list 关键说明： • 静态配置适用于固定IP环境，动态发现适用于云原生弹性环境。 • TLS证书必须包含节点所有可达IP/DNS，否则TLS握手会失败。

4.6 常见部署问题与排查

问题现象 可能原因 排查命令/方法
节点启动后无法加入集群 --initial-cluster-state设置错误或不匹配 检查所有节点的--initial-cluster-是否一致
TLS握手失败 证书hosts字段缺少节点IP或DNS openssl x509 -in <cert.pem> -text -noout 查看Subject Alternative Names
etcdctl连接超时 防火墙未放行2379/2380端口 telnet <node-ip> 2379 测试端口连通性
Leader选举失败 节点间网络延迟过高或丢包 etcdctl endpoint status --write-out=table 查看Raft term和leader
压测沙盘Federation环境建议：
  • 统一使用静态配置，避免discovery服务成为压测瓶颈。
  • 所有节点使用同一份CA签发的证书，便于证书轮换管理。
  • 在压测前执行etcdctl endpoint health --cluster确认所有节点健康，避免压测数据倾斜。
← 上一章 📖 返回目录 下一章 →