企业官网建设流程全解析

• 数据库
• 运维
• 云原生
• 高可用
• 监控

导读

本文围绕 Pigsty 的conf配置模板目录展开，系统讲解 Pigsty 的"配置即代码（IaC）"落地方式：从./configure的交互式配置生成流程，到单节点主模板、异构 PostgreSQL 内核模板、多节点高可用（HA）模板、应用（App）模板与演示（Demo）模板的完整选择与使用指南。读完本文，你将掌握如何通过./configure -c <conf>一键生成适用于单机、双机、三机乃至 20 节点生产环境的pigsty.yml，理解meta、rich、slim、mssql、polar、ha/trio、app/supa等模板各自的设计意图、关键参数与适用场景，并能结合仓库中的 configure 脚本源码理解配置生成的底层机制。

配置模板与 configure 机制

conf目录存放的是 Pigsty 的配置模板（Config Template），它们会在./configure流程中被使用。configure 是一个交互式 Bash 脚本，负责根据本机环境探测结果与用户指定的模板，生成最终的pigsty.yml配置文件。

configure 的用法与参数

配置模板通过./configure -c <conf>指定，其中<conf>是相对于conf目录的路径，可带可不带.yml后缀。脚本头部完整声明了支持的命令行参数（见 configure）：

未指定模板时，Pigsty 默认使用conf/meta.yml单节点模板。若指定了不存在的模板，脚本会报错config = conf/<mode>.yml not exists并以退出码 11 终止（configure）。

configure 的内部工作流

从 configure 的主流程可以看到，configure 依次执行如下探测与生成步骤：

1. 区域检测：通过探测google.com与pigsty.cc的可达性判断是否处于 GFW 之后，自动选择china或default镜像区域（configure）；
2. 版本校验：-v指定的 PostgreSQL 版本必须是14 15 16 17 18 19之一，否则退出（configure）；
3. 环境探测：检查内核（Linux/Darwin）、架构（x86_64/aarch64）、包管理器（rpm 系 dnf/yum/zypper 或 deb 系 apt）、发行版版本与 sudo/SSH 免密能力；
4. IP 探测：优先使用-i参数，其次自动探测；多 IP 时交互式询问用户；非交互模式下遇到歧义会报错退出（configure）；
5. 模板落盘：将conf/<mode>.yml以install -m 0600（权限 600）复制为pigsty.yml，并执行系列sed替换：
   • 将占位 IP10.10.10.10替换为探测到的primary_ip；
   • 当 CPU 核数小于 4 时，自动把pg_conf: oltp.yml降级为tiny.yml、node_tune: oltp降级为tiny（configure）；
   • 根据-r区域替换region，中国区域自动启用 Docker 镜像加速与 PIP 镜像；
   • -x时将HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY写入proxy_env；
   • -v时 upsertpg_version，并将pg18-扩展包名批量改写为pg<ver>-；PG 19 会额外加入beta软件源；
   • PG 版本 >= 17 或系统支持 C.UTF-8 时，追加pg_locale: C.UTF-8等区域设置；
   • -g时为 8 组前缀键（如grafana_admin_password、pg_admin_password、patroni_password等）及 7 组全局占位口令（如DBUser.Meta、S3User.Backup）生成 24 位随机字母数字密码（configure）。

配置生成完毕后，脚本提示检查配置并修改密码，然后按./deploy.yml或./deploy.yml -i <output>继续部署。

单节点主模板：从全功能到极简

主模板都是 1 节点配置，可在单机上完成 Pigsty 安装：

meta.yml：默认单节点模板精读

meta.yml 是 Pigsty 的默认模板，其拓扑如下：

• pg-meta：单节点 PostgreSQL 集群，10.10.10.10: { pg_seq: 1, pg_role: primary }定义了一个 primary 实例；注释中展示了如何追加replica（只读副本）与offline（ETL/交互查询离线实例）节点，这是从 1 节点平滑扩展为多节点的关键入口；
• infra：监控与告警基础设施（repo_enabled: false，1 节点模式下禁用本地仓库）；
• etcd：为 Patroni 提供 HA 共识的 DCS 服务；
• app：默认启动 pgadmin 应用（app: pgadmin），管理员账号admin@pigsty.cc / pigsty。

模板的核心业务建模体现在以下三组参数：

• pg_extensions：[ postgis, pgvector ]，声明要安装的扩展包；
• pg_users：业务用户定义，name是唯一必填字段。示例定义了两个用户：dbuser_meta（pigsty 管理员，dbrole_admin角色，启用 pgbouncer）与dbuser_view（只读用户，dbrole_readonly角色）；
• pg_databases：业务数据库定义，meta库以files/cmdb.sql为 baseline 初始化，创建pigstyschema，并安装postgis、vector扩展。

全局参数区定义了version: v4.5.0、admin_ip、region、proxy_env（含默认no_proxy列表）、infra_portal（通过 Nginx 门户暴露i.pigsty与adm.pigsty）、node_tune: oltp（节点调优规格，可选 oltp/olap/tiny/crit）、pg_conf: oltp.yml（PostgreSQL 调优规格）、pg_version: 18以及一组默认口令。pg_crontab中00 01 * * * /pg/bin/pg-backup full定义了每日凌晨 1 点的全量备份任务。

meta.yml 还注释保留了扩展与备份配置的完整骨架：pgbackrest_method: minio与pgbackrest_repo支持切换到 MinIO 或阿里云 OSS 等 S3 兼容对象存储做远程备份，并支持block: y（块级增量备份）、bundle（小文件打包）、cipher_type: aes-256-cbc（AES 加密）与按数量/按时间两种保留策略（meta.yml）。

rich.yml：功能增强版精读

rich.yml 在 meta.yml 基础上做了四方面增强：

1. 几乎全量扩展：pg_extensions: [ postgis, timescaledb, pgvector, pg_wait_sampling ]并配置pg_libs: 'timescaledb, pg_stat_statements, auto_explain, pg_wait_sampling'预加载；全局的repo_extra_packages注释中列出pg18-time/gis/rag/fts/olap/feat/lang/type/util/func/admin/stat/sec/fdw/sim/etl共 16 组扩展类别；
2. 本地软件源：repo_enabled: true，构建本地 repo 并从其中安装所有软件，适合离线或内网环境；
3. 内置 MinIO 备份仓库：定义minio集群与 3 个 S3 用户（pgbackrest/s3user_meta/s3user_data，对应pgsql/meta/data三种策略），并把pgbackrest_method切换为minio，形成"本地 + MinIO + 云 S3"三仓库备份方案；
4. 更完整的注释示例：pg_users中逐个注解了password/pgbouncer/comment/roles/state/login/superuser/createdb/createrole/inherit/replication/bypassrls/connlimit/expire_in/parameters/pool_mode等字段含义，并给出 PG16+ 增强角色语法（admin: true授予 ADMIN OPTION 等）；pg_databases中注解了baseline/schemas/extensions/owner/template/strategy/encoding/locale/locale_provider/icu_locale/tablespace/is_template/revokeconn/register_datasource/pool_*等完整字段。

rich.yml 还包含一个注释态 3 节点pg-test集群示例（含pg_services自定义服务：standby 服务把 5435 端口路由到同步副本的 pgbouncer），以及一个 1 节点 Redis 主从示例redis-ms（redis_node: 1+6380: { replica_of: '10.10.10.10 6379' }），便于后续用./redis.yml直接拉起。

slim.yml：无监控极简安装

slim.yml 只包含etcd与pg-meta两个集群，明确注释"不安装监控与 infra，只有原生 PostgreSQL"。它是轻量实验、嵌入式场景的首选，结构比 meta 更精简：无 infra、无 minio、无 app，仅保留 pgsql 核心参数与默认口令区。

异构内核模板：一个 Pigsty，12 类 PostgreSQL 发行版

Pigsty 的一个核心特色是支持多种 PostgreSQL 内核（kernel fork），同类模板共用同一套基础设施，仅通过pg_mode、pg_packages与专用参数切换内核：

mssql.yml：Babelfish 内核模板

mssql.yml 用于部署 Babelfish 内核——一个带 SQL Server 兼容能力的 PostgreSQL 17/18 fork。关键配置如下：

• pg_mode: mssql开启 MSSQL 兼容模式；pg_packages: [ babelfish, pgsql-common, sqlcmd ]替换内核并附带sqlcmd工具；
• pg_libs: 'babelfishpg_tds, pg_stat_statements, auto_explain'预加载 TDS 监听器，使 PG 直接监听 SQL Server 协议；
• 业务库mssql以 files/mssql.sql 为 baseline，安装uuid-ossp与babelfishpg_common/tsql/tds/money系列扩展，并设置babelfishpg_tsql.migration_mode: multi-db；
• 核心用户dbuser_mssql是 superuser 与库 owner；pg_hba_rules明确要求对 mssql 用户使用md5认证；
• pg_default_services将 primary/replica 服务分别路由到5433/5434 -> 1433（MSSQL 默认端口），default/offline服务则仍走5436/5438 -> postgres，实现"同集群同时暴露 PG 与 SQL Server 两种接入方式"。

polar.yml：PolarDB 内核模板

polar.yml 部署基于 PG 17 的 PolarDB PG fork（RAC 风味）：pg_mode: polar、pg_packages: [ polardb, pgsql-common ]。其特殊之处在于：

• 监控需排除polardb_admin库：pg_exporter_exclude_database: 'template0,template1,postgres,polardb_admin'；
• 通过pg_default_roles重定义系统角色体系，PolarDB 要求replicator是 superuser 才能做复制，因此示例中postgres与replicator均标记为superuser: true，同时额外定义了dbuser_dba（superuser + 会话级 pgbouncer）与dbuser_monitor角色。

其余内核模板（ivory/mysql/pgtde/oriole/agens/pgedge/supabase/pg19）结构类似，差异集中在pg_mode、pg_packages、pg_libs与扩展列表上，均可通过./configure -c <模板名>直接选用。例如supabase.yml是 Supabase 自托管的完整流水线模板：./configure -c supabase生成配置后，依次执行./deploy.yml（装 Pigsty + pgsql + minio）、./docker.yml（装 Docker）与./app.yml（用 Docker Compose 拉起 Supabase 全套服务）。

HA 模板：多节点高可用部署

多节点 HA 模板在 conf 的ha/子目录下，通过./configure -c ha/<name>使用：

ha/dual.yml：双节点故障模型

ha/dual.yml 面向"只有两台机器"的场景：.10为 admin 节点（承担 infra 与 etcd），.11为 pgsql primary。模板头部明确注释了双节点下的故障语义：

• 若.11宕机，由于 etcd 仍存活，.10会接管成为 primary；
• 若.10宕机（仅 etcd 或仅 pgsql 故障），.11作为 primary 仍可继续服务；
• 若 etcd 与 pgsql 同时不可用（如整节点宕机），primary 会主动降级自身。

集群启用了pg_vip_enabled: true与pg_vip_address: 10.10.10.2/24，通过 L2 VIP 绑定到当前 primary，业务侧通过 VIP 访问实现故障切换无感知。

ha/trio.yml：三节点标准 HA

ha/trio.yml 是生产推荐的三节点拓扑：3 infra + 3 etcd + 3 pgsql + 1 minio。

• infra 三节点中只有.10启用 repo（repo_enabled: false标记其余节点），并设置patroni_watchdog_mode: 'off'避免对 infra 节点做 fencing；
• etcd 三节点构成奇数成员 DCS，满足共识要求（注释建议生产用 3 或 5 节点）；
• pg-meta 三节点：.10primary、.11replica、.12replica 且pg_offline_query: true（离线可查询副本，承载报表/ETL 流量）；
• minio 单节点作为备份仓库，node_etc_hosts注册i.pigsty与sss.pigsty域名，pgbackrest_repo配置 local + minio 双仓库，保留策略为本地按数量（保留 2 份）、MinIO 按时间（保留 14 天），并启用 AES-256-CBC 加密。

ha/citus.yml：13 节点分布式集群

ha/citus.yml 定义了一个 6 工作组的 Citus 分布集群拓扑：pg-citus0协调节点（10.10.10.10，VIP 10.10.10.19）+pg-citus1~6六个工作组（每组 2 节点，VIP 依次为 10.10.10.29/39/49/59/69/79），并使用本地 repo 引导集群启动。

App 模板：随附的应用软件栈

conf/app/下的模板用于以 Docker 方式部署常见软件，通过./configure -c app/<name>生成配置、再以./app.yml启动：

以 app/supa.yml 为例，其完整启动流程为：./configure -c supabase→./deploy.yml（安装 Pigsty、pgsql、minio）→./docker.yml（安装 Docker）→./app.yml（以 Docker Compose 拉起 Supabase），支持 el8/el9/u22/u24/u26/d12 平台与 PG 15~18。仓库中对应应用的具体编排文件位于 app 目录，例如 app/supabase/docker-compose.yml。

Demo 模板：场景化参考配置

除主模板外，conf/demo/提供一组针对不同场景的演示与参考配置：

其中两个模板颇具实战价值：

demo/remote.yml——监控远端 RDS：该模板展示了如何用 Pigsty 监控不在本机部署的远程 PostgreSQL（如云 RDS）。方法是在infra组的pg_exporters中为每个远端实例分配一个本地空闲端口作为 key（如20001），并声明pg_cluster、pg_seq、pg_host、pg_port，可覆盖pg_exporter_url（直接给连接串）或pg_monitor_username/password，通过pg_databases把远端库注册为 Grafana 数据源（demo/remote.yml）。示例中包含阿里云 PolarDB（pxx.polardbpg.rds.aliyuncs.com）与 RDS PG 的监控配置，并可开启pg_exporter_auto_discovery自动发现数据库。这正是 Pigsty 从"部署平台"延伸为"统一监控平台"的典型用法。

demo/kernel.yml——内核矩阵：单文件定义 10 节点，同时承载 Vanilla PG+Citus、IvorySQL、Babelfish 等不同内核集群，每个集群通过pg_mode、pg_packages、pg_libs与扩展组合独立声明（如pg-citus集群安装citus并在库内启用citus, postgis, vector扩展），便于在一个环境里横向对比各内核行为。

模板选型与最佳实践

综合 conf/README.md 与上述模板源码，可归纳以下选型建议：

1. 单机快速上手：无特殊要求用默认meta；要离线/内网部署与备份仓库选rich；只要裸 PostgreSQL 选slim；只建监控栈选infra；
2. 内核切换：按业务兼容性需求选mssql（SQL Server）、ivory（Oracle）、polar（云原生 RAC）、pgedge（分布式）等，无需改动基础设施层；
3. 高可用：两机用ha/dual（注意其故障语义限制），生产至少三机用ha/trio，需要分布式用ha/citus，安全敏感场景参考ha/safe；
4. 应用扩展：在已有 pgsql 基础上，用app/*模板与 app.yml 拉起 Supabase、Dify、Odoo 等应用；
5. 后期扩节点：单节点模板中的注释已给出追加replica/offline节点的写法，可先以 1 节点起步再逐步扩容；也可以从一开始就用 HA 模板规划。

所有模板生成配置文件后，都应在部署前仔细检查密码等敏感项——./configure -g可一次性生成随机口令，这也是生产环境的推荐做法。整个配置体系以 conf/README.md 为索引、以 configure 脚本为生成引擎，构成了 Pigsty 完整、可复现、模板化的 IaC 部署骨架。

• 数据库
• 运维
• 云原生
• 高可用
• 监控