# HA 集群

> 用 pgcli 管理 Patroni 高可用集群 —— pg ha 命令集、动态配置、REST API、扩展、集群备份与恢复、直连 SQL

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

[Patroni](https://patroni.readthedocs.io) 是 PostgreSQL 高可用的事实标准：它掌管每个
postmaster 的生命周期、在成员间流式复制、并在 leader 失联时执行**自动 failover**。pgcli
把 Patroni 作为独立的顶级命令 `pg ha` 暴露出来——它是一种独立的模式，既不是普通的 `pg`
实例，也不是用 `pg addon install` 安装的插件。

> **关于归属。** Patroni 相关页面原先挂在 [插件 Addons](../addon/) 下。现在它们独立成
> **HA 集群**这一节，因为 `pg ha` 并不通过插件系统安装——插件索引里提到它只是为了方便
> 检索。etcd DCS 与 HAProxy 负载均衡仍是插件页面（[etcd](../addon/etcd/)、
> [HAProxy](../addon/haproxy/)）；本节会在相关处链回去。

## 子页面

| 页面 | 内容 |
|------|------|
| [Patroni HA](./ha/) | `pg ha` 命令集：创建、status、switchover/failover、pause、跨主机成员、密码、namespace 与 DCS 布局 |
| [动态配置](./ha-dynamic/) | `pg ha edit-config` / `pg ha ctl` —— 存在 DCS 里的运行时配置，以及为什么它绝不重建容器 |
| [REST API](./ha-rest-api/) | 每个成员的 Patroni REST API：健康检查、leader 重定向、HAProxy 探测什么 |
| [HA 集群扩展](./ha-extensions/) | 在集群范围内安装/卸载 PostgreSQL 扩展（滚动修改 shared_preload_libraries） |
| [集群备份](./ha-backup/) | `pg backup setup` + `pg ha snapshot` —— stanza、WAL 归档到 S3、跨主机的备份 SSH 通道 |
| [集群恢复](./ha-restore/) | `pg ha restore` —— 走自定义 bootstrap 机制的集群 PITR、leader 本机性预检、恢复后的重新基线 |
| [Exec / psql](./ha-exec/) | `pg ha exec` / `pg ha psql` —— 直连 leader 或任意成员跑 SQL，免 dsn、免进容器 |
| [示例：HA 集群 + 自签 CA 的 MinIO](./ha-example-minio/) | 实测通过的端到端流程：集群备份到一台服务自带证书的 MinIO，全程在完全隔离的第二套环境里 |
| [生成证书](./ha-cert/) | `pg cert` —— 签发带域名与 IP SAN 的自签证书，服务于任何不想走 CA 又需要 TLS 的场合（开发测试服务器、内部端点，或服务自带证书的 MinIO）：flag 一览，以及单张自签叶证书如何充当自己的信任锚 |
| [S3 存储高可用](./ha-s3-storage/) | 让仓库本身（MinIO/silo）也容错：pgcli 暴露的 SNSD 与 MNSD 两种形态及为何只有这两种，加上在数据目录之下用 ZFS —— 单机 raidz、分布式集群每节点各自建池、异构节点 |

## 典型路径

```bash
# 一台主机：引导集群（基于已安装的 etcd 插件成员）
pg ha create app --member node1 --etcd m1
pg ha create app --member node2 --etcd m1

# 其它主机用同一套密码登记自己的成员
pg ha passwords app --file app-passwd.yml
ssh other-host
pg ha create app --member node3 --advertise-host 10.0.0.12 \
    --etcd-endpoints 10.0.0.9:2379 --passwords-file app-passwd.yml

# 直接跑 SQL —— leader 由 pgcli 从 DCS 解析
pg ha exec app "SELECT version()"
pg ha psql app

# 备份它，并且能回到过去
pg backup setup --s3-endpoint ...
pg ha snapshot create app --type full
pg ha restore app --time "2026-08-26 15:30:00+00"
```

## 相关

- **插件**：[etcd](../addon/etcd/)（DCS）、[HAProxy](../addon/haproxy/)
  （可扛故障切换的稳定客户端端点，可选读写分离）、[MinIO](../addon/minio/)（备份所在的 S3 仓库）
- **[恢复 → Patroni 集群](../restore/#patroni-集群)**：与单实例恢复共通的 PITR 基础
- **[Failover：副本提升](../failover/)**：非 Patroni 的单副本提升路径（`pg replica`）
- **[Namespace 隔离](../namespace/)** —— scope、stanza、容器名都带 namespace 前缀

---

本节页面：

- [Patroni 高可用](/zh/docs/ha-cluster/ha/): 以 pgcli HA 模式运行 Patroni 版 PostgreSQL 高可用——自动故障切换、switchover，基于 DCS 的集群
- [Patroni 动态配置](/zh/docs/ha-cluster/ha-dynamic/): 存储在 DCS 中的所有可动态配置参数参考
- [Patroni REST API](/zh/docs/ha-cluster/ha-rest-api/): Patroni REST API 端点参考：健康检查、监控、集群管理
- [HA 集群扩展安装](/zh/docs/ha-cluster/ha-extensions/): 在 Patroni 管理的 HA 集群中安装和管理 PostgreSQL 扩展
- [Patroni 集群备份](/zh/docs/ha-cluster/ha-backup/): Patroni HA 集群的 pgBackRest 备份：backup setup、S3 仓库与 WAL 归档、pg ha snapshot 快照操作，以及副本 LSN 卡住时的 reinit 修复
- [Patroni 集群恢复](/zh/docs/ha-cluster/ha-restore/): 用 pg ha restore 为 Patroni HA 集群做时间点恢复（PITR）：自定义 bootstrap 机制、leader 本机性预检、端到端操作流程，以及恢复之后的重新基线步骤
- [HA Exec / psql](/zh/docs/ha-cluster/ha-exec/): 用 pg ha exec 和 pg ha psql 对 Patroni HA 集群执行 SQL：从 DCS 零配置解析 leader、免手拼 dsn、免进成员容器，并可用 --member 指定只读副本或跨主机节点
- [示例：HA 集群 + 自签 CA 的 MinIO](/zh/docs/ha-cluster/ha-example-minio/): 完整且实测通过的端到端流程：单 member 的 Patroni 集群，备份到一台对外提供自带（自签）域名证书的 MinIO 插件——全程运行在一个完全隔离的 pgcli 环境中
- [生成证书 —— pg cert](/zh/docs/ha-cluster/ha-cert/): pg cert 签发带域名与 IP SAN 的自签证书，服务于任何不想走 CA 又需要 TLS 的场合——开发测试服务器、内部端点、对外提供自带 TLS 证书的 MinIO。flag 一览，写出的内容（单张自签叶证书，不是一条链），以及它如何充当自己的信任锚
- [S3 存储高可用方案](/zh/docs/ha-cluster/ha-s3-storage/): 让 pgBackRest 背后的 MinIO/silo 对象存储也高可用：pgcli 暴露的四种部署形态（SNSD/SNMD/MNSD/MNMD）、原生多盘与 ZFS 磁盘冗余层的取舍，以及「每台主机多块盘的分布式集群」的两条路

---

反链：

- [插件 (Addons)](/zh/docs/addon/)