概念

• 1: 系统架构
• 2: 模块组件
• 3: 配置文件
• 4: 预置剧本

1 - 系统架构

实体概念模型

一套完整的Pigsty系统，可称为一个部署（Deployment）/ 环境（Environment） ，例如：生产环境，测试环境，预发环境等。

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

基础设施

基础设施（Infra） 部署于元节点上，监控，DNS，NTP，DCS，Yum源等。

集群

集群 可以是主机节点集群，PostgreSQL数据库集群，Redis数据库集群等……，部署于节点上。

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

模块

无论是基础设施，还是主机节点，或者是PGSQL与REDIS数据库，都通过模块的方式进行组织，并通过剧本的方式进行安装。

目前Pigsty有四个核心模块：INFRA，NODES，PGSQL，REDIS

各种模块可以根据用户的需求自由排列组合： 如果您想将Pigsty当作开箱即用的单机PostgreSQL发行版来使用，那么在一台机器上依次安装 INFRA, NODES, PGSQL 三个模块，就会有一个立即可用的，自我监控管理的数据库实例。 如果您想要一个生产环境的大规模主机监控系统，那么在一台机器上安装 INFRA 模块，在所有被监控的机器节点上安装NODES模块即可 如果您想部署管理大量的PostgreSQL集群，在这些纳入Pigsty管理的节点上再加装 PGSQL 模块即可。

2 - 模块组件

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集簇，使用 pigsty-matrixdb.yml 部署 Greenplum/MatrixDB 数据仓库。

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

3 - 配置文件

配置Pigsty

Pigsty采用声明式配置：用户配置描述状态，而Pigsty负责将真实组件调整至所期待的状态。

Pigsty通过配置清单（Inventory）来定义基础设施与数据库集群，每一套Pigsty部署都有一份对应的配置：无论是几百集群的生产环境，还是1核1GB的本地沙箱，在Pigsty中除了配置内容外没有任何区别。Pigsty的配置采用"Infra as Data"的哲学：用户通过声明式的配置描述自己的需求，而Pigsty负责将真实组件调整至所期待的状态。

在形式上，配置清单的具体实现可以是默认的本地配置文件，也可以是来自CMDB中的动态配置数据，本文介绍时均以默认YAML配置文件pigsty.yml 为例。在 配置过程 中，Pigsty会检测当前节点环境，并自动生成推荐的配置文件。

配置清单的内容主要是配置项，Pigsty提供了220个配置参数，可以在多个层次进行配置，大多数参数可以直接使用默认值。配置项按照类目可以分为四大类：INFRA/基础设施， NODES/主机节点， PGSQL/PG数据库， REDIS/Redis数据库，并可进一步细分为32个小类。

配置过程

进入 Pigsty 项目目录执行 configure，Pigsty会检测根据当前机器环境生成推荐配置文件，这一过程称作 配置 / Configure。

./configure [-n|--non-interactive] [-d|--download] [-i|--ip <ipaddr>] [-m|--mode {auto|demo}]

configure会检查下列事项，小问题会自动尝试修复，否则提示报错退出。

check_kernel     # kernel        = Linux
check_machine    # machine       = x86_64
check_release    # release       = CentOS 7.x
check_sudo       # current_user  = NOPASSWD sudo
check_ssh        # current_user  = NOPASSWD ssh
check_ipaddr     # primary_ip (arg|probe|input)              (INTERACTIVE: ask for ip)
check_admin      # check current_user@primary_ip nopass ssh sudo
check_mode       # check machine spec to determine node mode (tiny|oltp|olap|crit)
check_config     # generate config according to primary_ip and mode
check_pkg        # check offline installation package exists (INTERACTIVE: ask for download)
check_repo       # create repo from pkg.tgz if exists
check_repo_file  # create local file repo file if repo exists
check_utils      # check ansible sshpass and other utils installed

直接运行 ./configure 将启动交互式命令行向导，提示用户回答以下三个问题：

IP地址

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

下载软件包

当节点的/tmp/pkg.tgz路径下未找到离线软件包时，配置向导会询问是否从Github下载。 选择Y即会开始下载，选择N则会跳过。如果您的节点有良好的互联网访问与合适的代理配置，或者需要自行制作离线软件包，可以选择N。

配置模板

使用什么样的配置文件模板。 配置向导会根据当前机器环境自动选择配置模板，因此不会询问用户这个问题，用户通常也无需关心。 但用户总是可以通过命令行参数-m <mode>手工指定想要使用的配置模板，例如：

• demo 项目默认配置文件，4节点沙箱使用的配置文件，启用全部功能。
• auto 在生产环境中部署时推荐的配置文件模板，配置更加稳定保守。
• 此外Pigsty预置了几种配置模板，可以直接通过-m参数指定并使用，详见files/conf目录

在configure过程中，配置向导会根据当前机器环境自动选择配置模板，但用户可以通过-m <mode>手工指定使用配置模板。配置模板最重要的部分是将模板中占位IP地址10.10.10.10替换为当前机器的真实IP地址（内网主IP），并根据当前机器的配置选择合适的数据库规格模板。您可以直接使用默认生成的配置文件，或基于自动生成的配置文件进行进一步的定制与修改。

$ ./configure
configure pigsty v1.5.1 begin
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] release = 7.8.2003 , perfect
[ OK ] sudo = root ok
[ OK ] ssh = root@127.0.0.1 ok
[ OK ] primary_ip = 10.10.10.10  (from probe)
[ OK ] admin = root@10.10.10.10 ok
[ OK ] spec = mini (cpu = 2)
[ OK ] config = auto @ 10.10.10.10
[ OK ] cache = /tmp/pkg.tgz exists
[ OK ] repo = /www/pigsty ok
[ OK ] repo file = /etc/yum.repos.d/pigsty-local.repo
[ OK ] utils = install from local file repo
[ OK ] ansible = ansible 2.9.27
configure pigsty done. Use 'make install' to proceed

配置文件

Pigsty项目根目录下有一个具体的配置文件样例：pigsty.yml

配置文件顶层是一个key为all的单个对象，包含两个子项目：vars与children。

all:                      # 顶层对象 all
  vars: <123 keys>        # 全局配置 all.vars

  children:               # 分组定义：all.children 每一个项目定义了一个数据库集群 
    meta: <2 keys>...     # 特殊分组 meta ，定义了环境元节点
    
    pg-meta: <2 keys>...  # 数据库集群 pg-meta 的详细定义
    pg-test: <2 keys>...  # 数据库集群 pg-test 的详细定义
    ...

vars的内容为KV键值对，定义了全局配置参数，K为配置项名称，V为配置项内容。

children 的内容也是KV结构，K为集群名称，V为具体的集群定义，一个样例集群的定义如下所示：

• 集群定义同样包括两个子项目：vars定义了集群层面的配置。hosts定义了集群的实例成员。
• 集群配置中的参数会覆盖全局配置中的对应参数，而集群的配置参数又会被实例级别的同名配置参数所覆盖。集群配置参数中，唯pg_cluster为必选项，这是集群的名称，须与上层集群名保持一致。
• hosts中采用KV的方式定义集群实例成员，K为IP地址（须ssh可达），V为具体的实例配置参数
• 实例配置参数中有两个必须参数：pg_seq，与 pg_role，分别为实例的唯一序号和实例的角色。

pg-test:                 # 数据库集群名称默认作为群组名称
  vars:                  # 数据库集群级别变量
    pg_cluster: pg-test  # 一个定义在集群级别的必选配置项，在整个pg-test中保持一致。 
  hosts:                 # 数据库集群成员
    10.10.10.11: {pg_seq: 1, pg_role: primary} # 数据库实例成员
    10.10.10.12: {pg_seq: 2, pg_role: replica} # 必须定义身份参数 pg_role 与 pg_seq
    10.10.10.13: {pg_seq: 3, pg_role: offline} # 可以在此指定实例级别的变量

Pigsty配置文件遵循Ansible规则，采用YAML格式，默认使用单一配置文件。Pigsty的默认配置文件路径为Pigsty源代码根目录下的 pigsty.yml 。默认配置文件是在同目录下的ansible.cfg通过inventory = pigsty.yml指定的。您可以在执行任何剧本时，通过-i <config_path>参数指定其他的配置文件。

配置文件需要与Ansible 配合使用。Ansible是一个流行的DevOps工具，但普通用户无需了解Ansible的具体细节。如果您精通Ansible，则可以根据Ansible的清单组织规则自行调整配置文件的组织与结构：例如，使用分立式的配置文件，为每个集群设置单独的群组定义与变量定义文件。

您并不需要精通Ansible，用几分钟时间浏览Ansible快速上手，便足以开始使用Ansible执行剧本。

配置项

配置项的形式为键值对：键是配置项的名称，值是配置项的内容。值的形式各异，可能是简单的单个字符串，也可能是复杂的对象数组。

Pigsty的参数可以在不同的层次进行配置，并依据规则继承与覆盖，高优先级的配置项会覆盖低优先级的同名配置项。因此用户可以有的放矢，可以在不同层次，不同粒度上针对具体集群与具体实例进行精细配置。

配置项的层次

在Pigsty的配置文件中，配置项 可以出现在三种位置，全局，集群，实例。集群vars中定义的配置项会以同名键覆盖的方式覆盖全局配置项，实例中定义的配置项又会覆盖集群配置项与全局配置项。

并非所有配置项都适合在所有层次使用。例如，基础设施的参数通常只会在全局配置中定义，数据库实例的标号，角色，负载均衡权重等参数只能在实例层次配置，而一些操作选项则只能使用命令行参数提供（例如要创建的数据库名称），关于配置项的详情与适用范围，请参考配置项清单。

兜底与覆盖

除了配置文件中的三种配置粒度，Pigsty配置项目中还有两种额外的优先级层次：默认值兜底与命令行参数强制覆盖：

• 默认：当一个配置项在全局/集群/实例级别都没有出现时，将使用默认配置项。默认值的优先级最低，所有配置项都有默认值。默认参数定义于roles/<role>/default/main.yml中。
• 参数：当用户通过命令行传入参数时，参数指定的配置项具有最高优先级，将覆盖一切层次的配置。一些配置项只能通过命令行参数的方式指定与使用。

配置类目

Pigsty包含了220个固定配置项，分为四个部分：INFRA, NODES, PGSQL, REDIS，共计32类。

通常只有节点/数据库身份参数是必选参数，其他配置参数可直接使用默认值，按需修改。

4 - 预置剧本

Pigsty在底层通过 Ansible Playbook 实现核心管控功能，Pigsty提供的预置剧本分为四大类：

• infra : 使用 infra 系列剧本在元节点上单机安装Pigsty，并加装可选功能。
• nodes : 使用 nodes 系列剧本将更多节点纳入Pigsty监控管理，并供后续使用。
• pgsql : 使用 pgsql 系列剧本在已有节点上部署与管理PostgreSQL数据库集群。
• redis : 使用 redis 系列剧本在已有节点上部署与管理各种模式的Redis集群。

剧本概览

典型使用流程如下：

1. 使用 infra 系列剧本在元节点/本机安装 Pigsty ，部署基础设施。

   所有剧本都在元节点上发起执行，infra 系列剧本只作用于元节点本身。

2. 使用 nodes 系列剧本将其他节点纳入或移除Pigsty管理

   节点被托管后，可从元节点Grafana访问节点监控与日志，节点加入Consul集群。

3. 使用 pgsql 系列剧本在纳入管理的节点上部署PostgreSQL集群

   在托管节点上执行部署后，可以从元节点访问PostgreSQL监控与日志。

4. 使用 redis 系列剧本在纳入管理的节点上部署Redis集群

   在托管节点上执行部署后，可以从元节点访问Redis监控与日志。

                                           meta     node
[infra.yml]  ./infra.yml [-l meta]        +pigsty   +docker +consul +etcd
[nodes.yml]  ./nodes.yml -l pg-test                 +docker +consul +monitor
[pgsql.yml]  ./pgsql.yml -l pg-test                 +pgsql
[redis.yml]  ./redis.yml -l pg-test                 +redis

绝大多数剧本都是幂等设计，这意味着一些部署剧本在没有开启保护选项的情况下，可能会抹除现有数据库并创建新数据库。 当您处理现有数据库集群，或在生产环境进行操作时，请充分阅读并理解文档，再三校对命令，谨慎操作。对于误操作导致的数据库损失，作者不负任何责任。

Ansible快速上手

Pigsty剧本使用Ansible编写，用户并不需要完全理解Ansible的原理，只需要很少的知识即足以充分利用 Ansible 剧本。

• Ansible安装：如何安装Ansible？（Pigsty用户通常无需操心）
• 主机子集：如何针对特定主机执行剧本？
• 任务子集：如何执行剧本中的某些特定任务？
• 额外参数：如何传入额外的命令行参数以控制剧本行为？

Ansible安装

Ansible剧本需要使用ansible-playbook可执行命令，可使用包管理器安装Ansible，Ansible的安装由Pigsty自动处理，用户通常无需操心。

执行Ansible剧本时，直接将剧本作为可执行程序执行即可。执行剧本时有三个核心的参数需要关注：-l|-t|-e，分别用于限制执行的主机，与执行的任务，以及传入额外的参数。

主机子集

可以通过 -l|--limit <selector> 参数选择执行的目标，不指定此参数时，大多数剧本默认会以配置文件中定义的所有主机作为执行对象，这是非常危险的。 强烈建议在执行剧本时，指定执行的对象。

常用的对象有两种，集群与主机，例如：

./pgsql.yml                 # 在配置清单的所有主机上执行pgsql剧本（危险！）
./pgsql.yml -l pg-test      # 针对 pg-test 集群中的主机执行pgsql剧本
./pgsql.yml -l 10.10.10.10  # 针对 10.10.10.10 的主机执行pgsql剧本
./pgsql.yml -l pg-*         # 针对符合 pg-* 模式 (glob) 的集群执行剧本

任务子集

可以通过-t|--tags <tags>来选择执行的任务子集，不指定此参数时，会执行完整的剧本，指定此参数时，则将执行所选的任务子集，这是非常实用的。

./pgsql.yml -t pg_hba                            # 重新生成并应用集群HBA规则

用户可以通过,分隔，一次执行多个任务，例如当集群角色成员发生变化时，可以使用以下命令调整集群负载均衡配置。

./pgsql.yml -t haproxy_config,haproxy_reload     # 重新生成集群负载均衡器配置并应用

额外参数

可以通过-e|--extra-vars KEY=VALUE 传入额外的命令行参数，覆盖已有参数，或控制一些特殊的行为。

例如，以下剧本的部分行为可以通过命令行参数进行控制。

./nodes.yml -e ansible_user=admin -k -K      # 在配置节点时，使用另一个管理员用户 admin，并输入ssh与sudo密码
./pgsql.yml -e pg_clean=clean        # 在安装PG时，强制抹除已有运行中数据库实例（危险）
./infra-remove.yml -e rm_metadata=true       # 在卸载Pigsty时，一并移除数据
./infra-remove.yml -e rm_metadpkgs=true      # 在卸载Pigsty时，一并卸载软件
./nodes-remove.yml -e rm_dcs_server=true     # 在移除节点时，即使上面有DCS Server也强制移除
./pgsql-remove.yml -e rm_pgdata=true         # 在移除PG时，一并移除数据
./pgsql-remove.yml -e rm_pgpkgs=true         # 在移除PG时，一并卸载软件