【ETCD】etcd中配置参数详解

详细记录etcd服务启动的各个参数

1、etcd成员相关的配置项

--name 'default'  
  为该成员指定一个易读的名称。

--data-dir '${name}.etcd'  
  数据存储目录的路径。

--wal-dir ''  
  用于存放专用WAL（Write-Ahead Log）的目录路径。

--snapshot-count '100000'  
  触发快照到磁盘的已提交事务数量。

--heartbeat-interval '100'  
  心跳间隔时间（毫秒）。

--election-timeout '1000'  
  选举超时时间（毫秒）。详见调优文档。

--initial-election-tick-advance 'true'  
  是否在启动时加速初始选举计时，从而加快选举速度。

--listen-peer-urls 'http://localhost:2380'  
  用于监听对等节点流量的URL列表。

--listen-client-urls 'http://localhost:2379'  
  用于监听客户端 gRPC 和 HTTP 流量的 URL 列表（当未指定 --listen-client-http-urls 时生效）。

--listen-client-http-urls ''  
  仅用于 HTTP 客户端流量的 URL 列表。启用此标志会将 HTTP 服务从 --listen-client-urls 中移除。

--max-snapshots '5'  
  保留的最大快照文件数量（0表示不限制）。

--max-wals '5'  
  保留的最大WAL文件数量（0表示不限制）。

--quota-backend-bytes '0'  
  当后端大小超过给定配额时触发警报（0表示使用默认低空间配额）。

--backend-bbolt-freelist-type 'map'  
  指定Boltdb后端使用的freelist类型（支持 array 和 map 类型）。

--backend-batch-interval ''  
  提交后端事务前的最大时间间隔。

--backend-batch-limit '0'  
  提交后端事务前的最大操作数。

--max-txn-ops '128'  
  每个事务允许的最大操作数。

--max-request-bytes '1572864'  
  服务器可接受的客户端请求的最大字节数。

--grpc-keepalive-min-time '5s'  
  客户端在发送ping请求前应等待的最短时间间隔。

--grpc-keepalive-interval '2h'  
  服务器向客户端发送ping以检查连接是否存活的频率（0表示禁用）。

--grpc-keepalive-timeout '20s'  
  在关闭无响应连接前的额外等待时间（0表示禁用）。

--socket-reuse-port 'false'  
  启用后允许监听器设置SO_REUSEPORT选项，支持对已使用端口的重新绑定。

--socket-reuse-address 'false'  
  启用后允许监听器设置SO_REUSEADDR选项，支持绑定处于TIME_WAIT状态的地址。

2、Etcd集群引导和发现配置参数

--initial-advertise-peer-urls 'http://localhost:2380'  
  向集群中其他成员宣传的该节点的对等节点URL列表。

--initial-cluster 'default=http://localhost:2380'  
  引导时的初始集群配置。

--initial-cluster-state 'new'  
  初始集群状态（'new'表示新集群，'existing'表示已有集群）。

--initial-cluster-token 'etcd-cluster'  
  引导期间用于etcd集群的初始集群令牌。  
  指定该令牌可防止在运行多个集群时出现意外的跨集群交互。

--advertise-client-urls 'http://localhost:2379'  
  向外部公开宣传的该节点的客户端URL列表。  
  这些URL应可供与etcd集群通信的机器访问，etcd客户端库会解析这些URL以连接到集群。

--discovery ''  
  用于集群引导的发现URL。

--discovery-fallback 'proxy'  
  当发现服务失败时的预期行为（'exit'或'proxy'）。  
  'proxy'仅支持v2 API。

--discovery-proxy ''  
  访问发现服务时使用的HTTP代理。

--discovery-srv ''  
  用于引导集群的DNS SRV域。

--discovery-srv-name ''  
  引导时查询的DNS SRV名称后缀。

--strict-reconfig-check 'true'  
  拒绝可能导致法定人数丧失的重新配置请求。

--pre-vote 'true'  
  启用Raft预投票算法，以防止隔离的节点重新加入集群时引发中断。

--auto-compaction-retention '0'  
  自动压缩的保留时长。0表示禁用自动压缩。

--auto-compaction-mode 'periodic'  
  解释'auto-compaction-retention'的模式，可选'periodic'或'revision'。  
  'periodic'表示基于时间的保留，默认单位为小时（如'5m'表示5分钟）。  
  'revision'表示基于修订号的保留。

--enable-v2 'false'  
  接受etcd V2客户端请求。已被弃用，并将在v3.6中移除。

--v2-deprecation 'not-yet'  
  v2存储的弃用阶段。允许选择更高的兼容模式。支持的值：  
    'not-yet'                // 如果v2存储有有效内容，发出警告（v3.5默认值）。  
    'write-only'             // 不允许自定义v2状态（计划在v3.6中默认启用）。  
    'write-only-drop-data'   // 自定义的v2状态将被删除！  
    'gone'                   // v2存储不再维护（计划在v3.7中成为默认值）。

3、Etcd安全和TLS配置

--cert-file ''  
  客户端服务器TLS证书文件的路径。

--key-file ''  
  客户端服务器TLS密钥文件的路径。

--client-cert-auth 'false'  
  启用客户端证书认证。  
  建议启用客户端证书认证，以防止未经认证的客户端攻击（例如CVE-2023-44487），特别是在将etcd作为公共服务运行时。

--client-crl-file ''  
  客户端证书吊销列表文件的路径。

--client-cert-allowed-hostname ''  
  客户端证书认证允许的TLS主机名。

--trusted-ca-file ''  
  客户端服务器TLS受信任的CA证书文件路径。  
  设置此参数时，无论`--client-cert-auth`的值如何，都会自动启用客户端证书认证。

--auto-tls 'false'  
  使用自动生成的证书进行客户端TLS认证。

--peer-cert-file ''  
  对等节点服务器TLS证书文件的路径。

--peer-key-file ''  
  对等节点服务器TLS密钥文件的路径。

--peer-client-cert-auth 'false'  
  启用对等节点客户端证书认证。  
  建议启用对等节点证书认证，以防止未经认证的伪造对等节点攻击（例如CVE-2023-44487）。

--peer-trusted-ca-file ''  
  对等节点服务器TLS受信任的CA文件路径。

--peer-cert-allowed-cn ''  
  连接到对等端点时，客户端证书所需的CN（通用名称）。

--peer-cert-allowed-hostname ''  
  对等认证中允许的TLS主机名。

--peer-auto-tls 'false'  
  如果未提供`--peer-key-file`和`--peer-cert-file`，则使用自生成证书进行对等TLS认证。

--self-signed-cert-validity '1'  
  自动生成的客户端和对等节点证书的有效期，单位为年，默认值为1。

--peer-crl-file ''  
  对等节点证书吊销列表文件的路径。

--cipher-suites ''  
  支持的TLS密码套件列表，客户端/服务器和对等节点之间使用（空值将由Go自动填充）。

--cors '*'  
  CORS（跨域资源共享）允许的源列表，逗号分隔（空值或`*`表示允许所有源）。

--host-whitelist '*'  
  如果服务器不安全，HTTP客户端请求中可接受的主机名（空值或`*`表示允许所有主机）。

--tls-min-version 'TLS1.2'  
  etcd支持的最低TLS版本。

--tls-max-version ''  
  etcd支持的最高TLS版本（空值将由Go自动填充）。

4、etcd认证相关参数

--auth-token 'simple'  
  指定v3认证的令牌类型及特定选项，特别适用于JWT。格式为"type,var1=val1,var2=val2,..."。  
  可选类型：'simple'或'jwt'。  
  可用变量：  
  - `sign-method`: 指定JWT的签名方法，可选值为 'ES256'、'ES384'、'ES512'、'HS256'、'HS384'、'HS512'、'RS256'、'RS384'、'RS512'、'PS256'、'PS384' 或 'PS512'。  
  - `pub-key`: 指定用于验证JWT的公钥路径。  
  - `priv-key`: 指定用于签署JWT的私钥路径。  
  - `ttl`: 指定JWT令牌的生存时间（TTL）。

--bcrypt-cost 10  
  指定用于哈希认证密码的bcrypt算法的成本/强度。有效值为4到31之间的整数，值越高，计算成本越高，安全性越强。

--auth-token-ttl 300  
  认证令牌的生存时间（TTL），单位为秒。

5、etcd性能监控与指标

--enable-pprof 'false'  
  是否启用通过HTTP服务器提供的运行时性能分析数据。  
  地址为客户端URL加上"/debug/pprof/"。

--metrics 'basic'  
  设置导出指标的详细程度。  
  可选值：  
  - `basic`: 导出基本指标。  
  - `extensive`: 包括服务器端gRPC直方图指标在内的详细指标。

--listen-metrics-urls ''  
  用于监听指标和健康检查端点的URL列表。

6、etcd日志配置

--logger 'zap'  
  当前仅支持使用'Zap'进行结构化日志记录。

--log-outputs 'default'  
  指定日志输出目标。  
  - 可以使用'stdout'或'stderr'来跳过`journald`日志（即使在`systemd`下运行）。  
  - 也可以提供逗号分隔的输出目标列表。

--log-level 'info'  
  配置日志级别。支持的级别包括：  
  - `debug`: 调试信息。  
  - `info`: 普通信息。  
  - `warn`: 警告信息。  
  - `error`: 错误信息。  
  - `panic`: 崩溃信息。  
  - `fatal`: 致命错误信息。

--enable-log-rotation 'false'  
  是否启用日志轮转，仅适用于单个日志输出文件。

--log-rotation-config-json '{"maxsize": 100, "maxage": 0, "maxbackups": 0, "localtime": false, "compress": false}'  
  配置日志轮转（启用时生效）。  
  - `maxsize`: 单个日志文件的最大大小（单位：MB）。  
  - `maxage`: 日志文件的最大保留天数（0表示不限制）。  
  - `maxbackups`: 最大备份数量（0表示不限制）。  
  - `localtime`: 是否使用本地时间。  
  - `compress`: 是否启用gzip压缩。

Etcd 启动重要参数汇总表

分类	参数	作用	备注
节点配置	--name	设置节点名称，必须唯一。	确保集群中节点识别准确。
	--data-dir	指定数据存储目录。	用于持久化存储etcd数据。
集群配置	--initial-advertise-peer-urls	设置对等节点的广告URL。	集群内节点间通信地址。
	--listen-peer-urls	设置对等节点的监听URL。	监听集群内部通信流量。
	--listen-client-urls	设置客户端访问的监听URL。	客户端连接etcd的入口。
	--initial-cluster	配置初始集群成员列表。	启动新集群时必需。
	--initial-cluster-state	指定集群状态（new或existing）。	新建或加入已有集群时使用。
	--initial-cluster-token	设置集群唯一标识符。	防止跨集群的意外交互。
安全配置	--cert-file / --key-file	设置TLS证书和密钥文件。	启用加密通信。
	--client-cert-auth	启用客户端证书认证。	增强安全性，防止未经认证访问。
	--trusted-ca-file	设置受信任的CA证书路径。	验证客户端和对等节点证书。
	--peer-client-cert-auth	启用对等节点证书认证。	提高集群安全性。
	--peer-trusted-ca-file	设置对等节点的CA证书路径。	对等通信的信任链验证。
性能调优	--heartbeat-interval	设置心跳间隔时间（毫秒）。	影响集群同步速度和稳定性。
	--election-timeout	设置选举超时时间（毫秒）。	影响Raft选举速度。
	--snapshot-count	设置触发快照的事务数。	控制快照频率，平衡性能与存储。
	--max-txn-ops	设置每个事务允许的最大操作数。	防止事务过大影响性能。
认证与访问控制	--auth-token	指定认证令牌类型。	支持simple和jwt类型。
	--auth-token-ttl	设置认证令牌的有效时间（秒）。	控制令牌过期时间。
日志管理	--logger	设置日志记录方式。	当前仅支持zap。
	--log-level	设置日志级别。	支持debug、info、warn等。
	--log-outputs	设置日志输出目标。	可指定stdout、stderr或文件路径。
调试与监控	--enable-pprof	启用性能分析。	通过/debug/pprof/访问性能数据。
	--metrics	设置导出指标的详细程度。	支持basic和extensive。

说明：

• 节点与集群配置 是确保集群正常启动和运行的核心，尤其在多节点部署时尤为重要。
• 安全配置 则涉及到数据和通信的加密与认证，建议在生产环境中务必启用。
• 性能调优 参数影响etcd的资源使用与集群稳定性，需要根据具体需求进行调整。
• 日志与监控 有助于故障排查和性能优化。