K3s server 报 "etcdserver: request timed out" 或 leader election 频繁切换

k3s集群etcd不稳定主因是网络延迟高、磁盘i/o延迟大、cpu争抢或配置不当；需控制节点间rtt≤5ms，wal刷盘await≤20ms，禁用机械盘/nfs，关闭自动快照验证，并合理设置etcd超时参数与内存限制。

这是 K3s 集群中典型的 etcd 不稳定表现，根本原因通常是节点间网络延迟高、磁盘 I/O 延迟大、CPU 资源争抢严重，或配置不合理导致心跳/租约无法及时续期。

检查网络连通性与延迟

etcd 对节点间 RTT 极其敏感，建议控制在 10ms 内（生产环境最好

• 在每个 server 节点上执行 ping -c 5 和 nc -zv 2379，确认基础连通与端口可达
• 用 iperf3 或 qperf 测 UDP 往返延迟和丢包率；etcd 使用 Raft 心跳（默认每 100ms 一次），丢包或抖动 >5ms 就容易触发 timeout
• 避免将多个 K3s server 部署在同一物理机或过度拥挤的虚拟机中，尤其当共享网络带宽或磁盘资源时

排查磁盘 I/O 性能瓶颈

etcd 是同步写盘型数据库，wal 日志刷盘延迟超过 100ms 就可能错过 election timeout（默认 5s）：

摄图AI

摄图网旗下AI视觉创作平台

下载

• 运行 iostat -x 1 观察 %util、await、r_await/w_await；若 await >20ms 或 %util 持续 >80%，说明磁盘成为瓶颈
• K3s 默认使用 /var/lib/rancher/k3s/server/db/etcd，确保该路径挂载在本地 SSD 上，禁用机械盘、NFS、Ceph RBD 等慢速后端
• 可临时加参数验证：--etcd-snapshot-schedule-cron="0 * * * *" 关闭自动快照（快照期间会阻塞写请求），观察是否缓解

调整 etcd 超时与资源限制

不建议盲目调大 timeout，而应先定位根因；但若确属边缘场景（如弱网络测试环境），可谨慎微调：

• 通过启动参数增大 raft heartbeat 和 election timeout：--etcd-heartbeat-interval=500 --etcd-election-timeout=5000（单位 ms），注意两者的比例需保持 ≈ 1:10
• 为 K3s 进程设置合理 resource limit（尤其 memory），避免被 OOM killer 终止；etcd 占用内存随 key 数量增长，10w+ key 建议至少预留 2GB 内存
• 禁用 swap：swapoff -a 并注释 /etc/fstab 中 swap 行；swap 延迟会直接拖垮 etcd 的 goroutine 调度

验证 leader 状态与日志线索

不要只看 “leader changed” 日志，要结合时间戳与上下文判断是否真异常：

• 查当前 leader：curl -s http://127.0.0.1:2379/v2/stats/leader | jq .leader（需开启 etcd v2 API）
• 查健康状态：curl -s http://127.0.0.1:2379/health 应返回 {"health":"true"}
• 重点搜日志中的 "failed to send out heartbeat on time"、"restarting the election timer"、"applied entries took too long" —— 这些比 timeout 更早暴露问题