Pigsty 的主配置文件,描述您的整个部署
这是本节的多页打印视图。 .
配置
Pigsty 将基础设施和数据库视为代码。 您可以使用声明式配置 清单 描述一切。
通常是 YAML 格式的 Ansible 清单:pigsty.yml。
但 CMDB 也可以用作动态清单。
configure 过程将根据您的环境和输入生成配置。
但这是 可选的:您始终可以直接编辑 pigsty.yml 文件,如 教程 所示。
并且有大量的 模板 供您参考。
根据您的输入和环境生成配置文件
根据业务需求规划您的部署
可用的配置模板和示例
生产部署的安全考虑和最佳实践
使用 PostgreSQL 作为 CMDB 而不是本地 YAML 配置文件
具有 HA、PITR、IaC、ACL、监控、连接池的 PostgreSQL 集群
用于可观测性的 Nginx、仓库、DNS、NTP、Prometheus 和 Grafana 技术栈
将节点注册到期望状态并监控它,以及 VIP、HAProxy
可靠的分布式共识存储 (DCS),为 PGSQL HA 提供支持
兼容 S3 的对象存储,可选备份存储
高性能内存缓存,可选数据结构服务器
1 - 清单
每个 pigsty 部署都有一个对应的配置 清单。
它可以存储在 YAML 格式的本地配置文件中,或从 CMDB 或任何 ansible 兼容格式动态生成。
Pigsty 默认使用一个单一的 YAML 配置文件,即 pigsty.yml,位于 pigsty 主目录中。
pigsty/
configure 脚本将根据您的环境和输入生成具有良好默认值的 pigsty.yml 文件脚手架,
但它是 可选的:您始终可以直接编辑 pigsty.yml 文件,如教程所示。
结构
清单由两部分组成:全局变量 和多个 组。您可以在 all.children 中定义新集群。
并使用全局变量描述基础设施:all.vars。它可能看起来像这样:
在 conf/ 下有大量示例,在 configure 期间也可以用作模板。
集群
每个 ansible 组可能代表一个集群,可以是节点集群、PostgreSQL 集群、Redis 集群、Etcd 集群或 Minio 集群等…
集群定义由两部分组成:hosts 和 vars。
您可以在 <cls>.hosts 中定义集群成员,并在 <cls>.vars 中使用参数描述集群。
这是一个 3 节点 HA PG 集群的示例:
集群级别的 vars 将覆盖全局变量,主机级别的 vars 将覆盖集群变量和全局变量。
参数
参数是定义部署中所有实体的键值对。 键是字符串名称,值可以是五种类型之一:布尔值、字符串、数字、数组或对象。
参数可以在不同级别设置,具有以下优先级:
| 级别 | 位置 | 描述 | 优先级 |
|---|---|---|---|
| CLI 参数 | 命令行 | 通过 -e CLI 参数 |
最高 (5) |
| 主机变量 | <group>.hosts.<host> |
特定于单个主机的参数 | 高 (4) |
| 组变量 | <group>.vars |
组/集群中主机共享的参数 | 中等 (3) |
| 全局变量 | all.vars |
所有主机共享的参数 | 低 (2) |
| 默认值 | <roles>/default/main.yml |
角色实现默认值 | 最低 (1) |
以下是关于参数优先级的一些示例:
- 使用 Playbook CLI 参数
-e pg_version=16覆盖 PostgreSQL 主版本 - 使用主机变量上的实例级别参数
pg_role覆盖 pg 实例角色 - 使用组变量上的集群级别参数
pg_cluster覆盖 pg 集群名称。 - 使用全局变量上的全局参数
node_ntp_servers指定全局 NTP 服务器 - 如果没有设置
pg_version,pigsty 将使用角色实现的默认值(默认为18)
除了强制性的 身份参数 外,每个参数都有一个适当的默认值;它们用作标识符,必须明确设置。
例如上述片段中的 pg_cluster、pg_role 和 pg_seq。
可用参数根据模块而异:
参考
Pigsty 有 290+ 个参数,查看模块参数了解详细信息。
| 模块 | 部分 | 描述 | 数量 |
|---|---|---|---|
INFRA |
META |
Pigsty 元数据 | 4 |
INFRA |
CA |
自签名 CA | 3 |
INFRA |
INFRA_ID |
基础设施门户和身份 | 2 |
INFRA |
REPO |
本地软件仓库 | 9 |
INFRA |
INFRA_PACKAGE |
基础设施包 | 2 |
INFRA |
NGINX |
Nginx Web 服务器 | 7 |
INFRA |
DNS |
DNSMASQ 名称服务器 | 3 |
INFRA |
PROMETHEUS |
Prometheus 堆栈 | 18 |
INFRA |
GRAFANA |
Grafana 堆栈 | 6 |
INFRA |
LOKI |
Loki 日志服务 | 4 |
NODE |
NODE_ID |
节点身份参数 | 5 |
NODE |
NODE_DNS |
节点域名和解析器 | 6 |
NODE |
NODE_PACKAGE |
节点仓库和包 | 5 |
NODE |
NODE_TUNE |
节点调优和内核功能 | 10 |
NODE |
NODE_ADMIN |
管理员用户和凭据 | 7 |
NODE |
NODE_TIME |
节点时区、NTP、Crontabs | 5 |
NODE |
NODE_VIP |
节点 Keepalived L2 VIP | 8 |
NODE |
HAPROXY |
HAProxy 负载均衡器 | 10 |
NODE |
NODE_EXPORTER |
节点监控代理 | 3 |
NODE |
PROMTAIL |
Promtail 日志代理 | 4 |
DOCKER |
DOCKER |
Docker 守护进程 | 4 |
ETCD |
ETCD |
ETCD DCS 集群 | 10 |
MINIO |
MINIO |
MINIO S3 对象存储 | 15 |
REDIS |
REDIS |
Redis 键值 NoSQL 缓存 | 20 |
PGSQL |
PG_ID |
PG 身份参数 | 11 |
PGSQL |
PG_BUSINESS |
PG 业务对象定义 | 12 |
PGSQL |
PG_INSTALL |
安装 PG 包和扩展 | 10 |
PGSQL |
PG_BOOTSTRAP |
使用 Patroni 初始化 HA PG 集群 | 35 |
PGSQL |
PG_PROVISION |
创建数据库内对象 | 9 |
PGSQL |
PG_BACKUP |
使用 pgBackRest 设置备份仓库 | 5 |
PGSQL |
PG_ACCESS |
暴露服务、绑定 VIP、DNS | 16 |
PGSQL |
PG_MONITOR |
收集 Postgres 的指标和日志 | 18 |
PGSQL |
PG_EXPORTER |
移除 Postgres 集群 | 4 |
2 - 配置
configure 脚本将根据您的环境和输入生成具有良好默认值的 pigsty.yml 配置文件清单。
它是 可选的,您可以直接编辑 pigsty.yml,如教程所示。
pigsty/
用法
除非指定了 -n|--non-interactive,否则 configure 脚本是一个交互式向导。
| 选项 | 描述 |
|---|---|
-c|--conf |
根据此参数从配置模板生成配置 |
-i|--ip |
用给定 IP 替换 IP 地址占位符 10.10.10.10 |
-v|--version |
指定 PostgreSQL 主版本号(13|14|15|16|17|18) |
-r|--region |
根据 region 设置上游仓库镜像(default|china|europe) |
-o|--output |
将生成的配置清单写入指定文件(默认为 pigsty.yml) |
-x|--proxy |
将当前代理环境写入配置 proxy_env |
-s|--skip |
跳过交互式向导并使用默认/参数值 |
-n|--non-interactive |
非交互模式 |
-p|--port |
指定 SSH 端口(仅在设置时使用) |
示例
configure 输出示例:
行为
如果指定了 -c|--conf <template>,它将从指定的模板生成配置文件。例如 meta、app/supa 等…
如果没有给出配置模板,它将使用默认的单节点配置模板 meta。
如果指定了 -i|--ip <ipaddr>,它将用给定的 IP 地址替换配置模板中的占位符 10.10.10.10。
否则,如果当前节点只有一个 IP 地址,将使用该地址。如果有多个 IP 地址,它会要求您手动输入当前节点的主 IP 地址。
如果指定了 -v|--version,它将使用指定的 PostgreSQL 主版本号,范围从 13 到 18。
如果没有指定版本,它会保持 pg_version 不变,通常默认回退到 18。
如果指定了 -r|--region,它将直接使用指定的区域。在无法访问 Google 服务的地方将使用 china 镜像。
如果指定了 -x|--proxy,它将把当前代理环境变量写入配置 proxy_env。
在安装期间将被重用。包括:HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY。
如果指定了 -s|--skip,它将跳过 IP 地址替换和 ssh sudo 权限检查
如果指定了 -n|--non-interactive,此脚本不会询问您任何事情,但您必须使用 -i|--ip <ipaddr> 明确指定主 IP 地址。
如果指定了 -p|--port,它将使用指定的 SSH 端口而不是默认的 22。
当您的本地 SSH 端口不是 22 时使用。
Pigsty 将使用 C.UTF-8 作为默认区域设置,如果:
- PostgreSQL 主版本 ≥ 17,具有内置本地提供程序(默认)
- 或者,您的系统支持
C.utf8/C.utf-8区域设置(locale -a)
否则,默认将使用本地 C。
3 - 教程
您可以手动从零开始编写 pigsty 配置文件,而不是使用 configure 生成配置。
这里是一个教程,帮助您从零开始构建复杂的配置文件清单。
最小配置
这是一个最小的工作配置示例,您必须告诉 pigsty 管理节点和基础设施节点的 IP。
这将在 10.10.10.10(更改为您的 IP 地址)上安装 INFRA 和 NODE 模块。
您将拥有一个完整的可观测性堆栈和节点监控。但数据库服务尚未运行。
PGSQL & ETCD
要提供 PostgreSQL 服务,您必须定义其他组并安装 PGSQL 和 ETCD 模块。
我们在这里添加了两个新组:etcd 和 pg-meta,它们定义了一个 1 节点 ETCD 集群和一个 1 节点 PGSQL 集群。
使用 ./install.yml 重新创建所有内容,或使用这些命令进行增量步骤:
PGSQL 模块依赖 ETCD 进行 HA 共识,因此请确保首先安装 ETCD 模块。
数据库和用户
现在我们要自定义我们的 postgres 数据库集群,包括用户、数据库和备份:
我们在 pg-meta 集群级别定义一些额外的详细信息:
pg_users:定义一个新用户dbuser_meta,密码为DBUser.Metapg_databases:定义一个新数据库meta,包含 pigsty CMDB 模式和vector扩展node_crontab:定义在每天凌晨 1 点进行完整备份的 crontab
我们不使用 ./install.yml 重新创建所有内容,而是增量地进行更改:
PG 版本和扩展
您可以安装不同的 PostgreSQL 主版本,以及 437 相应的扩展。
让我们安装 PostgreSQL 16(而不是默认的 18),包含 timescaledb、postgis 和 pgvector 扩展。
repo_extra_packages:下载timescaledb和postgis扩展。pg_libs:预加载timescaledb、pg_stat_statements、auto_explain扩展。
让我们重新下载缺失的包(PG 16 内核和扩展),删除旧集群,并重新创建它:
更多节点
我们可以向此部署添加 3 个更多节点。
或者逐个添加它们:
PGSQL HA
现在我们要添加一个新的数据库集群 pg-test,具有 3 节点 HA 设置:
Pigsty 的工作假设是每个节点上只有一个 postgres 实例。 不支持在单个节点上运行多个 postgres 实例。
Redis 启动
Pigsty 有可选的 Redis 支持,用作 PostgreSQL 前面的缓存。
Redis HA 设置需要集群模式或哨兵基础设施,请查看 Redis 配置了解详情。
MinIO 启动
Pigsty 有可选的 MinIO 支持,用作 PostgreSQL 的备份存储。
严肃的生产 MinIO 部署通常需要至少 4 个节点,每个节点有 4 个磁盘(4N/16D)
Docker 启动
在 infra 组上安装 docker:
运行 PgAdmin
查看 App: Pgadmin 了解如何使用 Pigsty 运行 pgAdmin 的详细信息。简短版本:
自托管 Supabase
查看 App: Supabase 了解如何使用 Pigsty 运行 Supabase 的详细信息。简短版本:
4 - 模板
这个目录 conf 包含 pigsty 配置模板,将在 configure 过程中使用。
配置模板可以使用 ./configure -c <conf> 指定,其中 conf 是到 conf 目录的相对路径(有或没有 .yml 后缀)。
例如 ~/pigsty/conf/rich.yml 可以指定为 rich
如果没有给出 -c|--conf,默认会自动选择单节点 meta 配置模板。
基本模板
这里是单节点模板,提供不同的功能和配置。
| 模板 | 节点 | 描述 |
|---|---|---|
meta.yml |
1 | 默认 1 节点配置,pgsql、infra、node、etcd,最小扩展 |
rich.yml |
1 | meta + minio + 所有扩展 |
slim.yml |
1 | meta - infra - node 监控,最小安装 |
fat.yml |
1 | 下载PG13-18 所有包,安装全部扩展 |
异种内核
使用异种 Postgres 内核分支:
| 模板 | 节点 | 描述 |
|---|---|---|
mssql.yml |
1 | WiltonDB 和 Babelfish,具有 MSSQL 协议兼容性 |
polar.yml |
1 | PolarDB for PostgreSQL,具有 Aurora RAC 特性 |
ivory.yml |
1 | IvorySQL 集群,具有 Oracle 兼容性 |
mysql.yml |
1 | Halo 集群,具有 MySQL 协议兼容性 |
mongo.yml |
1 | FerretDB 和 DocumentDB,具有 Mongo 协议兼容性 |
oriole.yml |
1 | OrioleDB 集群,具有 OLTP 增强 |
多节点
| 模板 | 节点 | 描述 |
|---|---|---|
dual.yml |
2 | 半高可用部署 |
trio.yml |
3 | 标准高可用部署 |
full.yml |
4 | 沙箱部署 |
safe.yml |
4 | 带延迟副本的安全增强 |
simu.yml |
36 | 生产模拟 |
应用程序
| 模板 | 描述 |
|---|---|
app/supa.yml |
启动 1 节点 supabase |
app/odoo.yml |
启动 odoo ERP 系统 |
app/dify.yml |
启动 dify AI 工作流系统 |
app/electric.yml |
启动 electric 同步引擎应用 |
演示模板
| 模板 | 描述 |
|---|---|
demo/el.yml |
EL 8/9 系统的包含所有默认参数的配置文件 |
demo/debian.yml |
debian/ubuntu 系统的包含所有默认参数的配置文件 |
demo/remote.yml |
监控远程 pgsql 集群或 RDS PG 的示例配置 |
demo/redis.yml |
redis 集群的示例配置 |
demo/minio.yml |
3 节点 minio 集群的示例配置 |
demo/demo.yml |
pigsty 公共演示 的配置文件 |
citus.yml |
Citus 集群示例:1 个协调器和 3 个数据节点(4 节点) |
构建模板
| 模板 | 描述 |
|---|---|
build/oss.yml |
EL 8、9、Debian 12 和 Ubuntu 22.04/24.04 OSS 的构建配置 |
build/pro.yml |
EL 7-9、Ubuntu、Debian pro 版本的构建配置 |
5 - 安全
Pigsty 已经提供了一个默认安全的数据库身份验证和访问控制模型。
只要您遵循以下安全最佳实践,它对大多数常见场景来说都足够强大。
机密性
文件
pigsty.yml包含非常敏感的信息,如密码- 限制只有管理员/DBA 用户才能访问管理员/基础设施节点
- 如果您使用 GitOps 管理 pigsty 配置,请限制对仓库的访问
- 默认生成在
~/pigsty/files/pki/ca/ca.key - 在安全的地方备份它,不要丢弃它!
- 还要考虑保护各种证书的其他私钥
密码
在严肃的部署中,始终更改这些默认密码
grafana_admin_password:pigstypg_admin_password:DBUser.DBApg_monitor_password:DBUser.Monitorpg_replication_password:DBUser.Replicatorpatroni_password:Patroni.APIhaproxy_admin_password:pigstyminio_secret_key:minioadmin
如果您使用 MinIO 作为备份存储,还要更改这些凭据:
- 更改
minio_users.[pgbackrest].secret_key的密码 - 更改 pgbackrest 引用:
pgbackrest_repo.minio.s3_key_secret
- 将
$lib/passwordcheck添加到pg_libs以强制执行密码策略。 - 更强版本:
passwordcheck_cracklib
- 检查
pgbackrest_repo定义repo_cipher_type - 默认为
cipher_type: aes-256-cbc
- 使用
pg_pwd_enc默认scram-sha-256而不是传统的md5 - 默认行为是
scram-sha-256,md5已被弃用
为了合规目的,您可以为每个用户设置过期日期。
不要忘记使用 pgsql-user.yml playbook 定期刷新这些过期日期
IP 地址
- 默认的
pg_listen地址是0.0.0.0,即所有 IPv4 地址。 - 考虑使用
pg_listen: '${ip},${vip},${lo}'绑定到特定地址以获得更好的安全性。
- Grafana/Prometheus 默认绑定到所有 IP 地址以便于使用。
- 您可以修改它们的绑定配置,使其监听 localhost/内网 IP 并通过 Nginx 暴露。
- Redis 服务器默认绑定到所有 IP 地址以便于使用。您可以更改
redis_bind_address以监听内网 IP。 - 您也可以通过安全组或防火墙规则来实现。
- 有一个安全增强配置模板:
safe.yml
- 这默认通过
restapi.allowlist进行限制
网络流量
- Nginx SSL 由
nginx_sslmode控制,默认为enable。 - Nginx 域名由
infra_portal..domain指定。
patroni_ssl_enabled默认禁用- 因为它会影响健康检查和 API 调用。
- 注意这是一个全局选项,您必须在部署前决定。
pgbouncer_sslmode默认为disable- 因为它对性能有显著影响。
完整性
一致性
- 使用
crit.yml模板为pg_conf将牺牲一些可用性以获得最佳一致性。
-
将
node_tune设置为crit以减少脏页比率。 -
启用数据校验和以检测静默数据损坏。
-
pg_checksum在 v3.7.0 中默认启用 -
这可以稍后启用,但需要完整的集群扫描/停止。
审计
- 在 pg 集群引导后启用
log_connections和log_disconnections。 - 审计传入会话;这在
crit.yml中默认启用。
误操作
再次运行 install.yml 将销毁(覆盖)整个部署!
在 v3.5 之前,它默认会覆盖现有的 PostgreSQL。
使用 pg_safeguard 避免误操作
可用性
冗余
- 您需要至少三个节点(容忍一个节点故障)才能实现生产级高可用性。
- 如果您只有两个节点,您可以容忍特定备用节点的故障。
- 如果您有一个节点,请使用外部 S3/MinIO 进行冷备份和 wal 归档存储。
- 在严肃的生产部署中使用多个基础设施节点(例如,1~3)
- 通常,2 ~ 3 对于大型生产部署来说是足够的。
- 使用足够的 etcd 成员并使用奇数(1,3,5,7)。
- 查看 ETCD 配置 了解详情。
容错
访问
- 不要通过固定 IP 地址直接访问数据库;使用 VIP、DNS、HAProxy 或它们的组合。
- Haproxy 将在故障转移/切换时为客户端处理流量控制。
6 - CMDB
Pigsty 允许您使用 数据库(CMDB) 作为动态配置源,而不是静态配置文件。 您可以使用内置的 PostgreSQL 作为配置清单进行配置管理。
使用 Postgres CMDB,配置被组织在结构化关系表中,可以使用 SQL 轻松查询和操作。 这允许与其他系统和工具更容易地集成。
工作原理
Ansible 允许您使用动态清单脚本来即时生成清单配置。
其想法是在 ansible.cfg 中用动态 shell 脚本 inventory.sh 替换静态 pigsty.yml
inventory.sh 的内容非常简单,它将查询 PostgreSQL CMDB 并检索配置。
bin/inventory_load:将 YAML 配置文件加载到 CMDB 中bin/inventory_cmdb:使用 CMDB 作为配置清单(meta.pigsty)bin/inventory_conf:使用 YAML 文件作为配置清单(pigsty.yml)
CMDB 模式
CMDB 基线模式随 pigsty 一起提供:files/cmdb.sql
大多数默认配置模板都将其用作示例基线。这意味着默认情况下可以使用它。
加载配置数据
CMDB 默认为空,使用 bin/inventory_load 脚本将配置文件加载到 CMDB 中。
不带参数运行 bin/inventory_load 将加载默认的 pigsty.yml 到默认 CMDB 中。
使用 -p 指定配置文件路径,使用 -d 指定 CMDB URL。
切换清单
您可以通过以下方式切换到动态 CMDB 清单:
这实际上将 ansible.cfg 中的 inventory 参数更改为使用 inventory.sh 脚本。