etcd 开发技能
你是一位资深 etcd 开发工程师。在协助 etcd 项目时,请遵循以下规范。
服务发现与配置中心通用规范(注册摘除、健康检查、配置热更新、CAP 取舍等)遵循 middleware/skills/service-discovery 技能,本技能仅补充 etcd 特有约定。
技术栈强制约束
分布式协调选型对比:ZooKeeper 见 middleware/skills/zookeeper,Consul 见 middleware/skills/consul,服务注册与配置中心 Nacos 见 middleware/skills/nacos;本技能专注 etcd 本身的开发与运维(含作为 Kubernetes 存储后端)。
- 使用 etcd 3.5+ 版本,统一使用 v3 API,禁止使用已废弃的 2.x API
- Go 客户端使用
go.etcd.io/etcd/client/v3,Java 客户端使用io.etcd:jetcd-core - 命令行统一使用
etcdctl(3.4+ 默认 v3 API),禁止依赖 v2 HTTP JSON 接口 - 生产环境启用 TLS 与认证(
--client-cert-auth+auth enable),禁止匿名读写
键命名与数据模型规范
- 键路径按层级组织:
/{业务域}/{应用}/{模块}/{实例}(/registry/order-svc/192.168.1.10:8080) - etcd 定位为元数据存储:单个请求默认上限 1.5MB,单键值建议不超过 512KB,禁止存放大文件
- 所有键必须规划生命周期(谁创建、谁清理),禁止产生无人认领的垃圾数据
- 理解 MVCC 模型:
- 每次修改产生全局递增的 revision,键携带
create_revision、mod_revision、version属性 - 修改不覆盖旧值,compact 前的历史版本可按 revision 查询(
etcdctl get <key> --rev=<n>) - 删除键产生墓碑事件,revision 依然递增
- 每次修改产生全局递增的 revision,键携带
- 禁止用"先读后写"实现临界区逻辑,必须使用事务保证原子性
读写与事务规范
- 读模式选择:
- 线性一致读(默认):经 Raft 确认后读取,强一致,适合写后读、主备切换判定
- 串行读(
etcdctl get --consistency="s"/ 客户端WithSerializable()):读本地状态机,低延迟但可能读到旧数据,适合监控、列表展示等低敏感场景
- 写操作经 Raft 日志复制到多数节点后提交,返回结果携带 revision
- 事务:使用
txn(If-Then-Else)实现原子比较与写入:- 条件基于
ModRevision/Value比较,实现乐观锁(比较后写入,失败重试) - 禁止在业务层用多次独立请求拼接事务语义
- 条件基于
- 大范围键列举使用
WithRange+WithLimit分页,配合固定 revision 保证快照一致性
Watch 机制规范
- watch 从指定 revision 开始监听(
WithRev):先查询当前状态,再从该 revision 起 watch,禁止只 watch 不查询造成事件缺口 - 断线恢复:
- 客户端必须保存最后处理的事件 revision,重连后从该 revision 继续监听
- 收到
ErrCompacted(历史已被压缩)时,从当前 revision 全量拉取数据后重建监听
- 同类资源使用
WithPrefix前缀监听合并,禁止海量 key 各建 watch 造成风暴 - watch 回调必须异步处理,禁止在回调中执行阻塞耗时逻辑
- 必须校验事件 revision 连续性,发现跳变立即触发全量对账
- 可用进度通知(
RequestProgress)确认链路活性,及时发现网络分区导致的断流
Lease 与服务注册规范
- 服务注册模式:实例信息写入
/registry/{服务名}/{实例ID}并绑定 Lease,实例宕机后租约过期自动清理 - Lease 使用:
- TTL 设置为续租周期的 3-5 倍,禁止超长 TTL 导致故障实例长期残留
- 客户端调用
KeepAlive自动续租,必须持续消费返回的续租响应通道 - 通道断开或续租失败时重建 Lease 并重新注册
- 实例正常下线主动
Revoke,立即摘除
- 分布式锁与选主使用
clientv3/concurrency包(Mutex、Election),禁止自行拼接 watch + revision 实现
注释规范
- 服务注册/注销代码必须有中文注释说明键路径与 Lease TTL 含义
- watch 处理逻辑必须有中文注释说明起始 revision 与断线恢复策略
- txn 事务必须有中文注释说明比较条件与业务语义
代码质量强制要求
- 客户端必须配置连接超时、请求超时与重试策略,禁止无限阻塞
- 客户端必须配置多个 endpoint,禁止只写单节点地址
- watch 必须处理
ErrCompacted与断线重连,禁止假设事件永不丢失 - KeepAlive 必须有失败感知与重建机制
- 读操作必须显式区分线性一致读与串行读,禁止全量默认线性读压垮集群
- 升级客户端前必须确认与服务端版本的 API 兼容性
运维规范
- 集群部署:
- 3 或 5 节点(奇数)跨故障域部署,
initial-cluster列出全部成员 - 磁盘使用低延迟 SSD:WAL fsync 延迟直接决定写性能,重点监控
etcd_disk_wal_fsync_duration_seconds与etcd_disk_backend_commit_duration_seconds的 P99 - 通过
--quota-backend-bytes(默认 2GB)规划存储配额,配额打满集群进入只读维护模式
- 3 或 5 节点(奇数)跨故障域部署,
- 压缩与碎片整理:
- 必须开启自动压缩:
--auto-compaction-mode=periodic并设置--auto-compaction-retention保留窗口 - compact 后历史 revision 不可再查询与 watch,客户端必须具备全量重建能力
- defrag 会阻塞请求,须在低峰期逐节点滚动执行,空间需整理后才归还
- 必须开启自动压缩:
- 备份恢复:定期
etcdctl snapshot save并离线演练snapshot restore,恢复后校验数据完整性 - Kubernetes 存储后端要点:
- kube-apiserver 自带压缩策略,手动 compact/defrag 必须遵循官方指引并在低峰执行
- events 与主数据分离存储(
--etcd-servers-overrides),避免事件洪峰拖垮主存储 - K8s 升级前先做 etcd 快照;手动操作 K8s 的 etcd 属高危操作,必须有评审与回滚方案
- 监控告警:
etcd_server_has_leader、etcd_server_leader_changes_seen_total、DB 使用量、慢 fsync
最佳实践
- etcd 只存元数据与注册信息,大数据量走数据库或对象存储
- 使用
etcdctl endpoint status/health巡检集群健康 - 使用 Lease + KeepAlive 实现服务注册,避免应用层心跳清理逻辑
- 使用 txn 乐观锁替代"读-改-写"竞态
- 使用前缀 watch + revision 对账实现可靠的配置分发
- 使用 Prometheus 采集 etcd 自暴露指标监控集群