在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

etcd-io/etcd

菜单

操作指南

相关源文件

本指南提供在生产环境中部署、监控和维护 etcd 的实用信息。它涵盖了配置、监控、维护、升级和故障排除 etcd 集群等关键运营方面。有关 etcd 内部架构的信息，请参阅 架构。有关面向开发的指导，请参阅 开发指南。

部署和配置

硬件建议

对于生产部署，推荐以下最低要求：

  • CPU：2+ 核心（重负载场景建议 4+ 核心）
  • 内存：8GB+ RAM
  • 磁盘：强烈建议为 WAL 和数据目录使用 SSD
  • 网络：集群成员之间需要低延迟、高带宽的连接

部署拓扑

来源

关键配置参数

etcd 运行的关键参数类别如下：

成员配置

参数描述默认建议
--name此成员的易读名称默认选择一个描述性的名称
--data-dir数据目录的路径${name}.etcd使用专用的 SSD 卷
--wal-dir专用 WAL 目录的路径"" (与 data-dir 相同)与 data-dir 分开以获得更好的性能
--listen-peer-urls用于监听成员间通信的 URLhttp://:2380生产环境请使用安全 URL
--listen-client-urls用于监听客户端通信的 URLhttp://:2379配置内部和外部接口
--listen-client-http-urls仅用于监听 HTTP 客户端通信的 URL""当分离 gRPC 和 HTTP 流量时很有用

集群配置

参数描述默认建议
--initial-advertise-peer-urls广告给其他成员的 URLhttp://:2380所有成员都必须能够访问
--advertise-client-urls广告给客户端的 URLhttp://:2379所有客户端都必须能够访问
--initial-cluster初始集群配置default=http://:2380列出所有初始成员
--initial-cluster-token集群令牌etcd-cluster每个集群使用唯一的令牌
--initial-cluster-state初始集群状态new新集群使用 new，添加成员时使用 existing

存储和性能参数

参数描述默认建议
--quota-backend-bytes后端配额大小0 (低空间配额)根据可用磁盘空间设置（例如 8GB）
--snapshot-count快照前的事务数10000v3.6 中已弃用，将在 v3.7 中移除
--auto-compaction-mode压缩模式periodic基于时间的使用 periodic，基于版本的使用 revision
--auto-compaction-retention保留周期/版本数0（已禁用）24h 用于 periodic，或适当的版本数
--max-request-bytes最大客户端请求大小1.5MB根据您的数据大小需求调整

来源

示例配置文件

下面是一个生产 etcd 节点的示例配置文件

来源

监控和维护

健康监控

来源

运行状况检查端点

etcd 提供了几个端点来检查其健康状态

  1. 成员健康：/health HTTP 端点返回成员的健康状态
  2. 集群健康：使用 etcdctl endpoint health 检查所有端点的健康状况
  3. 指标：/metrics HTTP 端点提供 Prometheus 格式的指标
  4. 存活/就绪状态：/livez 和 /readyz HTTP 端点（v3.5+ 添加）用于 Kubernetes 风格的健康检查

来源

要监控的关键指标

根据最佳实践和更改日志条目，以下是需要监控的关键指标

集群健康指标

指标描述警报阈值
etcd_server_has_leader指示是否存在领导者为 0 时警报
etcd_server_leader_changes_seen_total领导者变更次数频繁变更时警报
etcd_server_proposals_failed_total失败的提议快速增加时警报
etcd_network_client_grpc_sent_bytes_total网络流量显著偏差时警报
etcd_network_client_grpc_received_bytes_total网络流量显著偏差时警报

性能和资源指标

指标描述警报阈值
etcd_disk_backend_commit_duration_seconds磁盘写入延迟持续高（>100ms）时警报
etcd_disk_wal_write_bytes_total写入 WAL 的字节数监控趋势
etcd_mvcc_db_total_size_in_bytes数据库大小接近配额时警报
etcd_debugging_mvcc_current_revision当前 MVCC 版本监控异常跳跃
etcd_server_slow_apply_total慢速应用请求持续增加时警报
etcd_server_slow_read_total慢速读取请求持续增加时警报
os_fd_used 和 os_fd_limit文件描述符使用情况接近限制时警报

来源

定期维护任务

碎片整理

为了回收磁盘空间和提高性能，建议定期进行碎片整理

注意：在 v3.5+ 中，您可以使用 --experimental-stop-grpc-service-on-defrag（或 v3.6+ 中的相应功能门）在碎片整理期间临时停止 gRPC 服务，以便客户端故障转移到其他成员。

来源

数据库压缩

自动压缩通过 --auto-compaction-mode 和 --auto-compaction-retention 配置。手动压缩请

来源

备份与恢复

定期备份对于灾难恢复至关重要

为了在恢复快照时提供额外的安全性，v3.6+ 提供了增加版本和标记已压缩的选项

来源

集群管理

成员管理

来源

添加成员

移除成员

替换故障成员

来源

灾难恢复

在大多数集群成员丢失的情况下

  1. 从最新的快照创建一个新的单成员集群
  1. 验证恢复的集群是否具有预期的数据
  2. 逐个向集群添加新成员

来源

升级 etcd

版本兼容性和建议

生产环境最低推荐版本

  • 3.4.x 系列推荐 v3.4.22+
  • 3.5.x 系列推荐 v3.5.6+
  • 任何 v3.6.x 版本

重要的升级注意事项

  • etcd 向后兼容前一个次要版本
  • 建议进行滚动升级以最大限度地减少中断
  • 升级前备份数据
  • 查看更新日志以了解破坏性变更

来源

滚动升级流程

用于在停机时间最少的情况下升级

  1. 一次升级一个成员
  2. 在继续进行下一个成员之前，验证每个成员的健康状况

来源

特定版本的升级说明

升级到 v3.6

v3.6 中的主要变更

  • 删除了 v2 API 支持
  • 将许多实验性标志重命名为常规标志或功能开关
  • 更改了服务器包的目录结构
  • 删除了几个已弃用的标志

来源

性能调优

关键性能参数

来源

性能调优指南

存储性能

参数建议
--quota-backend-bytes生产环境至少设置为 8GB
--backend-batch-interval增加此值可提高吞吐量，但会增加延迟
--backend-batch-limit默认值 (0) 使用 10000，批量操作时增加此值
--backend-bbolt-freelist-type使用 map 以获得更好的性能（默认）
--compaction-batch-limit限制每次压缩批次中删除的修订次数
--compaction-sleep-interval控制压缩批次之间的睡眠间隔

网络性能

参数建议
--max-request-bytes默认 1.5MB，如果存储更大的值，请增加此值
--max-concurrent-streams限制每个客户端的并发流数
--grpc-keepalive-min-time防止客户端过于频繁地 ping
--grpc-keepalive-interval服务器到客户端 ping 的间隔
--grpc-keepalive-timeout无响应连接的超时时间

Raft 协议调优

参数建议
--heartbeat-interval默认 100ms，可根据不同的网络环境进行调整
--election-timeout默认 1000ms (10 倍心跳间隔)，针对跨数据中心部署进行调整
--initial-election-tick-advance默认 true，有助于更快的初始领导者选举

来源

常见的性能问题和解决方案

问题原因解决方案
高延迟磁盘 I/O 缓慢使用 SSD，分离 WAL 目录
网络问题确保成员之间有低延迟的网络
值过大etcd 针对小值（<1MB）进行了优化
过高的内存使用过多的 Watcher限制 Watcher 数量，添加分页
过大的历史窗口调整压缩设置
频繁的领导者变更网络不稳定增加选举超时时间
高 CPU 负载确保有足够的 CPU 资源
数据库大小增长没有进行压缩启用自动压缩
碎片化定期碎片整理

来源

安全配置

TLS 配置

来源

认证与授权

etcd 支持基于角色的访问控制 (RBAC) 来处理 API 请求。

身份验证令牌选项

来源

网络安全注意事项

  1. 防火墙规则:

    • 限制对 etcd 端口（客户端为 2379，对等节点为 2380）的访问
    • 只允许受信任的客户端与 etcd 通信

  2. 主机白名单:

    • 使用 --host-whitelist 限制接受的主机名
    • 默认 * 允许任何主机名（非 TLS 时不安全）

  3. CORS 设置:

    • 使用 --cors 限制跨域资源共享
    • 默认 * 允许任何来源，生产环境中请限制

  4. 密码套件:

    • 使用 --cipher-suites 控制允许的密码套件
    • 将 --tls-min-version 设置为 TLS1.2 或更高版本

来源

故障排除

常见问题与解决方案

问题可能原因故障排除步骤
集群无法形成Peer URL 配置错误检查 --initial-cluster 是否与每个成员的advertised peer URLs匹配
集群 Token 不匹配确保所有成员使用相同的 --initial-cluster-token
防火墙阻止通信检查成员之间在 2380 端口上的连通性
认证失败证书过期检查证书有效性，过期则续期
CA 证书错误验证所有成员的 CA 证书是否一致
主机名验证失败检查 --client-cert-allowed-hostname 设置
数据不一致网络分区导致脑裂如果法定人数丢失，则从备份中恢复
后端数据损坏使用 etcdctl alarm list 检查警报
内存使用率高大量 Watcher通过指标检查 Watcher 数量
大型事务监控 etcd_debugging_mvcc_index_compaction_pause_duration_milliseconds
性能缓慢磁盘 I/O 瓶颈检查磁盘延迟，考虑使用 SSD
网络延迟监控成员之间的网络指标
数据库碎片化执行碎片整理

来源

警报处理

etcd 可能会发出需要操作员关注的警报

如果检测到损坏

  1. 使用 /health 端点识别损坏的成员
  2. 从集群中移除该成员
  3. 添加一个带有干净数据目录或从备份恢复的新成员

来源

诊断命令

来源

最佳实践总结

  1. 集群大小:

    • 生产环境至少使用 3 个成员
    • 5 个成员以提高容错能力
    • 7 个及以上成员可能会引入性能开销

  2. 数据安全:

    • 定期使用 etcdctl snapshot save 进行备份
    • 定期测试恢复过程
    • 启用自动压缩

  3. 性能:

    • 为数据目录使用 SSD
    • 考虑为 WAL 使用单独的磁盘
    • 监控磁盘空间使用情况
    • 定期碎片整理

  4. 安全:

    • 生产环境始终使用 TLS
    • 实施适当的 RBAC
    • 严格的防火墙规则
    • 定期轮换证书

  5. 监控:

    • 为关键指标设置警报
    • 监控 Leader 变更
    • 当数据库大小接近配额时发出警报
    • 关注磁盘 I/O 延迟

  6. 升级:

    • 升级前务必备份
    • 使用滚动升级
    • 验证客户端应用程序的兼容性
    • 查看更新日志以了解破坏性更改

来源