分类: 任务

如果经典3节点高可用部署同时出现两台（多数主体）故障，系统通常无法自动完成故障切换，需要人工介入： 首先判断另外两台服务器的情况，如果短时间内可以拉起，优先选择拉起另外两台服务。否则进入 紧急止血流程 紧急止血流程假设您的管理节点故障，只有单台普通数据库节点存活，在这种情况下，最快的恢复操作流程为： 调整 HAProxy 配置，将流量指向主库。 关闭 Patroni，手动提升 PostgreSQL 从库为主库。 调整HAProxy配置 如果你通过其他方式绕开 HAProxy 访问集群，那么可以跳 …

KAFKA 模块提供两个剧本：kafka.yml 用于部署 Apache Kafka 4.1+ 动态 KRaft 集群并收敛其安全、 资源与监控状态；kafka-rm.yml 用于下线集群或移除成员。 集群完整性约束 每个被选中的 kafka_cluster 必须包含其全部成员：部分选择会在写入前失败；选择一个集群、多个完整集群或不加 -l 裸跑全部集群都是允许的。先对完全相同的目标执行 --check；真实运行前仍需人工核验备份/重建意图、容量、业务窗口、回退方案与变更批准。 …

KAFKA 模块把 Kafka 安装在 /opt/kafka，使用 Systemd 管理服务，并把持久意图保存在 pigsty.yml。节点上的生成文件不应手工修改。 以下 Kafka CLI 示例都使用角色生成的 /etc/kafka/admin.properties。即使当前是 plaintext 也建议始终保留 --command-config：切换到 scram 管理通道时命令结构不变。将 <broker>:9092 替换为可达的 inventory_hostname 与端口。 …

常见运维场景如下： 初始化实例 重新配置 移除实例 添加新实例 多节点共享挂载 PITR 恢复 故障排查 性能调优 更多问题参见 FAQ。 初始化实例 ./juice.yml -l <host> ./juice.yml -l <host> -e fsname=<name> 初始化流程： 安装 juicefs 软件包 创建共享缓存目录（默认 /data/juice） 执行 juicefs format --no-update（仅首次创建有效） 创建挂载点目录并设置权限 渲染 systemd 单元与 …

JUICE 模块提供 juice.yml 剧本，用于部署与移除 JuiceFS 实例。 juice.yml juice.yml 的任务结构如下： juice_id : 校验配置、检查端口冲突 juice_install : 安装 juicefs 软件包 juice_cache : 创建共享缓存目录 juice_clean : 移除实例（state=absent） juice_instance : 创建实例（state=create） - juice_init : 格式化文件系统 …

Docker 模块提供了一个默认的剧本 docker.yml，用于安装 Docker Daemon 与 Docker Compose。 docker.yml 剧本原始文件：docker.yml 中 执行本剧本，将会在带有 docker_enabled: true 标记的目标节点上安装 docker-ce 与 docker-compose-plugin，启用 dockerd 服务 以下是 docker.yml 剧本中可用的任务子集： docker_install： 在节点上安装 …

您可以使用 PostgreSQL 作为 Grafana 后端使用的数据库。 这是了解 Pigsty 部署系统使用方式的好机会，完成此教程，您会了解： 如何 创建新数据库集群 如何在已有数据库集群中 创建新业务用户 如何在已有数据库集群中 创建新业务数据库 如何 访问Pigsty所创建的数据库 如何 管理Grafana中的监控面板 如何管理 Grafana 中的 PostgreSQL数据源 如何一步到位完成 Grafana数据库升级 太长不看 vi pigsty.yml # 取消注释DB/User …

以下是一些常见的 Redis 管理任务 SOP（预案）： REDIS 模块默认使用 redis_type: redis；选择 redis_type: valkey 时，服务端与客户端命令分别改为 valkey-server / valkey-cli。 本文命令行示例使用默认的 redis-cli，Valkey 集群请替换为 valkey-cli；剧本内部会自动选择正确的 CLI。 基础运维 初始化Redis 下线Redis 重新配置Redis 使用Redis客户端 高可用管理 手工设置Redis …

REDIS 模块提供了两个剧本，用于部署/移除 Redis 集群/节点/实例： redis.yml：部署 Redis 集群/节点/实例 redis-rm.yml：移除 Redis 集群/节点/实例 redis.yml 用于部署 Redis 的 redis.yml 剧本包含以下子任务： redis_node : 初始化redis节点 - redis_install : 按 `redis_type` 安装 Redis 或 Valkey，并安装 `redis-exporter` - …

创建集群 要创建一个集群，在配置清单中定义好后，执行 minio.yml 剧本即可。 minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio, minio_type: silo } } 例如，上面的配置定义了一个 SNSD 单机单盘 Silo 集群，使用以下命令即可创建所选对象存储集群： ./minio.yml -l minio # 在 minio 分组上安装 Silo 销毁集群 要销毁一个 …

MINIO 模块提供两个内置剧本： minio.yml：安装并配置 Silo minio-rm.yml：移除 Silo、配置和可选数据 minio.yml minio.yml 以 hosts: all 运行，但会在预任务阶段跳过没有定义 minio_cluster 的主机。进入角色后还会校验： minio_cluster 已定义且非空 minio_seq 已定义且为非负整数 minio_type 必须等于 silo 因此，minio_cluster 是模块成员门控，而 minio_seq 与 …

Etcd 模块提供了两个核心剧本：etcd.yml 用于安装与配置 Etcd 集群，etcd-rm.yml 用于移除 Etcd 集群或成员。 架构变化：Pigsty v3.6+ 自 Pigsty v3.6 起，etcd.yml 剧本专注于集群安装和成员添加，所有移除操作已迁移至独立的 etcd-rm.yml 剧本和 etcd_remove 角色。 etcd.yml 剧本原始文件：etcd.yml 执行本剧本，将会在硬编码的固定分组 etcd 上安装配置 Etcd 集群，并启动 etcd 服务。 …

以下是一些常见的 etcd 管理任务 SOP（预案）： 创建集群：如何初始化 etcd 集群？ 销毁集群：如何销毁 etcd 集群？ 环境变量：如何配置 etcd 客户端，以访问 etcd 服务器集群？ RBAC 认证：如何使用 etcd 的 RBAC 认证？ 重载配置：如何更新客户端使用的 etcd 服务器成员列表？ 添加成员：如何向现有 etcd 集群添加新成员？ 移除成员：如何从 etcd 集群移除老成员？ 便捷脚本：使用 bin/etcd-add 和 bin/etcd-rm 简化操作 更 …

下面是 Node 模块中常用的管理操作： 添加节点 移除节点 创建管理员 绑定VIP 添加节点监控 其他常见任务 更多问题请参考 FAQ：NODE 添加节点 要将节点添加到 Pigsty，您需要对该节点具有无密码的 ssh/sudo 访问权限。 您也可以选择一次性添加一个集群，或使用通配符匹配配置清单中要加入 Pigsty 的节点。 # ./node.yml -l <cls|ip|group> # 向 Pigsty 中添加节点的实际剧本 # bin/node-add …

Pigsty 提供两个与 NODE 模块相关的剧本： node.yml：纳管节点，调整节点到期望状态 node-rm.yml：从 Pigsty 中移除纳管节点 另提供两个包装命令工具：bin/node-add 与 bin/node-rm，用于快速调用剧本。 node.yml 向 Pigsty 添加节点的 node.yml 包含以下子任务： node-id ：生成节点身份标识 node_name ：设置主机名 node_hosts ：配置 /etc/hosts 记录 node_resolv ：配置 …

Pigsty 默认在管理节点维护一套自签名证书颁发机构（CA），为 PostgreSQL、Patroni、etcd、Silo、Nginx 和其他内部服务签发证书。面向公网的 Nginx 入口可以按 infra_portal 配置改用 Certbot/Let’s Encrypt 证书。 保护 CA 私钥 files/pki/ca/ca.key 是整个部署的信任根私钥。不要打印、提交、上传或通过不受保护的渠道传输它；应将它与 ca.crt 成对加密备份，并严格限制读权限。 自签名 CA …

本文介绍 INFRA 模块的日常管理操作，包括安装、卸载、扩容、以及各组件的管理维护。 安装 Infra 模块 使用 infra.yml 剧本在 infra 分组上安装 INFRA 模块： ./infra.yml # 在 infra 分组上安装 INFRA 模块 卸载 Infra 模块 使用 infra-rm.yml 剧本从 infra 分组上卸载 INFRA 模块： ./infra-rm.yml -l infra # 全量移除：注销、停服、删配置/环境/数据并卸载软件包 该剧本没有防误删开关， …

使用域名代替 IP 地址访问 Pigsty 的各项 Web 服务。 快速开始 将以下静态解析记录添加到 /etc/hosts： 10.10.10.10 i.pigsty 将 IP 地址替换为实际 Pigsty 节点的 IP。 为什么使用域名 比 IP 地址更易于记忆 灵活指向不同 IP 通过 Nginx 统一管理服务 支持 HTTPS 加密 防止某些地区的 ISP 劫持 允许通过代理访问内部绑定的服务 DNS 机制 DNS 协议：将域名解析为 IP 地址。多个域名可以指向同一个 IP。 HTTP …

Pigsty 的 REPO 角色会下载所需软件包，并在 /www/pigsty 创建可由 Nginx 提供服务的本地 YUM/APT 仓库。当前候选软件包版本为 SOW 0.3.0，源码统一使用 SOW 生成两类仓库元数据，不再分别调用 createrepo_c、modifyrepo_c 或 dpkg-scanpackages。 快速开始 将软件包加入 repo_packages 或 repo_extra_packages，然后执行： ./infra.yml -t repo_build # 仅当 …

Pigsty 在 INFRA 节点上安装 Nginx 作为所有 Web 服务的入口，默认监听在 80/443 标准端口上。 在 Pigsty 中，你可以通过修改配置清单，让 nginx 对外提供多种服务： 对外暴露 Grafana、VictoriaMetrics（VMUI）、Alertmanager、VictoriaLogs 等监控组件的 Web 界面 提供静态文件服务（如软件仓库、文档站，网站等） 代理自定义的应用服务（如内部应用、数据库管理界面，Docker 应用的界面等） 自动签发自签名的 …

本章节介绍 Pigsty 部署的日常管理和运维操作。

Pigsty 提供了三个与 INFRA 模块相关的剧本： deploy.yml：在所有节点上一次性部署 NODE、INFRA、ETCD、MINIO 与 PGSQL 核心模块 infra.yml：在 infra 节点上初始化 pigsty 基础设施 infra-rm.yml：从 infra 节点移除基础设施组件 deploy.yml 在所有节点上一次性部署 NODE、INFRA、ETCD、MINIO 与 PGSQL 核心模块，解决 INFRA/NODE 循环依赖问题。 该剧本会交叉执行 …

Pigsty 提供了一系列剧本，用于集群上下线扩缩容，用户/数据库管理，监控、备份恢复或迁移已有实例。 剧本 功能 pgsql.yml 初始化 PostgreSQL 集群或添加新的从库 pgsql-rm.yml 移除 PostgreSQL 集群，或移除某个实例 pgsql-user.yml 在现有的 PostgreSQL 集群中添加新的业务用户 pgsql-db.yml 在现有的 PostgreSQL 集群中添加新的业务数据库 pgsql-monitor.yml 将远程 PostgreSQL …

您可以在 PostgreSQL 集群上绑定一个可选的 L2 VIP —— 前提条件是：集群中的所有节点都在一个二层网络中。 这个 L2 VIP 强制使用 Master - Backup 模式，Master 始终指向在数据库集群主库实例所在的节点。 这个 VIP 由 VIP-Manager 组件管理，它会从 DCS （etcd） 中直接读取由 Patroni 写入的 Leader Key，从而判断自己是否是 Master。 启用VIP 在 PostgreSQL 集群上定义 …

使用 node_hugepage_count 和 node_hugepage_ratio 或 /pg/bin/pg-tune-hugepage 如果你计划启用大页（HugePage），请考虑使用 node_hugepage_count 和 node_hugepage_ratio，并配合 ./node.yml -t node_tune 进行应用。 大页对于数据库来说有利有弊，利是内存是专门管理的，不用担心被挪用，降低数据库 OOM 风险。缺点是某些场景下可能对性能由负面影响。 在 …

Pigsty v4.5.0 提供两个本机 Shell 工具： pg-fork：复制一个 PostgreSQL 数据目录，并为副本设置独立端口。 pg-pitr：调用 pgBackRest，将一个 已停止 的数据目录恢复到指定目标。 它们适合沙箱演练、旁路取证和临时测试，不是完整的 Patroni 集群恢复编排器。托管实例优先使用 pig pitr；多节点集群优先使用分阶段的 pgsql-pitr.yml。 先确认路径、备份和停机状态 pg-fork 会递归删除已存在的目标目录；pg-pitr 会 …

本教程在 Pigsty v4.5.0 的四节点沙箱中演练 PostgreSQL 时间点恢复。核心路径使用 pgsql-pitr.yml 的 down → pitr → up 三阶段，让操作者在覆盖数据、提升时间线和重建 HA 之前分别停下来验证。 如果只恢复当前节点，可使用 pig pitr；如果需要直接控制 pgBackRest，可参考 pg-pitr 低层工具。 只在可丢弃沙箱中照做 恢复会停止 Patroni/PostgreSQL，并以 pgbackrest --force restore …

克隆是恢复能力最有价值的用法：不动生产集群，把它的历史状态恢复到另一套集群上。 误删数据后从克隆库中导回、定期演练验证备份可用性、审计取证查看历史状态、把测试环境重置为生产某刻的快照 —— 这些场景的操作方式完全相同，本页给出完整流程。 目标集群需要能访问源集群的备份仓库、允许被覆盖，并使用兼容的 PostgreSQL 主版本。使用集中式仓库（Silo / S3）时， 仓库中以 stanza 隔离的各集群备份，对持有相应凭据的目标集群可见。 克隆会覆盖目标集群 先用 pig pg list <目 …

Pigsty 提供三个层次的恢复入口，共用 同一套参数语义，按场景选用： 入口 适用场景 特点 pgsql-pitr.yml 剧本 生产集群恢复 编排整个集群：HA 暂停、多节点、etcd 清理、恢复控制信息输出 pig pitr 命令 单节点集群 / 节点本机操作 无需管理节点，在数据库节点上直接编排执行 pig pb restore 原语 非 Patroni 托管的实例 pgbackrest restore 的直接封装，最精细的控制 手把手的沙箱演练教程请参阅 手工恢复； 用恢复克隆出新集群 …

备份管理命令应以数据库超级用户（pg_dbsu，默认 postgres）身份在数据库节点上执行。 您可以按习惯选择三种等价的入口： pig pb：pig 命令行工具 的封装 —— 自动检测 stanza、自动切换 DBSU 身份、带安全检查，推荐使用 pb：登录 shell 的别名函数，自动填充 --stanza 后转发给 pgbackrest pgbackrest：原生命令，完整选项参阅 pgBackRest 命令参考 命令一览 pig 命令 别名 对应 pgbackrest 命令 说明 …

备份存储在哪里，由两个参数决定：pgbackrest_repo 定义所有候选仓库， pgbackrest_method 选择实际使用哪一个。 仓库定义中的键值会 按固定规则 渲染为 pgbackrest 的 repo1-* 配置项， 因此 pgBackRest 支持的任何仓库选项 都可以直接写入。 v4.5.0 每次只把 pgbackrest_method 选中的一个字典项渲染为 repo1；候选项同时存在并不等于多仓备份。 默认仓库 Pigsty 预置了两个仓库定义：local 与 …

备份策略要回答三个问题：何时 备份（调度计划）、何处 存放（备份仓库）、 保留多久（保留策略）。本页给出两套久经考验的预设策略及其量化推演 —— 背后的权衡逻辑请参阅概念层文档 策略权衡。 备份频率与恢复速度直接相关：恢复时需要从最近的基础备份开始重放 WAL 日志到目标时间点， 备份越频繁，需要重放的 WAL 越少，恢复越快；而保留策略与仓库空间直接相关：窗口越长，占用空间越大。 每日全量备份 对于生产数据库，建议从最简单的每日全量备份策略开始。Pigsty 随附的标准 pigsty.yml …

Pigsty 的备份恢复功能，最终都会落实为 pgBackRest 命令的执行。 所以要真正掌握这套系统，需要理解两件事：pgBackRest 本身的概念体系（stanza、仓库、备份链、保留、时间线）， 以及 Pigsty 各层封装如何映射到它（参数如何变成命令行选项）。本页依次讲清这两部分。 pgBackRest 核心概念 Stanza：集群的备份身份 Stanza（节）是 pgBackRest 中一套 PostgreSQL 集群备份配置的名称，也是仓库内隔离不同集群的命名空间。 …

Pigsty 内置了一个剧本 pgsql-migration.yml，基于逻辑复制来实现在线数据库迁移。 通过预生成的自动化脚本，应用停机时间可以缩减到几秒内。但请注意，逻辑复制需要 PostgreSQL 10 以上的版本才能工作。 当然如果您有充足的停机时间预算，那么总是可以使用 pg_dump | psql 的方式进行停机迁移。 定义迁移任务 想要使用 Pigsty 提供的在线迁移剧本，您需要创建一个定义文件，来描述迁移任务的细节。 请查看任务定义文件示例作为参考： …

误删数据 如果是小批量 DELETE 误操作，可以考虑使用 pg_surgery 或者 pg_dirtyread 扩展进行原地手术恢复。 -- 立即关闭此表上的 Auto Vacuum 并中止 Auto Vacuum 本表的 worker 进程 ALTER TABLE public.some_table SET (autovacuum_enabled = off, toast.autovacuum_enabled = off); CREATE EXTENSION pg_dirtyread; …

本文档列举了 PostgreSQL 和 Pigsty 中可能出现的故障，以及定位、处理、分析问题的 SOP。 磁盘空间写满 磁盘空间写满是最常见的故障类型。 现象 当数据库所在磁盘空间耗尽时，PostgreSQL 将无法正常工作，可能出现以下现象：数据库日志反复报错"no space left on device"（磁盘空间不足）， 新数据无法写入，甚至 PostgreSQL 可能触发 PANIC 强制关闭。 Pigsty 带有 NodeFsSpaceFull 告警规则，当文件系统可用空间不足 …

Pigsty 使用 pgBackRest 管理 PostgreSQL 备份 —— 这可能是 PostgreSQL 生态中最强大的开源备份工具， 支持增量备份、并行处理、加密、Silo/S3 对象存储等众多特性。 每个 PGSQL 集群默认都预配置了备份与 WAL 归档，开箱即用。 本章是备份恢复的 实操手册：配置方法、管理命令、恢复操作与演练教程。 设计理念与心智模型（为什么、如何权衡）请参阅概念层文档 时间点恢复。 所有的备份恢复操作，最终都会落实为 pgBackRest 命令。Pigsty …

快速上手 Pigsty 提供 575 扩展，使用扩展涉及四个步骤：下载、安装、配置、启用。 pg-meta: hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } } vars: pg_cluster: pg-meta pg_extensions: [ postgis, timescaledb, pgvector ] # <--- 安装扩展软件包 pg_libs: 'timescaledb, pg_stat_statements, …

快速上手 PostgreSQL 版本升级分为两种类型：小版本升级 和 大版本升级，两者的风险和复杂度差异很大。 类型 示例 停机时间 数据兼容性 风险等级 小版本升级 17.2 → 17.3 秒级（滚动重启） 完全兼容 低 大版本升级 17 → 18 分钟级 需要升级数据目录 中 小版本 # 滚动升级：先从库后主库 ansible <cls> -b -a 'yum upgrade -y postgresql17*' pg restart --role replica --force <cls> …

Pigsty 使用 crontab 来管理定时任务，用于执行例行备份，冻结老化事务，重整膨胀表索引等维护工作。 速查手册 操作 快捷命令 说明 配置定时任务 ./pgsql.yml -t pg_crontab -l <cls> 应用 pg_crontab 配置 查看定时任务 crontab -l 以 postgres 用户查看 物理备份 pg-backup [full|diff|incr] 使用 pgBackRest 执行备份 事务冻结 pg-vacuum [database...] 冻结老化事 …

概述 Pigsty 的 PGSQL 模块由多个组件构成，每个组件都以 systemd 服务的形式运行在节点上。（pgbackrest 除外） 了解这些组件及其管理方式，对于维护生产环境中的 PostgreSQL 集群非常重要。 组件 端口 服务名 说明 Patroni 8008 patroni 高可用管理器，负责 PostgreSQL 的生命周期管理 PostgreSQL 5432 postgres 占位服务，默认不使用，应急使用 Pgbouncer 6432 pgbouncer 连接池中间件， …

概览 Pigsty 使用 Pgbouncer 作为 PostgreSQL 的连接池中间件，默认监听 6432 端口，代理访问本机 5432 端口上的 PostgreSQL 实例。 这是一个 可选组件，如果您并没有海量连接，也不需要事务池化与查询监控指标，可以关闭连接池，直连数据库，或者保留但不使用。 用户与数据库管理 Pgbouncer 中的用户和数据库由 Pigsty 自动管理，并在 创建数据库 与 创建用户 时自动应用 数据库配置 与 用户配置。 数据库管理：在 pg_databases 中 …

快速上手 Pigsty 使用声明式管理方式，首先在 配置清单 中 定义 HBA 规则，然后使用 bin/pgsql-hba <cls> 刷新规则。 pg-meta: hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } } vars: pg_cluster: pg-meta pg_hba_rules: # <--- 在这里定义 HBA 规则列表！ - {user: dbuser_app, db: app, addr: intra, auth: …

概览 Pigsty 使用 Patroni 管理 PostgreSQL 集群，它可以用来修改集群配置，查看集群状态，执行主从切换，重启集群，重做从库等操作。 要使用 Patroni 进行管理，您需要有以下两种身份之一： 从 INFRA 节点 上使用 管理员用户，可以管理环境中的所有集群。 从 PGSQL节点 上使用 pg_dbsu （默认为 postgres），可以管理当前集群。 Patroni 提供了 patronictl 命令行工具用于管理，Pigsty 提供了封装的快捷命令 pg 来简化其操 …

快速上手 Pigsty 使用声明式管理方式，首先在 配置清单 中 定义数据库，然后使用 bin/pgsql-db <cls> <dbname> 创建或修改数据库。 pg-meta: hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } } vars: pg_cluster: pg-meta pg_databases: [{ name: some_db }] # <--- 在这里定义数据库列表！ 脚本 bin/pgsql-db <cls> …

快速上手 Pigsty 使用声明式管理方式，首先在 配置清单 中 定义用户，然后使用 bin/pgsql-user <cls> <username> 创建或修改用户。 pg-meta: hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } } vars: pg_cluster: pg-meta pg_users: [{ name: dbuser_app, password: 'DBUser.App', pgbouncer: true }] # …

速查手册 操作 快捷命令 说明 创建集群 bin/pgsql-add <cls> 创建新的 PostgreSQL 集群 扩容集群 bin/pgsql-add <cls> <ip...> 为现有集群添加从库副本 缩容集群 bin/pgsql-rm <cls> <ip...> 从集群中移除指定实例 销毁集群 bin/pgsql-rm <cls> 销毁整个 PostgreSQL 集群 刷新服务 bin/pgsql-svc <cls> [ip...] 重载集群的负载均衡配置 刷新HBA …