跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

安装

Pigsty 入门指南

快速开始

快速开始准备 一台具有 SSH访问权限节点,新安装 Linux系统, 使用具有免密 sshsudo 权限的用户运行:

步骤 1

使用以下命令[**下载**](/zh/docs/prepare/software#pigsty) pigsty:

```bash
curl -fsSL https://repo.pigsty.io/get | bash -s v3.7.0; cd ~/pigsty;
```

步骤 2

执行 [`configure`](/zh/docs/config/configure) 生成 [配置清单](/zh/docs/config/inventory)。(<span class="text-red-500 font-black">务必修改</span> 生成的 [`pigsty.yml`](/zh/docs/config/inventory) 中的密码)

```bash
./configure
```

步骤 3

一键 [**安装部署**](/zh/docs/install/start) 所有组件:

```bash
./install.yml
```

Pigsty 安装完成!请探索 用户界面,访问 5432 端口上的 Postgres 服务,或 3000 端口上的 Grafana 监控大盘(admin / pigsty)。


下一步做什么?


安装

单机安装
    在当前 Linux 节点上,执行标准的完整在线安装流程
高可用安装
    在多个节点上安装,以实现真正的企业级高可用部署
离线安装
    在没有互联网连接的情况下,从本地离线包引导安装
精简安装
    仅安装高可用 Postgres 集群所必须的组件,不装监控

准备工作

准备
    准备节点、网络、存储、用户、ssh、sudo、ansible 等
Linux 操作系统
    检查兼容的 Linux 发行版和可用性矩阵
Vagrant
    使用 vagrant / virtualbox 置备本地 Linux 虚拟机
Terraform
    在云供应商上使用 terraform 置备云 Linux 服务器

参考

界面
    访问和管理 Pigsty 提供的数据库端点与图形用户界面
配置
    使用声明式的配置文件描述你需要的基础设施与集群
剧本
    了解可用的 Ansible 剧本和其使用方法
安全
    生产环境的安全加固和最佳实践

1 - 快速上手

如何在您的 Linux 主机上安装 pigsty?

本文是 Pigsty 单节点安装指南,多节点安装 介绍了在生产环境进行真正高可用部署的方法。


简化版本

准备 一台具有 SSH权限节点 并安装 兼容的Linux发行版, 使用带免密 sshsudo 权限的用户:

步骤 1

    [**下载**](#download) pigsty,它会自动安装至 `~/pigsty` 目录,并尝试安装 [`ansible`](/zh/docs/admin/ansible):

    ```bash
    curl -fsSL https://repo.pigsty.io/get | bash -s v3.7.0; cd ~/pigsty;
    ```

步骤 2

    使用 [`configure`](/docs/config/configure) 生成配置文件,或直接根据您的需求调整 [`pigsty.yml`](/zh/docs/config/inventory):

    ```bash
    ./configure   # 可以使用 -c [conf] 指定具体的配置模板
    ```

步骤 3

    使用 `install.yml` 剧本,一键 [**安装部署**](#install) 所有组件:

    ```bash
    ./install.yml
    ```

示例:在 RockyLinux 9 上的单机安装:

asciicast


准备

安装 Pigsty 涉及一些 准备工作 ,以下是简略检查清单:

项目 要求 项目 要求
节点 至少 1C1G,推荐 2C2G 规格 至少1个节点,2个为半高可用,3个以上真高可用
磁盘 /data,主挂载点,ext4/xfs 网络 静态 IPv4 地址,单节点可使用 127.0.0.1
VIP L2 VIP,可选 域名 本地/公网域名,可选
内核 Linux 发行版 el8/9/10,d12/13, u22/u24 x x86_64 / aarch64
Locale C.UTF-8C 防火墙 端口:80 / 443 / 22 / 5432
用户 避免使用 rootpostgres Sudo nopass sudo 权限
SSH 通过公钥 nopass 可达性 ssh <ip|alias> sudo ls 无错误

下载

推荐)您可以使用以下命令获取并解压最新稳定版本的 pigsty 源码:

curl -fsSL https://repo.pigsty.io/get | bash -s v3.7.0; cd ~/pigsty
curl -fsSL https://repo.pigsty.cc/get | bash -s v3.7.0; cd ~/pigsty   # 中国镜像
curl -fsSL https://repo.pigsty.io/get | bash -s v3.7.0; cd ~/pigsty

您也可以通过 gitpig 或直接从 GitHub 下载源码离线软件包 压缩包的方式安装。


配置

configure 脚本将根据您的环境和输入生成具有良好默认值的 pigsty.yml 配置文件 配置清单。 这是 可选的,您可以如 教程 所示直接编辑 pigsty.yml

有许多 配置模板 供您参考,以下是一些快速示例:

./configure                  # 使用默认模板,安装默认的 PG 18,带有必要扩展
./configure -v 17            # 使用 PG 17 的版本,而非默认的 PG18
./configure -c rich          # 创建本地软件仓库,下载所有扩展,安装主要扩展
./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.7.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.6)
[ OK ] sudo = vagrant ok
[ OK ] ssh = [email protected] 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 = [email protected] 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 可能如下所示:

~/pigsty/pigsty.yml
all:

  #==============================================================#
  # Clusters, Nodes, and Modules
  #==============================================================#
  children:

    #----------------------------------------------#
    # PGSQL : https://doc.pgsty.com/pgsql
    #----------------------------------------------#
    # this is an example single-node postgres cluster with pgvector installed, with one biz database & two biz users
    pg-meta:
      hosts:
        10.10.10.10: { 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

        # install, load, create pg extensions: https://doc.pgsty.com/pgsql/extension
        pg_extensions: [ postgis, pgvector ]

        # define business users/roles : https://doc.pgsty.com/pgsql/user
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }

        # define business databases : https://doc.pgsty.com/pgsql/db
        pg_databases:
          - name: meta
            baseline: cmdb.sql
            comment: "pigsty meta database"
            schemas: [pigsty]
            # define extensions in database : https://doc.pgsty.com/pgsql/extension/create
            extensions: [ postgis, vector ]

        # define HBA rules : https://doc.pgsty.com/pgsql/hba
        pg_hba_rules:
          - { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes' }

        # define backup policies: https://doc.pgsty.com/pgsql/backup
        node_crontab: [ '00 01 * * * postgres /pg/bin/pg-backup full' ] # make a full backup every day 1am

        # define (OPTIONAL) L2 VIP that bind to primary
        #pg_vip_enabled: true
        #pg_vip_address: 10.10.10.2/24
        #pg_vip_interface: eth1


    #----------------------------------------------#
    # INFRA : https://doc.pgsty.com/infra
    #----------------------------------------------#
    infra:
      hosts:
        10.10.10.10: { infra_seq: 1 }
      vars:
        repo_enabled: false   # disable in 1-node mode :  https://doc.pgsty.com/admin/repo
        #repo_extra_packages: [ pg18-main ,pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-olap ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl]

    #----------------------------------------------#
    # ETCD : https://doc.pgsty.com/etcd
    #----------------------------------------------#
    etcd:
      hosts:
        10.10.10.10: { etcd_seq: 1 }
      vars:
        etcd_cluster: etcd
        etcd_safeguard: false             # prevent purging running etcd instance?

    #----------------------------------------------#
    # MINIO : https://doc.pgsty.com/minio
    #----------------------------------------------#
    #minio:
    #  hosts:
    #    10.10.10.10: { minio_seq: 1 }
    #  vars:
    #    minio_cluster: minio
    #    minio_users:                      # list of minio user to be created
    #      - { access_key: pgbackrest  ,secret_key: S3User.Backup ,policy: pgsql }
    #      - { access_key: s3user_meta ,secret_key: S3User.Meta   ,policy: meta  }
    #      - { access_key: s3user_data ,secret_key: S3User.Data   ,policy: data  }

    #----------------------------------------------#
    # DOCKER : https://doc.pgsty.com/docker
    # APP    : https://doc.pgsty.com/app
    #----------------------------------------------#
    # launch example pgadmin app with: ./app.yml (http://10.10.10.10:8885 [email protected] / pigsty)
    app:
      hosts: { 10.10.10.10: {} }
      vars:
        docker_enabled: true                # enabled docker with ./docker.yml
        docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]
        app: pgadmin                        # specify the default app name to be installed (in the apps)
        apps:                               # define all applications, appname: definition
          pgadmin:                          # pgadmin app definition (app/pgadmin -> /opt/pgadmin)
            conf:                           # override /opt/pgadmin/.env
              PGADMIN_DEFAULT_EMAIL: [email protected]
              PGADMIN_DEFAULT_PASSWORD: pigsty


  #==============================================================#
  # Global Parameters
  #==============================================================#
  vars:

    #----------------------------------------------#
    # INFRA : https://doc.pgsty.com/infra
    #----------------------------------------------#
    version: v3.7.0                   # pigsty version string
    admin_ip: 10.10.10.10             # admin node ip address
    region: china                     # upstream mirror region: default|china|europe
    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:[email protected]
      # https_proxy: # set your proxy here: e.g http://user:[email protected]
      # all_proxy:   # set your proxy here: e.g http://user:[email protected]
    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}:9058" }
      alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9059" }
      blackbox     : { endpoint: "${admin_ip}:9115" }
      loki         : { endpoint: "${admin_ip}:3100" }
      pgadmin      : { domain: adm.pigsty ,endpoint: "${admin_ip}:8885" }
      #minio       : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }

    #----------------------------------------------#
    # PASSWORD : https://doc.pgsty.com/config/security
    #----------------------------------------------#
    grafana_admin_password: pigsty               # <-------- CHANGE ME!
    pg_admin_password: DBUser.DBA                # <-------- CHANGE ME!
    pg_monitor_password: DBUser.Monitor          # <-------- CHANGE ME!
    pg_replication_password: DBUser.Replicator   # <-------- CHANGE ME!
    patroni_password: Patroni.API                # <-------- CHANGE ME!
    haproxy_admin_password: pigsty               # <-------- CHANGE ME!
    minio_secret_key: minioadmin                 # <-------- CHANGE ME!

    #----------------------------------------------#
    # NODE : https://doc.pgsty.com/node/param
    #----------------------------------------------#
    nodename_overwrite: false             # do not overwrite node hostname on single node mode
    node_tune: tiny                       # node tuning specs: oltp,olap,tiny,crit
    node_etc_hosts: [ '10.10.10.10 h.pigsty a.pigsty p.pigsty g.pigsty sss.pigsty' ]
    node_repo_modules: 'node,infra,pgsql' # add these repos directly to the singleton node
    #node_repo_modules: local             # use this if you want to build & user local repo
    node_repo_remove: true                # remove existing node repo for node managed by pigsty
    #node_packages: [openssh-server]      # packages to be installed current nodes with the latest version

    #----------------------------------------------#
    # PGSQL : https://doc.pgsty.com/pgsql/param
    #----------------------------------------------#
    pg_version: 18                      # default postgres version
    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

    pg_conf: tiny.yml                   # pgsql tuning specs: {oltp,olap,tiny,crit}.yml
    pg_safeguard: false                 # prevent purging running postgres instance?
    pg_packages: [ pgsql-main, pgsql-common ]                 # pg kernel and common utils
    #pg_extensions: [ pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-olap ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl]
如果想要更多扩展怎么办?

只需在 pigsty.yml 中取消注释以下参数,使其看起来像这样:

pg_extensions: [ pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-olap ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl]

您可以用配置文件做更多神奇的事情,查看 配置 了解详情。


安装

Pigsty 中的一切都由 配置清单 所定义,也就是 上面 生成的 pigsty.yml 配置。

运行 install.yml 剧本 会实施这个部署计划。

~/pigsty
./install.yml

输出尾部如果带有 pgsql init donePLAY 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 仓库)可能会因为更新而进入崩溃状态并导致安装失败(有过多次先例)! 您可以选择等待上游仓库修复后安装,或者使用预制的 离线软件包 来解决这个问题。

不要在已经部署好的环境中重新运行 install.yml!

重新运行整个 install.yml 剧本将会覆盖式创建所有组件,有可能导致数据丢失和服务中断!

如果您熟悉 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

记住,大多数模块都需要先安装 NODE 模块。查看可用的 模块 了解详情

PGSQLINFRANODEETCDMINIOREDISFERRETDOCKER……

2 - 用户界面

探索仪表盘并访问数据库服务

安装完成后,您在当前节点上将安装有四个核心模块: PGSQLINFRANODEETCD

ID NODE PGSQL INFRA ETCD
1 node-1 pg-meta-1 infra-1 etcd-1

您可以直接通过以下 端口 直接访问 WebUI 服务(不推荐用于生产环境)。 或使用本地/公共 域名 通过 Nginx 门户 访问它们。

请注意,SSL 证书 需要与域名一起使用。

组件 端口 域名 备注 公共演示
Nginx 80/443 h.pigsty 门户、仓库、HAProxy 管理 home.pigsty.io
Grafana 3000 g.pigsty Grafana 仪表盘 g.pgsty.com
Prometheus 9058 p.pigsty Prometheus Web UI p.pigsty.io
AlertManager 9059 a.pigsty 告警管理 a.pigsty.io

您可以通过以下数据库用户和相应的 PGURL 访问默认端口 5432 上的默认 PostgreSQL 数据库(meta):

psql postgres://dbuser_dba:[email protected]:5432/meta
psql postgres://dbuser_meta:[email protected]:5432/meta
psql postgres://dbuser_view:[email protected]:5432/meta

PostgreSQL

个人用户开发测试使用时,可以直接使用默认超级用户和 IP:端口来访问 PostgreSQL:

DBSU

默认超级用户

默认数据库超级用户是 dbuser_dba,默认密码为 DBUser.DBA,如果修改过请使用您自己的密码。

用户名 dbuser_dba pg_admin_username
密码 DBUser.DBA pg_admin_password

CLI

内置的 psql CLI 已经为管理员用户(安装 Pigsty 使用的用户)配置了 .pgpass.pg_service.conf

p   # 别名:操作系统管理员用户 @ 当前节点
psql postgres://dbuser_dba:[email protected]/postgres  # 替换为您的 IP 和密码

GUI

您可以使用您喜欢的 GUI 工具来访问数据库,Pigsty 也提供了一些 GUI 工具的内置模板。

名称 描述 Pigsty 支持
PgAdmin 官方 PostgreSQL 管理工具 内置 Docker 模板,OSS
Supabase Studio 精美的第三方 PostgreSQL 管理 UI 内置 Docker 模板,OSS
PgWeb 轻量级基于 Web 的 PostgreSQL 客户端 内置 Docker 模板,OSS
Bytebase 具有良好 GUI 的模式迁移工具 内置 Docker 模板,OSS
DataGrip / IntelliJ 具有强大功能的专业数据库 IDE 商业 / 社区版
Navicat 流行的商业数据库管理工具 商业版
DBeaver 开源通用数据库 GUI OSS

默认设置

您可以定义业务 数据库用户配置模板 中有一些预定义的示例供您参考。

例如,默认的 meta 配置模板预定义了一个 meta 数据库:

  • 带有 Pigsty CMDB 模式(可选)
  • 预装来 timescaledb, postgis, citus, pgvector 四个业务扩展
  • 它定义了 dbuser_meta 作为具有 DDL 权限的业务管理员用户,和一个 dbuser_view 作为只读查看者用户。
pg-meta:
  hosts:
    10.10.10.10: { pg_seq: 1, pg_role: primary } # <---- 这个集群中只有一个实例,主库
  vars:
    pg_cluster: pg-meta                 # 必选参数,集群名

    pg_databases:                       # 数据库列表
      - name: meta
        baseline: cmdb.sql
        comment: "pigsty meta database"
        schemas: [pigsty]
        extensions: [ postgis, timescaledb, vector ]   # 安装了三个扩展

    pg_users:                           # 数据库用户列表
      - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
      - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }

    pg_hba_rules:                       # example hba rules
      - {user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes'}

这意味着您也可以使用这两个用户访问 meta 数据库:

psql postgres://dbuser_meta:[email protected]:5432/meta
psql postgres://dbuser_view:[email protected]:5432/meta

生产环境

要在生产环境中使用高可用 PostgreSQL 集群,您需要阅读以下文档来继续:

在这种情况下,您的流量在到达数据库之前会通过 haproxy 进行分发,并由 pgbouncer 池化。


Grafana

Grafana 是监控和可观测性平台,提供可视化面板能力,默认监听 3000 端口:

  • http://10.10.10.10:3000(替换为您的 IP)
通过域名访问

Pigsty 为 Web 组件提供了 静态本地域名,您可以通过 Nginx 访问 http://g.pigsty 来使用 Grafana 建议使用域名,因为您可以通过域名经由 Nginx 暴露所有服务,并为它们使用 SSL 证书。

Grafana 用户名和密码

默认凭据:admin:pigsty。如果您已更改默认凭据,请使用您自己的。

用户名 admin grafana_admin_username
密码 pigsty grafana_admin_password

您可以查看我们的公共演示站点来看看它是什么样子: https://g.pgsty.com

pigsty-home.jpg
本地域名的自签名 SSL 证书

Pigsty 默认会自动为本地静态域名 颁发自签名 SSL 证书,但您必须在浏览器中 信任自签名 CA 才不会弹窗报错。

使用真实域名和证书

Pigsty 支持使用 真实域名真正的免费 SSL 证书

只需替换 infra_portal 中的 domain 条目为你的真实域名,并使用 make cert 命令即可免费申请真实证书

3 - 多节点部署

如何在多个节点上安装 Pigsty,实现生产级别高可用?

你可以参考 配置教程 ,将一个单机 Pigsty 节点逐步扩展为多节点高可用部署。 但是完成这些工作最简单的办法,始终是在部署前就预先规划一切,并且一次性完成整个环境的置备。


单节点部署

我们已经在 快速上手 一节中演示了单节点安装的流程 —— 最简单的部署方式。

ID IP 地址 NODE PGSQL INFRA ETCD
1 10.10.10.10 meta pg-meta-1 infra-1 etcd-1

单节点没有高可用性,也没有冗余,如果您确实要将其用于生产环境,请为 PG 配置外部 MinIO / S3 / NFS… 作为远程备份仓库,这样能提供最低数据完整性灾难恢复能力。

Pigsty 有很多单节点 配置模板 供您参考。 你可以使用 Vagrant 默认的 meta.rb 来在本地置备此环境所需的虚拟机。 或者使用 Terraform 默认的 meta.tf 来在阿里云上置备此环境。


双节点部署

半高可用设置

双节点设置可实现一主一从的数据库物理复制和半高可用功能:

ID IP 地址 NODE PGSQL INFRA ETCD
1 10.10.10.10 meta pg-meta-1 infra-1 etcd-1
2 10.10.10.11 node-1 pg-meta-2

虽然比单节点设置更加健壮,但双节点架构的高可用性有限制:

  • 如果 node-2 故障,自动故障转移正常工作 - node-1 会自动被提升
  • 如果 node-1 故障,无法进行自动故障切换 - 需要手动提升 node-2

也就是说,这种"半高可用"设置只能从 特定的节点故障 中自动恢复,只允许坏其中一台特定的节点2。

您可以使用 dual.yml 配置模板,并使用 Vagrant dual.rb 来置备此环境所需的虚拟机。


三节点部署

真正的高可用

一个能够从任意单节点故障中自动恢复的真正高可用设置:

ID IP 地址 NODE PGSQL INFRA ETCD
1 10.10.10.10 node-1 pg-meta-1 infra-1 etcd-1
2 10.10.10.11 node-2 pg-meta-2 infra-2 etcd-2
3 10.10.10.12 node-3 pg-meta-3 infra-3 etcd-3

您可以使用 trio.yml 配置模板,并使用 Vagrant trio.rb 来置备此环境所需的虚拟机。


四节点沙箱

这是 Pigsty 中使用的 沙箱演示 环境,具有一个基础设施节点和三个额外的数据节点:

ID IP 地址 NODE PGSQL INFRA ETCD MINIO
1 10.10.10.10 meta pg-meta-1 infra-1 etcd-1 minio-1
2 10.10.10.11 node-1 pg-test-1
3 10.10.10.12 node-2 pg-test-1
4 10.10.10.13 node-3 pg-test-1

您可以使用 full.yml 配置模板,并使用 Vagrant full.rbTerraform full.tf 来置备此环境。


五节点构建

这个 pro.yml 是一个五节点构建环境,包含支持的 Linux 发行版

ID IP 地址 NODE PGSQL INFRA ETCD
1 10.10.10.8 el8 el8-1 infra-1
2 10.10.10.9 el9 el9-1 infra-2 etcd-2
3 10.10.10.12 u12 u12-1 infra-3
4 10.10.10.22 u22 u22-1 infra-4
5 10.10.10.24 u24 u24-1 infra-5

您可以使用 Vagrant pro.rbTerraform pro.tf 来置备此环境。


三十六节点仿真

一个包含 36 个节点的生产仿真环境(simu.yml),涵盖了所有 Pigsty 组件

IP 地址 规格 NODE PGSQL INFRA ETCD MINIO REDIS
10.10.10.10 8C32G meta1 pg-meta-1 infra-1
10.10.10.11 8C32G meta2 pg-meta-2 infra-2
10.10.10.12 2C4G pg12 pg-v12-1
10.10.10.13 2C4G pg13 pg-v13-1
10.10.10.14 2C4G pg14 pg-v14-1
10.10.10.15 2C4G pg15 pg-v15-1
10.10.10.16 2C4G pg16 pg-v16-1
10.10.10.17 2C4G pg17 pg-v17-1
10.10.10.18 2C4G proxy1
10.10.10.19 2C4G proxy2
10.10.10.21 2C4G minio1 etcd-1 minio-1 redis-meta-1
10.10.10.22 2C4G minio2 etcd-2 minio-2 redis-meta-2
10.10.10.23 2C4G minio3 etcd-3 minio-3 redis-meta-3
10.10.10.24 2C4G minio4 etcd-4 minio-4 redis-meta-4
10.10.10.25 2C4G minio5 etcd-5 minio-5 redis-meta-5
10.10.10.40 1C2G node40 pg-pitr-1
10.10.10.41 1C2G node41 pg-test-1 redis-test-1
10.10.10.42 1C2G node42 pg-test-2 redis-test-2
10.10.10.43 1C2G node43 pg-test-3 redis-test-3
10.10.10.44 1C2G node44 pg-test-4 redis-test-4
10.10.10.45 1C2G node45 pg-src-1 redis-src-1
10.10.10.46 1C2G node46 pg-src-2 redis-src-2
10.10.10.47 1C2G node47 pg-src-3 redis-src-3
10.10.10.48 1C2G node48 pg-dst-1 redis-dst-1
10.10.10.49 1C2G node49 pg-dst-2 redis-dst-2
10.10.10.50 1C2G node50 pg-citus0-1
10.10.10.51 1C2G node51 pg-citus0-2
10.10.10.52 1C2G node52 pg-citus1-1
10.10.10.53 1C2G node53 pg-citus1-2
10.10.10.54 1C2G node54 pg-citus2-1
10.10.10.55 1C2G node55 pg-citus2-2
10.10.10.56 1C2G node56 pg-citus3-1
10.10.10.57 1C2G node57 pg-citus3-2
10.10.10.58 1C2G node58 pg-citus4-1
10.10.10.59 1C2G node59 pg-citus4-2
10.10.10.88 4C8G test

您可以使用 Vagrant simu.rb 来置备此环境。 您可以在真实服务器(72C / 256G)上运行整个仿真,使用 Vagrant 的 libvirt 作为虚拟机提供程序。

  • 2 个基础设施节点,相互监控
  • 2 个专用代理节点运行 HAProxy
  • 5 节点 ETCD 集群可容忍 2 个节点故障,以及 5 节点 Redis Sentinel 集群
  • 5 节点 MinIO 集群,每个节点有 4 个磁盘
  • 10 个 PostgreSQL 集群:pg13 - pg15pg-srcpg-dstpg-pitrpg-test
  • 10 节点 Citus 集群有 5 个分片
  • Redis 独立集群 redis-srcredis-dst,以及原生集群 redis-test

4 - 离线安装

如何在没有互联网访问的情况下安装 pigsty?

Pigsty 默认从互联网上游 安装 所需软件包,但有些环境与互联网隔离。 为了解决这个问题,Pigsty 支持使用 离线软件包 进行离线安装。

步骤 1

    下载 pigsty 离线软件包,将其放到 `/tmp/pkg.tgz`

步骤 2

    下载 pigsty 源码包,解压(假设解压到 `~/pigsty`)

步骤 3

    `cd ~/pigsty; ./bootstrap`,它将解压软件包并使用本地仓库

步骤 4

    `vi ~/pigsty.yml`,覆盖 [`node_repo_modules`](/zh/docs/node/param#node_repo_modules) 设为 `local` 以使用本地仓库

步骤 5

    照常运行 `./install.yml`。它将从本地仓库安装所有内容。

什么是离线软件包?

离线软件包打包了所有需要的 RPM/DEB 软件包及其依赖; 它本质上是在正常 安装 后采取的本地 APT / YUM 仓库的快照压缩包。

您可以从 GitHub 发布页面 找到这些软件包,例如:

d6e9d6fa73620460ceb373a0c2f41ebe  pigsty-v3.7.0.tgz
987529769d85a3a01776caefefa93ecb  pigsty-pkg-v3.7.0.d12.aarch64.tgz
2d8272493784ae35abeac84568950623  pigsty-pkg-v3.7.0.d12.x86_64.tgz
090cc2531dcc25db3302f35cb3076dfa  pigsty-pkg-v3.7.0.d13.x86_64.tgz
ddc54a9c4a585da323c60736b8560f55  pigsty-pkg-v3.7.0.el10.aarch64.tgz
d376e75c490e8f326ea0f0fbb4a8fd9b  pigsty-pkg-v3.7.0.el10.x86_64.tgz
8c2deeba1e1d09ef3d46d77a99494e71  pigsty-pkg-v3.7.0.el8.aarch64.tgz
9795e059bd884b9d1b2208011abe43cd  pigsty-pkg-v3.7.0.el8.x86_64.tgz
08b860155d6764ae817ed25f2fcf9e5b  pigsty-pkg-v3.7.0.el9.aarch64.tgz
1ac430768e488a449d350ce245975baa  pigsty-pkg-v3.7.0.el9.x86_64.tgz
e033aaf23690755848db255904ab3bcd  pigsty-pkg-v3.7.0.u22.aarch64.tgz
cc022ea89181d89d271a9aaabca04165  pigsty-pkg-v3.7.0.u22.x86_64.tgz
0e978598796db3ce96caebd76c76e960  pigsty-pkg-v3.7.0.u24.aarch64.tgz
48223898ace8812cc4ea79cf3178476a  pigsty-pkg-v3.7.0.u24.x86_64.tgz

我们通常为以下 Linux 发行版 发布离线软件包,使用最新的操作系统次要版本。

EL Distribution Code Arch OS Code Package
RockyLinux 9.6 EL9 x86_64 el9.x86_64 pigsty-pkg-v3.7.0.el9.x86_64.tgz
Ubuntu 24.04.2 U24 x86_64 u24.x86_64 pigsty-pkg-v3.7.0.u24.x86_64.tgz
Debian 12.11 D12 x86_64 d12.x86_64 pigsty-pkg-v3.7.0.d12.x86_64.tgz
RockyLinux 9.6 EL9 x86_64 el9.aarch64 pigsty-pkg-v3.7.0.el9.aarch64.tgz
Ubuntu 24.04.2 U24 x86_64 u24.aarch64 pigsty-pkg-v3.7.0.u24.aarch64.tgz
Debian 12.11 D12 x86_64 d12.aarch64 pigsty-pkg-v3.7.0.d12.aarch64.tgz

https://github.com/pgsty/pigsty/releases/download/v3.7.0/pigsty-pkg-v3.7.0.el9.x86_64.tgz

离线软件包是为特定的 Linux 操作系统小版本制作的

在较低的操作系统小版本上使用更高小版本的离线软件包,大概率可以使用,但也有失败的可能


使用离线软件包?

将离线软件包放置于 /tmp/pkg.tgz 路径下,进入 ~/pigsty 目录执行 ./bootstrap,即可解包使用离线安装包。 Pigsty 会将其解压至 /www/pigsty,然后配置系统仓库列表启用此仓库,并从中安装 ansible

自从 Pigsty v3.6 版本起,大部份配置模板都默认不再构建本地软件仓库,而是直接从互联网上游安装软件包。 少部分配置模板如 richfull 依然保留了旧版本的行为 —— 先构建本地仓库再使用。

如果您想要在自己的配置中使用已经解包配置好的离线软件包,请修改以下配置:

  • repo_enabled:将此参数打开,设置为 true,则会构建本地软件源(在大部份配置中被显式关闭)
  • node_repo_modules:将此参数设置为 local,则环境中所有节点都从本地软件仓库安装
    • 在大部份模板中,此参数现在被显式配置为:node,infra,pgsql,即直接从这些上游软件仓库安装。
    • 将其设置为 local,则会使用本地软件仓库安装所有软件包,速度最快,没有其他仓库的变数干扰。
    • 如果你想同时使用本地软件仓库和上游软件仓库,可以将其设置为 local,node,infra,pgsql

优缺点

如果您使用的是上述列表中给出的操作系统(精确匹配的小版本),那么建议使用离线软件包。 Pigsty 为这些系统提供了开箱即用的预制离线软件包,在 GitHub 上提供免费下载。

使用离线软件包的优点
  • 官方离线软件包经过测试。
  • 在与互联网隔离的环境中交付的最简单方法。
  • 通过一次性预下载所有软件包来加速安装过程。
  • 快照确保可以正常工作,无需担心上游依赖项的变动导致依赖错漏。
使用离线软件包的缺点
  • 如果操作系统次要版本不匹配,操作系统的 rpm/deb 软件包可能会出现问题
  • 可能不包含最新的更新和操作系统安全补丁。

如果你使用的操作系统版本不在上述列表中,你可以考虑自制离线安装包,我们也提供针对更多操作系统大小版本的离线安装包预制服务(¥200)


引导程序

bootstrap 脚本将自动检测 /tmp/pkg.tgz 并默认将其解压到 /www/pigsty。 它还将设置操作系统软件包管理器的仓库文件,并安装 ansible 和其他工具。

我的仓库文件在哪里?

引导程序默认会 清除 现有仓库,以确保只安装所需的仓库。

您可以在 /etc/yum.repos.d/backup (EL) 或 /etc/apt/backup (Debian / Ubuntu) 中找到它们

如果您想保留现有仓库

您可以使用 -k|--keep 参数来保持现有仓库文件不变:

./bootstrap -k # 或 --keep

制作离线软件包

如果您选择的操作系统不在默认列表中, 您可以使用内置的 cache.yml 剧本制作自己的离线软件包。

步骤 1

    找到一台运行完全相同操作系统版本,且可以访问互联网的节点

步骤 2

    运行标准 [在线安装](/zh/docs/install) (建议使用 `rich` 配置模板:`configure -c rich`)

步骤 3

    `cd ~/pigsty; ./cache.yml`:制作并获取离线软件包到 `~/pigsty/dist/${version}/`

步骤 4

    将离线软件包复制到没有互联网访问的环境中(ftp、scp、usb 等),通过 `bootstrap` 解包使用
v3.6 的行为变化

自从 Pigsty v3.6 开始,大部份配置模板都直接从互联网上游安装软件包,而不是先下载到管理节点本地构建软件仓库,再从中安装。 你可以通过调整参数来恢复此前的默认行为,如果你需要构建自己的离线软件包,这很有用:

  • repo_enabled:将此参数打开,则会构建本地软件源(在大部份配置中被显式关闭)
  • node_repo_modules:将此参数设置为 local,则环境中所有节点都从本地软件仓库安装

部分配置模板,例如 richfull 依然直接保留旧版本的行为 —— 先构建本地仓库再使用,故无需调整。

我们提供付费服务,提供经过测试的预制 Linux 主版本.次版本制作离线软件包。(¥200)


混合方法

有一种混合方法可以使用离线软件包作为基础,并在线补足不匹配的增量软件包,这种办法可以融合离线安装与在线安装的优点。

例如,假设您使用的是 RockyLinux 9.5,但官方离线软件包是为 RockyLinux 9.6 制作的。 您可以使用 el9 离线软件包,(虽然是针对 9.6 制作的) 然后在执行正式安装前,执行 make repo-build 重新下载 9.5 对应的缺失软件包, Pigsty 将从上游仓库重新下载所需的增量。

5 - 精简安装

使用最少依赖安装 PostgreSQL

如果您只想要高可用 PostgreSQL 本身,而不需要监控、基础设施等功能,请考虑精简安装。

没有 INFRA 模块,没有监控,没有 本地仓库,只有 ETCDPGSQL 以及部分 NODE 功能


概述

使用精简安装,您需要:

步骤 1

  使用 `slim.yml` 配置模板(`configure -c slim`)

步骤 2

  运行 `slim.yml` 剧本而不是 `install.yml`
curl https://repo.pigsty.cc/get | bash -s v3.7.0
./configure -c slim
./install.yml

精简安装只安装这些核心组件:

组件 必需性 描述
patroni 必需 引导高可用 PostgreSQL 集群
etcd 必需 Patroni 的元数据库依赖(DCS)
pgbouncer 可选 PostgreSQL 连接池
vip-manager 可选 L2 VIP 绑定到 PostgreSQL 集群主节点
haproxy 可选 自动路由 服务
chronyd 可选 与 NTP 服务器的时间同步
tuned 可选 节点调优模板和内核参数管理

您可以关闭可选组件,只有两个必需组件是 patronietcd

软件包直接从互联网上游仓库安装,离线安装 在此处不适用。


配置

精简安装的配置文件示例:conf/slim.yml

all:
  children:
    infra: { hosts: { 10.10.10.10: { infra_seq: 1 }} ,vars: { repo_enabled: false }}
    etcd:  { hosts: { 10.10.10.10: { etcd_seq: 1  }} ,vars: { etcd_cluster: etcd  }}

    #----------------------------------------------#
    # PostgreSQL Cluster
    #----------------------------------------------#
    pg-meta:
      hosts:
        10.10.10.10: { pg_seq: 1, pg_role: primary }
      vars:
        pg_cluster: pg-meta
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }
        pg_databases:
          - { name: meta, baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [ vector ]}
        pg_hba_rules:
          - { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes' }
        node_crontab: [ '00 01 * * * postgres /pg/bin/pg-backup full' ] # make a full backup every 1am

  vars:
    #----------------------------------------------#
    # INFRA : https://doc.pgsty.com/infra/param
    #----------------------------------------------#
    version: v3.7.0                   # pigsty version string
    admin_ip: 10.10.10.10             # admin node ip address
    region: default                   # upstream mirror region: default,china,europe
    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}:9058" }
      alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9059" }
      blackbox     : { endpoint: "${admin_ip}:9115" }
      loki         : { endpoint: "${admin_ip}:3100" }

    #----------------------------------------------#
    # NODE : https://doc.pgsty.com/node/param
    #----------------------------------------------#
    nodename_overwrite: false           # do not overwrite node hostname on single node mode
    node_repo_modules: node,infra,pgsql # add these repos directly to the singleton node
    node_tune: oltp                     # node tuning specs: oltp,olap,tiny,crit

    #----------------------------------------------#
    # PGSQL : https://doc.pgsty.com/pgsql/param
    #----------------------------------------------#
    pg_version: 17                      # Default PostgreSQL Major Version is 17
    pg_conf: oltp.yml                   # pgsql tuning specs: {oltp,olap,tiny,crit}.yml
    pg_packages: [ pgsql-main, pgsql-common ]   # pg kernel and common utils
    #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]

    #----------------------------------------------#
    # SLIM: http://localhost:3000/docs/install/minimal
    #----------------------------------------------#
    nginx_enabled: false              # nginx not exists
    dns_enabled: false                # dnsmasq not exists
    prometheus_enabled: false         # prometheus not exists
    grafana_enabled: false            # grafana not exists
    pg_exporter_enabled: false        # disable pg_exporter
    pgbouncer_exporter_enabled: false # disable pgbouncer_exporter
    pgbackrest_exporter_enabled: false # disable pgbackrest_exporter
    pg_vip_enabled: false             # disable pg_vip

安装

使用 slim.yml 剧本而不是 install.yml 剧本:

./slim.yml
不要使用 install.yml 进行精简安装

这个 slim.yml 剧本是专门用来在精简安装场景中取代默认 install.yml 剧本的。

6 - 视频演示

安装过程的视频教程

请参见 Asciinema 终端录像: Vonng


标准安装

Pigsty v3.6.0, RockyLinux 9.6, x86_64, 标准安装, Link

这会使用默认的 meta 单节点配置模板,从互联网直接安装所有所需软件包。

curl -fsSL https://repo.pigsty.io/get | bash -s v3.6.0; cd ~/pigsty;
./configure
./install.yml

asciicast


完整安装

Pigsty v3.6.0, Ubuntu 24.04.2, x86_64, 完整安装

完整安装使用 rich 模板,在标准安装的基础上,有以下区别于改动:

  • 尽可能安装(但不都启用)所有 PostgreSQL 扩展插件
  • 构建本地软件仓库,先下载到本地仓库,再让所有节点都从本地软件仓库进行安装
  • 1 node minio used as central backup repo
  • cluster stub for 3-node pg-test / ferret / redis
  • stub for nginx, certs, and website self-hosting config
  • detailed comments for database / user / service
./configure -c rich     # use the conf/rich.yml template
./install.yml
curl -fsSL https://repo.pigsty.io/get | bash -s v3.6.0; cd ~/pigsty;
./configure -i rich
vi pigsty.yml   # edit password
./install.yml
make tu tssh
asciinema rec
ssh meta
ls /www/pigsty
cat ~/pigsty/pigsty.yml | grep node_repo_modules
sudo su - postgres
pg list
pb info
pg-backup incr
pb list
psql
SELECT * FROM pg_available_extensions;

Slim Install

Pigsty v3.6.0, Debian 12.11, aarch64, Slim Installation, Link

Postgres HA Cluster with essential modules, (with ETCD, without INFRA).

asciinema rec
ssh meta
curl -fsSL https://repo.pigsty.io/get | bash -s v3.6.0; cd ~/pigsty;
./configure -i slim
./slim.yml
sudo su - postgres
psql

Offline Install

Pigsty v3.6.0, RockyLinux 9.6, aarch64, Slim Installation

# download this offline package and put it to /tmp/pkg.tgz, we just skip downloading here
# curl https://github.com/pgsty/pigsty/releases/download/v3.6.0/pigsty-pkg-v3.6.0.el9.x86_64.tgz -o /tmp/pkg.tgz
scp ~/pigsty/dist/v3.6.0/pigsty-v3.6.0.tgz meta:~/pigsty.tgz

# download source package and extract it to ~/pigsty, we just skip downloading here
# curl https://github.com/pgsty/pigsty/releases/download/v3.6.0/pigsty-v3.6.0.tgz -o ~/pigsty.tgz; tar xzf ~/pigsty.tgz -C ~/
scp ~/pigsty/dist/v3.6.0/pigsty-pkg-v3.6.0.el9.aarch64.tgz meta:/tmp/pkg.tgz

ssh meta
tar -xf pigsty.yml  # extract pigsty source tarball
cd pigsty           # enter pigsty home dir
./bootstrap         # now bootstrap pigsty from local repo
./configure         # generate pigsty.yml
vi pigsty.yml       # use local repo rather than install from the internet upstream repo
#node_repo_modules: local

./install.yml

Supabase

Pigsty v3.6.0, Ubuntu 24.04, x86_64, Install Supabase

curl -fsSL https://repo.pigsty.io/get | bash -s v3.6.0; cd ~/pigsty;
./configure -c supabase
./install.yml
./docker.yml   # install docker & docker-compose
./app.yml      # launch supabase docker app with docker compose
vi pigsty.yml


curl -fsSL https://repo.pigsty.cc/get | bash -s v3.6.0; cd ~/pigsty
./configure -c supabase    # 使用 supabase 配置(请在 pigsty.yml 中更改凭据)
vi pigsty.yml              # 编辑域名、密码、密钥...
./install.yml              # 安装 pigsty
./docker.yml               # 安装 docker compose 组件
./app.yml                  # 使用 docker 启动 supabase 无状态部分


cd /opt/supabase
docker ps

sudo su - postgres
pg list
pb info
pg-backup incr
pb info

psql
\dn
\l
\du
table pg_available_extensions;

\c supabase
\dn
\du

# Now let's setup your domain name and HTTPS certificates
ssh meta            # the temp cloud server for the supabase demo
dig supa.pigsty.cc  # let's use this as example, use your domain name instead, and resolve it to your server IP
cd ~/pigsty/
grep supa.pigsty pigsty.yml -a2 -b2
sed -ie 's/supa.pigsty/supa.pigsty.cc/g' pigsty.yml  # rename old supa.pigsty domain placeholder to your domain name
sed -ie 's/supa.pigsty.cc/supa.pigsty/g' pigsty.yml  # rename old supa.pigsty domain placeholder to your domain name
grep supa.pigsty pigsty.yml -a2 -b2
curl -i https://supa.pigsty.cc