Patroni与etcd集成问题排查与解决指南

问题背景

在使用Patroni管理PostgreSQL高可用集群时，与etcd分布式键值存储服务的集成是一个常见配置。本文记录了一个典型的集成问题：Patroni无法从etcd获取机器列表，返回"404 page not found"错误。

现象描述

用户在使用Patroni 3.2.2与PostgreSQL 15.6时，遇到以下问题表现：

1. Patroni日志显示无法从etcd v3接口获取机器列表
2. 直接访问etcd的v3接口返回404错误
3. 切换到etcd v2协议后问题依旧存在
4. etcd服务本身运行正常，集群状态显示健康

根本原因分析

经过深入排查，发现问题的核心在于etcd的gRPC网关未正确启用。etcd v3 API默认使用gRPC协议，而Patroni需要通过HTTP接口与etcd通信。当gRPC网关未启用时，任何对/v3/路径的HTTP请求都会返回404错误。

解决方案

要解决此问题，需要在etcd配置文件中显式启用gRPC网关功能。具体配置如下：

1. 在每台etcd节点的配置文件中添加以下参数：

enable-grpc-gateway: true

2. 完整的etcd配置示例：

name: etcd-1
data-dir: /opt/etcd/data
listen-client-urls: http://192.168.96.120:2379,http://127.0.0.1:2379
advertise-client-urls: http://192.168.96.120:2379
listen-peer-urls: http://192.168.96.120:2380
initial-advertise-peer-urls: http://192.168.96.120:2380
initial-cluster: etcd-1=http://192.168.96.120:2380,etcd-2=http://192.168.96.121:2380,etcd-3=http://192.168.96.122:2380
initial-cluster-token: etcd-cluster-token
initial-cluster-state: new
enable-grpc-gateway: true

3. 修改配置后，重启etcd服务使配置生效：

systemctl restart etcd

验证步骤

配置生效后，可以通过以下方式验证：

1. 检查etcd v3接口是否可用：

curl http://127.0.0.1:2379/v3/version

2. 检查集群成员列表：

curl http://127.0.0.1:2379/v3/members

3. 确认Patroni能够正常连接etcd：

patronictl show-config

最佳实践建议

1. 在生产环境中，建议使用TLS加密etcd通信
2. 定期备份etcd数据目录
3. 监控etcd集群健康状态
4. 考虑使用etcdctl而不是直接curl进行管理操作
5. 保持etcd和Patroni版本兼容性

总结

etcd作为Patroni的分布式配置存储后端，其正确配置对PostgreSQL高可用集群至关重要。通过启用gRPC网关，可以解决Patroni与etcd v3 API的通信问题。建议在部署前仔细阅读官方文档，确保所有依赖服务配置正确。