企业官网建设流程全解析

“PostgreSQL 到底该怎么管？”这个问题我大概想了五年。数据库本身不复杂，复杂的是它身边的那些配套设施：备份要写脚本、高可用要搭 Patroni、监控要配 Prometheus、看板得自己画、告警要对接钉钉或邮箱，每一环单独拿出来都不难，但串在一起就是一座大山。后来我接触到 Pigsty，发现这条路终于可以走得更顺一些。Pigsty 是一个面向 PostgreSQL 的一体化开源数据库发行版，它把部署、高可用、监控、日志、备份这些原本分散的工作，整合成一套基于 Ansible 和 YAML 配置的交付体系，你写完一份集群描述文件，剩下的由它自动完成。

这篇文章不打算写成功能清单。我会从实际使用者的角度，讲清楚 Pigsty 的定位、内部组件如何协作、如何用一台机器快速体验、如何部署真正可用的主从集群，以及我在反复安装和切换过程中踩过的那些坑。无论你是刚接手 PostgreSQL 运维任务的新手，还是已经在生产环境摸爬滚打多年的老手，只要你想摆脱“装好 PG 之后还得独自伺候周边一大堆组件”的尴尬状态，这篇文章都应该能帮你省下不少时间。

1. 换个角度理解 Pigsty：它不只是一个监控面板，而是一个“库发行版”

我第一次听说 Pigsty 时，以为它只是给 PostgreSQL 配了一套好看的 Grafana 看板。后来完整用了一遍，才发现这个理解太浅了。Pigsty 的定位接近于“Linux 发行版”里的 CentOS 或 Ubuntu——它不是帮你装一个单纯的操作系统，而是把内核、常用软件、包管理、镜像源全部给你整理好，开箱即用。放到数据库场景里，Pigsty 是把 PostgreSQL 以及它周边的基础设施打成一套完整交付物。

1.1 它解决的到底是什么问题

单独安装 PostgreSQL 非常简单，一条包管理命令就能搞定。但到了生产环境，问题马上变多：

• 主库挂了，谁来把从库提升为新主？
• 应用连接字符串写的是固定 IP，故障切换后 IP 变了怎么办？
• 数据库指标看哪里？连接数、慢 SQL、复制延迟、缓存命中率，每个指标都要自己找口径组织。
• 日志分布在各个节点，出了问题要 SSH 到服务器上一台一台 tail。
• 备份策略怎么做？物理备份还是逻辑备份，保留几天，怎么验证可恢复性。

这些问题的答案并不在 PostgreSQL 内核里，而是散落在 Patroni、Etcd、HAProxy、Prometheus、Grafana、Loki、pg_probackup 等一堆开源工具中。Pigsty 所做的，就是把这些工具以 PostgreSQL 为核心重新编排，统一暴露给使用者，并通过一套 YAML 配置描述出整个环境的状态。

1.2 与“手动搭一套 PG 全家桶”的差异

如果你自己手动搭建过 PostgreSQL 高可用，一定体验过版本兼容性的痛苦。Patroni 需要特定版本的 psycopg2，Consul 和 Etcd 选哪个，HAProxy 的端口怎么规划，Prometheus 的 postgres_exporter 采集哪些指标，Grafana 有没有现成好用的仪表盘——这些都没有统一标准。每换一个环境，就要重来一遍。

Pigsty 把这些工具的默认版本、默认端口、默认权限关系全部固定下来。例如它规定每个节点上可能存在的角色：etcd负责元数据与选举；pgsql运行 PostgreSQL 实例；haproxy对外提供接入入口；monitor节点承载 Prometheus 和 Grafana。所有这一切可以在一个叫做pigsty.yml的文件中声明。你不用在多个服务器之间来回切换操作，只需要维护这一份配置。

1.3 开箱即用与离线交付的底气

我对 Pigsty 印象最深的一点，是它非常强调“本地源”这个设计。整个发行版把需要的 RPM 包或 DEB 包、常用的 Python 依赖、Grafana 插件模板，全部整理成本地软件源。初始化时，它会先构建一个基础设施节点，再基于这个节点向其他数据库节点分发软件包。也就是说，当你在离线内网环境部署时，只要提前准备好一份完整的安装包，后续的安装过程根本不依赖外网。这一点对那些有严格网络隔离要求的业务场景太重要了。我在实际交付中遇到过目标服务器无法访问外网的情况，手动装一个 PostgreSQL 都得倒腾半天依赖，而 Pigsty 因为内置了离线安装路径，整个布署过程反而比在线环境更稳定。

正是这种“库发行版”的思路，让 Pigsty 不再是一堆零散脚本的堆积，而是一个具备一致体验的完整产品。理解了这层定位，后面所有操作才有坐标系。

2. 架构拆解：从 etcd、Patroni 到 HAProxy，Pigsty 把高可用安排的明明白白

想要用好 Pigsty，必须先理解它内部的那套协作逻辑。它不是简单地把几个开源工具装在一起，而是给它们规定了明确的职责边界和交互方式。

2.1 四类角色，一张 YAML 描述清楚

在 Pigsty 的模型里，节点角色大致分为四种：

因为 infra 节点同时承担软件源的角色，所以整个 Pigsty 环境通常需要至少一台机器专门作为“元节点”。其他节点通过 Ansible 从这个元节点获取安装包和配置模板。

2.2 Patroni 加 Etcd：选主这件事得有个大家服气的裁判

PostgreSQL 高可用本质上是回答一个问题：主库死了，谁说了算？Patroni 给出了分布式系统里很经典的解法：借助外部分布式存储来做 leader 选举，同时它自己持续探测每个 PostgreSQL 实例的健康状态。

Pigsty 选择了 Etcd 作为 Patroni 的分布式一致性存储，而不是 Consul 或 ZooKeeper。原因是 Etcd 在 Kubernetes 生态里久经考验，部署和管理相对简洁，而且 Pigsty 本身也支持用同一套 Etcd 集群承载其他状态的保存。每个 PostgreSQL 节点上的 Patroni 会把主库位置、候选优先级、领导者租约等信息写入 Etcd。某个节点故障后，Patroni 会依据 Etcd 中的信息协商出新的主库。

我在实际测试中做过一次强制切换：把当前主库机器直接关机，大约 20 到 40 秒后，HAProxy 的流量就会切到新的主库。整个过程应用基本无感。这种效果并不是 PostgreSQL 数据库内核自己具备的能力，而是 Patroni 和 Etcd 协作的产物。

2.3 HAProxy：给太多无法直连数据库的团队一条活路

很多人会有疑问：客户端为什么不直接连接 PostgreSQL 而要走一层 HAProxy？直接连接看似简单，但有一个致命问题：主库切换后，客户端手里握着的连接全都失效。如果客户端本身不感知拓扑变化，就必须有人在前端把请求分流到当前的主库。HAProxy 在这里承担的就是数据库流量的“路由器”。

Pigsty 默认会给每个数据库节点分配两条 HAProxy 接入路径：一条指向当前主库，名称类似primary；另一条指向候选从库，名称类似replica。读写分离架构里，应用把只读流量打到replica端口，把写流量打到primary端口。主库切换时，Patroni 通过回调脚本触发 HAProxy 的配置变更，将主库端口重新指向新主节点。在应用看来，始终只需要连接同一个虚拟地址。

这里有一个细节：HAProxy 不参与 SQL 解析，它只做四层转发。所以 PostgreSQL 的预处理语句、事务、池化机制都不会受影响。它的性能损耗也极低，在我的测试环境中，即使不加任何外部连接池，纯 HAProxy 转发也能轻松扛住几千个并发连接。

2.4 Prometheus 三件套怎么融入架构

监控是 Pigsty 的另一个重头戏。每个 pgsql 节点上会部署 node_exporter 和 postgres_exporter，由 infra 节点上的 Prometheus 统一拉取指标。Grafana 预置了一百多个仪表盘，覆盖节点资源、数据库集群状态、表级膨胀、复制延迟、慢查询趋势等。Loki 负责收集各组件日志，提供关键字检索。

也就是说，你通过一份pigsty.yml部署出来的环境，不仅包含数据库本身，还包括一条完整的数据可观测链路。后面我会专门讲监控的使用，这里先让大家有个整体概念。

3. 预备环境与安装流程：YAML 配置写完之后，一条命令能办多少事

Pigsty 的安装过程完全围绕 Ansible 展开。你只要准备一台能够访问所有目标节点的控制主机，以及若干台待部署的服务器，然后写好一份 YAML 配置，剩下的大规模安装由 Ansible 并发执行。

3.1 环境准备阶段最容易忽略的三件事

我自己部署过好几轮 Pigsty，发现环境准备如果有一步不到位，后面排错会非常痛苦。先把最容易踩的坑列出来。

第一，操作系统兼容性。Pigsty 对操作系统有明确支持范围，我长期使用的是 CentOS 7.9、CentOS 9 Stream 和 Ubuntu 22.04。如果你用的是某个非常小众的 Linux 发行版，或者内核被深度修改过的定制系统，很可能在编译依赖阶段报错。

第二，主机名的规范化。Pigsty 会根据主机名生成大量标签，主机名里不要出现下划线或中文。建议统一用pg-test-01、pg-test-02这种风格。如果你的业务系统已经用了一堆不规则的机器名称，在部署前先把 hostname 改掉，否则后面 Grafana 看板里会出现一堆难认的标签。

第三，SSH 免密登录。Pigsty 控制机需要免密登录所有目标节点，而且至少需要 root 权限。有些人习惯用普通用户加 sudo，但在 Pigsty 的默认路径里，直接采用 root 登录是最省事的。先把每个节点的/root/.ssh/authorized_keys配置好，并通过ssh 节点IP确认能免密进入。

3.2 一份最简配置怎么改

安装 Pigsty 时，默认模板会生成一个pigsty.yml。下面是我在实验环境里经常使用的精简配置，假设我有三台机器，IP 分别为 10.10.10.10、10.10.10.11、10.10.10.12，规划如下：

• 10.10.10.10：infra + etcd + pgsql
• 10.10.10.11：etcd + pgsql
• 10.10.10.12：etcd + pgsql

这里把三台机器组成一个三成员 Etcd 集群，同时每台都跑 PostgreSQL，形成一主两从的高可用结构。

all: children: infra: hosts: 10.10.10.10: infra_seq: 1 etcd: hosts: 10.10.10.10: etcd_seq: 1 10.10.10.11: etcd_seq: 2 10.10.10.12: etcd_seq: 3 pgsql: hosts: 10.10.10.10: pgsql_seq: 1 pgsql_role: primary 10.10.10.11: pgsql_seq: 2 pgsql_role: replica 10.10.10.12: pgsql_seq: 3 pgsql_role: replica

在pgsql_cluster部分，建议给集群起个有业务含义的名字，例如pg-meta，并指定集群内的实例名。Pigsty 会基于这些标签生成服务发现、看板和告警规则。

3.3 从./install.sh到bin/pigsty install的完整动作

安装方式随版本演进而略有不同。在较新的版本里，控制台上执行./install.sh会先检查依赖，启动一个本地 Python 虚拟环境，并准备好 Ansible。随后你执行：

./install.sh bin/pigsty config edit bin/pigsty install

其中config edit会生成或修改pigsty.yml，将上一步的节点拓扑和集群配置填进去。install会按顺序执行整套 Playbook：

• 初始化基础设施角色：配置 Yum 源或 Apt 源，安装 Python、Ansible。
• 部署 infra 组件：Prometheus、Grafana、Loki、Nginx、Alertmanager。
• 部署 Etcd 集群。
• 部署 PostgreSQL、Patroni、HAProxy。
• 注册监控目标，加载 Grafana 数据源和看板。

整个过程如果网络畅通，三台机器的环境大概在 20 到 40 分钟能跑完。如果使用离线软件源，时间会更长，但不会因为外网中断而失败。

3.4 用检查命令确认一切正常

安装完成后，建议先跑几个命令验证。首先看服务是否存活：

bin/pigsty status

这个命令返回各个节点的角色和健康状态。然后在控制机上直接连接数据库：

psql -h 10.10.10.10 -U postgres -p 5432

Pigsty 默认创建了一个超级用户postgres，密码通常在安装日志或配置中有记录，但出于安全考虑，生产环境里一定要第一时间改掉。再检查监控入口，Grafana 默认端口是 3000，浏览器里打开http://10.10.10.10:3000，应该能看到预置的组织和团队配置。

我见过不少人把安装过程卡在“软件源配置”这一步。实际上 Pigsty 会在 infra 节点上建立一个本地 HTTP 服务，数据库节点从这台 infra 拉取 RPM 包。配置里的repo_url字段如果填错，所有节点都会安装失败。建议安装前先确认 infra 节点上3000之外，还有一个默认的 80 端口被 Nginx 占用，这是用来提供软件源和静态文件服务的。如果这台机器上已经跑着别的 Web 服务，需要提前改端口，避免冲突。

4. 实战建库：用 Pigsty 拉起一个 PostgreSQL 主从集群，并验证故障切换

配置和安装做完，只是拿到了一个“空舞台”。接下来你要真正创建业务数据库、测试高可用行为。这一节我记录一次完整的操作过程，覆盖从创建集群到手动宕机的验证。

4.1 新建一套业务集群，而不是复用默认集群

Pigsty 安装后默认会建立一个叫pg-meta的集群，用于承载基础设施本身的元数据。生产环境最好再独立创建一套业务集群，这样监控、备份和权限都可以隔离。创建集群的配置通常写在pigsty.yml里，通过pgsql_cluster下的新条目声明。

pgsql_cluster: pg-test: hosts: 10.10.10.11: { pgsql_seq: 1, pgsql_role: primary } 10.10.10.12: { pgsql_seq: 2, pgsql_role: replica } vars: pgsql_version: 16 pg_cluster: pg-test

接下来执行：

bin/pigsty pg add pg-test

这条命令只处理与pg-test集群相关的任务，不会影响已有的pg-meta。它会在目标节点上初始化数据目录、启动 Patroni、配置 HAProxy 路由，并把新集群自动注册到 Prometheus 监控里。这一步涉及的操作很多，但 Ansible 会保证幂等性，重复执行不会产生脏数据。

4.2 连接入口变得非常清晰

集群建立后，可以通过 HAProxy 端口访问。默认规则如下：

• 主库接入：端口 5432，后端只指向当前 leader。
• 只读接入：端口 5433，后端指向所有 replica，Pigsty 会做简单的轮询负载均衡。
• 直连节点：端口 5432 也可以直连到具体节点的 PostgreSQL，但建议优先走 HAProxy，避免主库切换后应用主动断开重连。

用psql测一下：

psql -h 10.10.10.11 -p 5432 -U postgres -d postgres psql -h 10.10.10.11 -p 5433 -U postgres -d postgres

第二个连接如果落在从库上，执行写操作会报只读错误，这是正确行为。很多新手看到从库不让写入，以为配错了，实际上这正是读写分离设计：写流量必须走 5432，读流量走 5433，语义清晰。

4.3 把主库杀掉，看 Patroni 和 HAProxy 如何接力

高可用验证不能只看文档，必须真实把主库“弄坏”。我常用的方法是直接停止主库所在节点的 PostgreSQL 进程，或者干脆用poweroff模拟整机宕机。下面是在主库节点上执行的操作：

systemctl stop patroni

这条命令会让 PostgreSQL 优雅关闭，同时 Patroni 向 Etcd 释放租约。几秒后，任意一个候选副本会竞选成为新主。在控制机上再次查询：

bin/pigsty pg check pg-test

可以看到集群 leader 已经变为原来的副本节点。此时再访问 HAProxy 的 5432 端口，写入依然成功。这就是 Patroni 与 HAProxy 协作的结果。

需要注意的是，Patroni 本身有一种“避免脑裂”机制：如果发现原主库仍然存活，它不会允许原主库作为新主库重新加入，而是将其降级为副本，然后跟随新主库重新同步数据。因此，即使原主库没有完全断电，只是网络抖动了一下，也不会出现双主写入的混乱局面。

4.4 副本扩容与缩容：一个隐藏的难点

如果你后面想给集群加新的从节点，最快捷的方式是在pg-test.hosts下增加一台机器的 IP，然后重新执行bin/pigsty pg add pg-test。Pigsty 会用新机器上空的实例启动一个基础备份，再从当前主库流式复制到新节点。整个过程中无需手动 pg_basebackup，也无需暂停写入。

缩容则要多留一个心眼。我刚开始操作时，直接从配置里删掉某个副本，然后执行了pgsql.yml的移除任务，结果发现清理不干净，监控里还残留旧节点。正确做法是先执行bin/pigsty pg remove pg-test -i 目标IP或者手动调用移除任务，把该节点上的 Patroni、HAProxy 配置、Prometheus 抓取目标一并删除，再动配置文件。如果顺序反了，后续想再重新加入这个节点，很容易出现 Etcd 中历史 key 未清理导致的冲突。

5. 监控不是附属品：Grafana 看板、Prometheus 指标和告警如何一并用起来

很多数据库部署方案把监控放在最后，好像监控只是“锦上添花”。Pigsty 不这么认为，它在安装数据库的同时就把监控体系完整搭建出来。你不需要额外安装任何采集器，只需要知道怎么用好这些看板和告警。

5.1 默认看板里最值得盯的三个页面

Grafana 登录后，你会看到大量预置看板。面对这么多仪表盘，容易眼花缭乱。我个人的习惯是只盯三个：集群总览、节点总览、慢查询分析。

PGSQL Cluster看板是最重要的入口。它把一条线从远端压到本地，生成很大的日志量，分析时访问日志存储压力很高，所以生产环境一般不会开启。另外一个常见问题是，有人登录 Grafana 后看不到任何数据，原因大多是 Prometheus 的抓取目标没有准备就绪。在 Prometheus 的 Target 页面检查一下，把 down 状态的 exporter 找出来修复，比在 Grafana 里到处点要有效得多。

5.3 告警规则的隐藏技巧

Pigsty 自带了一套告警规则，默认通过 Alertmanager 发送。你可以在alertmanager.yml里配置接收端，支持钉钉、企业微信、Slack 和邮件等。我最常用的是钉钉机器人，因为配置简单，只要填一个 Webhook 地址即可。

重要的不是怎么接，而是如何避免告警轰炸。Pigsty 默认的阈值有些偏敏感，比如“集群抖动”类告警，在滚动升级期间会大量出现。建议在接入生产环境前，先仔细过一遍默认告警规则文件，把与业务无关的规则禁用。否则凌晨 3 点被无关告警叫醒一次，之后再也不想用这套系统了。

我配置告警时做了三件事：把 “PG 实例重启”类告警直接关闭，因为计划内的升级和重启不需要打扰人；把 “复制延迟”告警从阈值 10MB 调整为 200MB，避免从库大量写入时瞬间超阈值；给每个告警规则加上负责人标签，方便转给对应值班人员。

5.4 慢查询日志的快速接入

日志组件 Loki 默认采集 PostgreSQL 日志，包括错误日志、自动清理日志和慢查询日志。使用前，需要确保 PostgreSQL 的log_min_duration_statement参数被设置成一个合理值。例如：

ALTER SYSTEM SET log_min_duration_statement = 500; SELECT pg_reload_conf();

这样执行超过 500 毫秒的 SQL 就会被记入日志，并通过 Loki 进入 Grafana。然后你可以用 LogQL 查询：

{app="pgsql"} |~ "duration" |~ "testdb"

把关键字替换成自己的业务库名，就能快速定位慢 SQL 出现的时间段和文本。这一套流程配置完成之后，你相当于同时拥有了数据库监控、主机监控和日志检索三件套，不用再把时间浪费在跳板机上敲命令了。

6. 经验沉淀：我用 Pigsty 时踩过的坑，以及我建议的初始化调优参数

最后这部分是我最想分享的内容。工具文档写得再好，也拍不到实际操作中的那些坑。我把自己在测试和生产准备阶段遇到过的问题，以及最后固定下来的一套初始化参数，整理在下面。

6.1 安装阶段最常见的两个失败原因

第一个失败原因是系统时钟不同步。Etcd 集群对时间偏差非常敏感，如果三台机器的系统时间差得太大，选主过程会异常，甚至出现间歇性的健康检查失败。Pigsty 不会自动帮你校正系统时间，所以部署前一定要确认各节点时间同步。我自己习惯在基础环境准备阶段就配置好chrony或ntpd，并且指定与业务网络内的时间服务器同步。

第二个失败原因是配置里填错了pg_version与整套软件源的对应关系。Pigsty 的软件源是按操作系统和数据库版本组织的，比如你选择的 Ubuntu 系统，却在软件源中只放了 CentOS 的包，安装时当然会失败。这种问题不会在第一阶段报错，而是到 PostgreSQL 初始化那一层才突然失败，排查起来非常费劲。最好的办法是严格按官方模板生成配置，只修改必要字段。

6.2 参数调优从哪里开始

Pigsty 默认的 PostgreSQL 参数相对保守，毕竟要考虑通用性。但如果你清楚自己的服务器配置，完全可以把参数调得更激进。下面是我对一台 16 核 CPU、64GB 内存、SSD 磁盘的常见机器的建议配置：

这些参数可以通过 Pigsty 的配置项直接下发。在pgsql_cluster.vars下面设置：

vars: pg_params: shared_buffers: 16GB effective_cache_size: 48GB work_mem: 32MB maintenance_work_mem: 2GB max_connections: 500 checkpoint_timeout: 15min max_wal_size: 16GB

修改后重新执行bin/pigsty pg reload或者直接重启实例，就能让参数生效。需要注意，max_connections是 Patroni 管理的关键参数，修改时 Pigsty 会把它写入 PostgreSQL 配置。

有一点必须反复强调：不要照搬别人的参数，一定要根据自己的业务负载做压测。我给的那个表只是起点，不是终点。尤其是max_connections，如果应用使用连接池，500 完全够用；如果几百个服务直连数据库，那 500 可能远远不够。参数调优的本质是在内存、CPU、IO 三者之间找平衡，而不是追求某个固定数值。

6.3 备份恢复：Pigsty 自带的脚本比想象中好用

Pigsty 内置了pg-probackup相关的封装脚本，可以按集群定期做全量或增量备份。它的思路是把备份集中放在某个目录，并保留一定策略。我第一次用时没仔细看，以为只支持手动执行，后来发现它已经集成了 cron 调度。

建议把备份目标路径指向一个独立的数据盘，不要让备份文件和 WAL 日志争抢同一块磁盘。否则当业务写入高峰来临时，备份进程会把 IO 占满，反而影响正常数据库服务。再一个建议是定期做恢复演练，而不是只在出故障时才发现备份坏了。我一般每两周从备份中恢复一个临时实例，跑一下核心业务的查询，确认备份数据可用。

6.4 最后的提醒：别把监控当摆设

部署完 Pigsty 后，我发现很多团队最喜欢做的是盯着 Grafana 的绿色状态喜悦一阵，然后就再也不打开了。等真正出问题时，看板里其实早就出现过征兆，只是没人解读。例如：复制延迟持续走高、事务 ID 回卷风险接近阈值、表格膨胀比例越来越大。Pigsty 把这些数据全部放在了默认看板中，如果团队里暂时没有专职 DBA，建议至少设置一个每日巡检的人，批量查看集群总览和节点总览，把异常截图发到值班群里。这种方法虽然原始，但非常有效。

我在一次模拟测试中就通过看板发现，某个从库的复制延迟在每天早上都有一个规律性尖峰，后来定位到是定时任务在同一时间大量写入造成的。如果没有 Pigsty 的复制延迟监控曲线，这个问题很难肉眼发现。

结尾也是一种经验：先从小集群开始，别急着上生产

如果你正准备引入 Pigsty，我的建议是先找三台虚拟机构建一个小型环境，完整走过一遍安装、建库、故障切换、备份恢复的全流程。在这个过程中，你一定要尝试把主库杀掉，观察监控指标如何变化，亲手把角色切回来。这个“亲手摧毁再重建”的循环做过几次之后，你对高可用的理解会完全不一样。

我个人在实际使用中的体会是，Pigsty 的价值不在于某个单项功能有多惊艳，而在于它把一堆数据库运维琐事收敛成了“配置 + 命令”的简单组合。它不可能替你解决所有业务问题，但至少让你在凌晨三点被叫醒时，能够更快地定位问题，而不是对着十几个终端窗口发懵。希望这篇文章能让你少走一些我走过的弯路，也欢迎你在实践后回来分享你自己的踩坑经历。