etcd 使用说明

 

启动模式与配置文件

模式/选项

功能描述

示例

etcd [flags]

以指定命令行参数启动 etcd 服务器

etcd --name node1 --data-dir /var/lib/etcd

etcd --version

显示 etcd 版本信息

etcd --version

etcd -h或 etcd --help

显示帮助信息

etcd -h

etcd --config-file

从配置文件启动（使用配置文件时，其他命令行参数和环境变量将被忽略）

etcd --config-file /etc/etcd/etcd.conf.yml

etcd gateway

启动无状态 TCP 连接转发网关（用于 v2 API 的 TCP 代理）

etcd gateway start --endpoints=localhost:2379

etcd grpc-proxy

启动无状态 gRPC L7 反向代理（用于 v3 API 的负载均衡和故障转移）

etcd grpc-proxy start --endpoints=localhost:2379

注意：gateway和 grpc-proxy是独立的模式，有自己的一组参数，通常用于特定的代理场景。

成员配置 (Member)

参数

默认值

功能描述

生产环境建议

--name

'default'

成员的人类可读名称，在集群中唯一标识一个节点

使用有意义的主机名或角色名，如 etcd-node-1

--data-dir

'${name}.etcd'

数据目录路径，存储快照、WAL 文件和成员信息

使用独立的高性能 SSD 盘，如 /var/lib/etcd

--wal-dir

''

专门的 WAL (Write Ahead Log) 目录路径（为空时存储在 data-dir 中）

高性能场景可分离 WAL 目录到独立磁盘以提高性能

--snapshot-count

100000

触发快照的已提交事务数

通常保持默认，IO 密集型场景可适当调高

--heartbeat-interval

100

心跳间隔（毫秒）。影响领导者发送心跳的频率

生产环境通常 100-400ms，内网质量好可设 100ms

--election-timeout

1000

选举超时时间（毫秒）。追随者等待领导者心跳的超时时间

通常是 heartbeat-interval的 5-10 倍，如 1000-4000ms

--initial-election-tick-advance

true

是否在启动时快速推进初始选举计时器以加速选举

保持默认 true 以加速初始选举

--listen-peer-urls

'http://localhost:2380'

监听对等通信（节点间通信）的 URL 列表

必须配置为可被集群其他节点访问的地址

--listen-client-urls

'http://localhost:2379'

监听客户端通信的 URL 列表

包括本地地址和可被客户端访问的地址

--max-snapshots

5

保留的最大快照文件数（0 表示无限制）

根据磁盘空间和备份策略设置，通常 5-10 个

--max-wals

5

保留的最大 WAL 文件数（0 表示无限制）

通常保持默认 5 个

--quota-backend-bytes

0

后端存储配额（字节），超过会触发空间不足告警

设置为小于磁盘容量的值，如 8GB: 8589934592

--backend-batch-interval

''

后端批处理提交的最大间隔时间

空表示使用默认值，通常不需要调整

--backend-batch-limit

0

后端批处理提交前的最大操作数

0 表示使用默认值，通常不需要调整

--max-txn-ops

128

单个事务中允许的最大操作数

根据业务需求调整，默认 128 对多数场景足够

--max-request-bytes

1572864

服务器接受的最大客户端请求大小（字节，约 1.5MB）

大键值场景可适当增加，如 10MB: 10485760

--grpc-keepalive-min-time

5s

客户端 ping 服务器前的最小等待时间

保持默认

--grpc-keepalive-interval

2h

服务器 ping 客户端检查连接存活的频率（0 表示禁用）

保持默认 2h

--grpc-keepalive-timeout

20s

关闭无响应连接前的额外等待时间（0 表示禁用）

保持默认 20s

集群配置 (Clustering)

参数

默认值

功能描述

生产环境建议

--initial-advertise-peer-urls

'http://localhost:2380'

向集群其他成员广告的对等通信 URL​

必须是其他节点可访问的地址，强烈建议使用静态IP或域名​

--initial-cluster

'default=http://localhost:2380'

初始集群成员列表（引导时使用）

格式：node1=http://ip1:2380,node2=http://ip2:2380,node3=http://ip3:2380

--initial-cluster-state

'new'

初始集群状态：'new'（新建集群）或 'existing'（加入现有集群）

首次启动设为 'new'，后续节点启动设为 'existing'

--initial-cluster-token

'etcd-cluster'

集群初始令牌，防止意外跨集群交互

为每个集群设置唯一令牌

--advertise-client-urls

'http://localhost:2379'

向客户端广告的客户端通信 URL​

必须是客户端可访问的地址，可以是负载均衡器地址

--discovery

''

用于引导集群的发现服务 URL

使用 etcd 发现服务时设置，如：https://discovery.etcd.io/<token>

--discovery-fallback

'proxy'

发现服务失败时的行为：'exit' 或 'proxy'

通常保持 'proxy'，但注意 proxy 仅支持 v2 API

--discovery-proxy

''

访问发现服务使用的 HTTP 代理

需要代理访问外部发现服务时设置

--discovery-srv

''

用于引导集群的 DNS SRV 记录域名

如：_etcd-server._tcp.example.com

--discovery-srv-name

''

DNS SRV 查询的后缀

与 discovery-srv 配合使用

--strict-reconfig-check

true

是否拒绝可能导致法定人数丢失的重新配置请求

生产环境必须为 true 以确保安全

--pre-vote

false

是否启用预投票阶段（可防止网络分区导致的不必要选举）

建议设置为 true 以提高选举稳定性

--auto-compaction-retention

0

自动压缩保留策略：0 表示禁用，>0 表示保留时间或版本数

如：'1h' 保留1小时历史，或 1000 保留1000个修订版本

--auto-compaction-mode

'periodic'

自动压缩模式：'periodic'（基于时间）或 'revision'（基于版本数）

与 auto-compaction-retention 配合使用

--enable-v2

false

是否接受 v2 API 请求

除非有兼容性需求，否则保持 false（v3 更高效）

安全配置 (Security)

参数

默认值

功能描述

生产环境建议

--cert-file

''

客户端 TLS 证书文件路径

必须与 key-file 配对使用，如 /etc/etcd/server.crt

--key-file

''

客户端 TLS 私钥文件路径

如 /etc/etcd/server.key

--client-cert-auth

false

是否启用客户端证书认证

生产环境建议设为 true 增强安全性

--client-crl-file

''

客户端证书吊销列表文件路径

需要证书吊销时设置

--client-cert-allowed-hostname

''

允许的客户端证书主机名

用于限制客户端证书的 SAN 字段

--trusted-ca-file

''

客户端 TLS 信任的 CA 证书文件路径

验证客户端证书的 CA，如 /etc/etcd/ca.crt

--auto-tls

false

是否使用自动生成的 TLS 证书（仅用于测试）

生产环境必须设为 false，使用手动配置的证书

--peer-cert-file

''

对等通信 TLS 证书文件路径

节点间 TLS 通信证书，如 /etc/etcd/peer.crt

--peer-key-file

''

对等通信 TLS 私钥文件路径

如 /etc/etcd/peer.key

--peer-client-cert-auth

false

是否启用对等客户端证书认证

生产环境建议设为 true

--peer-trusted-ca-file

''

对等通信 TLS 信任的 CA 证书文件路径

如 /etc/etcd/peer-ca.crt

--peer-cert-allowed-cn

''

对等连接要求的客户端证书通用名

限制对等节点的证书 CN 字段

--peer-cert-allowed-hostname

''

允许的对等证书主机名

限制对等证书的 SAN 字段

--peer-auto-tls

false

是否使用自动生成的对等 TLS 证书

生产环境必须设为 false

--peer-crl-file

''

对等证书吊销列表文件路径

需要证书吊销时设置

--cipher-suites

''

支持的 TLS 密码套件列表（逗号分隔）

指定强密码套件增强安全性

--cors

'*'

CORS 允许的来源（逗号分隔，* 表示允许所有）

按需限制来源增强安全性

--host-whitelist

'*'

接受 HTTP 请求的主机名白名单（服务器不安全时）

启用 TLS 时此设置无效

认证配置 (Auth)

参数

默认值

功能描述

生产环境建议

--auth-token

'simple'

v3 认证令牌类型：'simple' 或 'jwt'

通常使用 'simple'，JWT 适用于微服务场景

--bcrypt-cost

10

bcrypt 密码哈希算法的成本/强度（4-31）

保持默认 10，过高会影响性能

--auth-token-ttl

300

认证令牌的生存时间（秒）

根据安全策略调整，通常 300-3600 秒

性能分析与监控 (Profiling and Monitoring)

参数

默认值

功能描述

生产环境建议

--enable-pprof

false

是否通过 HTTP 服务器启用运行时性能分析

调试时启用，生产环境通常禁用

--metrics

'basic'

导出指标的详细程度：'basic' 或 'extensive'

监控需求高时设为 'extensive'（有性能开销）

--listen-metrics-urls

''

监听指标和健康检查端点的 URL 列表

如：http://localhost:2381用于暴露 Prometheus 指标

日志配置 (Logging)

参数

默认值

功能描述

生产环境建议

--logger

'capnslog'

日志记录器：'zap'（结构化日志）或 'capnslog'

推荐 'zap'，capnslog 将在 v3.5 弃用​

--log-outputs

'default'

日志输出目标：'stdout'、'stderr' 或逗号分隔的目标列表

容器化部署用 'stdout'，系统服务用文件路径

--log-level

'info'

日志级别：debug, info, warn, error, panic, fatal

生产环境用 'info' 或 'warn'，调试用 'debug'

--log-package-levels

''

为每个包指定日志级别（即将弃用）

如：'etcdserver=DEBUG,etcdmain=CRITICAL'

v2 代理配置 (v2 Proxy) - 即将在 v4 中弃用

参数

默认值

功能描述

注意

--proxy

'off'

代理模式：'off'、'readonly' 或 'on'

v2 API 代理功能，新集群不应使用

--proxy-failure-wait

5000

端点被标记为失败状态的持续时间（毫秒）

  

--proxy-refresh-interval

30000

端点刷新间隔（毫秒）

  

--proxy-dial-timeout

1000

拨号超时时间（毫秒）

  

--proxy-write-timeout

5000

写入超时时间（毫秒）

  

--proxy-read-timeout

0

读取超时时间（毫秒），0 表示不超时

  

实验性功能 (Experimental Feature)

参数

默认值

功能描述

注意

--experimental-initial-corrupt-check

false

是否在服务客户端/对等流量前检查数据损坏

启用可确保数据完整性，但增加启动时间

--experimental-corrupt-check-time

0s

集群数据损坏检查的时间间隔

0 表示不进行周期性检查

--experimental-enable-v2v3

''

通过 v3 后端在指定前缀下提供 v2 API 请求

如：'/v2'，用于 v2 到 v3 的迁移

--experimental-backend-bbolt-freelist-type

'array'

后端 bbolt 使用的空闲列表类型：'array' 或 'map'

map 类型在某些场景下性能更好

--experimental-enable-lease-checkpoint

false

启用主租赁者持久化租约剩余 TTL 以防止长期租约无限自动续期

启用可防止租约无限期续期

--experimental-compaction-batch-limit

1000

每次压缩批处理中删除的最大修订版本数

调整压缩性能

--experimental-peer-skip-client-san-verification

false

跳过对等连接中客户端证书 SAN 字段的验证

仅用于测试，生产环境禁用

--experimental-watch-progress-notify-interval

10m

定期发送 watch 进度通知的时间间隔

长连接 watch 场景可调整

不安全功能 (Unsafe Feature)

参数

默认值

功能描述

警告

--force-new-cluster

false

强制创建新的单成员集群（用于灾难恢复）

危险：会破坏一致性保证，仅用于恢复场景

已弃用参数 (TO BE DEPRECATED)

参数

默认值

替代方案

弃用版本

--debug

false

使用 --log-level=debug

v3.5

--log-package-levels

''

暂无直接替代，通过日志配置文件控制

v3.5

生产环境启动配置示例

# 三节点 etcd 集群的典型启动参数（节点1示例）
etcd \
  --name etcd-node-1 \
  --data-dir /var/lib/etcd \
  --wal-dir /var/lib/etcd/wal \
  --listen-peer-urls https://192.168.1.101:2380 \
  --listen-client-urls https://192.168.1.101:2379,https://127.0.0.1:2379 \
  --initial-advertise-peer-urls https://etcd-node-1.example.com:2380 \
  --advertise-client-urls https://etcd.example.com:2379 \
  --initial-cluster-token my-etcd-cluster \
  --initial-cluster etcd-node-1=https://etcd-node-1.example.com:2380,etcd-node-2=https://etcd-node-2.example.com:2380,etcd-node-3=https://etcd-node-3.example.com:2380 \
  --initial-cluster-state new \
  --heartbeat-interval 200 \
  --election-timeout 2000 \
  --snapshot-count 10000 \
  --quota-backend-bytes 8589934592 \
  --max-snapshots 5 \
  --max-wals 5 \
  --auto-compaction-retention 2h \
  --auto-compaction-mode periodic \
  --cert-file /etc/etcd/ssl/server.crt \
  --key-file /etc/etcd/ssl/server.key \
  --peer-cert-file /etc/etcd/ssl/peer.crt \
  --peer-key-file /etc/etcd/ssl/peer.key \
  --trusted-ca-file /etc/etcd/ssl/ca.crt \
  --peer-trusted-ca-file /etc/etcd/ssl/ca.crt \
  --client-cert-auth true \
  --peer-client-cert-auth true \
  --logger zap \
  --log-level info \
  --log-outputs stdout \
  --metrics extensive \
  --listen-metrics-urls http://localhost:2381

关键注意事项

  1. TLS 配置：生产环境必须启用 TLS，为客户端和对等通信分别配置证书。

  2. 地址配置：

    • listen-peer-urls：集群内部通信地址

    • advertise-client-urls：客户端访问地址

    • initial-advertise-peer-urls：集群节点间通信的广告地址

  3. 集群引导：

    • 首次启动集群时，所有节点使用相同的 initial-cluster列表和 initial-cluster-state new

    • 已有集群添加节点时，使用 initial-cluster-state existing

  4. 数据目录：确保数据目录在快速、可靠的存储上，并有足够的磁盘空间。

  5. 选举参数：

    • election-timeout必须大于 heartbeat-interval

    • 通常设置为：election-timeout = 5-10 * heartbeat-interval

  6. 监控：通过 --listen-metrics-urls暴露指标，使用 Prometheus 监控集群健康状态。

posted @ 2026-01-12 10:23  小吉猫  阅读(4)  评论(0)    收藏  举报