# 管理 Patroni 高可用 > 使用 Patroni 管理 PG 集群高可用，包括，修改参数，查看状态，主从切换，重启，重做从库等操作。 --- LLMS 索引： [llms.txt](/zh/llms.txt) --- ## 概览 Pigsty 使用 Patroni 管理 PostgreSQL 集群，它可以用来修改集群配置，查看集群状态，执行主从切换，重启集群，重做从库等操作。 要使用 Patroni 进行管理，您需要有以下两种身份之一： - 从 [**INFRA 节点**](/docs/concept/arch/node#infra节点) 上使用 [**管理员用户**](/docs/deploy/admin)，可以管理环境中的所有集群。 - 从 [**PGSQL节点**](/docs/concept/arch/node#pgsql节点) 上使用 [**`pg_dbsu`**](/docs/pgsql/param#pg_dbsu) （默认为 `postgres`），可以管理当前集群。 Patroni 提供了 [**`patronictl`**](https://patroni.readthedocs.io/en/latest/patronictl.html) 命令行工具用于管理，Pigsty 提供了封装的快捷命令 `pg` 来简化其操作。 > [!DETAILS]- 通过 pg 别名使用 patronictl > ```bash > pg () > { > local patroni_conf="/infra/conf/patronictl.yml"; > if [ ! -r ${patroni_conf} ]; then > patroni_conf="/etc/patroni/patroni.yml"; > if [ ! -r ${patroni_conf} ]; then > echo "error: patronictl config not found"; > return 1; > fi; > fi; > patronictl -c ${patroni_conf} "$@" > } > ``` ---------------- ## 可用命令 | 命令 | 功能 | 说明 | |----------------------------|--------|--------------------------------| | [**`edit-config`**](#修改配置) | 修改配置 | 交互式修改集群的 Patroni/PostgreSQL 配置 | | [**`list`**](#查看状态) | 查看状态 | 列出集群成员及其状态 | | [**`switchover`**](#主动切换) | 主动切换 | 将主库角色切换到指定从库（计划内维护） | | [**`failover`**](#故障切换) | 故障切换 | 强制故障转移到指定从库（紧急情况） | | [**`restart`**](#重启实例) | 重启实例 | 重启 PostgreSQL 实例以应用需要重启的参数 | | [**`reload`**](#重载配置) | 重载配置 | 重载 Patroni 配置（无需重启） | | [**`reinit`**](#重做从库) | 重做从库 | 重新初始化从库（擦除数据并重新复制） | | [**`pause`**](#暂停自动切换) | 暂停自动切换 | 暂停 Patroni 的自动故障转移功能 | | [**`resume`**](#恢复自动切换) | 恢复自动切换 | 恢复 Patroni 的自动故障转移功能 | | [**`history`**](#查看历史) | 查看历史 | 显示集群的故障转移历史记录 | | [**`show-config`**](#显示配置) | 显示配置 | 显示集群当前的配置（只读） | | [**`query`**](#执行查询) | 执行查询 | 在集群成员上执行 SQL 查询 | | [**`topology`**](#查看拓扑) | 查看拓扑 | 显示集群的复制拓扑结构 | | [**`version`**](#查看版本) | 查看版本 | 显示 Patroni 版本信息 | | [**`remove`**](#移除成员) | 移除成员 | 从 DCS 中移除集群成员（危险操作） | {.full-width} ---------------- ## 修改配置 使用 [**`edit-config`**](https://patroni.readthedocs.io/en/latest/patronictl.html#patronictl-edit-config) 子命令可以交互式修改集群的 Patroni 与 PostgreSQL 配置。该命令会打开一个编辑器，让您修改存储在 DCS（分布式配置存储）中的集群配置，修改后会自动应用到所有集群成员。您可以更改 Patroni 本身的参数（如 `ttl`、`loop_wait`、`synchronous_mode` 等），以及 `postgresql.parameters` 中的 PostgreSQL 参数。 ```bash pg edit-config # 交互式编辑集群配置 pg edit-config --force # 跳过确认提示直接应用 pg edit-config -p = # 修改 PostgreSQL 参数（--pg 简写） pg edit-config -s = # 修改 Patroni 参数（--set 简写） ```
demo/pgsql-config.cast
以下是一些常见的配置修改示例： ```bash # 修改 PostgreSQL 参数：慢查询阈值（会询问是否应用） pg edit-config pg-test -p log_min_duration_statement=1000 # 修改 PostgreSQL 参数并跳过确认 pg edit-config pg-test -p log_min_duration_statement=1000 --force # 修改多个 PostgreSQL 参数 pg edit-config pg-test -p work_mem=256MB -p maintenance_work_mem=1GB --force # 修改 Patroni 参数：增大故障检测时间窗口（增大 RTO） pg edit-config pg-test -s loop_wait=15 -s ttl=60 --force # 修改 Patroni 参数：启用同步复制模式 pg edit-config pg-test -s synchronous_mode=true --force # 修改 Patroni 参数：启用严格同步模式（至少一个同步从库才允许写入） pg edit-config pg-test -s synchronous_mode_strict=true --force # 修改需要重启的参数（修改后需执行 pg restart） pg edit-config pg-test -p shared_buffers=4GB --force pg edit-config pg-test -p shared_preload_libraries='timescaledb, pg_stat_statements' --force pg edit-config pg-test -p max_connections=200 --force ``` 部分参数修改后需要重启 PostgreSQL 才能生效，您可以使用 `pg list` 检查集群状态，带 `*` 标记的实例表示需要重启。然后使用 `pg restart` 命令重启集群使配置生效。 您也可以使用 `curl` 或编写程序直接调用 Patroni 提供的 [**REST API**](https://patroni.readthedocs.io/en/latest/rest_api.html) 来修改配置： ```bash # 查看当前配置 curl -s 10.10.10.11:8008/config | jq . # 通过 API 修改参数（需要认证） curl -u 'postgres:Patroni.API' \ -d '{"postgresql":{"parameters": {"log_min_duration_statement":200}}}' \ -s -X PATCH http://10.10.10.11:8008/config | jq . ``` ---------------- ## 查看状态 使用 [**`list`**](https://patroni.readthedocs.io/en/latest/patronictl.html#patronictl-list) 子命令可以查看集群成员及其状态。输出结果会显示每个实例的名称、主机地址、角色、运行状态、时间线和复制延迟等信息。这是日常运维中最常用的命令之一，用于快速了解集群的健康状况。 ```bash pg list # 查看指定集群的状态 pg list # 列出所有集群（需要在管理节点上执行） pg list -e # 显示扩展信息（--extended） pg list -t # 显示时间戳（--timestamp） pg list -f json # 以 JSON 格式输出（--format） pg list -W 5 # 每 5 秒刷新一次（--watch） ``` 输出示例： ```text + Cluster: pg-test (7322261897169354773) -----+----+--------------+ | Member | Host | Role | State | TL | Lag in MB | +-----------+-------------+---------+---------+----+--------------+ | pg-test-1 | 10.10.10.11 | Leader | running | 1 | | | pg-test-2 | 10.10.10.12 | Replica | running | 1 | 0 | | pg-test-3 | 10.10.10.13 | Replica | running | 1 | 0 | +-----------+-------------+---------+---------+----+--------------+ ``` 输出列说明：**Member** 是实例名称，由 `pg_cluster`-`pg_seq` 组成；**Host** 是实例所在主机的 IP 地址；**Role** 表示角色，包括 Leader（主库）、Replica（从库）、Sync Standby（同步从库）、Standby Leader（级联复制的级联主库）等；**State** 表示运行状态，常见值包括 `running`（正常运行）、`streaming`（流复制中）、`in archive recovery`（归档恢复中）、`starting`（启动中）、`stopped`（已停止）等；**TL** 是时间线编号（Timeline），每次主从切换后会递增；**Lag in MB** 是复制延迟，以 MB 为单位，主库不显示此值。 如果某个实例需要重启才能应用配置更改，实例名称后会显示 `*` 标记： ```text + Cluster: pg-test (7322261897169354773) -------+----+--------------+ | Member | Host | Role | State | TL | Lag in MB | +-------------+-------------+---------+---------+----+--------------+ | pg-test-1 * | 10.10.10.11 | Leader | running | 1 | | | pg-test-2 * | 10.10.10.12 | Replica | running | 1 | 0 | +-------------+-------------+---------+---------+----+--------------+ ``` ---------------- ## 主动切换 使用 [**`switchover`**](https://patroni.readthedocs.io/en/latest/patronictl.html#patronictl-switchover) 子命令可以执行计划内的主从切换。Switchover 是一种优雅的切换方式：Patroni 会先确保从库完全同步，然后让主库降级为从库，最后提升目标从库为新主库。这个过程通常只需要几秒钟，期间会有短暂的写入不可用。适用于主库所在主机需要维护、升级、或者需要将主库迁移到性能更好的节点等场景。 ```bash pg switchover # 交互式切换，会提示选择目标从库 pg switchover --leader # 指定当前主库名称 pg switchover --candidate # 指定目标从库名称 pg switchover --scheduled