快速上手
如何在您的 Linux 主机上安装 pigsty？
这是单节点安装指南，请查看 多节点 来了解真正的高可用生产环境部署。
简化版本
准备 一台具有 SSH权限 的 节点 并安装 兼容的Linux发行版，
使用免密 ssh 和 sudo 权限的用户：
下载 pigsty，它会自动安装至 ~/pigsty 目录，并安装 ansible：
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;使用 configure 生成配置清单文件，或直接根据需求调整 pigsty.yml：
./configure使用 install.yml 剧本，一键 安装部署 所有组件：
./install.yml示例：在 RockyLinux 9 上的单机安装：
准备
查看 准备工作 了解所有详细信息，这里是快速摘要：
| 项目 | 要求 | 项目 | 要求 |
|---|---|---|---|
| 节点 | 至少 1C1G，推荐 2C2G | 规格 | 至少1个节点，2个为半高可用，3个以上真高可用 |
| 磁盘 | /data，主挂载点，ext4/xfs | 网络 | 静态 IPv4 地址 |
| VIP | 可选的 L2 VIP | 域名 | 可选的本地/公共域名 |
| 内核 | Linux | 发行版 | el8, el9, d12, u22, u24 x x86_64 / aarch64 |
| 本地化 | C.UTF-8 或 C | 防火墙 | 端口：80 / 443 / 22 / 5432 |
| 用户 | 避免使用 root 和 postgres | Sudo | nopass sudo 权限 |
| SSH | 通过公钥 nopass | 可达性 | ssh <ip|alias> sudo ls 无错误 |
下载
（推荐）您可以使用以下命令获取并解压最新稳定版本的 pigsty 源码：
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigstycurl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty # 中国镜像curl -fsSL https://repo.pigsty.io/get | bash -s v3.6.0; cd ~/pigsty您也可以通过 git、pig 或直接从 GitHub 下载源码 和 离线软件包 压缩包的方式安装。
配置
configure 脚本将根据您的环境和输入生成具有良好默认值的 pigsty.yml 配置文件 配置清单。
这是 可选的，您可以如 教程 所示直接编辑 pigsty.yml。
有许多 配置模板 供您参考，以下是一些快速示例：
./configure # 使用默认模板，PG 17 带最少扩展
./configure -v 16 # 使用 PG 16 而非 17 的默认元数据模板
./configure -c rich # PG 17 带所有可用扩展和更多演示数据库
./configure -c slim # 最小安装模板，与 ./slim.yml 剧本一起使用
./configure -c app/supa # 使用 app/supa 自托管 supabase 配置模板
./configure -c ivory # 使用 ivorysql 内核而非原生 PG
./configure -i 10.11.12.13 # 显式指定主 IP 地址
./configure -r china # 使用中国镜像而非默认仓库
./configure -c full -s # 使用 4 节点沙箱配置模板，不进行 IP 替换和探测让我们不带任何参数执行 configure，如果发现多个 IP 地址，它可能会要求您输入主 IP 地址。
[vagrant@node-2 pigsty]$ ./configure
configure pigsty v3.6.0 begin
[ OK ] region = default
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] package = rpm,dnf
[ OK ] vendor = rocky (Rocky Linux)
[ OK ] version = 9 (9.5)
[ OK ] sudo = vagrant ok
[ OK ] ssh = vagrant@127.0.0.1 ok
[WARN] Multiple IP address candidates found:
(1) 192.168.121.24 inet 192.168.121.24/24 brd 192.168.121.255 scope global dynamic noprefixroute eth0
(2) 10.10.10.12 inet 10.10.10.12/24 brd 10.10.10.255 scope global noprefixroute eth1
[ IN ] INPUT primary_ip address (of current meta node, e.g 10.10.10.10):
=> 10.10.10.12 # <------- 在这里输入你的首要 IPv4 地址！
[ OK ] primary_ip = 10.10.10.12 (from input)
[ OK ] admin = vagrant@10.10.10.12 ok
[ OK ] mode = meta (el9)
[ OK ] locale = C.UTF-8
[ OK ] configure pigsty done
proceed with ./install.yml该脚本将把 IP 占位符 10.10.10.10 替换为当前节点的主 IPv4 地址。
在 手动 配置 pigsty 时请注意这一点。检查生成的 pigsty.yml 以继续。
嘿！别忘了这些密码！
然后修改默认 密码 并进行必要的调整，最终的 pigsty.yml 可能如下所示：
---
all:
#==============================================================#
# Clusters, Nodes, and Modules
#==============================================================#
children:
#----------------------------------#
# infra: monitor, alert, repo, etc..
#----------------------------------#
infra:
hosts:
10.10.10.12: { infra_seq: 1 }
vars:
docker_enabled: true # enabled docker with ./docker.yml
docker_registry_mirrors: ["https://docker.1ms.run", "https://docker.m.daocloud.io"]
#----------------------------------#
# etcd cluster for HA postgres DCS
#----------------------------------#
etcd:
hosts:
10.10.10.12: { etcd_seq: 1 }
vars:
etcd_cluster: etcd
#----------------------------------#
# minio (OPTIONAL backup repo)
#----------------------------------#
#minio:
# hosts:
# 10.10.10.12: { minio_seq: 1 }
# vars:
# minio_cluster: minio
#----------------------------------#
# pgsql (singleton on current node)
#----------------------------------#
# this is an example single-node postgres cluster with pgvector installed, with one biz database & two biz users
pg-meta:
hosts:
10.10.10.12: { pg_seq: 1, pg_role: primary } # <---- primary instance with read-write capability
#x.xx.xx.xx: { pg_seq: 2, pg_role: replica } # <---- read only replica for read-only online traffic
#x.xx.xx.xy: { pg_seq: 3, pg_role: offline } # <---- offline instance of ETL & interactive queries
vars:
pg_cluster: pg-meta # required identity parameter, usually same as group name
# define business databases here: https://pgsty.com/pgsql/db
pg_databases: # define business databases on this cluster, array of database definition
- name: meta # REQUIRED, `name` is the only mandatory field of a database definition
baseline: cmdb.sql # optional, database sql baseline path, (relative path among ansible search path, e.g: files/)
schemas: [ pigsty ] # optional, additional schemas to be created, array of schema names
extensions: # optional, additional extensions to be installed: array of `{name[,schema]}`
- { name: vector } # install pgvector extension on this database by default
comment: pigsty meta database # optional, comment string for this database
#pgbouncer: true # optional, add this database to pgbouncer database list? true by default
#owner: postgres # optional, database owner, postgres by default
#template: template1 # optional, which template to use, template1 by default
#encoding: UTF8 # optional, database encoding, UTF8 by default. (MUST same as template database)
#locale: C # optional, database locale, C by default. (MUST same as template database)
#lc_collate: C # optional, database collate, C by default. (MUST same as template database)
#lc_ctype: C # optional, database ctype, C by default. (MUST same as template database)
#tablespace: pg_default # optional, default tablespace, 'pg_default' by default.
#allowconn: true # optional, allow connection, true by default. false will disable connect at all
#revokeconn: false # optional, revoke public connection privilege. false by default. (leave connect with grant option to owner)
#register_datasource: true # optional, register this database to grafana datasources? true by default
#connlimit: -1 # optional, database connection limit, default -1 disable limit
#pool_auth_user: dbuser_meta # optional, all connection to this pgbouncer database will be authenticated by this user
#pool_mode: transaction # optional, pgbouncer pool mode at database level, default transaction
#pool_size: 64 # optional, pgbouncer pool size at database level, default 64
#pool_size_reserve: 32 # optional, pgbouncer pool size reserve at database level, default 32
#pool_size_min: 0 # optional, pgbouncer pool size min at database level, default 0
#pool_max_db_conn: 100 # optional, max database connections at database level, default 100
#- { name: grafana ,owner: dbuser_grafana ,revokeconn: true ,comment: grafana primary database } # define another database
# define business users here: https://pgsty.com/pgsql/user
pg_users: # define business users/roles on this cluster, array of user definition
- name: dbuser_meta # REQUIRED, `name` is the only mandatory field of a user definition
password: DBUser.Meta # optional, password, can be a scram-sha-256 hash string or plain text
login: true # optional, can log in, true by default (new biz ROLE should be false)
superuser: false # optional, is superuser? false by default
createdb: false # optional, can create database? false by default
createrole: false # optional, can create role? false by default
inherit: true # optional, can this role use inherited privileges? true by default
replication: false # optional, can this role do replication? false by default
bypassrls: false # optional, can this role bypass row level security? false by default
pgbouncer: true # optional, add this user to pgbouncer user-list? false by default (production user should be true explicitly)
connlimit: -1 # optional, user connection limit, default -1 disable limit
expire_in: 3650 # optional, now + n days when this role is expired (OVERWRITE expire_at)
expire_at: '2030-12-31' # optional, YYYY-MM-DD 'timestamp' when this role is expired (OVERWRITTEN by expire_in)
comment: pigsty admin user # optional, comment string for this user/role
roles: [dbrole_admin] # optional, belonged roles. default roles are: dbrole_{admin,readonly,readwrite,offline}
parameters: {} # optional, role level parameters with `ALTER ROLE SET`
pool_mode: transaction # optional, pgbouncer pool mode at user level, transaction by default
pool_connlimit: -1 # optional, max database connections at user level, default -1 disable limit
- { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly], comment: read-only viewer for meta database }
# define pg extensions: https://pgsty.com/pgsql/extension
pg_libs: 'pg_stat_statements, auto_explain' # add timescaledb to shared_preload_libraries
pg_extensions: [ pgvector ] # check list for available extension for your pg & os combination: https://ext.pgsty.com/list
# define HBA rules here: https://pgsty.com/pgsql/hba
pg_hba_rules: # example hba rules
- {user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes'}
#pg_vip_enabled: true # define a L2 VIP which bind to cluster primary instance
#pg_vip_address: 10.10.10.2/24 # L2 VIP Address and netmask
#pg_vip_interface: eth1 # L2 VIP Network interface, overwrite on host vars if member have different network interface names
node_crontab: [ '00 01 * * * postgres /pg/bin/pg-backup full' ] # make a full backup every 1am
#==============================================================#
# Global Parameters
#==============================================================#
vars:
#----------------------------------#
# Meta Data
#----------------------------------#
version: v3.6.0 # pigsty version string
admin_ip: 10.10.10.12 # admin node ip address
region: china # upstream mirror region: default|china|europe
pg_locale: C.UTF-8 # overwrite default C local
pg_lc_collate: C.UTF-8 # overwrite default C lc_collate
pg_lc_ctype: C.UTF-8 # overwrite default C lc_ctype
node_tune: oltp # node tuning specs: oltp,olap,tiny,crit
pg_conf: oltp.yml # pgsql tuning specs: {oltp,olap,tiny,crit}.yml
proxy_env: # global proxy env when downloading packages
no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
# http_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
# all_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
infra_portal: # domain names and upstream servers
home : { domain: h.pigsty }
grafana : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" , websocket: true }
prometheus : { domain: p.pigsty ,endpoint: "${admin_ip}:9090" }
alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9093" }
blackbox : { endpoint: "${admin_ip}:9115" }
loki : { endpoint: "${admin_ip}:3100" }
#minio : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
#----------------------------------#
# MinIO Related Options
#----------------------------------#
#pgbackrest_method: minio # if you want to use minio as backup repo instead of 'local' fs, uncomment this
#minio_users: # and configure `pgbackrest_repo` & `minio_users` accordingly
# - { access_key: dba , secret_key: S3User.DBA, policy: consoleAdmin }
# - { access_key: pgbackrest , secret_key: S3User.Backup, policy: readwrite }
#pgbackrest_repo: # pgbackrest repo: https://pgbackrest.org/configuration.html#section-repository
# minio: ... # optional minio repo for pgbackrest ...
# s3_key: pgbackrest # minio user access key for pgbackrest
# s3_key_secret: S3User.Backup # minio user secret key for pgbackrest
# cipher_pass: pgBackRest # AES encryption password, default is 'pgBackRest'
# if you want to use minio as backup repo instead of 'local' fs, uncomment this, and configure `pgbackrest_repo`
#pgbackrest_method: minio
#node_etc_hosts: [ '10.10.10.12 h.pigsty a.pigsty p.pigsty g.pigsty sss.pigsty' ]
#----------------------------------#
# Credential: CHANGE THESE PASSWORDS
#----------------------------------#
#grafana_admin_username: admin
grafana_admin_password: pigsty # <----- CHANGE ME
#pg_admin_username: dbuser_dba
pg_admin_password: DBUser.DBA # <----- CHANGE ME
#pg_monitor_username: dbuser_monitor
pg_monitor_password: DBUser.Monitor # <----- CHANGE ME
#pg_replication_username: replicator
pg_replication_password: DBUser.Replicator # <----- CHANGE ME
#patroni_username: postgres
patroni_password: Patroni.API # <----- CHANGE ME
#haproxy_admin_username: admin
haproxy_admin_password: pigsty # <----- CHANGE ME
#minio_access_key: minioadmin
minio_secret_key: minioadmin # <----- CHANGE ME
#----------------------------------#
# Safe Guard
#----------------------------------#
# you can enable these flags after bootstrap, to prevent purging running etcd / pgsql instances
etcd_safeguard: false # prevent purging running etcd instance?
pg_safeguard: false # prevent purging running postgres instance? false by default
#----------------------------------#
# Repo, Node, Packages
#----------------------------------#
repo_remove: true # remove existing repo on admin node during repo bootstrap
node_repo_remove: true # remove existing node repo for node managed by pigsty
repo_extra_packages: [ pg17-main ] #,pg17-core ,pg17-time ,pg17-gis ,pg17-rag ,pg17-fts ,pg17-olap ,pg17-feat ,pg17-lang ,pg17-type ,pg17-util ,pg17-func ,pg17-admin ,pg17-stat ,pg17-sec ,pg17-fdw ,pg17-sim ,pg17-etl]
pg_version: 17 # default postgres version
#pg_extensions: [pg17-time ,pg17-gis ,pg17-rag ,pg17-fts ,pg17-feat ,pg17-lang ,pg17-type ,pg17-util ,pg17-func ,pg17-admin ,pg17-stat ,pg17-sec ,pg17-fdw ,pg17-sim ,pg17-etl ] #,pg17-olap]如果想要更多扩展怎么办？
只需在 pigsty.yml 中取消注释以下两个参数，使其看起来像这样：
repo_extra_packages: [ pg17-main ,pg17-core ,pg17-time ,pg17-gis ,pg17-rag ,pg17-fts ,pg17-olap ,pg17-feat ,pg17-lang ,pg17-type ,pg17-util ,pg17-func ,pg17-admin ,pg17-stat ,pg17-sec ,pg17-fdw ,pg17-sim ,pg17-etl]
pg_extensions: [pg17-time ,pg17-gis ,pg17-rag ,pg17-fts ,pg17-feat ,pg17-lang ,pg17-type ,pg17-util ,pg17-func ,pg17-admin ,pg17-stat ,pg17-sec ,pg17-fdw ,pg17-sim ,pg17-etl ] #,pg17-olap]您可以用配置文件做更多神奇的事情，查看 配置 了解详情。
安装
Pigsty 中的一切都在 配置清单 中描述：即 上面 生成的 pigsty.yml 蓝图。
运行 install.yml 副本 将其实现为现实。
./install.yml如果您在输出中看到类似 pgsql init done 或 grafana datasource meta、PLAY RECAP 等内容，说明安装已经完成！
......
TASK [pgsql : pgsql init done] *************************************************
ok: [10.10.10.11] => {
"msg": "postgres://10.10.10.11/postgres | meta | dbuser_meta dbuser_view "
}
......
TASK [pg_monitor : load grafana datasource meta] *******************************
changed: [10.10.10.11]
PLAY RECAP *********************************************************************
10.10.10.11 : ok=302 changed=232 unreachable=0 failed=0 skipped=65 rescued=0 ignored=1
localhost : ok=6 changed=3 unreachable=0 failed=0 skipped=1 rescued=0 ignored=0有时上游仓库（如 linux / pgdg 仓库）可能会损坏，这确实会时不时发生，并导致安装失败。 您可以使用预制的 离线软件包 来解决这个问题。
在现有部署上绝不要再次运行这个！
完整重新运行这个副本将会摧毁（清除）当前部署并创建一个新的！
如果您对 ansible 有足够的了解并知道自己在做什么，仍请谨慎操作！
安装完成后，您可以探索 界面 并部署 更多节点 和更多高可用数据库集群。
更多
您可以使用 pigsty 部署和监控 更多集群：向 配置清单 添加定义并运行：
bin/node-add pg-test # 初始化集群 pg-test 的 3 个节点
bin/pgsql-add pg-test # 初始化高可用 PGSQL 集群 pg-test
bin/redis-add redis-ms # 初始化 redis 集群 redis-ms