云原生 etcd 最佳实践¶

腾讯云云原生 etcd（Cloud Service for etcd）是基于开源 etcd 针对云原生服务场景进行优化的 etcd 托管解决方案，通过多可用区高可用架构、精细化监控告警、可靠的数据安全保障等企业级能力，为用户提供"开箱即用"的分布式存储解决方案。

etcd 在元数据存储、服务发现、分布式选举等业务场景被大量使用，为了让您更好的使用好 etcd，我们从可靠性、安全性、可观测性、数据安全、常见问题与解决方案等五方面，整理了如下最佳实践，帮助业务进一步提升线上服务的稳定性，避免踩坑。

可靠性¶

部署架构¶

整体架构¶

云原生 etcd 底层资源基于 K8s StatefulSet 进行容器化部署，通过 operator 进行管理，支持将节点打散到不同的可用区，在 3 个可用区的情况下，单可用区挂掉不影响集群正常服务，节点挂掉之后可以快速自愈，最大程度降低不可用时间。数据持久化存储于腾讯云云硬盘，具备多副本的容灾能力。

多 AZ 容灾¶

云原生 etcd 支持高可用部署，当 region 存在 3 个可用区的情况下，您在创建集群时可开启此功能，开启后集群节点将部署在 3 个可用区。

3AZ 部署场景，任意 AZ 故障都只会影响少数节点，剩余多数节点仍可维持多数派共识，保障集群正常运行，但您需要注意的是跨 AZ 部署，可能存在轻微网络延迟，对性能、延时要求极高的场景性能略微下降。如果您的业务为核心业务，对高可用要求比较高，推荐采取这种部署方式。

当 region 只存在 2 个可用区时，多 AZ 部署也具备一定的机房故障容灾能力，AZ 故障的时候，若只影响单副本，则服务整体可用。若 AZ 故障影响的是多数副本，可能存在 etcd 不可用的场景。此场景，紧急情况下，您也可以通过工单联系我们，我们可以通过单节点数据协助业务恢复。

无论那种部署模式，都强烈建议您开启定时备份功能，故障后可及时通过备份进行恢复。对数据一致性要求不高的场景，若业务未做 3AZ 容灾，当出现机房故障影响多数节点后，您可以通过此功能快速恢复集群。

存量非多 AZ 集群调整成多可用区容灾，您可以参考以下文档：etcd 多可用区容灾配置

CLB 最佳实践¶

您创建 etcd 集群时，默认使用的为共享型 CLB，共享型 CLB 实例提供并发连接数 5 万、每秒新建连接数 5000、每秒查询数（QPS）5000 的保障能力，因此您在使用时也请关注业务规模，避免因为连接数打满等因素造成服务受到影响。如果你的业务规模超出当前共享型 CLB 的性能上限，您可以通过控制台调整 CLB 规格，升级为性能容量型。详见：CLB 性能规格说明

另外 CLB 的可用性，请参考如下产品文档：CLB 可用性说明

水平垂直扩缩容¶

节点扩容和升降配¶

针对用户业务规模扩张的场景，云原生 etcd 支持控制台一键扩容/缩容、升配/降配，自动处理证书更新、配置同步等底层操作，降低运维复杂度。由于节点升降配过程会触发滚动更新，您需要在进行此操作前，确认业务是否具有 watch 重连机制，以及当前 etcd 集群的负载情况，避免因为滚动更新后触发大量 List 导致负载进一步升高，影响集群稳定性，因此建议您在集群低负载以及业务低峰期进行操作，如果您有任何疑虑，可以通过工单方式向云原生 etcd 团队寻求帮助。

具体操作说明您可参考文档：etcd 扩缩容操作指南

性能调优¶

cetcd 默认参数介绍¶

• 心跳与选举：为了平衡容错与性能，心跳与选举超时参数设置如下，能够有效降低跨 AZ 部署的网络延时影响以及避免频繁 Leader 选举。

--heartbeat-interval=500ms
--election-timeout=2500ms

• 数据压缩：为了防止存储膨胀，控制台在集群创建的高级设置中提供周期性压缩和根据 revision 压缩两种模式供您选择。其中，周期性压缩适用场景：需保留固定时间段内的历史数据（如审计、回滚需求）；根据 revision 压缩适用场景：高频写入场景（如频繁更新配置或元数据），需控制存储空间占用，您可以根据您的业务场景进行选择。

--auto-compaction-mode=revision/periodic
--auto-compaction-retention=1000/5m

• db 配额：为了防止 db 过大对 etcd 启动耗时、快照、boltdb 性能以及集群稳定性等方面造成影响，db 配额默认配置为 6GB。

--quota-backend-bytes="6442450944"

• 单个请求大小限制：默认设置为 2MB，不建议您对该参数进行修改，避免因为 expensive request 产生高昂的内存开销以及高延迟和 GC 压力。

--max-request-bytes=2MB

• snapshot-count：该参数设置为默认值 100000，此值过大会消耗较多内存，过小则的话在某节点数据落后时，如果它请求同步的日志条目 Leader 已经压缩了，此时需要将整个 db 文件发送给落后节点，然后进行快照重建，快照重建是极其昂贵的操作，对服务质量有较大影响。

如果您的集群 key 数量较少、但是 key-value 比较大、同时频繁更新，可能会出现内存压力较大，业务当前可以来工单联系我们对该值进行调整，可显著降低内存开销。

--snapshot-count=100000

如果您根据您的业务特殊需求，需要对某些参数进行调优，可以通过工单进行反馈，可以协助您进行分析和优化。

etcd 源码优化¶

源码优化及版本更新：云原生 etcd 代码在社区源码基础上针对数据安全提升、性能提升等方面都有优化，具体相关优化可参考文档：etcd 源码优化说明，并且版本上线前将经过完善的内部测试和大规模验证，通过混沌工程进行故障演练来保证新版本的稳定性。如果您有开启指定特性的需求，可以通过工单反馈。

可靠性容量数据¶

压测说明：腾讯云内部针对不同规格 etcd 集群，压测全量 List 资源，单个资源 12k 大小，资源数量在 3w、6w、9w、12w 等时的最大并发情况，在 etcd 内存达到 90% 或者 etcd 出现 OOM 时停止压测，您可以参考下表中的压测数据，针对您的业务场景估算出您 etcd 集群配置的最佳规格，以及在当前规格下，业务并发 List 是否超过 etcd 性能瓶颈，及时进行调整。

安全性¶

TLS 加密¶

控制台开启 HTTPS 双向认证¶

为了保障 etcd 集群数据传输的安全性，建议您在创建集群时，在控制台启用 Https，您需要注意的是开启后不支持修改。

客户端配置示例¶

您在启用 Https 后，可以通过如下客户端配置连接 etcd 进行相关操作。

etcdctl --endpoints=https://etcd-server:2379 \
  --cacert=ca.pem \
  --cert=client.pem \
  --key=client-key.pem \
  get key

访问来源控制¶

控制台配置安全组：您在创建 etcd 集群时还可以在控制台配置安全组，安全组具备有状态的数据包过滤功能，可用于设置云服务器、负载均衡、云数据库等实例的网络访问控制，控制实例级别的出入流量。

您在配置时需要注意，放通所选子网的 2379，2380 端口，否则可能造成 etcd 实例创建失败。

密码鉴权¶

如果您的业务场景为多个团队或业务共享同一个 etcd 集群时，密码鉴权可提供细粒度的权限隔离。但目前控制台暂不支持开启密码鉴权，您可以通过 etcdctl 工具参考如下操作进行配置。

您需要注意的是，开启密码鉴权可能有一定的性能影响，并且会导致快照失败，您可以通过工单进行反馈，我们将协助您进行处理，具体文档可参考：etcd 密码鉴权配置

基础鉴权配置¶

1. 创建 root 用户

etcdctl user add root
# 输入密码（如 root:root）此操作会生成加密存储的密码（使用 bcrypt 算法加盐加密）

2. 创建普通用户

etcdctl --user root:root user add app_user
# 输入密码（如 app_user:123456）

3. 创建角色并分配权限

# 创建角色（如 readwrite_role）
etcdctl --user root:root role add readwrite_role

# 授予角色对 `/app/config/` 路径的读写权限
etcdctl --user root:root role grant-permission readwrite_role readwrite --prefix /app/config/

4. 绑定用户与角色

etcdctl --user root:root user grant-role app_user readwrite_role

5. 启用鉴权

etcdctl --user root:root auth enable

客户端访问配置¶

# 查询键值（需携带用户名密码）
etcdctl --user app_user:123456 get /app/config/database_url

# 写入键值
etcdctl --user app_user:123456 put /app/config/api_key "secure_key_2025"

可观测性¶

基础监控¶

核心指标采集：控制台从节点资源、业务指标、实例级指标、实例接口等四个维度默认提供您需要关注的各项性能指标和可用性指标监控，并且可以根据每个监控配置对应告警。

建议您重点关注数据库大小、CPU 使用量、内存使用量等核心指标，配置相关告警。如果上述指标存在异常，可以查阅第五章常见问题与解决方案进行排查或通过工单反馈，由云原生 etcd 团队协助您解决。

监控和告警配置您可参考文档：etcd 监控告警配置

Prometheus¶

自定义监控及告警：如果基础监控无法满足您的业务需求，云原生 etcd 服务无缝对接腾讯云原生监控服务，您可以创建集群时，在控制台高级设置中关联已有 Prometheus，自行聚合需要的监控指标和面板，帮助您更好的监控 etcd 集群状态。

数据安全¶

数据备份¶

etcd 数据备份是分布式系统运维中不可或缺的环节，直接影响系统的可用性和安全性。通过结合快照备份及自动化工具，能建立有效的数据保护体系，为业务稳定运行提供坚实保障。

云原生 etcd 提供定时备份功能，为了数据安全及系统可用性，强烈建议您在控制台开启该功能。

控制台备份¶

控制台在创建集群的高级设置中支持开启集群备份策略，定时将数据备份到腾讯云对象存储 COS，开启后您还可以在控制台快照管理页对备份策略进行修改。

快照备份管理相关操作可参考文档：etcd 快照备份管理

指令备份¶

如果您对定时备份功能有疑虑，可以参考下列指令进行手动备份，将快照文件备份到本地。

etcdctl snapshot save /backup/etcd-snapshot-$(date +%Y%m%d).db

数据恢复¶

控制台恢复：云原生 etcd 控制台支持根据备份数据恢复集群，您可以在控制台快照管理页通过备份数据进行集群恢复。

如果是本地快照文件，您也可以通过控制台导入快照文件后，进行恢复。

数据同步¶

控制台数据同步：如果您有将源 etcd 数据导入到云原生 etcd 集群的需求，那您可以使用此数据同步功能，通过控制台数据同步页将源 etcd 实例的数据通过 Snapshot 的形式一次性导入到目标实例。

数据同步相关操作可参考文档：etcd 数据同步

误删除保护¶

禁止级联删除：为了保障数据安全，云原生 etcd 还提供了误删除保护功能，在您删除集群之前，需确保已移除集群中的所有存储数据。

具体可参考文档：etcd 误删除保护

如果您在清理数据前，已经删除了所有 CVM 资源，导致无法连接 etcd 集群，您可以通过工单授权运维团队协助您进行集群删除。

常见问题与解决方案¶

如果您在云原生 etcd 使用过程中，遇到下列相关的问题，您可以参考以下最佳实践进行问题排查或者采取相关措施进行问题规避，如果以下最佳实践无法解决您的问题，您还可以通过工单进行反馈，由云原生 etcd 团队协助您解决问题。

etcd OOM 问题¶

etcd 的 OOM（Out of Memory）问题会直接威胁分布式系统的稳定性，导致业务中断、系统崩溃等一系列风险。您可以参考以下最佳实践，降低 OOM 发生概率，提高业务的稳定性。

避免大 Key-Value¶

假设写入了 100 个 1M 大小的 key，通过 Range 接口一次查询 100 个 key，那么 boltdb 遍历、反序列化过程将花费至少 100MB 的内存。也就是说，一次查询就耗费了至少 100MB 的内存、产生了至少 100MB 的流量，随着 QPS 增大后，很容易 OOM、网卡出现丢包。

etcd 默认限制单个 Key-Value 不超过 1.5MB，写入超过此限制的 Key-Value 会返回错误 etcdserver: request is too large。强烈建议不要将 etcd 当成数据库来用，存储过大的数据。

控制 Watcher 数量¶

Watch 监听机制耗费的内存跟 client 连接数、gRPC Stream、Watcher 数有关，具体可参考如下计算。

# c1 表示每个连接耗费的内存，每个 client 连接消耗大约 17kb 的内存
# c2 表示每个 gRPC Stream 耗费的内存，每个 gRPC Stream 消耗大约 18kb 的内存
# c3 表示每个 watcher 耗费的内存，每个 watcher 消耗大约 350 个字节
memory = c1 * number_of_conn + c2 * avg_number_of_stream_per_conn + c3 * avg_number_of_watch_stream

当您的业务场景大量使用 watcher 的时候，应提前估算下内存容量大小，选择合适的内存配置节点。若大量事件堆积，将产生较高昂的内存的开销。

您可以通过 etcd_debugging_mvcc_pending_events_total 指标监控堆积的事件数，etcd_debugging_slow_watcher_total 指标监控慢的 watcher 数，来及时发现异常。

Raft 日志压缩¶

当发起一个 put 请求的时候，etcd 需通过 Raft 模块将此请求同步到其他节点，在此过程中会追加到 raftLog 的内存存储中，那么随着写请求增多，内存中保留的 Raft 日志条目会越来越多，内存占用也会越大。

etcd 提供了快照和压缩功能来解决这个问题。如果您的集群 key 数量较少且内存压力较大时，可以根据业务需求，通过调整 --snapshot-count 参数来控制生成快照的频率，其默认值是 100000。

压缩与碎片清理¶

一个 put 写请求的日志条目被集群多数节点确认提交后，会被应用到 MVCC 模块的 treeIndex 和 boltdb。并且每次对 key 的修改、删除操作都会在 key 的索引项中追加一条修改记录（revision）。因此，随着修改次数的增加，etcd 内存会一直增加。

为了避免内存索引项占用过多的内存，key 的长度不应过长，同时您需要配置好合理的压缩策略，并且在需要时进行碎片清理。

您可以通过控制台选择周期性压缩或根据 revision 压缩配置集群压缩模式，具体可参见第一章性能参数调优。

避免客户端高频 List 操作¶

全量 List 请求需在内存中构建完整响应，数据量越大内存消耗越高，因此建议您尽量减少高频 List 操作。

根据腾讯云内部 etcd 压测结果，不同规格 etcd 集群可支持 List 操作的最大并发数可参考第一节可靠性容量数据，您可以结合您的业务场景进行合理的资源配置。

Lease 续约问题¶

很多业务场景会使用 etcd 作为服务发现，可能在使用过程中遇到 Lease 堆积以及 Lease 续约失败等问题，如果您在使用中也遇到相关问题，可以参考以下最佳实践。

具体案例 1¶

现象：客户端每隔心跳间隔为对应的 key 绑定一个新的 lease，最终造成 lease 大量堆积，集群不可用。由于 etcd 的 lease 作为一个独立的对象存在，每次更新 key 如果都新生成一个新的 lease，并且客户端没有对老的 lease 进行吊销的话，那么老的 lease 会持续存在，直到过期后被 etcd 吊销。

影响：产生 lease 大量堆积，不仅会造成 etcd 高负载，同时会导致正常的 lease 过期后也无法被吊销，影响使用。

优化方案：建议每个客户端使用一个 lease，定期使用 KeepAlive 进行续期。

具体案例 2¶

现象：单个客户端维护大量 Lease 时，因 etcd server 处理瓶颈导致续约请求堆积，最终 Lease 续约失败。

优化方案：

• 客户端连接池优化：若 etcd CPU 利用率低，可通过客户端建立多连接（如 gRPC 多路复用）分摊请求压力。
• TTL 配置：需要结合具体业务场景配置，但 TTL 不建议配置过短，否则很容易出现续约不及时的场景。

数据一致性保障¶

etcd 数据不一致核心原因是它使用的 Raft 算法只能保证各个节点日志同步的一致性，但 Apply 流程是异步的，它从一致性模块获取日志命令，应用到状态机的准确性取决于业务逻辑，这块是没有机制保证的，因此建议您可以通过以下方式进行规避。

版本选择¶

避免使用存在隐患的版本，升级至稳定性版本（如腾讯云验证 3.5.12 版本），需对比 Changelog 确认修复项（如 Raft 日志同步漏洞）。

数据备份¶

启用产品化定时备份能力（如定时全量快照），存储至独立灾备系统。建议您开启云原生 etcd 的定时备份功能。

巡检¶

实现巡检功能，定时去统计各个节点的 key 数量，这样可以快速地发现数据不一致，从而及时介入，控制数据不一致影响，降低风险。建议您可以使用云原生 etcd 的基础监控结合相应指标配置告警，或者接入 Prometheus，自定义巡检指标。

DB Size 风险控制¶

etcd 社区建议 db 大小不超过 8G，大 db 对 etcd 启动耗时、快照、boltdb 性能以及集群稳定性等方面都有影响。因此建议您参考以下最佳实践，通过定期巡检和压缩的方式有效控制该风险，避免因此对您的业务造成影响。

定期巡检¶

监控 etcd_mvcc_db_total_size_in_bytes，超过阈值（如 6GB）时清理无用数据。云原生 etcd 基础监控中已经对该指标进行了采集，您可以通过"数据库大小"监控视图结合业务需求配置告警，及时进行处理。

压缩与碎片整理¶

开启自动压缩：根据业务需求，配置合适的压缩策略，例如 --auto-compaction-mode=revision --auto-compaction-retention=1000。

使用云原生 etcd 时，您可以通过控制台进行压缩策略的配置。

Defrag 操作：逐个节点执行 etcdctl defrag，优先处理 Follower，Leader 最后处理，观察 DB Size 回涨稳定后再继续。但您需要注意的是，该操作有损，如非必要，最好不要进行操作。

Defrag 操作相当于将当前的 boltdb 数据遍历后写到一个新的 db 文件，然后 replace 掉老的 db 文件，期间会对整个 db 文件加锁，阻塞该节点的读写操作，造成访问该节点的请求受到影响。

etcd 限速问题¶

当您使用 etcd 遇到 "etcdserver: too many requests" 错误时，这是由于 Raft 模块处理请求的速度落后于客户端写入速度，导致日志积压，触发了限速。此时您可以参考以下最佳实践对 etcd 集群进行分析，并采取相应的处理措施。

资源瓶颈¶

CPU/内存压力：高并发下 etcd 节点资源耗尽，无法及时处理请求。您可以查看基础监控确认是否是 etcd 资源压力导致的，此时可以在控制台进行升配，具体操作可以参考第一节中"水平垂直扩缩容"相关内容。

磁盘 I/O 性能差：WAL 日志同步耗时过长，您可以查看基础监控中节点资源监控中"文件系统读取速率"以及"文件系统写入速率"是否异常或者通过查看 etcd_disk_wal_fsync_duration_seconds 指标是否异常进行判断。如果有异常，可以通过工单反馈，以便能够及时协助您处理。

网络带宽限制：跨节点数据同步流量过大。您可以查看基础监控中节点资源监控中"网络发送速率"是否异常或者通过查看 etcd_network_peer_sent_bytes_total 指标是否存在突增。存在异常，也建议您及时工单反馈。

客户端异常行为¶

未优化的批量写入：单次写入大量 Key-Value 或未启用事务合并操作。此时建议您针对客户端写入逻辑进行优化，可以进行对写操作分批或者启动事务合并。

频繁 Leader 选举问题¶

如果您查看集群监控，发现 etcd 频繁触发 Leader 选举，那建议您可以参考以下原因进行分析。如果您使用的是云原生 etcd，并判断为高负载或者磁盘 IO 延时高等原因导致，可以及时工单反馈。

心跳超时设置过短¶

--election-timeout 设置过短（默认 1000ms），在网络高延迟场景下易误触发选举。

网络质量差¶

节点间心跳（Heartbeat）因网络抖动无法及时到达，导致 Follower 误判 Leader 失效。

磁盘 IO 延时高¶

Leader 节点写入 WAL 日志时磁盘延迟过高（etcd_disk_wal_fsync_duration 指标异常），心跳发送被阻塞。

高负载¶

CPU/内存资源耗尽导致 Leader 处理心跳延迟。

快照数量配置不合理¶

--snapshot-count 参数配置不合理，导致频繁触发快照，磁盘压力大。

密码鉴权性能问题¶

在 etcd 中开启密码鉴权（Basic Auth）会引入一定的性能开销，尤其是在高并发或大规模集群场景下。密码验证依赖 bcrypt 哈希计算，其计算复杂度可调（--bcrypt-cost 参数），但高 cost 值会显著增加 CPU 负载。

并且每次客户端请求均需验证用户名和密码，相较证书认证会增加 1~5ms 的延迟。建议您在非必要的业务场景，可以采用证书认证，同时您可以参考以下优化建议进行性能优化。

降低密码哈希计算开销¶

调整 bcrypt cost 值，默认 cost 值为 10，在权衡安全性后，可降低至 8~9，cost=8 时，哈希计算速度提升约 4 倍，但抗暴力破解能力下降。

使用混合认证模式¶

内部高频服务使用证书认证，外部工具或临时访问（如 etcdctl 命令行）使用密码鉴权。

分权分域隔离¶

按业务拆分集群，将高频读写业务与低频管理操作分离到不同 etcd 集群，减少单集群压力。