Skip to content
中间件
etcd
安装与配置

安装与配置

etcd 多平台安装方式（Windows / Linux / macOS / Docker）、单机与集群配置、etcdutl 管理工具，以及 etcd.conf 核心参数详解。

适用 etcd 版本: v3.5.x / v3.6.x

安装

Windows

打开 etcd Releases，下载 Windows 版本 zip 包，解压后包含以下文件：

  • etcd.exe — etcd 服务端
  • etcdctl.exe — 命令行客户端
  • etcdutl.exe — 运维工具（快照、后端管理等）

双击 etcd.exe，看到类似 ready to serve client requests 即启动成功。默认监听：

  • 客户端端口: 127.0.0.1:2379
  • 节点间通信端口: 127.0.0.1:2380
# 验证安装
etcdctl version

# 测试存取
etcdctl put hello world
etcdctl get hello

💡 最佳实践：建议将 etcd 目录加入 PATH 环境变量，方便全局使用 etcdctl。

Windows 自定义启动参数 

# 指定数据目录和端口
.\etcd.exe --data-dir .\etcd-data --listen-client-urls http://0.0.0.0:2379 --advertise-client-urls http://localhost:2379

macOS 

# Homebrew 安装
brew install etcd

# 启动服务
brew services start etcd

# 或直接前台运行
etcd

Linux

二进制安装（推荐） 

# 下载并解压
ETCD_VER=v3.5.16
wget https://github.com/etcd-io/etcd/releases/download/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz
tar -xzf etcd-${ETCD_VER}-linux-amd64.tar.gz
cd etcd-${ETCD_VER}-linux-amd64

# 复制到系统路径
sudo cp etcd etcdctl etcdutl /usr/local/bin/

# 启动
etcd

systemd 服务 

# /etc/systemd/system/etcd.service
[Unit]
Description=etcd key-value store
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/etcd \
  --name etcd-01 \
  --data-dir /var/lib/etcd \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://192.168.1.10:2379 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --initial-advertise-peer-urls http://192.168.1.10:2380 \
  --initial-cluster etcd-01=http://192.168.1.10:2380 \
  --initial-cluster-state new
Restart=always
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable etcd
sudo systemctl start etcd

Docker 

# 单机测试（宿主机网络）
docker run -d \
  --name etcd \
  --network host \
  -v /data/etcd-data:/etcd-data \
  quay.io/coreos/etcd:v3.5.16 \
  etcd \
  --data-dir /etcd-data \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://127.0.0.1:2379

# 测试
docker exec etcd etcdctl put foo bar
docker exec etcd etcdctl get foo

Docker Compose 单节点 

# docker-compose.yml
version: '3.8'
services:
  etcd:
    image: quay.io/coreos/etcd:v3.5.16
    container_name: etcd
    ports:
      - "2379:2379"
      - "2380:2380"
    environment:
      - ETCD_NAME=etcd-01
      - ETCD_DATA_DIR=/etcd-data
      - ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
      - ETCD_ADVERTISE_CLIENT_URLS=http://127.0.0.1:2379
      - ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
      - ETCD_INITIAL_ADVERTISE_PEER_URLS=http://etcd-01:2380
      - ETCD_INITIAL_CLUSTER=etcd-01=http://etcd-01:2380
      - ETCD_INITIAL_CLUSTER_STATE=new
    volumes:
      - etcd-data:/etcd-data

volumes:
  etcd-data:

Docker Compose 3 节点集群 

# docker-compose-cluster.yml
version: '3.8'
services:
  etcd1:
    image: quay.io/coreos/etcd:v3.5.16
    environment:
      - ETCD_NAME=etcd1
      - ETCD_INITIAL_CLUSTER=etcd1=http://etcd1:2380,etcd2=http://etcd2:2380,etcd3=http://etcd3:2380
      - ETCD_INITIAL_CLUSTER_STATE=new
      - ETCD_INITIAL_CLUSTER_TOKEN=etcd-cluster
      - ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
      - ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
      - ETCD_ADVERTISE_CLIENT_URLS=http://etcd1:2379
      - ETCD_INITIAL_ADVERTISE_PEER_URLS=http://etcd1:2380
    ports:
      - "2379:2379"
    volumes:
      - etcd1-data:/etcd-data
    networks:
      - etcd-net

  etcd2:
    image: quay.io/coreos/etcd:v3.5.16
    environment:
      - ETCD_NAME=etcd2
      - ETCD_INITIAL_CLUSTER=etcd1=http://etcd1:2380,etcd2=http://etcd2:2380,etcd3=http://etcd3:2380
      - ETCD_INITIAL_CLUSTER_STATE=new
      - ETCD_INITIAL_CLUSTER_TOKEN=etcd-cluster
      - ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
      - ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
      - ETCD_ADVERTISE_CLIENT_URLS=http://etcd2:2379
      - ETCD_INITIAL_ADVERTISE_PEER_URLS=http://etcd2:2380
    ports:
      - "2380:2379"
    volumes:
      - etcd2-data:/etcd-data
    networks:
      - etcd-net

  etcd3:
    image: quay.io/coreos/etcd:v3.5.16
    environment:
      - ETCD_NAME=etcd3
      - ETCD_INITIAL_CLUSTER=etcd1=http://etcd1:2380,etcd2=http://etcd2:2380,etcd3=http://etcd3:2380
      - ETCD_INITIAL_CLUSTER_STATE=new
      - ETCD_INITIAL_CLUSTER_TOKEN=etcd-cluster
      - ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
      - ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
      - ETCD_ADVERTISE_CLIENT_URLS=http://etcd3:2379
      - ETCD_INITIAL_ADVERTISE_PEER_URLS=http://etcd3:2380
    ports:
      - "2381:2379"
    volumes:
      - etcd3-data:/etcd-data
    networks:
      - etcd-net

volumes:
  etcd1-data:
  etcd2-data:
  etcd3-data:

networks:
  etcd-net:
    driver: bridge

核心配置参数

etcd 命令行参数速查表

参数 说明 默认值 示例
--name 节点名称（集群内唯一） default etcd-01
--data-dir 数据存储目录 ${name}.etcd /var/lib/etcd
--listen-client-urls 客户端请求监听地址 http://localhost:2379 http://0.0.0.0:2379
--advertise-client-urls 对外公告的客户端地址 http://localhost:2379 http://10.0.0.1:2379
--listen-peer-urls 节点间通信监听地址 http://localhost:2380 http://0.0.0.0:2380
--initial-advertise-peer-urls 对外公告的节点通信地址 http://localhost:2380 http://10.0.0.1:2380
--initial-cluster 集群初始节点列表 — etcd1=http://10.0.0.1:2380,etcd2=...
--initial-cluster-state 集群初始状态 new new / existing
--initial-cluster-token 集群唯一标识 Token etcd-cluster my-etcd-cluster
--snapshot-count 多少次提交后触发快照 100000 50000
--heartbeat-interval Raft 心跳间隔（ms） 100 100
--election-timeout Raft 选举超时（ms） 1000 1000
--max-request-bytes 单个请求最大字节数 1572864（1.5MB） 10485760
--quota-backend-bytes 后端数据库最大大小 2147483648（2GB） 8589934592（8GB）
--auto-compaction-mode 自动压缩模式 — periodic / revision
--auto-compaction-retention 自动压缩保留时间（h）或版本数 — 1
--log-level 日志级别 info debug / info / warn / error
--cipher-suites TLS 加密套件列表 — TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,...

关键配置说明

  • --initial-cluster-state：new 用于启动新集群；已有集群重启或新增节点时使用 existing
  • --quota-backend-bytes：超过此值后写入被拒绝，必须手动压缩和碎片整理
  • --snapshot-count：值越小快照越频繁，占用空间越小但 IO 压力越大

etcdutl 工具

etcdutl 是 etcd 的离线运维工具（v3.5+ 从 etcdctl 中独立出来），主要用于：

# 查看后端数据库状态
etcdutl backend status /var/lib/etcd

# 检查数据完整性
etcdutl backend check /var/lib/etcd

# 读取快照状态
etcdutl snapshot status backup.db

# 离线碎片整理
etcdutl defrag /var/lib/etcd

# 快照内提取键值数据（调试用）
mkdir out && etcdutl snapshot restore backup.db --data-dir out

💡 最佳实践：定期检查 quota-backend-bytes 使用率（etcdctl endpoint status），接近上限前触发压缩。生产环境务必配置 --auto-compaction-mode=periodic --auto-compaction-retention=1。

核心概念