Patroni与ETCD v3协议兼容性问题解析

问题背景

在使用Patroni 4.0.4版本与ETCD 3.4.30版本搭建PostgreSQL高可用集群时，用户遇到了连接问题。Patroni服务启动时报错"Failed to get list of machines from http://10.1.1.10:2379/v2: EtcdException('Bad response : 404 page not found')"，表明Patroni无法通过ETCD v2 API与ETCD集群通信。

技术分析

协议版本不匹配

ETCD从v3版本开始，默认不再支持v2 API。而Patroni配置中默认使用的是ETCD v2协议配置方式：

etcd:
  host: 10.1.1.10:2379

这种配置方式会尝试通过/v2路径访问ETCD API，而ETCD v3默认关闭了v2 API支持，因此返回404错误。

解决方案

正确的做法是明确指定使用ETCD v3协议：

etcd3:
  host: 10.1.1.10:2379

这一修改告诉Patroni使用ETCD v3 API进行通信，避免了协议版本不匹配的问题。

深入理解

ETCD协议演进

ETCD经历了从v2到v3的重大协议变更：

1. v2版本使用RESTful HTTP API
2. v3版本改用gRPC协议，性能更高
3. v3默认禁用v2 API以简化维护

Patroni的兼容性设计

Patroni同时支持两种ETCD协议配置方式：

1. etcd: - 使用v2 API
2. etcd3: - 使用v3 API

这种设计确保了与不同版本ETCD集群的兼容性。

最佳实践建议

1. 明确协议版本：在配置中始终明确指定协议版本
2. 版本一致性：确保Patroni版本与ETCD版本匹配
3. 协议检查：使用etcdctl endpoint status验证ETCD版本
4. 配置验证：启动前使用patronictl show-config检查配置

总结

Patroni与ETCD集成时，协议版本匹配是关键。对于ETCD v3及以上版本，必须使用etcd3:配置项而非etcd:。这一细微但关键的差异决定了Patroni能否成功与ETCD集群建立连接。理解这一机制有助于快速诊断和解决类似的高可用集群搭建问题。