Pigsty v1.5.1 文档

• 1: Pigsty入门指南
• 2: Pigsty 快速上手
• 3: Pigsty亮点特性
• 4: FAQ: 常见问题
• 5: 概念导览
• 6: 架构
• 7: 基础设施
• 8: 概念：节点
• 9: PGSQL 概念
• 10: Redis 概念
• 11: PGSQL服务与接入
• 12: PGSQL业务用户与数据库
• 13: PGSQL 权限认证与访问控制
• 14: Pigsty部署
• 15: 准备工作
• 16: 沙箱环境
• 17: 监控系统部署
• 18: PostgreSQL集群部署
• 19: 部署与监控Redis
• 20: MatrixDB部署与监控
• 21: Pigsty剧本
• 22: 剧本：INFRA
• 23: 剧本：NODES
• 24: 剧本：PGSQL
• 25: 剧本：REDIS
• 26: 配置Pigsty
• 27: 配置：Infra
• 28: 配置：Nodes
• 29: 配置：PGSQL
• 30: 配置：REDIS
• 31: 定制：PGSQL深度定制与修改
• 32: Pigsty Dashboards
• 33: 服务发现
• 34: 监控指标
• 35: 告警系统
• 36: 扩展应用
• 37: 容器指南
• 38: 升级Grafana后端数据库
• 39: 部署教程：Jupyter Lab数据分析环境
• 40: 备份与恢复
• 41: 离线安装
• 42: 使用CMDB
• 43: 数据库迁移教程
• 44: SOP: 标准操作流程
• 45: 目录结构
• 46: 数据库高可用场景演练
• 47: 数据库常见故障诊断与处理
• 48: 社区
• 49: 路线图
• 50: 开发日志与发布说明
• 51: 为什么使用 Pigsty
• 52: 用户界面
• 53: Pigsty部署
• 54: 定制 PostgreSQL 模板
• 55: 部署与监控Redis
• 56: PGWeb
• 57: 使用TimescaleDB存储Prometheus数据

curl -SL https://github.com/Vonng/pigsty/releases/download/v1.5.1/pigsty.tgz | gzip -d | tar -xC ~ # 下载
cd ~/pigsty && ./configure                            # 配置
make install                                          # 安装

1 - Pigsty入门指南

不同的用户有不同的关注点，如果遇到问题，欢迎查阅FAQ，提交Issue，或向社区求助。

新用户

新接触PostgreSQL与Pigsty的用户，可以参阅 亮点特性了解Pigsty的功能，或访问Pigsty演示站点：http://demo.pigsty.cc 进行直观地交互式体验概览其功能。如果您想自己动手试一试，可以按照 快速上手 中的介绍，一键在本地拉起一样的沙箱环境。

Pigsty演示中内置了几个典型基于Pigsty开发的数据应用，用于演示此发型版的能力，例如：pglog，covid，isd，dbeng，worktime等，此外，您还可以参考 Docker应用教程，使用Pigsty部署生产级的SaaS软件服务。

开发者（Dev）

开发者更关注的问题是：如何最快地下载，安装并接入数据库，请参考 快速上手

Pigsty针对易用性进行了大量优化，在全新CentOS 7.8节点上，无需互联网访问即可完成一键安装。

Pigsty提供了预置的 Vagrant & Terraform 模板，用于在本地x86笔记本/PC或云上一键拉起4台虚拟机，部署沙箱环境。

用户也可以自行准备虚拟机，云虚拟机，或生产物理机器来进行标准部署流程。

Pigsty中的数据库，对外以服务的方式交付，用户通过PG连接串进行接入。

部署完成后，开发者可以参考教程中的内容，熟悉基本管理操作，并了解访问数据库的方法，如果有问题

如果您想要深入了解Pigsty本身的设计与架构，可以参考概念一章中的主题：

• 系统架构
• 基础设施
• 元节点 与 节点
• 概念：PGSQL数据库集群
• PGSQL服务 与 PGSQL接入
• PGSQL权限 与 PGSQL认证
• PGSQL业务用户 与 PGSQL业务数据库

Pigsty中的绝大多数操作都是一键傻瓜式的，而真正的精髓隐藏在配置中。

运维人员 （OPS）

运维人员更关注实施部署的细节，以下教程将介绍Pigsty安装部署的细节：

• Pigsty部署
• Pigsty资源准备
• 制作离线安装包
• 基础设施初始化
• PostgreSQL数据库初始化
• Redis数据库初始化

其中，教程升级Grafana后端数据库展示了一个完整的，具有代表性的案例：搭建并使用一套专供Grafana使用的Postgres数据库集群，将上述主题的内容付诸于实践。

管理员（DBA）

DBA通常更关注监控系统的用法与日常维护的具体方式。

监控系统教程

• 监控指标简介
• 监控面板简介
• 告警系统简介
• 服务发现机制
• 分析CSV日志

日常维护管理

• 集群创建/扩容
• 集群下线/缩容
• 集群配置变更/重启
• 集群业务用户创建
• 集群业务数据库创建
• 集群HBA规则调整
• 集群流量控制
• 集群角色调整
• 监控对象调整
• 集群主从切换
• 重置组件
• 替换集群DCS服务器

专业用户

对于专业用户（深度定制，二次开发），Pigsty提供了丰富的配置项与定制接口。

几乎所有配置项都配置有合理的默认值，无需修改即可使用。专业用户可以参考配置项文档按需自行调整或按需定制。

2 - Pigsty 快速上手

Pigsty的安装分为三个步骤：部署准备，修改配置，执行剧本

Pigsty有两种典型使用模式：单机安装 与 集群管理。

• 单机：在单个节点上安装Pigsty，将其作为开箱即用的Postgres数据库使用（开发测试）
• 集群：在单机安装的基础上，部署、监控、管理其他节点与多种不同种类的数据库（运维管理）

单机安装

在一台节点上安装Pigsty时，Pigsty会在该节点上部署完整的基础设施运行时 与 一个单节点PostgreSQL数据库集群。对于个人用户、简单场景、小微企业来说，您可以直接开箱使用此数据库。

准备好新装机器（Linux x86_64 CentOS 7.8.2003）一台，配置管理用户ssh本机sudo访问，然后下载Pigsty。

curl -SL https://github.com/Vonng/pigsty/releases/download/v1.5.1/pigsty.tgz | gzip -d | tar -xC ~  # 下载最新pigsty源代码
cd ~/pigsty; ./configure                               # 根据当前环境生成配置
./infra.yml                                            # 在当前节点上完成安装

如果您有可用的Macbook/PC/笔记本或云厂商账号，可使用沙箱部署在本机或云端自动创建虚拟机。

执行完毕后，您已经在当前节点完成了Pigsty的安装，上面带有完整的基础设施与一个开箱即用的PostgreSQL数据库实例，当前节点的5432对外提供数据库服务，80端口对外提供所有WebUI类服务。

80端口为所有Web图形界面服务的访问端点。尽管可以绕过Nginx直接使用端口访问各项服务，例如3000端口的Grafana，但强烈建议用户通过在本机配置静态DNS的方式，使用域名访问各项Web子服务。

访问 http://g.pigsty 或 http://<primary_ip>:3000 即可浏览 Pigsty监控系统主页 (用户名: admin, 密码: pigsty)

集群管理

Pigsty还可以用作大规模生产环境的集群/数据库管理。您可以从单机安装Pigsty的节点（将作为集群的元节点，或称作元节点/Meta）上发起控制，将更多的 机器节点 纳入Pigsty的管理与监控中。 更重要的是，Pigsty还可以在这些节点上部署并管理各式各样的数据库集群与应用：创建高可用的PostgreSQL数据库集群；创建不同类型的Redis集簇；部署 Greenplum/MatrixDB 数据仓库，并获取关于节点、数据库与应用的实时洞察。

# 在四节点本地沙箱/云端演示环境中，可以使用以下命令在其他三台节点上部署数据库集群
./nodes.yml  -l pg-test      # 初始化集群pg-test包含的三台机器节点（配置节点+纳入监控）
./pgsql.yml  -l pg-test      # 初始化高可用PGSQL数据库集群pg-test
./redis.yml  -l redis-test   # 初始化Redis集群 redis-test
./pgsql-matrixdb.yml -l mx-*  # 初始化MatrixDB集群mx-mdw,mx-sdw

沙箱环境

Pigsty设计了一个标准的，4节点的演示教学环境,称为沙箱环境，您可以参考教程，使用Vagrant或Terraform快速在本机或公有云上拉起所需的四台虚拟机资源，并进行部署测试。跑通流程后稍作修改，便可用于生产环境部署。

以默认的沙箱环境为例，假设您已经在10.10.10.10元节点上完成单机Pigsty的安装：

./infra.yml # 在沙箱环境的 10.10.10.10 meta 机器上，完成完整的单机Pigsty安装

主机初始化

现希望将三个节点：10.10.10.11, 10.10.10.12, 10.10.10.13 纳入管理，则可使用 nodes.yml 剧本：

./nodes.yml -l pg-test      # 初始化集群pg-test包含的三台机器节点（配置节点+纳入监控）

执行完毕后，这三台节点已经带有DCS服务，主机监控与日志收集。可以用于后续的数据库集群部署。详情请参考节点 配置 与 剧本。

PostgreSQL部署

使用 pgsql.yml 剧本，可以在这三台节点上初始化一主两从的高可用PostgreSQL数据库集群 pg-test。

./pgsql.yml  -l pg-test      # 初始化高可用PGSQL数据库集群pg-test

部署完成后，即可从监控系统 中看到新创建的PostgreSQL集群。

详情请参考：PgSQL数据库集群 配置、定制 与 剧本。

Redis部署

除了标准的PostgreSQL集群，您还可以部署各种其他类型的集群，甚至其他类型的数据库。

例如在沙箱中部署Redis，可以使用Redis数据库集群 配置 与 剧本。

./configure -m redis
./nodes.yml    # 配置所有用于安装Redis的节点
./redis.yml    # 在所有节点上按照配置声明Redis

MatrixDB部署

例如在沙箱中部署开源数据仓库MatrixDB（Greenplum7），可以使用以下命令：

./configure -m mxdb  # 使用沙箱环境MatrixDB配置文件模板
./download matrix    # 下载MatrixDB软件包并构建本地源
./infra.yml -e no_cmdb=true  # 如果您准备在meta节点上部署 MatrixDB Master，添加no_cmdb选项，否则正常安装即可。
./nodes.yml                  # 配置所有用于安装MatrixDB的节点
./pgsql-matrixdb.yml          # 在上述节点上安装MatrixDB

3 - Pigsty亮点特性

开箱即用的数据库发行版：用得上，用的好，用着简单还省钱！

• 开箱即用的PostgreSQL数据库发行版
• 自动驾驶的智能监控管控运维解决方案
• 简单易用的数据库即代码开发者工具箱
• 降本增效的开源云数据库PaaS替代方案

自动驾驶高可用 / 极致入微可观测 / 简单易用门槛低 / 自由部署体验齐 / 应用广泛生态全 / 自主可控更省钱

PostgreSQL数据库发行版

RedHat for Linux! 开箱即用！ 从无到有，让用户用得上！

Pigsty将高可用集群部署，扩容缩容，主从复制，故障切换，流量代理，连接池，服务发现，访问控制，监控系统，告警系统，日志采集等生产级成熟解决方案封装为发行版。一次性解决在生产环境与各类场景下使用 世界上最先进的开源关系型数据库 —— PostgreSQL 时会遇到的各种问题，真正做到开箱即用。

• Pigsty深度整合PostgreSQL 14.4 与强力扩展：时序数据 TimescaleDB 2.7、地理空间 PostGIS 3.2、分布式 Citus 11.0，及上百+海量扩展插件，全部开箱即用。

• Pigsty打包了大规模生产环境所需的基础设施：Grafana，Prometheus，Loki，Ansible，Consul，Docker等， 亦可作为部署监控其他数据库与应用的运行时/PaaS。

• Pigsty集成了数据分析生态的常用工具：Jupyter，ECharts，Grafana，PostgREST，Postgres，可作为数据分析环境，或低代码数据可视化应用开发平台。

智能监控管控运维解决方案

Auto-Pilot for Postgres! 自动驾驶！ 从有到优，让用户用的爽！

• Pigsty带有一个无可比拟的数据库监控系统，通过30+精心设计组织的监控面板呈现超1200类指标，从全局概览到单个库内对象一览无余，提供终极的可观测性！

• Pigsty提供高可用的 PostgreSQL 数据库集群，任意成员存活即可正常对外提供服务；各实例幂等，提供类分布式数据库的体验；故障自愈，极大简化运维工作！

• Pigsty支持部署不同种类的数据库集群与实例：经典 PGSQL 主从复制集群/灾备集群，同步/延迟/离线/级联实例，Citus/Greenplum集群，Redis 主从/哨兵/原生集群。

数据库即代码开发者工具箱

HashiCorp for Database! 简单易用！从优到易，让用户省心！

• Pigsty秉持 Infra as Data 的设计理念，用户只需用几行声明式的配置文件描述自己想要的数据库，即可使用幂等剧本，一键将其创建。Just like Kubernetes!

• Pigsty向开发者交付简单易用的数据库工具箱：一键下载安装，自动配置；一键部署各类开源数据库，一键迁移备份、扩容缩容，极大拉低数据库管理使用门槛，量产DBA！

• Pigsty能够简化数据库部署与交付、解决环境配置统一的难题：无论是上千套数据库几万核的生产环境，还是本地1C1G的笔记本均可完整运行；基于Vagrant的本地沙箱与基于Terraform的多云部署，云上云下，一键拉起！

开源云数据库PaaS替代方案

Alternative for RDS! 安全可控，降本增效！从易到廉，给用户省钱！

• Pigsty相比云厂商RDS，在拥有更低使用⻔槛与更丰富功能的前提下，可节约 50% - 80% 的数据库软硬件成本，初级研发人员即可自主管理成百上千套数据库。

• Pigsty采用模块化设计，可自由组合，按需定制扩展。可在生产环境部署管理各种数据库，或仅仅将其当成主机监控；可用于开发数据库可视化Demo、或支撑各类SaaS应用。

• 开源免费的生产级数据库解决方案，用于补全云原生生态缺失的最后一块拼图。稳定可靠，经过长时间大规模生产部署验证，提供可选的专业技术支持服务。

自动驾驶高可用

故障自愈，高枕无忧

以PostgreSQL为例，Pigsty创建的数据库集群是分布式、高可用的数据库集群。只要集群中有任意实例存活，集群就可以对外提供完整的读写服务与只读服务。

Pigsty的高可用架构久经生产环境考验，Pigsty使用 Patroni + Consul 进行故障检测、Fencing与自动故障切换，通过HAProxy、VIP或DNS实现流量的自动切换，以极低的复杂度代价实现了完整的高可用方案，让主从架构的数据库能用出了布式数据库般的体验。

数据库集群可以自动进行故障检测与主从切换，普通故障能在几秒到几十秒内自愈：主库故障RTO < 1min，只读流量几乎无影响，同步集群 RPO = 0 不丢数据。

数据库集群中的每个数据库实例在使用上都是幂等的，任意实例都可以通过内建负载均衡组件HAProxy提供完整的读写服务。任何一个或多个Haproxy实例都可以作为集群的负载均衡器，并通过健康检查进行流量分发，对外屏蔽集群成员的区别。用户可以通过配置灵活定义服务，并通过多种可选方式接入。

极致入微可观测

You can’t manage you don’t measure.

监控系统提供了对系统状态的度量，是运维管理工作的基石。【DEMO】

Pigsty带有一个针对大规模数据库集群管理而设计的专业级监控系统，基于业内最佳实践，采用Prometheus、Alertmanager、Grafana、Loki作为监控基础设施。开源开放，定制便利，可复用，可移植，没有厂商锁定。

Pigsty在PostgreSQL监控上做到无可比拟，通过30+监控面板与上千仪表盘综合呈现约1200+类指标，覆盖从全局大盘到单个对象的详细信息，从数据库目录到节点日志全部一览无遗。与同类产品相比在指标的覆盖率与监控面板丰富程度上一骑绝尘，为专业用户提供无可替代的价值。详略得当的层次设计，为业余用户带来直观便捷的管理体验。

Pigsty的监控系统可用于监控原生部署的各类数据库实例：PGSQL，REDIS，GPSQL等，也可以独立使用，监控已有的数据库实例或远端云厂商RDS，或仅仅作为主机监控使用，它还可以用作数据可视化作品的展示平台。

简单易用门槛低

HashiCorp for Database! Database as Code, Infra as Data!

Pigsty采纳 Database as Data 的设计哲学，使用类似 Kubernetes 的声明式配置，通过大量可选的配置选项对数据库与运行环境进行描述，并通过幂等的预置剧本自动创建所需的数据库集群，提供私有云般的使用体验。

用户只需要通过配置文件或图形界面描述“自己想要什么样的数据库”，而无需关心Pigsty如何去创建或修改它。Pigsty会根据用户的配置文件清单，在几分钟内从裸机节点上创造出所需的数据库集群。

例如，在三台机器上创建一主两从的数据库集群pg-test，只需要几行配置与一行命令pgsql.yml -l pg-test，即可创建出如下一节所介绍的高可用数据库集群。

#----------------------------------#
# cluster: pg-meta (on meta node)  #
#----------------------------------#
# pg-meta is the default SINGLE-NODE pgsql cluster deployed on meta node (10.10.10.10)
# if you have multiple n meta nodes, consider deploying pg-meta as n-node cluster too

pg-meta:                                # required, ansible group name , pgsql cluster name. should be unique among environment
  hosts:                                # `<cluster>.hosts` holds instances definition of this cluster
    10.10.10.10:                        # INSTANCE-LEVEL CONFIG: ip address is the key. values are instance level config entries (dict)
      pg_seq: 1                         # required, unique identity parameter (+integer) among pg_cluster
      pg_role: primary                  # required, pg_role is mandatory identity parameter, primary|replica|offline|delayed
      pg_offline_query: true            # instance with `pg_offline_query: true` will take offline traffic (saga, etl,...)
      # some variables can be overwritten on instance level. e.g: pg_upstream, pg_weight, etc...
    #---------------
    # mandatory                         # all configuration above (`ip`, `pg_seq`, `pg_role`) and `pg_cluster` are mandatory
    #---------------
  vars:                                 # `<cluster>.vars` holds CLUSTER LEVEL CONFIG of this pgsql cluster
    pg_cluster: pg-meta                 # required, pgsql cluster name, unique among cluster, used as namespace of cluster resources

    #---------------
    # optional                          # all configuration below are OPTIONAL for a pgsql cluster (Overwrite global default)
    #---------------
    pg_version: 14                      # pgsql version to be installed (use global version if missing)
    node_tune: tiny                     # node optimization profile: {oltp|olap|crit|tiny}, use tiny for vm sandbox
    pg_conf: tiny.yml                   # pgsql template:  {oltp|olap|crit|tiny}, use tiny for sandbox
    patroni_mode: default               # entering patroni pause mode after bootstrap  {default|pause|remove}
    patroni_watchdog_mode: off          # disable patroni watchdog on meta node        {off|require|automatic}
    pg_lc_ctype: en_US.UTF8             # use en_US.UTF8 locale for i18n char support  (required by `pg_trgm`)

    #---------------
    # biz databases                     # Defining Business Databases (Optional)
    #---------------
    pg_databases:                       # define business databases on this cluster, array of database definition
      # define the default `meta` database
      - 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/)
        # 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)
        # pgbouncer: true               # optional, add this database to pgbouncer database list? true by default
        comment: pigsty meta database   # optional, comment string for this database
        connlimit: -1                   # optional, database connection limit, default -1 disable limit
        schemas: [pigsty]               # optional, additional schemas to be created, array of schema names
        extensions:                     # optional, additional extensions to be installed: array of schema definition `{name,schema}`
          - { name: adminpack, schema: pg_catalog }    # install adminpack to pg_catalog
          - { name: postgis, schema: public }          # if schema is omitted, extension will be installed according to search_path.
          - { name: timescaledb }                      # some extensions are not relocatable, you can just omit the schema part

      # define an additional database named grafana & prometheus (optional)
      # - { name: grafana,    owner: dbuser_grafana    , revokeconn: true , comment: grafana    primary database }
      # - { name: prometheus, owner: dbuser_prometheus , revokeconn: true , comment: prometheus primary database , extensions: [{ name: timescaledb }]}

    #---------------
    # biz users                         # Defining Business Users (Optional)
    #---------------
    pg_users:                           # define business users/roles on this cluster, array of user definition
      # define admin user for meta database (This user are used for pigsty app deployment by default)
      - name: dbuser_meta               # required, `name` is the only mandatory field of a user definition
        password: md5d3d10d8cad606308bdb180148bf663e1  # md5 salted password of 'DBUser.Meta'
        # optional, plain text and md5 password are both acceptable (prefixed with `md5`)
        login: true                     # optional, can login, 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`
        # search_path: public         # key value config parameters according to postgresql documentation (e.g: use pigsty as default search_path)
      - {name: dbuser_view , password: DBUser.Viewer  ,pgbouncer: true ,roles: [dbrole_readonly], comment: read-only viewer for meta database}

      # define additional business users for prometheus & grafana (optional)
      - {name: dbuser_grafana    , password: DBUser.Grafana    ,pgbouncer: true ,roles: [dbrole_admin], comment: admin user for grafana database }
      - {name: dbuser_prometheus , password: DBUser.Prometheus ,pgbouncer: true ,roles: [dbrole_admin], comment: admin user for prometheus database , createrole: true }

    #---------------
    # hba rules                                         # Defining extra HBA rules on this cluster (Optional)
    #---------------
    pg_hba_rules_extra:                                 # Extra HBA rules to be installed on this cluster
      - title: reject grafana non-local access          # required, rule title (used as hba description & comment string)
        role: common                                    # required, which roles will be applied? ('common' applies to all roles)
        rules:                                          # required, rule content: array of hba string
          - local   grafana         dbuser_grafana                          md5
          - host    grafana         dbuser_grafana      127.0.0.1/32        md5
          - host    grafana         dbuser_grafana      10.10.10.10/32      md5

    vip_mode: l2                        # setup a level-2 vip for cluster pg-meta
    vip_address: 10.10.10.2             # virtual ip address that binds to primary instance of cluster pg-meta
    vip_cidrmask: 8                     # cidr network mask length
    vip_interface: eth1                 # interface to add virtual ip

#----------------------------------#
# redis sentinel example           #
#----------------------------------#
redis-meta:
  hosts:
    10.10.10.10:
      redis_node: 1
      redis_instances:  { 6001 : {} ,6002 : {} , 6003 : {} }
  vars:
    redis_cluster: redis-meta
    redis_mode: sentinel
    redis_max_memory: 128MB

#----------------------------------#
# redis cluster example            #
#----------------------------------#
redis-test:
  hosts:
    10.10.10.11:
      redis_node: 1
      redis_instances: { 6501 : {} ,6502 : {} ,6503 : {} ,6504 : {} ,6505 : {} ,6506 : {} }
    10.10.10.12:
      redis_node: 2
      redis_instances: { 6501 : {} ,6502 : {} ,6503 : {} ,6504 : {} ,6505 : {} ,6506 : {} }
  vars:
    redis_cluster: redis-test           # name of this redis 'cluster'
    redis_mode: cluster                 # standalone,cluster,sentinel
    redis_max_memory: 64MB              # max memory used by each redis instance
    redis_mem_policy: allkeys-lru       # memory eviction policy

#----------------------------------#
# redis standalone example         #
#----------------------------------#
redis-common:
  hosts:
    10.10.10.13:
      redis_node: 1
      redis_instances:
        6501: {}
        6502: { replica_of: '10.10.10.13 6501' }
        6503: { replica_of: '10.10.10.13 6501' }
  vars:
    redis_cluster: redis-common         # name of this redis 'cluster'
    redis_mode: standalone              # standalone,cluster,sentinel
    redis_max_memory: 64MB              # max memory used by each redis instance

#----------------------------------#
# cluster: mx-mdw (gp master)
#----------------------------------#
mx-mdw:
  hosts:
    10.10.10.10: { pg_seq: 1, pg_role: primary , nodename: mx-mdw-1 }
  vars:
    gp_role: master          # this cluster is used as greenplum master
    pg_shard: mx             # pgsql sharding name & gpsql deployment name
    pg_cluster: mx-mdw       # this master cluster name is mx-mdw
    pg_databases:
      - { name: matrixmgr , extensions: [ { name: matrixdbts } ] }
      - { name: meta }
    pg_users:
      - { name: meta , password: DBUser.Meta , pgbouncer: true }
      - { name: dbuser_monitor , password: DBUser.Monitor , roles: [ dbrole_readonly ], superuser: true }

    pgbouncer_enabled: true                # enable pgbouncer for greenplum master
    pgbouncer_exporter_enabled: false      # enable pgbouncer_exporter for greenplum master
    pg_exporter_params: 'host=127.0.0.1&sslmode=disable'  # use 127.0.0.1 as local monitor host

#----------------------------------#
# cluster: mx-sdw (gp master)
#----------------------------------#
mx-sdw:
  hosts:
    10.10.10.11:
      nodename: mx-sdw-1        # greenplum segment node
      pg_instances:             # greenplum segment instances
        6000: { pg_cluster: mx-seg1, pg_seq: 1, pg_role: primary , pg_exporter_port: 9633 }
        6001: { pg_cluster: mx-seg2, pg_seq: 2, pg_role: replica , pg_exporter_port: 9634 }
    10.10.10.12:
      nodename: mx-sdw-2
      pg_instances:
        6000: { pg_cluster: mx-seg2, pg_seq: 1, pg_role: primary , pg_exporter_port: 9633  }
        6001: { pg_cluster: mx-seg3, pg_seq: 2, pg_role: replica , pg_exporter_port: 9634  }
    10.10.10.13:
      nodename: mx-sdw-3
      pg_instances:
        6000: { pg_cluster: mx-seg3, pg_seq: 1, pg_role: primary , pg_exporter_port: 9633 }
        6001: { pg_cluster: mx-seg1, pg_seq: 2, pg_role: replica , pg_exporter_port: 9634 }
  vars:
    gp_role: segment               # these are nodes for gp segments
    pg_shard: mx                   # pgsql sharding name & gpsql deployment name
    pg_cluster: mx-sdw             # these segment clusters name is mx-sdw
    pg_preflight_skip: true        # skip preflight check (since pg_seq & pg_role & pg_cluster not exists)
    pg_exporter_config: pg_exporter_basic.yml                             # use basic config to avoid segment server crash
    pg_exporter_params: 'options=-c%20gp_role%3Dutility&sslmode=disable'  # use gp_role = utility to connect to segments

自由部署体验齐

无论是几万核的生产环境，还是1核2G的本地虚拟机，云上云下，用哪个云，体验如一！

无论是生产环境、预发环境、还是本地开发测试环境，对Pigsty来说，只有配置文件的内容差异。无论在哪里部署，都能带来统一的使用体验。

Pigsty可以利用Vagrant与Virtualbox，在您自己的笔记本电脑上拉起安装所需的虚拟机沙箱环境，或通过Terraform，自动向云服务商申请ECS/VPC资源，一键创建，一键销毁，自动获取多云部署的能力。

沙箱环境中的虚拟机具有固定的资源名称与IP地址，非常适于软件开发测试、实验演示。 沙箱配置默认为2核4GB的单节点，IP地址 10.10.10.10，部署有一个名为pg-meta-1的单机数据库实例。 此外还有四节点版本的完整版沙箱，带有额外三个数据库节点，可用于充分展现Pigsty高可用架构与监控系统的能力。

应用广泛生态全

一键拉起生产级SaaS应用，数据分析快速上手，低代码开发可视化大屏

SaaS软件应用

Pigsty在元节点上默认安装了Docker，您可以一键拉起各类SaaS应用：开源私有代码托管平台Gitlab，开源论坛Discourse，开源社交网络Mastodon，开源ERP软件Odoo，以及用友、金蝶等软件。 您可以使用Docker拉起无状态的部分，修改其数据库连接串使用外部数据库，获取丝滑的云原生管理体验与生产级的数据持久性。详情请参考 教程:Docker应用。

数据分析与可视化应用

Pigsty既是开箱即用的PostgreSQL发行版，也可以用做数据分析环境，或制作低代码的可视化应用。您可以直接从SQL数据处理到Echarts绘图一步到位，也可以使用更精细的工作流：例如使用PG作为主数据库，存储数据并用SQL实现业务逻辑；使用内置的PostgREST自动生成后端API，使用内置的JupyterLab用Python进行复杂数据分析，并使用Echarts进行数据可视化，并通过Grafana获得交互能力。

Pigsty自带有几个应用样例作为参考：

• 分析PG CSV日志样本pglog
• 新冠疫情数据可视化 covid
• 全球地表气象站数据查询 isd
• 数据库流行度排行趋势 dbeng
• 查询大厂工作上下班安排 worktime

自主可控更省钱

Pigsty可将数据库的综合持有成本降低 50% ～ 80% ，并让数据真正掌控在用户自己的手中！

公有云数据库/RDS，是一种所谓"开箱即用"的解决方案，但它交出的答卷离让用户满意还有很长路要走：相比自建数据库成本昂贵，许多需要超级用户权限的功能被阉割，愚笨的UI与大锅饭式的功能，但在所有问题中，最重要的问题莫过于云软件的安全与成本问题：

自主可控

• 运行在你自己的电脑上的软件，即使软件供应商倒闭也可以继续运行下去。但如果提供云软件的公司/部门倒闭或决定停止支持，这些软件就没法工作了，而你用这些软件创造的数据就被锁死了。因为数据只存储在云端，而不是你自己服务器的磁盘上，而您能指望的补偿通常只有鸡肋的代金券。
• 无法定制或扩展的问题在云数据库中进一步加剧。云数据库通常不向用户提供数据库超级用户，这将锁死一大批高级功能，以及自行加装扩展功能的能力。与此相对应，‘流复制’，‘高可用’这些本该是数据库标配的东西往往作为增值项向用户出售。
• 云服务可能在没有警告和追索手段的情况下突然暂停你的账户。您可能在完全无辜的情况下，被自动化系统判定为违反服务条款：未备案使用80与53端口，账户被爆破并用于发送恶意软件或钓鱼邮件，触发违背服务条款。或因为一些政治原因被云厂商锤翻，例如Parler。
• 国内不用SaaS坚持自研或开源自建的习惯，是被恶劣的生态产业环境真金白银教育出来的。在信息时代把核心资产 — 数据放在别人的硬盘上，就像把金条放在超市存包柜中一样。您无法避免，无法监督、甚至无法意识到利益冲突的云厂商，或者仅仅是怀有恶意或好奇的运维与DBA人员偷窥盗窃您的珍贵数据。

Pigsty则不然，它可以部署在任意地方，包括您自己的服务器上。它开源免费，无需License，无需互联网访问，不收集任何用户数据。您可以在自己的服务器运行它直到海枯石烂。

降本增效

云数据库的成本则是另一个问题：省钱是用户的刚需。公有云厂商的RDS相比传统商业数据库也许有优势，但在自建开源数据库前仍然是暴利天价。据统计，RDS的综合持有成本比起基于云服务器自建要高达 2~3倍，比起IDC托管自建更是高出 5～10倍。

Pigsty相比使用云数据库有显著成本优势。例如，您可以使用云数据库一半的开销购买同规格的云服务器，并使用Pigsty自行部署数据库。在这种情况下，您既可以享受公有云的绝大部份管理之快捷便利（IaaS），又可以立竿见影节省一半以上的开销。

更重要的是，Pigsty能显著提高用户效能：它允许一两个高级DBA将所有琐碎杂务交由软件处理，轻松管理几百套数据库集群；也可以让一个初级研发人员，经过简单的学习培训后，即可迅速达到一个高级DBA的廉价七成正确水平。

Pigsty开源免费，在提供类似甚至超过云厂商RDS使用体验的前提下，可将数据库的综合持有成本降低 50% ～ 80% ，并让数据真正掌控在用户自己的手中！

4 - FAQ: 常见问题

这里列出了Pigsty用户常遇到的问题，如果您遇到了难以解决的问题，可以联系我们，或提交Issue。

• 准备
• 下载
• 配置
• 安装
• 沙箱
• 监控
• INFRA
• NODES
• PGSQL

准备

您需要确保机器节点硬件规格与操作系统符合安装要求，详情参见：准备工作

机器节点要求

安装Pigsty需要至少一个机器节点：规格至少为1核2GB，1核1G也可安装但容易OOM。

如果您希望部署自我管理的高可用PostgreSQL数据库集群，建议最少使用3个规格相同的节点。

操作系统要求

这是一个经过充分验证的操作系统版本，Pigsty开发、测试、打包都默认基于CentOS 7.8。CentOS 7.6也经过充分的验证。其他CentOS 7.x及其等效版本RHEL7 , Oracle Linux 7理论上没有问题，但并未进行测试与验证。

软件版本策略

Pigsty遵循语义版本号规则: <major>.<minor>.<release>。大版本更新意味着重大的根本性架构调整，次版本号增长意味着一次显著更新，通常意味着软件包版本更新，API的微小变动，以及其它增量功能变更，通常会包含一份升级注意事项说明。Release版本号通常用于Bug修复与文档更新，Release版本号增长不会变更软件包版本（即 v1.0.1 与 v1.0.0对应的 pkg.tgz是相同的）。

Pigsty计划会每1-3个月发布一个Minor Release，每1-2年发布一个Major Release。

沙箱虚拟机置备

部署Pigsty需要用到物理机/虚拟机节点，您可以直接自备物理机/虚拟机用于部署。但IaaS资源置备仍然是一件麻烦事，所以Pigsty提供了基于Vagrant与HashiCorp的IaaS层资源模板，您可以一键获取部署Pigsty4节点沙箱环境所需的虚拟机资源。

沙箱环境是一个配置规格、对象标识符、IP地址与默认数据库全部预先确定的环境，由一个元节点与三个普通节点组成，无论是本地版还是云端版都保持一致，用于开发/测试/演示/说明。使用以下命令拉起Vagrant本地沙箱：

make deps    # 安装homebrew，并通过homebrew安装vagrant与virtualbox（需重启）
make dns     # 向本机/etc/hosts写入静态域名 (需sudo输入密码)
make start   # 使用Vagrant拉起单个meta节点  (start4则为4个节点)

下载

Pigsty源码包是安装Pigsty时的必选项。离线软件包是可选的推荐项，情请参考 软件下载。

如何下载Pigsty源码包

执行以上命令，可自动下载最新稳定版本 pigsty.tgz ，并解压至 ~/pigsty目录。您也可以从下列位置手工下载特定版本的Pigsty源码包，如果您需要在无互联网的环境中安装，可以提前下载并通过 scp/sftp 等方式上传至生产服务器。

https://github.com/Vonng/pigsty/releases/download/v1.5.1/pigsty.tgz   # Github Release
http://download.pigsty.cc/v1.5.1/pigsty.tgz                           # 中国大陆用加速CDN
https://pan.baidu.com/s/1DZIa9X2jAxx69Zj-aRHoaw?pwd=8su9              # 百度云网盘下载

下载其他Pigsty软件包

Pigsty源码包内提供了一个download脚本，用于下载Pigsty相关资源：Pigsty源代码包本身：pigsty.tgz / 离线软件安装包：pkg.tgz / MatrixDB/Greenplum软件包：matrix.tgz / 一些SaaS应用镜像与可视化应用案例：app.tgz。其中源码包为必选项，离线软件包 pkg.tgz为建议项，使用 ./download pkg 会自动下载并提取离线软件包。

# download to /tmp/*.tgz
./download pigsty.tgz   # download pigsty source tarball
./download pkg.tgz      # download pigsty offline pkgs
./download app.tgz      # download extra pigsty apps
./download matrix.tgz   # download matrixdb packages
# download and extract
./download pigsty       # download and extract pigsty to ~/pigsty
./download pkg          # download and extract pkg    to /www/pigsty
./download app          # download and extract app    to ~/app
./download matrix       # download and extract matrix to /www/matrix

如何下载Pigsty离线软件包

Pigsty的离线软件包 pkg.tgz 打包了所有所需的软件依赖。在执行Pigsty安装时如果使用离线软件包，可以跳过从互联网下载软件的步骤。

在 ./configure 过程中，如果离线安装包/tmp/pkg.tgz不存在，向导会提示用户下载，回答“Y”即可自动从Github或CDN下载；回答“N”则会跳过下载。您也可以从下列位置手工下载离线软件包，并放置于 /tmp/pkg.tgz，则安装时会自动使用。

curl https://github.com/Vonng/pigsty/releases/download/v1.5.1/pkg.tgz -o /tmp/pkg.tgz
curl http://download.pigsty.cc/v1.5.1/pkg.tgz -o /tmp/pkg.tgz         # China CDN
https://pan.baidu.com/s/1DZIa9X2jAxx69Zj-aRHoaw?pwd=8su9              # Baidu Yun

离线软件包出现RPM冲突

Pigsty离线软件包基于CentOS 7.8操作系统制作，如果您使用的不是此精确OS Release，或者并未使用全新安装操作系统的节点进行安装，有小概率会出现RPM包依赖问题。

如果只是个别RPM依赖问题，您可以在 /www/pigsty 中删除相关RPM包，并删除标记文件 /www/pigsty/repo_complete。而后，执行常规的安装流程时，Pigsty会从 repo_upsteram 指定的上游或其他本地可用源下载缺失的依赖RPM包。如果您没有可用的互联网访问或本地源，请使用相同OS环境的有网节点制作离线软件包 后，拷贝至生产环境使用。

配置

Pigsty的安装、配置、部署都是一键傻瓜式，唯有配置是Pigsty的核心灵魂。

配置过程做了些什么

当您下载完 Pigsty 源码包，解压并进入其中后，需要先执行 ./configure 完成环境配置过程。

Pigsty会检测当前环境是否满足安装要求，并根据当前机器环境生成推荐配置文件 pigsty.yml。在files/conf/目录中，有一系列名为pigsty-*.yml的配置文件，可以作为不同场景下的配置参考模板，通过-m指定。

Configure过程会安装Ansible，一般节点的默认源都带有此软件包，如果离线安装包存在，则会从离线安装包内安装Ansible。

Pigsty的配置文件在哪

Pigsty有且仅有一个配置文件： pigsty.yml ，位于源代码根目录下，它描述了整个环境的状态。

在同一目录的ansible.cfg中：inventory = pigsty.yml 指定了此文件为默认配置文件，您也可以在执行剧本时，使用-i参数，指定使用其他位置的配置文件。此外，如果您使用CMDB作为配置源，那么请在CMDB中修改配置。

配置文件中的占位IP地址

当配置过程检测到当前机器上有多块网卡与多个IP地址时，配置向导会提示您输入主要使用的IP地址， 即用户从内部网络访问该节点时使用的IP地址，注意请不要使用公网IP地址。

该IP地址，将用于替换配置文件模板中的 10.10.10.10。

用户需要修改什么配置吗？

Pigsty提供了220+配置参数，您可以定制整个基础设施/平台/数据库的方方面面。通常在单机安装的情况下，不需要对配置文件进行任何调整即可直接使用。但仍然有个别参数，如果有需要，可以提前调整：

• 访问Web服务组件时使用的域名：nginx_upstream （一些服务只能使用域名通过Nginx代理访问）
• Pigsty假设存在一个/data目录用于盛放所有数据，如果您的数据盘挂载点与此不同，可以调整这些路径。

安装

安装时执行了什么？

configure过程默认会生成配置文件，并在其中将当前节点标记为 元节点。而make install则会针对元节点执行Pigsty元节点初始化剧本 infra.yml ，部署基础设施组件，并将元节点作为一个普通的节点进行初始化，并在其上部署一个单例PostgreSQL数据库作为CMDB。

下载RPM包速度太慢

Pigsty已经尽可能使用国内yum镜像进行下载，然而少量软件包仍然受到GFW的影响，导致下载缓慢，例如直接从Github下载的相关软件。有以下解决方案：

1. Pigsty提供离线软件包，预先打包了所有软件及其依赖，可以跳过从互联网下载软件的步骤。

2. 通过 proxy_env 指定代理服务器，通过代理服务器下载。

3. 通过 repo_upsteram 使用其他国内可用的镜像源。

远端节点无法通过标准SSH命令访问

如果您的目标机器藏在SSH跳板机之后，或者进行了某些定制化修改无法通过ssh ip的方式直接访问，则可以考虑使用 Ansible连接参数。您可以通过 ansible_port指定其他SSH端口，或 ansible_host 指定SSH Alias。

pg-test:
  vars: { pg_cluster: pg-test }
  hosts:
    10.10.10.11: {pg_seq: 1, pg_role: primary, ansible_host: node-1 }
    10.10.10.12: {pg_seq: 2, pg_role: replica, ansible_port: 22223, ansible_user: admin }
    10.10.10.13: {pg_seq: 3, pg_role: offline, ansible_port: 22224 }

远端节点SSH与SUDO需要密码

执行部署与变更时，您所使用的管理用户必须拥有所有节点的ssh与sudo权限。免密码并非必需，您总是可以在执行剧本时通过-k|-K参数传入ssh与sudo的密码，甚至通过 -eansible_host=<another_user> 使用其他用户来执行剧本。但Pigsty强烈建议为管理用户配置SSH免密码登陆与免密码sudo。

沙箱

Pigsty沙箱提供了标准的开发/测试/演示环境，可以在本地用Vagrant或云端用Terraform快速拉起。

Vagrant沙箱首次启动太慢

Pigsty沙箱默认使用CentOS 7虚拟机，Vagrant首次启动虚拟机时，会下载CentOS/7的ISO镜像Box，尺寸不小。

使用代理可能会提高下载速度，下载CentOS7 Box只需要在首次启动沙箱时进行，后续重建沙箱时会直接复用。

用户也可以选择自行下载CentOS 7 安装ISO镜像手工创建所需虚拟机。

阿里云CentOS 7.8 RPM报错

阿里云的CentOS 7.8 服务器镜像默认安装了 nscd ，锁死了 glibc 版本，会导致安装时出现RPM依赖错误。

"Error: Package: nscd-2.17-307.el7.1.x86_64 (@base)"

在所有机器上执行 yum remove -y nscd 即可解决此问题，使用Ansible可以批量执行：

ansible all -b -a 'yum remove -y nscd'

虚拟机时间失去同步

Virtualbox虚拟机关机后虚拟机内时间可能与宿主机不一致。可以尝试使用以下命令：make sync，强制执行NTP时间同步。

sudo ntpdate -u pool.ntp.org
make sync4 # 使用NTP POOL时间同步快捷方式
make ss    # 使用阿里云NTP服务器同步

即可解决长时间休眠或关机重启后监控系统没有数据的问题。此外，重启虚拟机也可以强行重置时间，且无需互联网访问：make dw4; make up4。

为什么不使用容器盛放数据库

虽然Docker对于提高环境兼容性有非常好的效果，然而数据库并不属于容器使用的最佳场景。此外Docker与Kubernetes本身也有使用门槛。为了满足“降低门槛”的主旨，Pigsty采用裸机部署。

Pigsty在设计之初就考虑到容器化云化的需求，这体现在其配置定义的声明式实现中。并不需要太多修改就可以迁移改造为云原生解决方案。当时机成熟时，会使用Kubernetes Operator的方式进行重构。

监控

监控系统的性能存储开销有多大

一个典型的生产实例，产出5千个时间序列，一次抓取大约耗时 200ms 左右；相比抓取周期15s几乎微不足道。

存储取决于用户数据库的复杂程度（workload）。作为参考：200个生产数据库实例1天产生的监控数据量约为16GB。Pigsty默认保留两周的监控数据，可以通过参数调整。

是否可以监控已有的PG实例？

对于非Pigsty供给方案创建的外部数据库，可以使用仅监控模式部署，详情请参考文档。

如果该实例可以被Pigsty管理，您可以考虑采用与标准部署相同的方式，在目标节点上部署 node_exporter,pg_exporter, promtail 等组件。

如果您只有访问该数据库的URL（例如RDS云数据库实例），则可以使用 精简监控部署 模式，在该模式下，Pigsty会通过部署于元节点本地的 pg_exporter 实例监控远程PG实例。

监控已有PG实例需要怎么做？

监控对象被移除后为什么还能看到

INFRA

基础设施包括哪些组件？

Ansible/Pigsty CLI用于发起管理与部署；元节点上的PostgreSQL作为CMDB；Consul Server作为元数据库用于高可用；NTPD与DNS提供时间与域名解析基础服务；Docker作为无状态应用部署底座；Prometheus用于监控指标时序数据收集，Loki用于日志收集；Grafana用于监控/可视化展示，AlertManager用于汇总告警；YumRepo用于提供本地软件源；Nginx对外收拢所有WebUI类服务访问入口。

是否可以使用已有的DCS集群

在 dcs_servers中填入对应的集群，即可使用外部的DCS集群。

DCS Server与元节点并没有对应关系：在默认情况下，Pigsty会在元节点上安装一个单节点的Consul Server。如果在执行节点初始化时当前节点的IP地址在 dcs_servers 中被定义，则该节点会配置DCS Server服务。DCS用于其他数据库实例的高可用选主。在生产环境中，建议使用3～5个节点的专用外部DCS集群。

NODES

Abort because consul instance already exists

当目标节点的Consul服务已经存在时，nodes.yml 会根据 dcs_clean 参数采取行动，如果为真，那么在初始化过程中现有的Consul会被抹除。

Pigsty也提供了相应的保护机制 参数： dcs_safeguard

您可以在配置文件 pigsty.yml 中修改这些参数，也可以直接在执行剧本时，通过额外参数机制指定：

./nodes.yml -e dcs_clean=true

PGSQL

Abort because postgres instance already exists

当目标节点的PostgreSQL服务已经存在时，pgsql.yml 会根据 pg_clean 参数采取行动，如果为真，那么在初始化过程中现有的PostgreSQL实例会被抹除。

Pigsty也提供了相应的保护机制 参数： pg_safeguard

您可以在配置文件 pigsty.yml 中修改这些参数，也可以直接在执行剧本时，通过额外参数机制指定：

./pgsql.yml -e pg_clean=true

PostgreSQL数据库如何保证高可用

Pigsty使用Patroni代管Postgres，Patroni使用Consul达成领导者共识，当主库故障超过阈值后（30秒），会触发新一轮领导者选举，获胜者成为新的集群主库，所有其他从库追随新的集群主库，原有故障主库上线后会自动降级为从库并追随新主库。

客户端使用HAProxy服务接入数据库，HAproxy使用HTTP健康检查从Patroni处获取主从角色信息，并依此分发流量。Pigsty的数据库集群成员在使用上幂等，只要集群还有任意一个实例存活，读写与只读流量都可以继续工作，访问任意一个实例的5433端口，都可以确保访问集群主库读写服务。

DCS自身的可用性通过多节点共识保证，故生产环境中建议部署3个或更多元节点，或使用外部的DCS集群。

如何确保PostgreSQL集群故障不丢数据

Crit模板针对数据一致性和持久性而优化，默认启用同步提交与数据校验和。可以确保在故障切换时没有任何数据损失，并能及时检测上报因存储故障、断电等其他异常情况导致的静默数据腐坏。

数据损坏导致拖从库失败

Pigsty默认为PGSQL集群中的所有成员都启用 cloneform: true 功能，即，制作从库时可以从该实例上拖取基础备份。如果某个实例因为数据文件损坏无法完成从库制作，那么您可以修改该实例上的Patroni配置文件，将clonefrom设置为false，以避免从损坏的实例上拉取数据。

5 - 概念导览

Index

Glossary

节点

Node

元节点

Meta

源码包

Source Package

离线软件包

Offline Software Package

沙箱

Sandbox

生产环境

Production Environment/Prod Env

单节点模式

Singleton Meta

集群管理模式

Cluster Manage

数据库集群

Database Cluster

沙箱

Sandbox

置备

Provisioning

管理用户

Admin Uesr

管理用户置备

Admin Provisioning

软件置备

Software Provisioning

配置过程

Configure

配置清单

Inventory

配置项

Config Entry

集群

Cluster

实例

Instance

服务

Service

水平分片集群

Sharding Cluster

剧本

Playbook

部署

Deploy/Deployment

主库

Primary

从库

Replica

同步从库

Standby

离线从库

Offline

延迟从库

Delayed

热备份

Hot Standby

冷备份

Cold Standby

恢复

Restore

告警

Alert/Alerting

指标

Metric/Metrics

面板

Dashboard

仪表盘

Panel

监控目标

Monitor Target

仅监控模式

Monly

身份

Identity

身份参数

Identity Parameter

健康检查

HealthCheck

服务发行

Service Discovery

Redis标准主从

Standalone

Redis原生集群

Native Cluster

Redis哨兵

Redis Sentinel

6 - 架构

Pigsty在逻辑由几个独立模块组成，可以根据不同的场景自由排列组合。

模块

Pigsty目前提供四个功能模块：

• INFRA 是Pigsty的基础设施部分，包括监控/告警/可视化/日志/DNS/NTP等公共组件。
• NODES 是主机节点管理模块，用于配置节点，安装软件，收集监控指标与日志。
• PGSQL 是PostgreSQL数据库部署管控模块，包括各种类型的PG集群部署与监控。
• REDIS 是Redis数据库部署管控模块，包括Redis 主从/集群/哨兵部署与监控

用法

您可以自行选择在哪些节点上启用哪些模块，适配不同的需求场景。

默认情况下，Pigsty将执行单机安装，将当前节点初始化为一个加装了 INFRA，NODES，与PGSQL的元节点。

您可以进一步加入其他节点，并在其上加装不同的数据库模块。

单机部署

如果您想将Pigsty当作开箱即用的单机PostgreSQL发行版来使用，那么在一台机器上依次安装 INFRA, NODES, PGSQL 三个模块，就会有一个立即可用的，自我监控管理的数据库实例。

执行 infra.yml 剧本在单机上安装Pigsty，在该节点上部署基础设施 ，并拉起一个单节点PostgreSQL数据库集群。个人用户、简单场景、小微企业可以直接开箱使用此数据库。完整安装Pigsty的节点称为元节点（Meta）。

但Pigsty的能力不只于此，它还可以用于监控管理更多的节点与数据库。

主机监控

如果您想要一个生产环境的大规模主机监控系统，那么在一台机器上安装INFRA模块，在所有被监控的机器节点上安装NODES模块即可。所有的主机节点会配置有软件源，软件包，DNS，NTP，节点监控，日志收集，DCS Agent这些生产环境所需的组件。纳入Pigsty管理的主机节点会带有详细的监控信息，并可以用于进一步部署各式各样的数据库模块。

在元节点上通过 nodes.yml 剧本为更多节点加装NODES模块，纳入Pigsty管理中。

数据库集群

当您将节点纳入Pigsty后，这些节点可以用于进一步部署各种数据库集群。

如果您想部署管理大量的PostgreSQL集群，在这些纳入Pigsty管理的节点上再加装 **PGSQL **模块即可。您可以一键部署各种各样的PGSQL集群：单实例，一主N从的高可用集群，同步集群，法定人数提交的同步集群，带有离线ETL角色的集群，异地容灾的备集群，延迟复制集群，Citus分布式集群，TimescaleDB集群，MatrixDB数据仓库集群。

如果你想部署并监控管理很多Redis集群，也只要在Pigsty托管的节点上加装REDIS模块即可。

使用 pgsql.yml 创建高可用的PostgreSQL数据库集群，使用 redis.yml创建主从、集群、哨兵模式的Redis集簇，使用 pgsql-matrixdb.yml 部署 Greenplum/MatrixDB 数据仓库。

Pigsty后续会按需逐步添加新类型的数据库功能模块：KAFKA, MINIO, MONGO等。

模型

一套完整的Pigsty系统，可称为一个部署（Deployment）/ 环境（Environment） 。

例如：生产环境，测试环境，预发环境等。

一套Pigsty部署在架构上分为两个部分：一套基础设施，与多套集群，两者均通过一份配置清单（Inventory）进行描述。

• 基础设施（Infra） ：部署于元节点上，监控，DNS，NTP，DCS，Yum源等。
• 集群：自治的（数据库）服务单元，部署于节点上。

集群包含有节点，实例，服务三种核心资源：一个集群会包含多个实例，部署于多个 节点（Node）上，提供多种不同的 服务（Service），每个数据库实例之下又会有更细分的ER模型。

7 - 基础设施

Pigsty提供了一套完整的，开箱即用的PaaS基础设施。

每一套 Pigsty 部署（Deployment） 中，都需要有一些基础设施，才能使整个系统正常工作。基础设施通常由专业的运维团队或云厂商负责，但Pigsty作为一个开箱即用的PaaS解决方案，将基本的基础设施集成至供给方案中。

概览

Pigsty会在元节点（默认为当前安装的节点）上部署一套完整的基础设施，包括：

基础设施部署于 元节点 上。一套环境中包含一个或多个元节点，用于基础设施部署。除了 分布式配置存储（DCS） 之外，所有基础设施组件都采用副本式部署。

Nginx

Nginx是Pigsty所有WebUI类服务的访问入口，默认使用管理节点80端口。

有许多带有WebUI的基础设施组件通过Nginx对外暴露服务，例如Grafana，Prometheus，AlertManager，Consul，以及HAProxy流量管理页等。 此外，YumRepo，文档，执行计划可视化器等静态文件资源也通过Nginx对外提供服务。

Nginx会根据 nginx_upstream 的内容，通过域名的方式，将访问请求转发至对应的上游组件处理。 Pigsty强烈建议使用域名访问Pigsty UI系统，而不是直接通过IP+端口的方式访问，基于以下几个理由：

• 一些组件默认只监听 127.0.0.1 ，因此只能通过Nginx代理访问
• 通过域名访问可以将访问收拢至Nginx，审计一切请求，并方便地集成认证机制。
• 域名更容易记忆，并提供了配置灵活性。

如果您没有可用的互联网域名或本地DNS解析，您可以在 /etc/hosts或C:\Windows\System32\drivers\etc\hosts中添加本地静态解析记录。

Nginx相关配置参数位于：配置：INFRA - NGINX

Yum Repo

Pigsty会在安装时首先建立一个本地Yum软件源，以加速后续软件安装。

该Yum源由Nginx提供服务，默认位于为 /www/pigsty，可以访问 http://yum.pigsty/pigsty 获取。Pigsty的离线软件包即是将已经建立好的Yum Repo目录整个打成压缩包。

当Pigsty尝试构建本地源时，如果发现本地源目录 /www/pigsty 已经存在，且带有 /www/pigsty/repo_complete 标记文件，则会认为本地源已经构建完成，从而跳过从原始上游下载软件的步骤，消除了对互联网访问的依赖。

Repo文件位于 /www/pigsty.repo，默认可以通过http://yum.pigsty/pigsty.repo 获取

curl http://yum.pigsty/pigsty.repo -o /etc/yum.repos.d/pigsty.repo

您也可以在没有Nginx的情况下直接使用文件本地源：

[pigsty-local]
name=Pigsty local $releasever - $basearch
baseurl=file:///www/pigsty/
enabled=1
gpgcheck=0

Yum Repo相关配置参数位于：配置：INFRA - REPO

Grafana

Grafana是开源的可视化/监控平台，是Pigsty WebUI的核心，默认监听3000端口，可以直接通过IP:3000或域名http://g.pigsty访问。

Pigsty的监控系统基于Dashboard构建，通过URL进行连接与跳转。您可以快速地在监控中下钻上卷，快速定位故障与问题。

此外，Grafana还可以用作通用的低代码前后端平台，制作交互式可视化数据应用。因此，Pigsty使用的Grafana带有一些额外的可视化插件，例如ECharts面板。

Grafana相关配置参数位于：配置：INFRA - GRAFANA

AlertManager

AlertManager是与Prometheus配套的告警平台，默认监听9093端口，可以直接通过IP:9093或域名http://a.pigsty访问。

Prometheus的告警事件会发送至AlertManager，但如果需要进一步处理，用户需要进一步对其进行配置，例如提供SMTP服务配置以发送告警邮件。

Prometheus

Prometheus是监控时序数据库，默认监听9090端口，可以直接通过IP:9090或域名http://p.pigsty访问。

Prometheus是监控用时序数据库。

• Prometheus默认通过本地静态文件服务发现获取监控对象，并为其关联身份信息。
• Prometheus可以选择使用Consul服务发现，自动获取监控对象。
• Prometheus从Exporter拉取监控指标数据，进行预计算加工后存入自己的TSDB中。
• Prometheus计算报警规则，将报警事件发往Alertmanager处理。

Prometheus相关配置参数位于：配置：INFRA - PROMETHEUS

Loki

Prometheus是监控时序数据库，默认监听3100端口。

Loki是用于日志收集的日志数据库，节点上的Promtail向元节点上的Loki推送日志。

LOKI相关配置参数位于：配置：INFRA - LOKI

Consul

Consul Server用于保存DCS的状态，达成共识，提供元数据查询服务，亦提供基于DCS的服务发现。

Consul相关配置参数位于：配置：INFRA - DCS

Docker

Pigsty默认在元节点上安装Docker，您可以拉起各式各样的无状态应用，并使用外部数据库获得生产级的持久性。Docker相关配置参数位于：配置：INFRA - DOCKER

PostgreSQL

PostgreSQL相关配置参数位于：配置：PGSQL，使用CMDB作为配置源，请参考CMDB教程。

• 用于支持各种高级功能的MetaDB（亦是一个标准的数据库集群，由Ansible拉起）

• 用于执行剧本，发起控制的Ansible，使用动态Inventory时会访问CMDB

• 定时任务控制器（支持备份，清理，统计，巡检，等特性），会访问CMDB

Ansible

Pigsty默认会在元节点上安装Ansible，Ansible是一个流行的运维工具，采用声明式的配置风格与幂等的剧本设计，可以极大降低系统维护的复杂度。命令行工具 pigsty-cli 会调用Ansible Playbook发起管控

Ansible相关配置参数位于：配置：INFRA - CONNECT

Dnsmasq

Dnsmasq提供环境内的DNS解析服务（可选）

• DNS服务为可选，可使用已有DNS服务器
• 部分DNS解析将转交由Consul DNS进行

DNSMASQ相关配置参数位于：配置：INFRA - Nameserver

NTP

NTP服务用于同步环境内所有节点的时间（可选）

NTP相关配置参数位于：配置：NODES - NTP

Demo

Pigsty 提供了一个公开演示的demo，地址为： http://demo.pigsty.cc

因为演示实例为1核1GB的空虚拟机空实例，故显示内容较为单薄，请以实际效果为准。

8 - 概念：节点

Pigsty使用节点（Node）进行安装与部署，节点可以是物理机，虚拟机，甚至Pod。

在Pigsty中有两种节点：元节点 与（普通）节点。

元节点用于发起管理，普通节点是纳入Pigsty管理的节点。

• 元节点（Meta）：执行 infra.yml 剧本安装Pigsty，安装 INFRA，NODES，PGSQL 三个模块。
• 节点（Node）：通过 nodes.yml 剧本纳入管理的普通节点，默认安装 NODES 模块。

元节点

元节点即完整安装Pigsty，带有管理功能的节点，部署有完整的基础设施组件。

当您在某节点上执行 ./configure 时，当前节点会被默认作为元节点，填入配置文件 meta 分组中。

在每套环境中，Pigsty最少需要一个元节点，该节点将作为整个环境的控制中心。元节点负责各种管理工作：保存状态，管理配置，发起任务，收集指标，等等。整个环境的基础设施组件，Nginx，Grafana，Prometheus，Alertmanager，NTP，DNS Nameserver，DCS都将部署在元节点上。

复用元节点

元节点亦可复用为普通数据库节点，在元节点上默认运行有名为 pg-meta 的PostgreSQL数据库集群。提供额外的扩展功能：CMDB，巡检报告，扩展应用，日志分析，数据分析与处理等

以Pigsty附带的四节点沙箱环境为例，组件在节点上的分布如下图所示：

沙箱由一个元节点与四个普通节点组成，这里元节点也被复用为一个普通节点。沙箱内部署有一套基础设施与两套数据库集群。 meta 为元节点，部署有基础设施组件，同时被复用为普通数据库节点，部署有单主数据库集群pg-meta。 node-1，node-2，node-3 为普通数据库节点，部署有数据库集群pg-test。

元节点上的服务

元节点上默认运行的服务如下所示：

元节点与DCS

默认情况下，元节点上将部署元数据库 （Consul 或 Etcd），用户也可以使用已有的外部DCS集群。如果将DCS部署至元节点上，建议在生产环境使用3个元节点，以充分保证DCS服务的可用性。DCS外的基础设施组件都将以对等副本的方式部署在所有元节点上。元节点的数量要求最少1个，推荐3个，建议不超过5个。

使用多个元节点

复数个元节点是可能的，通常一个元节点足矣，两个元节点可以互为备份，三个元节点自身便足以部署生产级DCS Server集群。

本着开箱即用的原则，Pigsty默认在所有元节点上部署DCS Server。但如果单纯是为了追求DCS Server集群的高可用而使用超过3个管理节点并没有太大的意义。您可以使用一个外部维护管理的，3～5节点的DCS集群来保证DCS服务可用性。

元节点的特征是节点地址配置于配置文件的 all.children.meta.host 分组中，带有meta_node: true 标记。在 configure 过程中，执行安装的当前节点会被配置为元节点，复数个元节点则需要手工配置，可参考三管理节点样例配置文件： pigsty-dcs3.yml。

如果您没有使用任何外部DCS集群服务作为仲裁者，那么有意义的高可用最少需要3个节点。如果您只有两个节点，建议主库故障时人工介入以避免脑裂出现。

节点

您可以使用Pigsty管理更多的节点，并使用这些节点部署数据库。

纳入Pigsty管理的节点会被 nodes.yml 调整至 配置：NODES 所描述的状态，加装节点监控与日志收集组件，您可以从监控系统中查阅节点状态与日志。被Pigsty管理的节点可以进一步用于部署各种数据库，或您自己的应用。

节点身份

每个节点都有身份参数，通过在<cluster>.hosts与<cluster>.vars中的相关参数进行配置。

在Pigsty中，节点有两个重要的身份参数： nodename 与 node_cluster，这两者将在监控系统中用作节点的 实例标识（ins） 与 集群标识 （cls）。nodename 与 node_cluster 并不是必选参数，当留白或置空时，nodename 会使用节点当前的主机名，而 node_cluster 则会使用固定的默认值：nodes。

此外，Pigsty还会使用IP地址作为数据库节点的唯一标识， IP地址即配置清单中主机的inventory_hostname ，体现为<cluster>.hosts对象中的key。尽管一个节点可能有多块网卡和多个IP地址，但您必须指定一个首要IP地址作为节点唯一标识。该地址应当为内网地址，即您访问该节点上的数据库时使用那个IP地址。

该IP地址并不一定是管理节点SSH访问使用的IP地址，您可以通过 Ansible Connect 相关参数，通过SSH隧道或跳板机中转的方式间接操作管理目标节点。

以下集群配置声明了一个三节点集群：

node-test:
  hosts:
    10.10.10.11: { nodename: node-test-1 }
    10.10.10.12: { pg_hostname: true } # 从PG借用身份 pg-test-2
    10.10.10.13: {  } # 不显式指定nodename，则使用原有hostname: node-3
  vars:
    node_cluster: node-test

在监控系统中，相关的时序监控数据标签为：

node_load1{cls="pg-meta", ins="pg-meta-1", ip="10.10.10.10", job="nodes"}
node_load1{cls="pg-test", ins="pg-test-1", ip="10.10.10.11", job="nodes"}
node_load1{cls="pg-test", ins="pg-test-2", ip="10.10.10.12", job="nodes"}
node_load1{cls="pg-test", ins="pg-test-3", ip="10.10.10.13", job="nodes"}

节点默认服务

PGSQL节点服务

PGSQL节点是用于部署PostgreSQL集群的节点， 在标准节点上额外加装了 PGSQL 模块。

在执行默认的PostgreSQL部署时，因为Pigsty默认采用节点独占1:1部署，因此可以通过 pg_hostname 参数，将数据库实例的身份参数（pg_cluster 与 pg_instance）借用至节点的 nodename 与 node_cluster 身份参数上。

除了 节点默认服务) 外，PGSQL节点上运行有下列服务：

节点交互

以单个 元节点 和 单个 节点 构成的环境为例，架构如下图所示：

元节点与数据库节点之间的交互主要包括：

• 数据库集群/节点的域名依赖元节点的Nameserver进行解析 （可选）。

• 数据库节点软件安装需要用到元节点上的Yum Repo。

• 数据库集群/节点的监控指标会被元节点的Prometheus收集。

• 数据库的日志会被Promtail收集并发往Loki。

• Pigsty会从元节点上发起对数据库节点的管理:

  • 执行集群创建，扩缩容，实例/集群回收
  • 创建业务用户、业务数据库、修改服务、HBA修改；
  • 执行日志采集、垃圾清理，备份，巡检等

• 数据库节点的Consul会向元节点的DCS同步本地注册的服务，并代理状态读写操作。

• 数据库节点会从元节点（或其他NTP服务器）同步时间l

9 - PGSQL 概念

介绍 PostgreSQL 数据库集群管理所需的核心概念

• PGSQL集群 / 实体模型 / 身份参数

• 集群 / 实例 / 节点 / 服务

• PostgreSQL高可用

• 部署：PGSQL ｜配置：PGSQL | 剧本：PGSQL ｜ 定制：PGSQL

• PGSQL服务 与 PGSQL接入

• PGSQL权限 与 PGSQL认证

• PGSQL业务用户 与 PGSQL业务数据库

PGSQL集群

生产环境的PGSQL数据库以集群为单位进行组织，集群是一个由主从复制所关联的一组数据库实例所构成的逻辑实体。每个数据库集群是一个自组织的业务服务单元，由至少一个数据库实例组成。

沙箱环境

集群是基本的业务服务单元，下图展示了沙箱环境中的复制拓扑。其中pg-meta-1单独构成一个数据库集群pg-meta，而pg-test-1，pg-test-2，pg-test-3共同构成另一个逻辑集群pg-test。

pg-meta-1
(primary)

pg-test-1 -------------> pg-test-2
(primary)      |         (replica)
               |
               ^-------> pg-test-3
                         (replica)

高可用

主库故障RTO ≈ 30s~1min，RPO < 10MB，从库故障RTO≈0（仅故障实例连接中断）

Pigsty默认创建创建高可用PostgreSQL数据库集群。只要集群中有任意实例存活，集群就可以对外提供完整的读写服务与只读服务。Pigsty可以自动进行故障切换，业务方只读流量不受影响；读写流量的影响视具体配置与负载，通常在几秒到几十秒的范围。

默认情况下， Pigsty部署的集群采用 可用性优先 模式，主库宕机时，未及时复制至从库部分的数据可能会丢失（正常约几百KB，不超过10MB），您可以参考 同步从库 的说明，使用 一致性优先 模式，此模式下 RPO = 0 。

Pigsty的高可用使用 Patroni + HAProxy实现，前者负责故障切换，后者负责流量切换。Patroni会利用DCS服务进行心跳保活，集群主库默认会注册一个时长为15秒的租约并定期续租。当主库故障无法续租时，租约释放，触发新一轮集群选举。通常，复制延迟最小者（数据损失最小化）会被选举为新的集群领导者。集群进入新的时间线，包括旧主库在内的其他成员都会重新追随新的领导者。

Pigsty提供了多种流量接入方式，如果您使用默认的HAProxy接入，则无需担心集群故障切换对业务流量产生影响。HAProxy会自动检测集群中的实例状态，并正确分发流量。例如，5433端口上的 Primary服务，会使用HTTP GET ip:8008/primary 健康检查，从集群中所有的Patroni处获取信息，找出集群主库，并将流量分发至主库上。HAProxy本身是无状态的，均匀部署在每个节点/实例上。任意或所有HAProxy都可以作为集群的服务接入点。

组件交互

在单个数据库节点/实例上，各组件通过以下联系相互配合：

• vip-manager通过查询Consul获取集群主库信息，将集群专用L2 VIP绑定至主库节点（默认沙箱接入方案）。
• Haproxy是数据库流量入口，用于对外暴露服务，使用不同端口（543x）区分不同的服务。
  • Haproxy的9101端口暴露Haproxy的内部监控指标，同时提供Admin界面控制流量。
  • Haproxy 5433端口默认指向集群主库连接池6432端口
  • Haproxy 5434端口默认指向集群从库连接池6432端口
  • Haproxy 5436端口默认直接指向集群主库5432端口
  • Haproxy 5438端口默认直接指向集群离线实例5432端口
• Pgbouncer用于池化数据库连接，缓冲故障冲击，暴露额外指标。
  • 生产服务（高频非交互，5433/5434）必须通过Pgbouncer访问。
  • 直连服务（管理与ETL，5436/5438）必须绕开Pgbouncer直连。
• Postgres提供实际数据库服务，通过流复制构成主从数据库集群。
• Patroni用于监管Postgres服务，负责主从选举与切换，健康检查，配置管理。
  • Patroni使用Consul达成共识，作为集群领导者选举的依据。
• Consul Agent用于下发配置，接受服务注册，服务发现，提供DNS查询。
  • 所有使用端口的进程服务都会注册至Consul中
• PGB Exporter，PG Exporter， Node Exporter分别用于暴露数据库，连接池，节点的监控指标
• Promtail是日志收集组件，用于向基础设施Loki发送采集到的PG，PGB，Patroni与节点日志

实体模型

在Pigsty中，PostgreSQL有四类核心实体：

• PGSQL集群 （Cluster），以下简称为集群
• PGSQL服务 （Service），以下简称为服务
• PGSQL实例 （Instance） ，以下简称为实例
• PGSQL节点 （Node） ，以下简称为节点

实体说明

• 集群（Cluster） 是基本自治单元，由用户指定唯一标识，表达业务含义，作为顶层命名空间。
• 集群在硬件层面上包含一系列的节点（Node），即物理机，虚机（或Pod），可以通过IP唯一标识。
• 集群在软件层面上包含一系列的实例（Instance），即软件服务器，可以通过IP:Port唯一标识。
• 集群在服务层面上包含一系列的服务（Service），即可访问的域名与端点，可以通过域名唯一标识。

实体命名规则

• 集群的命名可以使用任意满足DNS域名规范的名称，不能带点（[a-zA-Z0-9-]+）。
• 节点命名采用集群名称作为前缀，后接-，再接一个整数序号（建议从0开始分配，与k8s保持一致）
• PGSQL采用独占式部署，节点与实例一一对应，因此实例命名可与节点命名一致，即${cluster}-${seq}的方式。
• 服务命名亦采用集群名称作为前缀，后接-连接服务具体内容，如primary, replica,offline,standby等。

以沙箱环境的测试数据库集群 pg-test 为例：

• 一个集群：用于测试的数据库集群名为“pg-test”
• 两种角色：primary 与 replica，分别是集群主库与从库。
• 三个实例：集群由三个数据库实例：pg-test-1, pg-test-2, pg-test-3组成
• 三个节点：集群部署在三个节点上：10.10.10.11, 10.10.10.12, 10.10.10.13上。
• 四个服务：
  • 读写服务： pg-test-primary
  • 只读服务： pg-test-replica
  • 直连管理服务： pg-test-default
  • 离线查询服务： pg-test-offline

身份参数

实体与标识符是一种概念模型，下面介绍Pigsty中的具体实现。

pg_cluster，pg_role，pg_seq 属于 身份参数 ，用于生成实体标识。

除IP地址外，这三个参数是定义一套新的数据库集群的最小必须参数集

• 集群标识：pg_cluster ： {{ pg_cluster }}
• 实例标识：pg_instance ： {{ pg_cluster }}-{{ pg_seq }}
• 服务标识：pg_service ：{{ pg_cluster }}-{{ pg_role }}
• 节点标识：nodename：
  • 若 pg_hostname: true: 使用与 pg_instance相同的：{{ pg_cluster }}-{{ pg_seq }}
  • 若 pg_hostname: false: 显式指定{{ nodename }}则直接使用，否则使用现有主机名。

下面是沙箱环境中 pg-test 集群的定义样例：

pg-test:
  hosts:
    10.10.10.11: {pg_seq: 1, pg_role: replica}
    10.10.10.12: {pg_seq: 2, pg_role: primary}
    10.10.10.13: {pg_seq: 3, pg_role: replica}
  vars:
    pg_cluster: pg-test
    pg_hostname: true     # 使用1:1 PG实例的身份作为节点的身份

因此，该集群三个成员的身份标识如下：

在监控系统中，相关的时序监控数据标签为：

pg_up{cls="pg-meta", ins="pg-meta-1", ip="10.10.10.10", job="pgsql"}
pg_up{cls="pg-test", ins="pg-test-1", ip="10.10.10.11", job="pgsql"}
pg_up{cls="pg-test", ins="pg-test-2", ip="10.10.10.12", job="pgsql"}
pg_up{cls="pg-test", ins="pg-test-3", ip="10.10.10.13", job="pgsql"}

集群（Cluster）

集群是基本的自治业务单元，这意味着集群能够作为一个整体组织对外提供服务。类似于k8s中Deployment的概念。注意这里的集群是软件层面的概念，不要与PG Cluster（数据库集簇，即包含多个PG Database的单个PG实例的数据目录）或Node Cluster（机器集群）混淆。

集群是管理的基本单位之一，是用于统合各类资源的组织单位。例如一个PG集群可能包括：

• 三个物理机器节点
• 一个主库实例，对外提供数据库读写服务。
• 两个从库实例，对外提供数据库只读副本服务。
• 两个对外暴露的服务：读写服务，只读副本服务。

集群命名规则

每个集群都有用户根据业务需求定义的唯一标识符，本例中定义了一个名为pg-test的数据库集群。

集群名称，其实类似于命名空间的作用。所有隶属本集群的资源，都会使用该命名空间。

集群标识符（cls）必须在一套环境中唯一，建议采用符合DNS标准 RFC1034 命名规则的标识符。

良好的集群名称应当仅使用小写字母，数字，以及 减号连字符（hyphen）-，且只使用字母启头。这样集群中所有对象都可以该标识符作为自己标识符的前缀，严格约束的标识符可以应用于更广泛地场景。

cluster_name := [a-z][a-z0-9-]*

集群命名中不应该包括点（dot）.，之所以强调不要在集群名称中用点，是因为有一种流行的命名方式便是采用点号分隔的层次标识符，例如com.foo.bar。这种命名方式虽然简洁名快，但用户给出的名字中域名层次数目不可控。如果集群需要与外部系统交互，而外部系统对于命名有约束，这样的名字就会带来麻烦。最直观的例子是Kubernetes中的Pod，Pod的命名规则中不允许出现.。

集群命名的内涵，建议采用-分隔的两段式，三段式名称，例如：

<集群类型>-<业务>-<业务线>

典型的集群名称包括：pg-meta, pg-test-fin, pg-infrastructure-biz

实例（Instance）

实例指带一个具体的数据库服务器，它可以是单个进程，也可能是共享命运的一组进程，也可以是一个Pod中几个紧密关联的容器。实例的关键要素在于：

• 可以通过实例标识（ins）符唯一标识
• 具有处理请求的能力（而不管接收请求的究竟是数据库，还是连接池或负载均衡器）

例如，我们可以把一个Postgres进程，为之服务的独占Pgbouncer连接池，PgExporter监控组件，高可用组件，管理Agent看作一个提供服务的整体，视为一个数据库实例，使用同样的标识符指称。

实例命名规则

实例隶属于集群，每个实例在集群范围内都有着自己的唯一标识用于区分。实例标识符ins建议采用与Kubernetes Pod一致的命名规则：即集群名称连以从0/1开始递增分配的整数序号<cls>-<seq>。

Pigsty默认使用从1开始的自增序列号依次为集群中的新数据库实例命名，例如，数据库集群pg-test有三个数据库实例，那么这三个实例就可以依次命名为：pg-test-1, pg-test-2和pg-test-3。

实例名ins一旦分配即不可变，该实例将在整个集群的生命周期中使用此标识符。

此外，采用独占节点部署模式时，数据库实例与机器节点可以互相使用对方的标识符。即我们也可用数据库实例标识ins来唯一指称一个机器节点。

节点（Node）

节点是对硬件资源的一种抽象，通常指代一台工作机器，无论是物理机（bare metal）还是虚拟机（vm），或者是Kubernetes 中的Pod。

节点的关键特征是：

• 节点是硬件资源的抽象，可以运行软件服务，部署数据库实例
• 节点可以使用IP地址作为唯一标识符

节点命名规则

Pigsty使用 ip 地址作为节点唯一标识符，如果机器有多个IP地址，则以配置清单中指定的，实际访问使用的IP地址为准。为便于管理，节点应当拥有一个人类可读的充满意义的名称作为节点的主机名。主机名nodename，数据库实例标识ins，节点标识ip 三者在Pigsty中彼此一一对应，可交叉混用做数据库实例、机器节点、HAProxy负载均衡器的标识符。

节点的命名与数据库实例一致，在整个集群的生命周期中保持不变，便于监控与管理。

服务（Service）

服务 是对软件服务（例如Postgres，Redis）的一种命名抽象（named abstraction）。服务可以有各种各样的实现，但其的关键要素在于：

• 可以寻址访问的服务名称，用于对外提供接入，例如：
  • 一个DNS域名（pg-test-primary）
  • 一个Nginx/Haproxy Port
• 服务流量路由解析与负载均衡机制，用于决定哪个实例负责处理请求，例如：
  • DNS L7：DNS解析记录
  • HTTP Proxy： Nginx/Ingress L7：Nginx Upstream配置
  • TCP Proxy： Haproxy L4：Haproxy Backend配置
  • Kubernetes：Ingress： Pod Selector。
  • 服务也需要决定由哪个组件来处理请求：连接池，或是数据库本身。

更多关于服务的介绍，请参考服务一章。

服务命名规则

服务标识 (svc) 由两部分组成：作为命名空间的 cls， 与服务承载的角色（role）

在PostgreSQL数据库集群中，实例可能有不同的身份：集群领导者（主库），普通从库，同步从库，离线从库，延迟从库，不同的实例可能会提供不同的服务；同时直连数据库与通过连接池中间件访问数据库也属于性质不同的服务。通常我们会使用服务目标实例的身份角色来标识服务，例如在数据库集群pg-test中：

• 指向 主库连接池（primary）角色实例的服务，叫做pg-test-primary
• 指向 从库连接池（replica）角色实例的服务，叫做pg-test-replica
• 指向 离线从库数据库（offline）的服务，叫做pg-test-offline
• 指向 同步复制从库（standby）的服务，叫做pg-test-standby

请注意，服务并不够成对实例的划分，同一个服务可以指向集群内多个不同的实例，然而同一个实例也可以承接来自不同服务的请求。例如，角色为 standby的同步从库既可以承接来自 pg-test-standby 的同步读取请求，也可以承接来自 pg-test-replica 的普通读取请求。

10 - Redis 概念

介绍 Redis 数据库集群管理所需的核心概念

部署：Redis ｜配置：Redis | 剧本：Redis

实体概念模型

Redis的实体概念模型与PostgreSQL几乎相同，同样包括 集群（Cluster） 与 实例（Instance） 的概念。注意这里的Cluster概念指的不是 Redis原生集群方案中的集群。

核心的区别在于，Redis通常采用单机多实例部署，一个物理/虚拟机节点上通常会部署多个 Redis实例，以充分利用多核CPU。因此，定义Redis实例的方式与PGSQL稍有不同。

在Pigsty管理的Redis中，节点完全隶属于集群，即目前尚不允许在一个节点上部署两个不同集群的Redis实例，但这并不影响您在在一个节点上部署多个独立Redis实例。

Redis身份参数

身份参数是定义Redis集群时必须提供的信息，包括：

• redis_cluster 标识了Redis集群的名称，在集群层面进行配置，作为集群资源的顶层命名空间。
• redis_node 标识了节点在集群中的序号
• redis_instances 是一个JSON对象，Key为实例端口号，Value为一个JSON对象，包含实例特殊的配置

11 - PGSQL服务与接入

如何定义PostgreSQL服务，并通过负载均衡与连接池实现稳定可靠高性能的接入

单机用户无需关注服务与接入的概念，这是针对在生产环境中使用高可用PostgreSQL数据库集群所提出的概念。

单机用户

完成单机部署后，该节点的5432端口对外提供PostgreSQL数据库服务，80端口对外提供UI类服务。

在当前元节点上，使用管理用户无参数执行 psql 可以直接连接到本机预定义的 meta 数据库，开箱即用。

从外部（宿主机）使用客户端工具访问PG时，可以使用以下URL：

psql postgres://dbuser_dba:[email protected]/meta         # 默认超级用户 直连
psql postgres://dbuser_meta:[email protected]/meta       # 默认业务用户 直连

您可以使用由 pg_admin_username 与 pg_admin_password 指定的管理员用户，或预先在meta数据库中定义的其他业务用户（dbuser_meta）访问该数据库。

在生产环境使用Pigsty部署的高可用数据库集群，强烈不建议使用IP直连的方式接入数据库服务。

服务

**服务（Service）**是数据库集群对外提供功能的形式。

在真实世界的生产环境中，我们会使用基于复制的主从数据库集群。集群中有且仅有一个实例作为领导者（主库），可以接受写入，而其他实例（从库）则会从持续从集群领导者获取变更日志，与领导者保持一致。同时从库还可以承载只读请求，对于读多写少的场景可以显著分担主库负载，因此区分集群的写入请求与只读请求是一个常规实践。

此外对于高频短连接的生产环境，我们还会通过连接池中间件（Pgbouncer）对请求进行池化，减少连接与后端进程的创建开销。但对于ETL与变更执行等场景，我们又需要绕过连接池，直接访问数据库。

此外，高可用集群在故障时会出现故障切换（Failover），故障切换会导致集群的领导者出现变更。因此高可用的数据库方案要求写入流量可以自动适配集群的领导者变化。

这些不同的访问需求（读写分离，池化与直连，故障切换自动适配）最终抽象为服务的概念。

通常来说，数据库集群必须提供一种服务：

• 读写服务（primary） ：可以写入数据库

对于生产数据库集群至少应当提供两种服务：

• 读写服务（primary） ：可以写入数据库
• 只读服务（replica） ：可以访问只读数据副本

此外，根据具体的业务场景，可能还会有其他的服务，例如：

• 离线从库服务（offline）：不承接线上只读流量的专用从库，用于ETL与个人查询
• 同步从库服务（standby） ：采用同步提交，没有复制延迟的只读服务
• 延迟从库服务（delayed） ： 允许业务访问固定时间间隔之前的旧数据
• 默认直连服务（default） ： 允许（管理）用户绕过连接池直接管理数据库的服务

默认服务

Pigsty默认对外提供四种服务：primary, replica, default, offline

您可以通过配置文件为全局或单个集群定义新的服务

以默认的元数据库pg-meta为例

psql postgres://dbuser_meta:DBUser.Meta@pg-meta:5433/meta     # 生产读写
psql postgres://dbuser_meta:DBUser.Meta@pg-meta:5434/meta     # 生产只读
psql postgres://dbuser_dba:DBUser.DBA@pg-meta:5436/meta       # 直连主库
psql postgres://dbuser_stats:DBUser.Stats@pg-meta:5438/meta   # 直连离线

下面将详细介绍这四种服务

Primary服务

Primary服务服务于线上生产读写访问，它将集群的5433端口，映射为 主库连接池（默认6432） 端口。

Primary服务选择集群中的所有实例作为其成员，但只有健康检查/primary为真者，才能实际承接流量。

在集群中有且仅有一个实例是主库，只有其健康检查为真。

# primary service will route {ip|name}:5433 to primary pgbouncer (5433->6432 rw)
- name: primary           # service name {{ pg_cluster }}-primary
  src_ip: "*"
  src_port: 5433
  dst_port: pgbouncer     # 5433 route to pgbouncer
  check_url: /primary     # primary health check, success when instance is primary
  selector: "[]"            # select all instance as primary service candidate

主库上的高可用组件Patroni针对Primary健康检查返回200，用于确保集群不会出现一个以上的主库实例。

当集群发生故障切换时，新主库的健康检查为真，老主库的健康检查为假，因此流量将迁移至新主库上。业务方会察觉到约30秒的 Primary服务 不可用时间。

Replica服务

Replica服务服务于线上生产只读访问，它将集群的5434端口，映射为 从库连接池（默认6432） 端口。

Replica服务选择集群中的所有实例作为其成员，但只有健康检查/read-only为真者，才能实际承接流量，该健康检查对所有可以承接只读流量的实例（包括主库）返回成功。所以集群中的任何成员都可以承载只读流量。

但默认情况下，只有从库承载只读请求，Replica服务定义了selector_backup，该选择器将集群的主库作为 备份实例 加入到Replica服务中。只要当Replica服务中所有其他实例，即所有从库宕机时，主库才会开始承接只读流量。

另一个作为备份实例的角色是offline角色，Offline实例通常专用于OLAP/ETL/个人交互式查询，不适合与在线查询混合，因此只有当集群中所有的replica宕机后，offline才会被用于承接只读流量。

# replica service will route {ip|name}:5434 to replica pgbouncer (5434->6432 ro)
- name: replica           # service name {{ pg_cluster }}-replica
  src_ip: "*"
  src_port: 5434
  dst_port: pgbouncer
  check_url: /read-only   # read-only health check. (including primary)
  selector: "[]"          # select all instance as replica service candidate
  selector_backup: "[? pg_role == `primary` || pg_role == `offline` ]"

Default服务

Default服务服务于线上主库直连，它将集群的5436端口，映射为主库Postgres端口（默认5432）。

Default服务针对交互式的读写访问，包括：执行管理命令，执行DDL变更，连接至主库执行DML，执行CDC。交互式的操作不应当通过连接池访问，因此Default服务将流量直接转发至Postgres，绕过了Pgbouncer。

Default服务与Primary服务类似，采用相同的配置选项。出于演示目显式填入了默认参数。

# default service will route {ip|name}:5436 to primary postgres (5436->5432 primary)
- name: default           # service's actual name is {{ pg_cluster }}-default
  src_ip: "*"             # service bind ip address, * for all, vip for cluster virtual ip address
  src_port: 5436          # bind port, mandatory
  dst_port: postgres      # target port: postgres|pgbouncer|port_number , pgbouncer(6432) by default
  check_method: http      # health check method: only http is available for now
  check_port: patroni     # health check port:  patroni|pg_exporter|port_number , patroni by default
  check_url: /primary     # health check url path, / as default
  check_code: 200         # health check http code, 200 as default
  selector: "[]"          # instance selector
  haproxy:                # haproxy specific fields
    maxconn: 3000         # default front-end connection
    balance: roundrobin   # load balance algorithm (roundrobin by default)
    default_server_options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

Offline服务

Offline服务用于离线访问与个人查询。它将集群的5438端口，映射为离线实例Postgres端口（默认5432）。

Offline服务针对交互式的只读访问，包括：ETL，离线大型分析查询，个人用户查询。交互式的操作不应当通过连接池访问，因此Default服务将流量直接转发至离线实例的Postgres，绕过了Pgbouncer。

离线实例指的是 pg_role 为 offline 或带有 pg_offline_query 标记的实例。离线实例外的其他其他从库将作为Offline的备份实例，这样当Offline实例宕机时，Offline服务仍然可以从其他从库获取服务。

# offline service will route {ip|name}:5438 to offline postgres (5438->5432 offline)
- name: offline           # service name {{ pg_cluster }}-offline
  src_ip: "*"
  src_port: 5438
  dst_port: postgres
  check_url: /replica     # offline MUST be a replica
  selector: "[? pg_role == `offline` || pg_offline_query ]"         # instances with pg_role == 'offline' or instance marked with 'pg_offline_query == true'
  selector_backup: "[? pg_role == `replica` && !pg_offline_query]"  # replica are used as backup server in offline service

自定义服务

在以上由 pg_services 配置的默认服务之外，用户可以使用相同的服务定义，在 pg_services_extra 配置项中为PostgreSQL数据库集群定义额外的服务。

一个集群都可以定义多个服务，每个服务包含任意数量的集群成员，服务通过端口进行区分。以下代码定义了一个新的服务standby，使用5435端口对外提供同步读取功能。该服务会从集群中的同步从库（或主库）进行读取，从而确保所有读取都不存在延迟。

# standby service will route {ip|name}:5435 to sync replica's pgbouncer (5435->6432 standby)
- name: standby                   # required, service name, the actual svc name will be prefixed with `pg_cluster`, e.g: pg-meta-standby
  src_ip: "*"                     # required, service bind ip address, `*` for all ip, `vip` for cluster `vip_address`
  src_port: 5435                  # required, service exposed port (work as kubernetes service node port mode)
  dst_port: postgres              # optional, destination port, postgres|pgbouncer|<port_number>   , pgbouncer(6432) by default
  check_method: http              # optional, health check method: http is the only available method for now
  check_port: patroni             # optional, health check port: patroni|pg_exporter|<port_number> , patroni(8008) by default
  check_url: /read-only?lag=0     # optional, health check url path, / by default
  check_code: 200                 # optional, health check expected http code, 200 by default
  selector: "[]"                  # required, JMESPath to filter inventory ()
  selector_backup: "[? pg_role == `primary`]"  # primary used as backup server for standby service (will not work because /sync for )
  haproxy:                        # optional, adhoc parameters for haproxy service provider (vip_l4 is another service provider)
    maxconn: 3000                 # optional, max allowed front-end connection
    balance: roundrobin           # optional, haproxy load balance algorithm (roundrobin by default, other: leastconn)
    default_server_options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

必选项目

• 名称（service.name）：

  服务名称，服务的完整名称以数据库集群名为前缀，以service.name为后缀，通过-连接。例如在pg-test集群中name=primary的服务，其完整服务名称为pg-test-primary。

• 端口（service.port）：

  在Pigsty中，服务默认采用NodePort的形式对外暴露，因此暴露端口为必选项。但如果使用外部负载均衡服务接入方案，您也可以通过其他的方式区分服务。

• 选择器（service.selector）：

  选择器指定了服务的实例成员，采用JMESPath的形式，从所有集群实例成员中筛选变量。默认的[]选择器会选取所有的集群成员。

可选项目

• 备份选择器（service.selector）：

  可选的 备份选择器service.selector_backup会选择或标记用于服务备份的实例列表，即集群中所有其他成员失效时，备份实例才接管服务。例如可以将primary实例加入replica服务的备选集中，当所有从库失效后主库依然可以承载集群的只读流量。

• 源端IP（service.src_ip） ：

  表示服务对外使用的IP地址，默认为*，即本机所有IP地址。使用vip则会使用vip_address变量取值，或者也可以填入网卡支持的特定IP地址。

• 宿端口（service.dst_port）：

  服务的流量将指向目标实例上的哪个端口？postgres 会指向数据库监听的端口，pgbouncer会指向连接池所监听的端口，也可以填入固定的端口号。

• 健康检查方式（service.check_method）:

  服务如何检查实例的健康状态？目前仅支持HTTP

• 健康检查端口（service.check_port）:

  服务检查实例的哪个端口获取实例的健康状态？ patroni会从Patroni（默认8008）获取，pg_exporter会从PG Exporter（默认9630）获取，用户也可以填入自定义的端口号。

• 健康检查路径（service.check_url）:

  服务执行HTTP检查时，使用的URL PATH。默认会使用/作为健康检查，PG Exporter与Patroni提供了多样的健康检查方式，可以用于主从流量区分。例如，/primary仅会对主库返回成功，/replica仅会对从库返回成功。/read-only则会对任何支持只读的实例（包括主库）返回成功。

• 健康检查代码（service.check_code）:

  HTTP健康检查所期待的代码，默认为200

• Haproxy特定配置（service.haproxy） ：

  关于服务供应软件（HAProxy）的专有配置项

服务实现

目前Pigsty默认使用基于HAProxy的服务实现，也有基于DPVS 4层负载均衡（L4VIP）的私有实现。两者相互等效，各有优势。详情请参考接入一节。

接入

接入是为了解决生产环境中高并发，高可用，高性能的问题。个人用户可以选择无视接入机制，绕过域名、VIP、负载均衡器、连接池，直接通过IP地址访问数据库。

个人用户可直接用连接串 postgres://dbuser_dba:[email protected]:5432/meta 访问默认数据库 （注意替换IP地址与密码，沙箱环境可从宿主机访问）

在Pigsty的默认配置中，每一个数据库实例/节点上都一一对应部署有一个功能完整的负载均衡器（HAProxy），因此整个数据库集群中的任意实例都可以作为整个集群的服务接入点。Pigsty数据库集群的交付边界止步于接入层负载均衡器（HAProxy）；您需要自行决定接入策略：如何将业务流量分发至集群中的一台、多台、或全部负载均衡实例。

Pigsty提供了丰富的接入方式，用户可以根据自己的网络基础设施情况与喜好自行选择。作为样例，Pigsty沙箱中使用了一个绑定在集群主库上的L2 VIP，一个绑定在该VIP上的域名。应用程序通过域名透过L2 VIP访问集群主库上的负载均衡实例。当该节点不可用时，VIP会随集群主库漂移，流量也随之由新主库上的负载均衡器承载，如下图所示：

另一种经典的策略是直接使用DNS轮询的方式，将DNS域名解析至所有实例，本文会给出几种常见的接入模式。

用户接口

从用户的角度来看，访问数据库只需要一个连接串；而Pigsty向最终用户交付的接口，也是一个数据库连接串。

不同的接入方式在形式上的区别是连接串中主机与端口部分的不同。

端口

Pigsty使用不同的端口来区分数据库服务，提供Postgres等效服务的端口如下：

主机

根据host部分填入的内容，与可用的port值，可以排列组合出多种连接串来。

可用连接串组合

以单节点沙箱环境为例，以下连接串都可以用于数据库集群pg-test上的test数据库：

# 通过集群域名接入
postgres://test@pg-test:5432/test               # DNS -> L2 VIP -> 主库直连
postgres://test@pg-test:6432/test               # DNS -> L2 VIP -> 主库连接池 -> 主库
postgres://test@pg-test:5433/test               # DNS -> L2 VIP -> HAProxy -> 主库连接池 -> 主库
postgres://test@pg-test:5434/test               # DNS -> L2 VIP -> HAProxy -> 从库连接池 -> 从库
postgres://dbuser_dba@pg-test:5436/test         # DNS -> L2 VIP -> HAProxy -> 主库直连（管理用）
postgres://dbuser_stats@pg-test:5438/test       # DNS -> L2 VIP -> HAProxy -> 离线库直连（ETL/个人查询用）

# 通过集群VIP直接接入
postgres://[email protected]:5432/test            # L2 VIP -> 主库直连
postgres://[email protected]:6432/test            # L2 VIP -> 主库连接池 -> 主库
postgres://[email protected]:5433/test            # L2 VIP -> HAProxy -> 主库连接池 -> 主库
postgres://[email protected]:5434/test            # L2 VIP -> HAProxy -> 从库连接池 -> 从库
postgres://[email protected]:5436/test      # L2 VIP -> HAProxy -> 主库直连（管理用）
postgres://[email protected]:5438/test   # L2 VIP -> HAProxy -> 离线库直连（ETL/个人查询用）

# 直接指定任意集群实例名
postgres://test@pg-test-1:5432/test             # DNS -> 数据库实例直连 （单实例接入）
postgres://test@pg-test-1:6432/test             # DNS -> 连接池 -> 数据库
postgres://test@pg-test-1:5433/test             # DNS -> HAProxy -> 连接池 -> 数据库读写
postgres://test@pg-test-1:5434/test             # DNS -> HAProxy -> 连接池 -> 数据库只读
postgres://dbuser_dba@pg-test-1:5436/test       # DNS -> HAProxy -> 数据库直连
postgres://dbuser_stats@pg-test-1:5438/test     # DNS -> HAProxy -> 数据库离线读写

# 直接指定任意集群实例IP接入
postgres://[email protected]:5432/test           # 数据库实例直连 （直接指定实例，无自动流量分发）
postgres://[email protected]:6432/test           # 连接池 -> 数据库
postgres://[email protected]:5433/test           # HAProxy -> 连接池 -> 数据库读写
postgres://[email protected]:5434/test           # HAProxy -> 连接池 -> 数据库只读
postgres://[email protected]:5436/test     # HAProxy -> 数据库直连
postgres://[email protected]:5438/test   # HAProxy -> 数据库离线读写

# 直接指定任意集群实例IP接入
postgres://[email protected]:5432/test           # 数据库实例直连 （直接指定实例，无自动流量分发）
postgres://[email protected]:6432/test           # 连接池 -> 数据库
postgres://[email protected]:5433/test           # HAProxy -> 连接池 -> 数据库读写
postgres://[email protected]:5434/test           # HAProxy -> 连接池 -> 数据库只读
postgres://[email protected]:5436/test     # HAProxy -> 数据库直连
postgres://[email protected]:5438/test   # HAProxy -> 数据库离线读写

# 智能客户端自动读写分离（连接池）
postgres://[email protected]:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs=primary
postgres://[email protected]:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs=prefer-standby

# 智能客户端自动读写分离（数据库）
postgres://[email protected]:5432,10.10.10.12:5432,10.10.10.13:5432/test?target_session_attrs=primary
postgres://[email protected]:5432,10.10.10.12:5432,10.10.10.13:5432/test?target_session_attrs=prefer-standby

在集群层次，用户可以通过集群域名+服务端口的方式访问集群提供的 四种默认服务，Pigsty强烈建议使用这种方式。当然用户也可以绕开域名，直接使用集群的VIP（L2 or L4）访问数据库集群。

在实例层次，用户可以通过节点IP/域名 + 5432端口直连Postgres数据库，也可以用6432端口经由Pgbouncer访问数据库。还可以通过Haproxy经由5433~543x访问实例所属集群提供的服务。

典型接入方案

Pigsty推荐使用基于Haproxy的接入方案（1/2），在生产环境中如果有基础设施支持，也可以使用基于L4VIP（或与之等效的负载均衡服务）的接入方案（3）。

L2 VIP + Haproxy

方案简介

Pigsty沙箱使用的标准接入方案，采用单个域名绑定至单个L2 VIP，VIP指向集群中的HAProxy。

集群中的Haproxy采用Node Port的方式统一对外暴露 服务。每个Haproxy都是幂等的实例，提供完整的负载均衡与服务分发功能。Haproxy部署于每一个数据库节点上，因此整个集群的每一个成员在使用效果上都是幂等的。（例如访问任何一个成员的5433端口都会连接至主库连接池，访问任意成员的5434端口都会连接至某个从库的连接池）

Haproxy本身的可用性通过幂等副本实现，每一个Haproxy都可以作为访问入口，用户可以使用一个、两个、多个，所有Haproxy实例，每一个Haproxy提供的功能都是完全相同的。

每个集群都分配有一个L2 VIP，固定绑定至集群主库。当主库发生切换时，该L2 VIP也会随之漂移至新的主库上。这是通过vip-manager实现的：vip-manager会查询Consul获取集群当前主库信息，然后在主库上监听VIP地址。

集群的L2 VIP有与之对应的域名。域名固定解析至该L2 VIP，在生命周期中不发生变化。

方案优越性

• 无单点，高可用
• VIP固定绑定至主库，可以灵活访问

方案局限性

• 多一跳
• Client IP地址丢失，部分HBA策略无法正常生效
• 所有候选主库必须位于同一二层网络。
  • 作为备选，用户也可以通过使用L4 VIP绕开此限制，但相比L2 VIP会额外多一跳。
  • 作为备选，用户也可以选择不用L2 VIP，而用DNS直接指向HAProxy，但可能会受到客户端DNS缓存的影响。

方案示意

DNS + Haproxy

方案简介

标准高可用接入方案，系统无单点。灵活性，适用性，性能达到一个较好的平衡。

集群中的Haproxy采用Node Port的方式统一对外暴露 服务。每个Haproxy都是幂等的实例，提供完整的负载均衡与服务分发功能。Haproxy部署于每一个数据库节点上，因此整个集群的每一个成员在使用效果上都是幂等的。（例如访问任何一个成员的5433端口都会连接至主库连接池，访问任意成员的5434端口都会连接至某个从库的连接池）

Haproxy本身的可用性通过幂等副本实现，每一个Haproxy都可以作为访问入口，用户可以使用一个、两个、多个，所有Haproxy实例，每一个Haproxy提供的功能都是完全相同的。

用户需要自行确保应用能够访问到任意一个健康的Haproxy实例。作为最朴素的一种实现，用户可以将数据库集群的DNS域名解析至若干Haproxy实例，并启用DNS轮询响应。而客户端可以选择完全不缓存DNS，或者使用长连接并实现建立连接失败后重试的机制。又或者参考方案2，在架构侧通过额外的L2/L4 VIP确保Haproxy本身的高可用。

方案优越性

• 无单点，高可用
• VIP固定绑定至主库，可以灵活访问

方案局限性

• 多一跳

• Client IP地址丢失，部分HBA策略无法正常生效

• Haproxy本身的高可用通过幂等副本，DNS轮询与客户端重连实现

  DNS应有轮询机制，客户端应当使用长连接，并有建连失败重试机制。以便单Haproxy故障时可以自动漂移至集群中的其他Haproxy实例。如果无法做到这一点，可以考虑使用接入方案2，使用L2/L4 VIP确保Haproxy高可用。

方案示意

L4 VIP + Haproxy

L4 VIP

Consul DNS

Static DNS

IP

12 - PGSQL业务用户与数据库

如何定义并创建PostgreSQL业务用户与数据库。

用户

在PostgreSQL中，用户（User） 指的是数据库集簇中的一个对象，由SQL语句CREATE USER/ROLE所创建。

在PostgreSQL中，用户直接隶属于数据库集簇而非某个具体的数据库。因此在创建业务数据库和业务用户时，应当遵循"先用户，后数据库"的原则。

定义用户

Pigsty通过两个配置参数定义数据库集群中的角色与用户：

• pg_default_roles
• pg_users

前者定义了整套环境中共有的角色，后者定义单个集群中特有的业务角色与用户。二者形式相同，均为用户定义对象数组。 下面是一个用户定义的例子：

- name: dbuser_meta               # required, `name` is the only mandatory field of a user definition
  password: md5d3d10d8cad606308bdb180148bf663e1  # md5 salted password of 'DBUser.Meta'
  # optional, plain text and md5 password are both acceptable (prefixed with `md5`)
  login: true                     # optional, can login, 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`
  # search_path: public         # key value config parameters according to postgresql documentation (e.g: use pigsty as default search_path)

• name : 每一个用户或角色必须指定 name，唯一的必选参数。
• password : 是可选项，如果留空则不设置密码，可以使用MD5密文密码。
• login, superuser, createdb, createrole, inherit, replication, bypassrls : 都是布尔类型标记，用于设置用户属性。如果不设置，则采用系统默认值。 其中pg_default_roles的用户默认不带有login属性，而pg_users默认带有login属性，可通过显式配置覆盖。
• expire_at与expire_in用于控制用户过期时间，expire_at使用形如YYYY-mm-DD的日期时间戳。expire_in使用从现在开始的过期天数，如果expire_in存在则会覆盖expire_at选项。
• pgbouncer: true 用于控制是否将新用户加入Pgbouncer用户列表中，该参数必须显式定义为true，相应用户才会被加入到Pgbouncer用户列表。
• roles 为该角色/用户所属的分组，可以指定多个分组，例如为用户添加默认角色。

创建用户

在创建数据库集群（或主库实例）时，pg_default_roles 与 pg_users 定义的角色和用户会自动依序创建。

在运行中的已有数据库集群上，使用预制剧本 pgsql-createuser.yml 来创建新的业务数据库。

首先，您需要在相应数据库集群配置的 pg_users 配置项中添加该用户的定义。然后，使用以下命令即可在对应集群上创建该用户或角色。

bin/createuser <pg_cluster> <username>    # <pg_cluster> 为集群名称，<user.name> 是新用户名。必须先定义，再执行脚本进行创建
bin/createuser pg-meta dbuser_meta        # 例：在pg-meta集群中创建dbuser_meta用户
./pgsql-createuser.yml -l <pg_cluster> -e pg_user=<user.name>  # 该脚本实际上调用了以下Ansible剧本完成对应任务

当目标用户已经存在时，Pigsty会修改目标用户的属性使其符合配置。

如果被创建的用户带有pgbouncer: true标记，该剧本会同时修改并重载数据库集群内所有Pgbouncer的配置/etc/pgbouncer/userlist.txt。

Pgbouncer中的用户

Pgbouncer的操作系统用户将与数据库超级用户保持一致，都使用{{ pg_dbsu }}，默认为postgres。 Pigsty默认使用Postgres管理用户作为Pgbouncer的管理用户，使用Postgres的监控用户同时作为Pgbouncer的监控用户。

Pgbouncer的用户列表通过/etc/pgbouncer/userlist.txt文件进行控制， Pgbouncer的用户权限通过/etc/pgbouncer/pgb_hba.conf进行控制。

只有显式添加pgbouncer: true配置条目的用户才会被加入到Pgbouncer用户列表中，并通过Pgbouncer访问数据库。 通常生产应用使用的账号应当通过Pgbouncer连接池访问数据库，而个人用户，管理，ETL等则应当直接访问数据库。

正常情况下请使用 pgsql-createuser.yml 剧本管理数据库用户。紧急情况下亦可在数据库实例上以postgres用户执行以下命令来手工添加用户，需要在集群中所有Pgbouncer上执行该命令并重新加载配置。

# 紧急情况下可以使用该命令手工添加用户，用法：pgbouncer-create-user <username> [password]
/pg/bin/pgbouncer-create-user

pgbouncer-create-user dbp_vonng Test.Password # 明文密码
pgbouncer-create-user dbp_vonng md596bceae83ba2937778af09adf00ae738 # md5密码
pgbouncer-create-user dbp_vonng auto          # 从数据库查询获取密码
pgbouncer-create-user dbp_vonng null          # 使用空密码

数据库

这里的 数据库（Database） 所指代的既非数据库软件，也不是数据库服务器进程，而是指数据库集簇中的一个逻辑对象，由SQL语句CREATE DATABASE所创建。

Pigsty会对默认模板数据库template1进行修改与定制，创建默认模式，安装默认扩展，配置默认权限，新创建的数据库默认会从template1继承这些设置。

PostgreSQL提供了 模式(Schema) 作为命名空间，因此并不推荐在单个数据库集簇中创建过多数据库。

pg_exporter 默认会通过 自动发现 机制查找所有业务数据库并监控。

定义数据库

Pigsty通过 pg_databases 配置参数定义数据库集群中的数据库，这是一个数据库定义构成的对象数组， 数组内的数据库按照定义顺序依次创建，因此后面定义的数据库可以使用先前定义的数据库作为模板。

下面是一个数据库定义的例子：

- 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/)
  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)
  pgbouncer: true                 # optional, add this database to pgbouncer database list? true by default
  comment: pigsty meta database   # optional, comment string for this database
  connlimit: -1                   # optional, database connection limit, default -1 disable limit
  schemas: [pigsty]               # optional, additional schemas to be created, array of schema names
  extensions:                     # optional, additional extensions to be installed: array of schema definition `{name,schema}`
    - {name: adminpack, schema: pg_catalog}    # install adminpack to pg_catalog and install postgis to public
    - {name: postgis, schema: public}          # if schema is omitted, extension will be installed according to search_path.

• name：数据库名称，必选项。
• baseline：SQL文件路径（Ansible搜索路径，通常位于files），用于初始化数据库内容。
• owner：数据库属主，默认为postgres
• template：数据库创建时使用的模板，默认为template1
• encoding：数据库默认字符编码，默认为UTF8，默认与实例保持一致。建议不要配置与修改。
• locale：数据库默认的本地化规则，默认为C，建议不要配置，与实例保持一致。
• lc_collate：数据库默认的本地化字符串排序规则，默认与实例设置相同，建议不要修改，必须与模板数据库一致。强烈建议不要配置，或配置为C。
• lc_ctype：数据库默认的LOCALE，默认与实例设置相同，建议不要修改或设置，必须与模板数据库一致。建议配置为C或en_US.UTF8。
• allowconn：是否允许连接至数据库，默认为true，不建议修改。
• revokeconn：是否回收连接至数据库的权限？默认为false。如果为true，则数据库上的PUBLIC CONNECT权限会被回收。只有默认用户（dbsu|monitor|admin|replicator|owner）可以连接。此外，admin|owner 会拥有GRANT OPTION，可以赋予其他用户连接权限。
• tablespace：数据库关联的表空间，默认为pg_default。
• connlimit：数据库连接数限制，默认为-1，即没有限制。
• extensions：对象数组 ，每一个对象定义了一个数据库中的扩展，以及其安装的模式。
• parameters：KV对象，每一个KV定义了一个需要针对数据库通过ALTER DATABASE修改的参数。
• pgbouncer：布尔选项，是否将该数据库加入到Pgbouncer中。所有数据库都会加入至Pgbouncer列表，除非显式指定pgbouncer: false。
• comment：数据库备注信息。

创建数据库

在创建数据库集群（或主库实例）时，pg_databases 定义的数据库会依序自动创建。

在运行中的已有数据库集群上，使用预制剧本 pgsql-createdb.yml 来创建新的业务数据库。

首先在相应数据库集群配置的 pg_databases 配置项中添加该数据库的定义。然后，使用以下命令即可在对应集群上创建该数据库：

bin/createdb <pg_cluster>  <database.name> # <pg_cluster> 为集群名称，<database.name> 是新数据库的name。
bin/createdb pg-meta meta                  # 例：在pg-meta集群中创建meta数据库
./pgsql-createdb.yml -l <pg_cluster> -e pg_database=<dbname>  # 该脚本实际上调用了以下Ansible剧本完成对应任务

当目标数据库已经存在时，Pigsty会修改目标数据库的属性使其符合配置。

如果您为数据库配置了owner参数，则必须确保数据库创建时该用户已经存在。所以通常建议先完成业务用户的创建，再创建数据库。

该剧本默认会修改并重载数据库集群内所有Pgbouncer的配置/etc/pgbouncer/database.txt。但如果被创建的数据库带有pgbouncer: false标记，该剧本会跳过Pgbouncer配置阶段

Pgbouncer中的数据库

Pgbouncer的操作系统用户将与数据库超级用户保持一致，都使用{{ pg_dbsu }}，默认为postgres。 Pgbouncer的管理数据库名为pgbouncer，可以使用postgres与dbuser_dba用户进行管理，在操作系统用户postgres下执行快捷方式pgb即可以管理员身份连接至pgbouncer

Pgbouncer中的数据库列表通过/etc/pgbouncer/database.txt文件进行控制，默认内容类似以下格式

# 数据库名 = 实际目标连接信息
meta = host=/var/run/postgresql
grafana = host=/var/run/postgresql
prometheus = host=/var/run/postgresql

在Pigsty中，Pgbouncer与Postgres实例采用1:1同机部署，使用 /var/run/postgresql Unix Socket通信。

通常情况下，所有新数据库都会被加入到Pgbouncer的数据库列表中。如果您希望某数据库无法通过Pgbouncer访问，可以在数据库定义中显式指定pgbouncer: false。

正常情况下请使用 pgsql-createdb.yml 剧本创建新的数据库。亦可在数据库实例上以postgres用户执行以下命令来手工添加数据库，需要在集群中所有Pgbouncer上执行该命令并重新加载配置。

# 特殊情况下可以使用该命令手工添加数据库
# pgbouncer-create-user <dbname> [connstr] [dblist=/etc/pgbouncer/database.txt]
/pg/bin/pgbouncer-create-db
pgbouncer-create-db meta                     # 创建meta数据库，指向本机同名数据库
pgbouncer-create-db test host=10.10.10.13    # 创建test数据库并将其指向10.10.10.13上的同名数据库

13 - PGSQL 权限认证与访问控制

Pigsty提供了一套开箱即用的访问控制模型，简单实用，可满足基本安全需求。

PostgreSQL提供了标准的访问控制机制：认证（Authentication）与权限（Privileges），认证与权限都基于角色（Role）体系进行。

角色

Pigsty的默认角色体系包含四个默认角色，以及四个默认用户。

以下是Pigsty自带的8个默认用户/角色的定义

默认角色

Pigsty带有四个默认角色：

• 只读角色（dbrole_readonly）：对所有数据表具有只读权限。
• 读写角色（dbrole_readwrite）：对所有数据表具有写入权限，继承dbrole_readonly
• 管理角色（dbrole_admin）：可以执行DDL变更，继承dbrole_readwrite
• 离线角色（dbrole_offline）：特殊只读角色，用于执行慢查询/ETL/交互查询，仅允许在特定实例上访问。

其定义如下所示

- { name: dbrole_readonly  , login: false , comment: role for global read-only access  }                            # production read-only role
- { name: dbrole_offline ,   login: false , comment: role for restricted read-only access (offline instance) }      # restricted-read-only role
- { name: dbrole_readwrite , login: false , roles: [dbrole_readonly], comment: role for global read-write access }  # production read-write role
- { name: dbrole_admin , login: false , roles: [pg_monitor, dbrole_readwrite] , comment: role for object creation } # production DDL change role

默认用户

Pigsty带有四个默认用户：

• 超级用户（postgres），数据库的拥有者与创建者，与操作系统用户一致
• 复制用户（replicator），用于主从复制的系统用户
• 监控用户（dbuser_monitor），用于监控数据库与连接池指标的用户
• 管理员（dbuser_dba），执行日常管理操作与数据库变更的管理员用户

其定义如下所示：

- { name: postgres , superuser: true , comment: system superuser }                             # system dbsu, name is designated by `pg_dbsu`
- { name: dbuser_dba , superuser: true , roles: [dbrole_admin] , comment: system admin user }  # admin dbsu, name is designated by `pg_admin_username`
- { name: replicator , replication: true , bypassrls: true , roles: [pg_monitor, dbrole_readonly] , comment: system replicator }                   # replicator
- { name: dbuser_monitor , roles: [pg_monitor, dbrole_readonly] , comment: system monitor user , parameters: {log_min_duration_statement: 1000 } } # monitor user

在Pigsty中，4个默认的重要用户的用户名和密码是由独立参数控制与管理的：

pg_dbsu: postgres                             # os user for database

# - system roles - #
pg_replication_username: replicator           # system replication user
pg_replication_password: DBUser.Replicator    # system replication password
pg_monitor_username: dbuser_monitor           # system monitor user
pg_monitor_password: DBUser.Monitor           # system monitor password
pg_admin_username: dbuser_dba                 # system admin user
pg_admin_password: DBUser.DBA                 # system admin password

出于安全考虑，不建议为默认超级用户postgres设置密码或允许远程访问，所以没有专门的dbsu_password选项。 如果有此类需求，可在pg_default_roles中为超级用户设置密码。

此外，用户可以在 pg_users 定义集群特定的业务用户，定义方式与 pg_default_roles 一致。

认证

认证是数据库验证来访连接身份的过程。Pigsty默认使用md5密码认证，并基于PostgreSQL HBA机制提供访问控制。

HBA是Host Based Authentication的缩写，可以将其视作IP黑白名单。

HBA配置方式

在Pigsty中，所有实例的HBA都由配置文件生成而来，最终生成的HBA规则因实例的角色（pg_role）而不同。 Pigsty的HBA由下列变量控制：

• pg_hba_rules: 环境统一的HBA规则
• pg_hba_rules_extra: 特定于实例或集群的HBA规则
• pgbouncer_hba_rules: 连接池使用的HBA规则
• pgbouncer_hba_rules_extra: 特定于实例或集群的连接池HBA规则

每个变量都是由下列样式的规则组成的数组：

- title: allow intranet admin password access
  role: common
  rules:
    - host    all     +dbrole_admin               10.0.0.0/8          md5
    - host    all     +dbrole_admin               172.16.0.0/12       md5
    - host    all     +dbrole_admin               192.168.0.0/16      md5

基于角色的HBA

role = common的HBA规则组会安装到所有的实例上，而其他的取值，例如（role : primary）则只会安装至pg_role = primary的实例上。因此用户可以通过角色体系定义灵活的HBA规则。

作为特例，role: offline 的HBA规则，除了会安装至pg_role == 'offline'的实例，也会安装至pg_offline_query == true的实例上。

HBA的渲染优先级规则为：

• hard_coded_rules 全局硬编码规则
• pg_hba_rules_extra.common 集群通用规则
• pg_hba_rules_extra.pg_role 集群角色规则
• pg_hba_rules.pg_role 全局角色规则
• pg_hba_rules.offline 集群离线规则
• pg_hba_rules_extra.offline 全局离线规则
• pg_hba_rules.common 全局通用规则

默认HBA规则

在默认配置下，主库与从库会使用以下的HBA规则：

• 超级用户通过本地操作系统认证访问
• 其他用户可以从本地用密码访问
• 复制用户可以从局域网段通过密码访问
• 监控用户可以通过本地访问
• 所有人都可以在元节点上使用密码访问
• 管理员可以从局域网通过密码访问
• 所有人都可以从内网通过密码访问
• 读写用户（生产业务账号）可以通过本地（连接池）访问 （部分访问控制转交连接池处理）
• 在从库上：只读用户（个人）可以从本地（连接池）访问。 （意味主库上拒绝只读用户连接）
• pg_role == 'offline' 或带有pg_offline_query == true的实例上，会添加允许dbrole_offline分组用户访问的HBA规则。

#==============================================================#
# Default HBA
#==============================================================#
# allow local su with ident"
local   all             postgres                               ident
local   replication     postgres                               ident

# allow local user password access
local   all             all                                    md5

# allow local/intranet replication with password
local   replication     replicator                              md5
host    replication     replicator         127.0.0.1/32         md5
host    all             replicator         10.0.0.0/8           md5
host    all             replicator         172.16.0.0/12        md5
host    all             replicator         192.168.0.0/16       md5
host    replication     replicator         10.0.0.0/8           md5
host    replication     replicator         172.16.0.0/12        md5
host    replication     replicator         192.168.0.0/16       md5

# allow local role monitor with password
local   all             dbuser_monitor                          md5
host    all             dbuser_monitor      127.0.0.1/32        md5

#==============================================================#
# Extra HBA
#==============================================================#
# add extra hba rules here

#==============================================================#
# primary HBA
#==============================================================#

#==============================================================#
# special HBA for instance marked with 'pg_offline_query = true'
#==============================================================#

#==============================================================#
# Common HBA
#==============================================================#
#  allow meta node password access
host    all     all                         10.10.10.10/32      md5

#  allow intranet admin password access
host    all     +dbrole_admin               10.0.0.0/8          md5
host    all     +dbrole_admin               172.16.0.0/12       md5
host    all     +dbrole_admin               192.168.0.0/16      md5

#  allow intranet password access
host    all             all                 10.0.0.0/8          md5
host    all             all                 172.16.0.0/12       md5
host    all             all                 192.168.0.0/16      md5

#  allow local read/write (local production user via pgbouncer)
local   all     +dbrole_readonly                                md5
host    all     +dbrole_readonly           127.0.0.1/32         md5

#==============================================================#
# Ad Hoc HBA
#===========================================================

修改HBA规则

HBA规则会在集群/实例初始化时自动生成。

用户可以在数据库集群/实例创建并运行后通过剧本修改并应用新的HBA规则：

./pgsql.yml -t pg_hba    # 通过-l指定目标集群
bin/reloadhba <cluster>  # 重载目标集群的HBA规则

当数据库集簇目录被销毁重建后，新副本会拥有和集群主库相同的HBA规则（因为从库的数据集簇目录是主库的二进制副本，而HBA规则也在数据集簇目录中）。 这通常不是用户期待的行为。您可以使用上面的命令针对特定实例进行HBA修复。

Pgbouncer的HBA

在Pigsty中，Pgbouncer亦使用HBA进行访问控制，用法与Postgres HBA基本一致

• pgbouncer_hba_rules: 连接池使用的HBA规则
• pgbouncer_hba_rules_extra: 特定于实例或集群的连接池HBA规则

默认的Pgbouncer HBA规则允许从本地和内网通过密码访问

pgbouncer_hba_rules:                          # pgbouncer host-based authentication rules
  - title: local password access
    role: common
    rules:
      - local  all          all                                     md5
      - host   all          all                     127.0.0.1/32    md5

  - title: intranet password access
    role: common
    rules:
      - host   all          all                     10.0.0.0/8      md5
      - host   all          all                     172.16.0.0/12   md5
      - host   all          all                     192.168.0.0/16  md5

权限

Pigsty的默认权限模型与默认角色紧密关联。使用Pigsty访问控制模型时，新创建的业务用户都应当属于四种默认角色之一，默认角色拥有的权限如下所示：

• 所有用户都可以访问所有模式
• 只读用户可以读取所有表
• 读写用户可以对所有表进行DML操作（INSERT, UPDATE, DELETE）
• 管理员可以执行DDL变更操作（CREATE, USAGE, TRUNCATE, REFERENCES, TRIGGER）
• 离线用户与只读用户类似，但只允许访问pg_role == 'offline' 或 pg_offline_query = true 的实例

GRANT USAGE                         ON SCHEMAS   TO dbrole_readonly;
GRANT SELECT                        ON TABLES    TO dbrole_readonly;
GRANT SELECT                        ON SEQUENCES TO dbrole_readonly;
GRANT EXECUTE                       ON FUNCTIONS TO dbrole_readonly;
GRANT USAGE                         ON SCHEMAS   TO dbrole_offline;
GRANT SELECT                        ON TABLES    TO dbrole_offline;
GRANT SELECT                        ON SEQUENCES TO dbrole_offline;
GRANT EXECUTE                       ON FUNCTIONS TO dbrole_readonly;
GRANT INSERT, UPDATE, DELETE        ON TABLES    TO dbrole_readwrite;
GRANT USAGE,  UPDATE                ON SEQUENCES TO dbrole_readwrite;
GRANT TRUNCATE, REFERENCES, TRIGGER ON TABLES    TO dbrole_admin;
GRANT CREATE                        ON SCHEMAS   TO dbrole_admin;
GRANT USAGE                         ON TYPES     TO dbrole_admin;

对象权限的维护

数据库对象的默认访问权限通过PostgreSQL的ALTER DEFAULT PRIVILEGES确保。

所有由 {{ dbsu }}, {{ pg_admin_username }}, {{ dbrole_admin }} 创建的对象，都会拥有以上默认权限。 反过来说，如果是由其他角色创建的对象，则并不会配置有正确的默认访问权限。

Pigsty非常不建议使用业务用户执行DDL变更，因为PostgreSQL的ALTER DEFAULT PRIVILEGE仅针对“由特定用户创建的对象”生效，默认情况下超级用户postgres和dbuser_dba创建的对象拥有默认的权限配置，如果希望授予业务用户执行DDL的权限，那么除了为业务用户赋予 dbrole_admin 角色外，使用者还需牢记在执行DDL变更时首先要执行：

SET ROLE dbrole_admin; -- dbrole_admin 创建的对象具有正确的默认权限

这样创建的对象才会具有默认的访问权限。

数据库的权限

数据库有三种权限：CONNECT, CREATE, TEMP，以及特殊的属主OWNERSHIP。数据库的定义由参数pg_database控制。一个完整的数据库定义如下所示：

pg_databases:                       # define business databases on this cluster, array of database definition
  # define the default `meta` database
  - 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/)
    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)
    pgbouncer: true                 # optional, add this database to pgbouncer database list? true by default
    comment: pigsty meta database   # optional, comment string for this database
    connlimit: -1                   # optional, database connection limit, default -1 disable limit
    schemas: [pigsty]               # optional, additional schemas to be created, array of schema names
    extensions:                     # optional, additional extensions to be installed: array of schema definition `{name,schema}`
      - {name: adminpack, schema: pg_catalog}    # install adminpack to pg_catalog and install postgis to public
      - {name: postgis, schema: public}          # if schema is omitted, extension will be installed according to search_path.