概念

• 1: 命名原则
• 2: 系统架构
• 3: 监控系统
• 3.1: 可观测性
• 3.2: 监控层级
• 3.3: 身份管理
• 3.4: 监控指标
• 3.5: 报警规则
• 4: 供给方案
• 4.1: 数据库接入
• 4.2: 数据库服务
• 4.3: 高可用
• 4.4: 目录结构
• 4.5: 访问控制

1 - 命名原则

名之必可言也，言之必可行也。

概念及其命名是非常重要的东西，命名风格体现了工程师对系统架构的认知。定义不清的概念将导致沟通困惑，随意设定的名称将产生意想不到的额外负担。因此需要审慎地设计。本文介绍 Pigsty 中的相关实体，以及其命名所遵循的原则。

结论

Pigsty中，核心的四类实体为：集群（Cluster），服务（Service），实例（Instance），节点（Node）

• 集群（Cluster） 是基本自治单元，由用户指定唯一标识，表达业务含义，作为顶层命名空间。
• 集群在硬件层面上包含一系列的节点（Node），即物理机，虚机（或Pod），可以通过IP唯一标识。
• 集群在软件层面上包含一系列的实例（Instance），即软件服务器，可以通过IP:Port唯一标识。
• 集群在服务层面上包含一系列的服务（Service），即可访问的域名与端点，可以通过域名唯一标识。
• 集群的命名可以使用任意满足DNS域名规范的名称，不能带点（[a-zA-Z0-9-]+）。
• 节点命名采用集群名称作为前缀，后接-，再接一个整数序号（建议从0开始分配，与k8s保持一致）
• 因为Pigsty采用独占式部署，节点与实例一一对应。则实例命名可与节点命名保持一致，即${cluster}-${seq}的方式。
• 服务命名亦采用集群名称作为前缀，后接-连接服务具体内容，如primary, replica,offline,delayed等。

以上图为例，用于测试的数据库集群名为“pg-test”，该集群由一主两从三个数据库服务器实例组成，部署在集群所属的三个节点上。pg-test集群集群对外提供两种服务，读写服务pg-test-primary与只读副本服务pg-test-replica。

实体

在Postgres集群管理中，有如下实体概念：

集群（Cluster）

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

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

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

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

节点（Node）

节点是对硬件资源的一种抽象，通常指代一台工作机器，无论是物理机（bare metal）还是虚拟机（vm），或者是k8s中的Pod。这里注意k8s中Node是硬件资源的抽象，但在实际管理使用上，是k8s中的Pod而不是Node更类似于这里Node概念。总之，节点的关键要素是：

• 节点是硬件资源的抽象，可以运行一系列的软件服务
• 节点可以使用IP地址作为唯一标识符

尽管可以使用lan_ip地址作为节点唯一标识符，但为了便于管理，节点应当拥有一个人类可读的充满意义的名称作为节点的Hostname，作为另一个常用的节点唯一标识。

服务（Service）

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

• 可以寻址访问的服务名称，用于对外提供接入，例如：
  • 一个DNS域名（pg-test-primary）
  • 一个Nginx/Haproxy Endpoint
• 服务流量路由解析与负载均衡机制，用于决定哪个实例负责处理请求，例如：
  • DNS L7：DNS解析记录
  • HTTP Proxy：Nginx/Ingress L7：Nginx Upstream配置
  • TCP Proxy：Haproxy L4：Haproxy Backend配置
  • Kubernetes：Ingress：Pod Selector 选择器。

同一个数据集簇中通常包括主库与从库，两者分别提供读写服务（primary）和只读副本服务(replica)。

实例（Instance）

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

• 可以通过IP:Port唯一标识
• 具有处理请求的能力

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

实例隶属于集群，每个实例在集群范围内都有着自己的唯一标识用于区分。

实例由服务负责解析，实例提供被寻址的能力，而Service将请求流量解析到具体的实例组上。

命名规则

一个对象可以有很多组标签（Tag）与元数据（Metadata/Annotation），但通常只能有一个名字（Name）。

管理数据库和软件与管理宠物类似，都需要花心思照顾。而起名字就是其中非常重要的一项工作。肆意的名字（例如 XÆA-12，NULL，史珍香）很可能会引入不必要的麻烦（额外复杂度），而设计得当的名字则可能会有意想不到的惊喜效果。

总体而言，对象起名应当遵循一些原则：

• 简洁直白，人类可读：名字是给人看的，因此要好记，便于使用。

• 体现功能，反映特征：名字需要反映对象的关键特征

• 独一无二，唯一标识：名字在命名空间内，自己的类目下应当是独一无二，可以惟一标识寻址的。

• 不要把太多无关的东西塞到名字里去：在名字中嵌入很多重要元数据是一个很有吸引力的想法，但维护起来会非常痛苦，例如反例：pg:user:profile:10.11.12.13:5432:replica:13。

集群命名

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

集群命名的形式，建议采用符合DNS标准 RFC1034 的命名规则，以免给后续改造埋坑。例如哪一天想要搬到云上去，发现以前用的名字不支持，那就要再改一遍名，成本巨大。

我认为更好的方式是采用更为严格的限制：集群的名称不应该包括点（dot）。应当仅使用小写字母，数字，以及减号连字符（hyphen）-。这样，集群中的所有对象都可以使用这个名称作为前缀，用于各种各样的地方，而不用担心打破某些约束。即集群命名规则为：

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

之所以强调不要在集群名称中用点，是因为以前很流行一种命名方式，例如com.foo.bar。即由点分割的层次结构命名法。这种命名方式虽然简洁名快，但有一个问题，就是用户给出的名字里可能有任意多的层次，数量不可控。如果集群需要与外部系统交互，而外部系统对于命名有一些约束，那么这样的名字就会带来麻烦。一个最直观的例子是K8s中的Pod，Pod的命名规则中不允许出现.。

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

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

比如：pg-test-tt就表示tt 业务线下的test集群，类型为pg。pg-user-fin表示fin业务线下的user服务。

节点命名

节点命名建议采用与k8s Pod一致的命名规则，即

<cluster_name>-<seq>

Node的名称会在集群资源分配阶段确定下来，每个节点都会分配到一个序号${seq}，从0开始的自增整型。这个与k8s中StatefulSet的命名规则保持一致，因此能够做到云上云下一致管理。

例如，集群pg-test有三个节点，那么这三个节点就可以命名为：

pg-test-1, pg-test-2和pg-test-3。

节点的命名，在整个集群的生命周期中保持不变，便于监控与管理。

实例命名

对于数据库来说，通常都会采用独占式部署方式，一个实例占用整个机器节点。PG实例与Node是一一对应的关系，因此可以简单地采用Node的标识符作为Instance的标识符。例如，节点pg-test-1上的PG实例名即为：pg-test-1，以此类推。

采用独占部署的方式有很大优势，一个节点即一个实例，这样能最小化管理复杂度。混部的需求通常来自资源利用率的压力，但虚拟机或者云平台可以有效解决这种问题。通过vm或pod的抽象，即使是每个redis（1核1G）实例也可以有一个独占的节点环境。

作为一种约定，每个集群中的0号节点（Pod），会作为默认主库。因为它是初始化时第一个分配的节点。

服务命名

通常来说，数据库对外提供两种基础服务：primary 读写服务，与replica只读副本服务。

那么服务就可以采用一种简单的命名规则：

<cluster_name>-<service_name>

例如这里pg-test集群就包含两个服务：读写服务pg-test-primary与只读副本服务pg-test-replica。

一种流行的实例/节点命名规则：<cluster_name>-<service_role>-<sequence>，即把数据库的主从身份嵌入到实例名称中。这种命名方式有好处也有坏处。好处是管理的时候一眼就能看出来哪一个实例/节点是主库，哪些是从库。缺点是一但发生Failover，实例与节点的名称必须进行调整才能维持一执性，这就带来的额外的维护工作。此外，服务与节点实例是相对独立的概念，这种Embedding命名方式扭曲了这一关系，将实例唯一隶属至服务。但复杂的场景下这一假设可能并不满足。例如，集群可能有几种不同的服务划分方式，而不同的划分方式之间很可能会出现重叠。

• 可读从库（解析至包含主库在内的所有实例）
• 同步从库（解析至采用同步提交的备库）
• 延迟从库，备份实例（解析至特定具体实例）

因此不要把服务角色嵌入实例名称，而是在服务中维护目标实例列表。毕竟名字并非全能，不要把太多非必要的信息嵌入到对象名称中。

2 - 系统架构

一套Pigsty部署在架构上分为两个部分：

• 基础设施（Infra） ：部署于元节点上，监控，DNS，NTP，DCS，Yum源等基础服务。
• 数据库集群（PgSQL）：部署于数据库节点上，以集群为单位对外提供数据库服务。

同时，用于部署的 节点（物理机，虚拟机，Pod）也分为两种：

• 元节点（Meta）：部署基础设施，执行控制逻辑，每个Pigsty部署至少需要一个元节点。
• 数据库节点（Node）：用于部署数据库集群/实例，节点与数据库实例一一对应。

沙箱样例

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

图：Pigsty沙箱中包含的节点与组件

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

基础设施

每一套 Pigsty 部署（Deployment） 中，都需要有一些基础设施，才能使整个系统正常工作。

基础设施通常由专业的运维团队或云厂商负责，但Pigsty作为一个开箱即用的产品解决方案，将基本的基础设施集成至供给方案中。

• 域名基础设施：Dnsmasq（部分请求转发至Consul DNS处理）
• 时间基础设施：NTP
• 监控基础设施：Prometheus
• 报警基础设施：Altermanager
• 可视化基础设施：Grafana
• 本地源基础设施：Yum/Nginx
• 分布式配置存储：etcd/consul
• Pigsty基础设施：元数据库MetaDB，管理组件Ansible，定时任务，与其他高级特性组件。

基础设施部署于 元节点 上。一套环境中包含一个或多个元节点，用于基础设施部署。

除了 分布式配置存储（DCS） 之外，所有基础设施组件都采用副本式部署；如果有多个元节点，元节点上的DCS（etcd/consul）会共同作为DCS Server。

元节点

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

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

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

部署于元节点上的基础设置架构如下图所示：

其主要交互关系如下：

• Dnsmasq提供环境内的DNS解析服务（可选，可使用已有Nameserver）

  部分DNS解析将转交由Consul DNS进行

• Nginx对外暴露所有Web服务，通过域名进行区分转发。

• Yum Repo是Nginx的默认服务器，为环境中所有节点提供从离线安装软件的能力。

• Grafana是Pigsty监控系统的载体，用于可视化Prometheus与CMDB中的数据。

• Prometheus是监控用时序数据库。

  • Prometheus默认从Consul获取所有需要抓取的Exporter，并为其关联身份信息。
  • Prometheus从Exporter拉取监控指标数据，进行预计算加工后存入自己的TSDB中。
  • Prometheus计算报警规则，将报警事件发往Alertmanager处理。

• Consul Server用于保存DCS的状态，达成共识，服务元数据查询。

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

• Pigsty相关组件：

  • 用于执行剧本，发起控制的Ansible
  • 用于支持各种高级功能的MetaDB（也是一个标准的数据库集群）
  • 定时任务控制器（备份，清理，统计，巡检，高级特性暂未加入）

数据库集群

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

集群是基本的业务服务单元，下图展示了沙箱环境中的复制拓扑。其中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)

下图从数据库集群的视角重新排列pg-test集群中相关组件的位置。

图：从数据库集群的逻辑视角审视架构（标准接入方案）

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

在Pigsty中，每个“数据库实例”在使用上是幂等的，采用类似NodePort的方式对外暴露 数据库服务。默认情况下，访问任意实例的5433端口即可访问主库，访问任意实例的5434端口即可访问从库。用户也可以灵活地同时使用不同的方式访问数据库，详情请参考：数据库接入。

数据库节点

数据库节点负责运行数据库实例， 在Pigsty中数据库实例固定采用独占式部署，一个节点上有且仅有一个数据库实例，因此节点与数据库实例可以互用唯一标识（IP地址与实例名）。

一个典型的数据库节点上运行的服务如下所示：

主要交互关系如下：

• 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分别用于暴露数据库，连接池，节点的监控指标

节点与元节点交互

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

图：单个元节点与单个数据库节点（点击查看大图）

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

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

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

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

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

  执行集群创建，扩缩容，用户、服务、HBA修改；日志收集、垃圾清理，备份，巡检等

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

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

3 - 监控系统

3.1 - 可观测性

对于系统管理来说，最重要到问题之一就是可观测性（Observability），下图展示了Postgres的可观测性。

原图地址：https://pgstats.dev/

PostgreSQL 提供了丰富的观测接口，包括系统目录，统计视图，辅助函数。 这些都是用户可以观测的信息。这里列出的信息全部为Pigsty所收录。Pigsty通过精心的设计，将晦涩的指标数据，转换成了人类可以轻松理解的洞察。

可观测性

经典的监控模型中，有三类重要信息：

• 指标（Metrics）：可累加的，原子性的逻辑计量单元，可在时间段上进行更新与统计汇总。
• 日志（Log）：离散事件的记录与描述
• 追踪（Trace）：与单次请求绑定的相关元数据

Pigsty重点关注 指标 信息，也会在后续加入对 日志 的采集、处理与展示，但Pigsty不会收集数据库的 追踪 信息。

指标

下面让以一个具体的例子来介绍指标的获取及其加工产物。

pg_stat_statements是Postgres官方提供的统计插件，可以暴露出数据库中执行的每一类查询的详细统计指标。

图：pg_stat_statements原始数据视图

这里pg_stat_statements提供的原始指标数据以表格的形式呈现。每一类查询都分配有一个查询ID，紧接着是调用次数，总耗时，最大、最小、平均单次耗时，响应时间都标准差，每次调用平均返回的行数，用于块IO的时间这些指标，（如果是PG13，还有更为细化的计划时间、执行时间、产生的WAL记录数量等新指标）。

这些系统视图与系统信息函数，就是Pigsty中指标数据的原始来源。直接查阅这种数据表很容易让人眼花缭乱，失去焦点。需要将这种指标转换为洞察，也就是以直观图表的方式呈现。

图：加工后的相关监控面板，PG Cluster Query看板部分截图

这里的表格数据经过一系列的加工处理，最终呈现为若干监控面板。最基本的数据加工是对表格中的原始数据进行标红上色，但也足以提供相当实用的改进：慢查询一览无余，但这不过是雕虫小技。重要的是，原始数据视图只能呈现当前时刻的快照；而通过Pigsty，用户可以回溯任意时刻或任意时间段。获取更深刻的性能洞察。

上图是集群视角下的查询看板 （PG Cluster Query），用户可以看到整个集群中所有查询的概览，包括每一类查询的QPS与RT，平均响应时间排名，以及耗费的总时间占比。

当用户对某一类具体查询感兴趣时，就可以点击查询ID，跳转到查询详情页（PG Query Detail）中。如下图所示。这里会显示查询的语句，以及一些核心指标。

图：呈现单类查询的详细信息，PG Query Detail 看板截图

上图是实际生产环境中的一次慢查询优化记录，用户可以从右侧中间的Realtime Response Time 面板中发现一个突变。该查询的平均响应时间从七八秒突降到了七八毫秒。我们定位到了这个慢查询并添加了适当的索引，那么优化的效果就立刻在图表上以直观的形式展现出来，给出实时的反馈。

这就是Pigsty需要解决的核心问题：From observability to insight。

日志

除了指标外，还有一类重要的观测数据：日志（Log），日志是对离散事件的记录与描述。

如果说指标是对数据库系统的被动观测，那么日志就是数据库系统及其周边组件主动上报的信息。

Pigsty目前尚未对数据库日志进行挖掘，但在后续的版本中将集成pgbadger与mtail，引入日志统一收集、分析、处理的基础设施。并添加数据库日志相关的监控指标。

用户可以自行使用开源组件对PostgreSQL日志进行分析。

追踪

PostgreSQL提供了对DTrace的支持，用户也可以使用采样探针分析PostgreSQL查询执行时的性能瓶颈。但此类数据仅在某些特定场景会用到，实用性一般，因此Pigsty不会针对数据库收集Trace数据。

接下来？

只有指标并不够，我们还需要将这些信息组织起来，才能构建出体系来。阅读 监控层级 了解更多信息

3.2 - 监控层级

正如 命名原则 中所介绍，Pigsty中的对象分为多个层次：集群，服务，实例，节点。

监控系统层次

Pigsty的监控系统中有着更多的层次，除了实例与集群这两个最为普遍层次，整个系统中还有着其他层次的组织。自顶向下可以分为7个层级：概览，分片，集群，服务，实例，数据库，对象。

图：Pigsty的监控面板被划分为7个逻辑层级与5个实现层级

逻辑层次

生产环境的数据库往往是以集群为单位组织的，集群是基本的业务服务单元，也是最为重要的监控层次。

集群是一个由主从复制所关联的一组数据库实例所构成的，实例是最基本的监控层次。

而多套数据库集群共同组成一个现实世界中的生产环境，概览（Overview） 层次的监控提供了对整个环境的整体描述。

按照水平拆分的模式服务于同一业务的多个数据库集群称为分片（Shard），分片层次的监控对于定位数据分布、倾斜等问题很有帮助。

服务 是夹在集群与实例中间的层次，服务通常与DNS，域名，VIP，NodePort等资源紧密关联。

数据库（Database） 是亚实例级对象，一个数据库集群/实例可能会同时有多个数据库存在，数据库层面的监控关注单个数据库内的活动。

对象（Object） 是数据库内的实体，包括表，索引，序列号，函数，查询，连接池等，对象层面的监控关注这些对象的统计指标，与业务紧密相关。

层次精简

作为一种精简，正如网络的OSI 7层模型在实际中被简化为TCP/IP五层模型一样，这七个层次也以 集群 和 实例 为界，简化为五个层次： 概览（Overview） ，集群（Cluster） ， 服务（Service），实例（Instance） ，数据库（Database） 。

这样，最终的层次划分也变得十分简洁：所有集群层次以上的信息，都是 概览 层次，所有实例以下的监控都算作 数据库 层次，夹在 集群 与 实例 中间的，就是 服务 层次。

命名规则

分完层次后，最重要的问题就是命名问题：

1. 需要一种方式来标识、引用系统中不同层次内的各个组件，

2. 这种命名方式，应当合理地反映出系统中各个实体的层次关系

3. 这种命名方式，应当可以按照规则自动生成，只有这样，才可以在集群扩容缩容，Failover时做到免维护自动化运行，

当我们理清了系统中存在的层次后，就可以着手为系统中的每个实体起名。

Pigsty所遵循的基本命名规则，请参考 命名原则 一节。

Pigsty使用独立的名称管理机制，实体的命名自成体系。

如果需要与外部系统对接，用户可以直接使用这套命名体系，或通过转接适配的方式采用自己的命名体系。

集群命名

Pigsty的集群名称由用户指定，满足[a-z0-9][a-z0-9-]*的正则表达式，形如pg-test，pg-meta。

节点命名

Pigsty的节点从属于集群。Pigsty的节点名称由两部分组成：集群名 与 节点编号，并使用-连接。

形式为${pg_cluster}-${pg_seq}，例如pg-meta-1，pg-test-2。

在形式上，节点编号是长度合理的自然数（包括0），在集群范围内唯一，每个节点都有自己的编号。

实例的编号可以由用户显式指定并分配，通常采用从0或1开始分配，一旦分配，在集群生命周期内不再变更。

实例命名

Pigsty的实例从属于集群，采用独占节点式部署。

因为实例与节点存在一一对应关系，因此实例名与节点命保持一致。

服务命名

Pigsty的服务从属于集群。Pigsty的服务名称由两部分组成：集群名 与 角色（Role），并使用-连接。

形式为${pg_cluster}-${pg_role}，例如pg-meta-primary，pg-test-replica。

pg_role的可选项包括：primary|replica|offline|delayed。

primary是特殊的角色，每个集群必须，且只能定义一个pg_role = primary的实例作为主库。

其他的角色大体上由用户定义，其中replica|offline|delayed 是Pigsty预定义的角色。

接下来？

划分好监控的层级后，需要对为监控对象赋予身份，方能进行管理。

3.3 - 身份管理

所有的实例都具有身份（Identity），身份信息是与实例关联的元数据，用于标识实例。

图：使用Consul服务发现时，Postgres服务带有的身份信息

身份参数

身份参数是任何集群与实例都必须定义的唯一标识符。

身份关联

为系统中的对象命名后，还需要将 身份信息 关联至具体的实例上。

身份信息属于业务赋予的元数据，数据库实例本身不会意识到这些身份信息，它不知道自己为谁而服务，从属于哪个业务，或者自己是集群中的几号实例。

身份赋予可以有多种形式，最朴素的身份关联方式就是运维人员的记忆：DBA在脑海中记住了IP地址为10.2.3.4上的数据库实例，是用于支付的实例，而另一台上的数据库实例则用于用户管理。更好的管理方式是通过配置文件，或者采用服务发现的方式来管理集群成员的身份。

Pigsty同时提供这两种身份管理的方式：基于Consul的服务发现，与基于配置文件的服务发现

参数 prometheus_sd_method (consul|static) 控制这一行为：

• consul：基于Consul进行服务发现，默认配置
• static：基于本地配置文件进行服务发现

Pigsty建议使用consul服务发现，当服务器发生Failover时，监控系统会自动更正目标实例所注册的身份。

Consul服务发现

Pigsty默认采用 Consul服务发现的方式管理环境中的服务。

Pigsty内置了基于DCS的配置管理与自动服务发现，用户可以直观地察看系统中的所有节点与服务信息，以及健康状态。Pigsty中的所有服务都会自动注册至DCS中，因此创建、销毁、修改数据库集群时，元数据会自动修正，监控系统能够自动发现监控目标，无需手动维护配置。

用户亦可通过Consul提供的DNS与服务发现机制，实现基于DNS的自动流量切换。

Consul采用了Client/Server架构，整个环境中存在1～5个不等的Consul Server，用于实际的元数据存储。所有节点上都部署有Consul Agent，代理本机服务与Consul Server的通信。Pigsty默认通过本地Consul配置文件的方式注册服务。

服务注册

在每个节点上，都运行有 consul agent。服务通过JSON配置文件的方式，由consul agent注册至DCS中。

JSON配置文件的默认位置是/etc/consul.d/，采用svc-<service>.json的命名规则，以postgres为例：

{
  "service": {
    "name": "postgres",
    "port": {{ pg_port }},
    "tags": [
      "{{ pg_role }}",
      "{{ pg_cluster }}"
    ],
    "meta": {
      "type": "postgres",
      "role": "{{ pg_role }}",
      "seq": "{{ pg_seq }}",
      "instance": "{{ pg_instance }}",
      "service": "{{ pg_service }}",
      "cluster": "{{ pg_cluster }}",
      "version": "{{ pg_version }}"
    },
    "check": {
      "tcp": "127.0.0.1:{{ pg_port }}",
      "interval": "15s",
      "timeout": "1s"
    }
  }
}

其中meta与tags部分是服务的元数据，存储有实例的身份信息。

服务查询

用户可以通过Consul提供的DNS服务，或者直接调用Consul API发现注册到Consul中的服务

使用DNS API查阅consul服务的方式，请参阅Consul文档。

图：查询pg-bench-1上的 pg_exporter 服务。

服务发现

Prometheus会自动通过consul_sd_configs发现环境中的监控对象。同时带有pg和exporter标签的服务会自动被识别为抓取对象：

- job_name: pg
  # https://prometheus.io/docs/prometheus/latest/configuration/configuration/#consul_sd_config
  consul_sd_configs:
    - server: localhost:8500
      refresh_interval: 5s
      tags:
        - pg
        - exporter

图：被Prometheus发现的服务，身份信息已关联至实例的指标维度上。

服务维护

有时候，因为数据库主从发生切换，导致注册的角色与数据库实例的实际角色出现偏差。这时候需要通过反熵过程处理这种异常。

基于Patroni的故障切换可以正常地通过回调逻辑修正注册的角色，但人工完成的角色切换则需要人工介入处理。

使用以下脚本可以自动检测并修复数据库的服务注册。建议在数据库实例上配置Crontab，或在元节点上设置定期巡检任务。

/pg/bin/pg-register $(pg-role)

静态文件服务发现

static服务发现依赖/etc/prometheus/targets/*.yml中的配置进行服务发现。采用这种方式的优势是不依赖Consul。

当Pigsty监控系统与外部管控方案集成时，这种模式对原系统的侵入性较小。但是缺点是，当集群内发生主从切换时，用户需要自行维护实例角色信息。手动维护时，可以根据以下命令从配置文件生成Prometheus所需的监控对象配置文件并载入生效。

详见 Prometheus服务发现。

./infra.yml --tags=prometheus_targtes,prometheus_reload

Pigsty默认生成的静态监控对象文件示例如下：

#==============================================================#
# File      :   targets/all.yml
# Ctime     :   2021-02-18
# Mtime     :   2021-02-18
# Desc      :   Prometheus Static Monitoring Targets Definition
# Path      :   /etc/prometheus/targets/all.yml
# Copyright (C) 2018-2021 Ruohang Feng
#==============================================================#

#======> pg-meta-1 [primary]
- labels: {cls: pg-meta, ins: pg-meta-1, ip: 10.10.10.10, role: primary, svc: pg-meta-primary}
  targets: [10.10.10.10:9630, 10.10.10.10:9100, 10.10.10.10:9631, 10.10.10.10:9101]

#======> pg-test-1 [primary]
- labels: {cls: pg-test, ins: pg-test-1, ip: 10.10.10.11, role: primary, svc: pg-test-primary}
  targets: [10.10.10.11:9630, 10.10.10.11:9100, 10.10.10.11:9631, 10.10.10.11:9101]

#======> pg-test-2 [replica]
- labels: {cls: pg-test, ins: pg-test-2, ip: 10.10.10.12, role: replica, svc: pg-test-replica}
  targets: [10.10.10.12:9630, 10.10.10.12:9100, 10.10.10.12:9631, 10.10.10.12:9101]

#======> pg-test-3 [replica]
- labels: {cls: pg-test, ins: pg-test-3, ip: 10.10.10.13, role: replica, svc: pg-test-replica}
  targets: [10.10.10.13:9630, 10.10.10.13:9100, 10.10.10.13:9631, 10.10.10.13:9101]

身份关联

无论是通过Consul服务发现，还是静态文件服务发现。最终的效果是实现身份信息与实例监控指标相互关联。

这一关联，是通过 监控指标 的维度标签实现的。

阅读下一节 监控指标 ，了解这些指标是如何通过标签组织起来的。

3.4 - 监控指标

指标（Metric） 是Pigsty监控系统的核心概念。

指标形式

指标在形式上是可累加的，原子性的逻辑计量单元，可在时间段上进行更新与统计汇总。

指标通常以 带有维度标签的时间序列 的形式存在。举个例子，Pigsty沙箱中的pg:ins:qps_realtime指展示了所有实例的实时QPS。

pg:ins:qps_realtime{cls="pg-meta", ins="pg-meta-1", ip="10.10.10.10", role="primary"} 0
pg:ins:qps_realtime{cls="pg-test", ins="pg-test-1", ip="10.10.10.11", role="primary"} 327.6
pg:ins:qps_realtime{cls="pg-test", ins="pg-test-2", ip="10.10.10.12", role="replica"} 517.0
pg:ins:qps_realtime{cls="pg-test", ins="pg-test-3", ip="10.10.10.13", role="replica"} 0

用户可以对指标进行运算：求和、求导，聚合，等等。例如：

$ sum(pg:ins:qps_realtime) by (cls)        -- 查询按集群聚合的 实时实例QPS
{cls="pg-meta"} 0
{cls="pg-test"} 844.6

$ avg(pg:ins:qps_realtime) by (cls)        -- 查询每个集群中 所有实例的平均 实时实例QPS
{cls="pg-meta"} 0
{cls="pg-test"} 280

$ avg_over_time(pg:ins:qps_realtime[30m])  -- 过去30分钟内实例的平均QPS
pg:ins:qps_realtime{cls="pg-meta", ins="pg-meta-1", ip="10.10.10.10", role="primary"} 0
pg:ins:qps_realtime{cls="pg-test", ins="pg-test-1", ip="10.10.10.11", role="primary"} 130
pg:ins:qps_realtime{cls="pg-test", ins="pg-test-2", ip="10.10.10.12", role="replica"} 100
pg:ins:qps_realtime{cls="pg-test", ins="pg-test-3", ip="10.10.10.13", role="replica"} 0

指标模型

每一个指标（Metric），都是一类数据，通常会对应多个时间序列（time series）。同一个指标对应的不同时间序列通过维度进行区分。

指标 + 维度，可以具体定位一个时间序列。每一个时间序列都是由 （时间戳，取值）二元组构成的数组。

Pigsty采用Prometheus的指标模型，其逻辑概念可以用以下的SQL DDL表示。

-- 指标表，指标与时间序列构成1:n关系
CREATE TABLE metrics (
    id   INT PRIMARY KEY,         -- 指标标识
    name TEXT UNIQUE              -- 指标名称，[...其他指标元数据，例如类型]
);

-- 时间序列表，每个时间序列都对应一个指标。
CREATE TABLE series (
    id        BIGINT PRIMARY KEY,               -- 时间序列标识 
    metric_id INTEGER REFERENCES metrics (id),  -- 时间序列所属的指标
    dimension JSONB DEFAULT '{}'                -- 时间序列带有的维度信息，采用键值对的形式表示
);

-- 时许数据表，保存最终的采样数据点。每个采样点都属于一个时间序列
CREATE TABLE series_data (
    series_id BIGINT REFERENCES series(id),     -- 时间序列标识
    ts        TIMESTAMP,                        -- 采样点时间戳
    value     FLOAT,                            -- 采样点指标值
    PRIMARY KEY (series_id, ts)                 -- 每个采样点可以通过 所属时间序列 与 时间戳 唯一标识
);

这里我们以pg:ins:qps指标为例：

-- 样例指标数据
INSERT INTO metrics VALUES(1, 'pg:ins:qps');  -- 该指标名为 pg:ins:qps ，是一个 GAUGE。
INSERT INTO series VALUES                     -- 该指标包含有四个时间序列，通过维度标签区分
(1001, 1, '{"cls": "pg-meta", "ins": "pg-meta-1", "role": "primary", "other": "..."}'),
(1002, 1, '{"cls": "pg-test", "ins": "pg-test-1", "role": "primary", "other": "..."}'),
(1003, 1, '{"cls": "pg-test", "ins": "pg-test-2", "role": "replica", "other": "..."}'),
(1004, 1, '{"cls": "pg-test", "ins": "pg-test-3", "role": "replica", "other": "..."}');
INSERT INTO series_data VALUES                 -- 每个时间序列底层的采样点
(1001, now(), 1000),                           -- 实例 pg-meta-1 在当前时刻QPS为1000
(1002, now(), 1000),                           -- 实例 pg-test-1 在当前时刻QPS为1000
(1003, now(), 5000),                           -- 实例 pg-test-2 在当前时刻QPS为1000
(1004, now(), 5001);                           -- 实例 pg-test-3 在当前时刻QPS为5001

• pg_up 是一个指标，包含有4个时间序列。记录了整个环境中所有实例的存活状态。
• pg_up{ins": "pg-test-1", ...}是一个时间序列，记录了特定实例pg-test-1 的存活状态

指标来源

Pigsty的监控数据主要有四种主要来源： 数据库，连接池，操作系统，负载均衡器。通过相应的exporter对外暴露。

完整来源包括：

• PostgreSQL本身的监控指标
• PostgreSQL日志中的统计指标
• PostgreSQL系统目录信息
• Pgbouncer连接池中间价的指标
• PgExporter指标
• 数据库工作节点Node的指标
• 负载均衡器Haproxy指标
• DCS（Consul）工作指标
• 监控系统自身工作指标：Grafana，Prometheus，Nginx
• Blackbox探活指标

关于全部可用的指标清单，请查阅 参考-指标清单 一节

指标数量

那么，Pigsty总共包含了多少指标呢？ 这里是一副各个指标来源占比的饼图。我们可以看到，右侧蓝绿黄对应的部分是数据库及数据库相关组件所暴露的指标，而左下方红橙色部分则对应着机器节点相关指标。左上方紫色部分则是负载均衡器的相关指标。

数据库指标中，与postgres本身有关的原始指标约230个，与中间件有关的原始指标约50个，基于这些原始指标，Pigsty又通过层次聚合与预计算，精心设计出约350个与DB相关的衍生指标。

因此，对于每个数据库集群来说，单纯针对数据库及其附件的监控指标就有621个。而机器原始指标281个，衍生指标83个一共364个。加上负载均衡器的170个指标，我们总共有接近1200类指标。

注意，这里我们必须辨析一下指标（metric）与时间序列（ Time-series）的区别。 这里我们使用的量词是 类 而不是个 。 因为一个指标可能对应多个时间序列。例如一个数据库中有20张表，那么 pg_table_index_scan 这样的指标就会对应有20个对应的时间序列。

截止至2021年，Pigsty的指标覆盖率在所有作者已知的开源/商业监控系统中一骑绝尘，详情请参考横向对比。

指标层次

Pigsty还会基于现有指标进行加工处理，产出 衍生指标（Derived Metrics） 。

例如指标可以按照不同的层次进行聚合

从原始监控时间序列数据，到最终的成品图表，中间还有着若干道加工工序。

这里以TPS指标的衍生流程为例。

原始数据是从Pgbouncer抓取得到的事务计数器，集群中有四个实例，而每个实例上又有两个数据库，所以一个实例总共有8个DB层次的TPS指标。

而下面的图表，则是整个集群内每个实例的QPS横向对比，因此在这里，我们使用预定义的规则，首先对原始事务计数器求导获取8个DB层面的TPS指标，然后将8个DB层次的时间序列聚合为4个实例层次的TPS指标，最后再将这四个实例级别的TPS指标聚合为集群层次的TPS指标。

Pigsty共定义了360类衍生聚合指标，后续还会不断增加。衍生指标定义规则详见 参考-衍生指标

特殊指标

目录（Catalog） 是一种特殊的指标

Catalog与Metrics比较相似但又不完全相同，边界比较模糊。最简单的例子，一个表的页面数量和元组数量，应该算Catalog还是算Metrics？

跳过这种概念游戏，实践上Catalog和Metrics主要的区别是，Catalog里的信息通常是不怎么变化的，比如表的定义之类的，如果也像Metrics这样比如几秒抓一次，显然是一种浪费。所以我们会将这一类偏静态的信息划归Catalog。

Catalog主要由定时任务（例如巡检）负责抓取，而不由Prometheus采集。一些特别重要的Catalog信息，例如pg_class中的一些信息，也会转换为指标被Prometheus所采集。

小结

了解了Pigsty指标后，不妨了解一下Pigsty的 报警系统 是如何将这些指标数据用于实际生产用途的。

3.5 - 报警规则

报警对于日常故障响应，提高系统可用性至关重要。

漏报会导致可用性降低，误报会导致敏感性下降，有必要对报警规则进行审慎的设计。

• 合理定义报警级别，以及相应的处理流程
• 合理定义报警指标，去除重复报警项，补充缺失报警项
• 根据历史监控数据科学配置报警阈值，减少误报率。
• 合理疏理特例规则，消除维护工作，ETL，离线查询导致的误报。

报警分类学

按紧急程度分类

• P0：FATAL：产生重大场外影响的事故，需要紧急介入处理。例如主库宕机，复制中断。（严重事故）

• P1：ERROR：场外影响轻微，或有冗余处理的事故，需要在分钟级别内进行响应处理。（事故）

• P2：WARNING：即将产生影响，放任可能在小时级别内恶化，需在小时级别进行响应。（关注事件）

• P3：NOTICE：需要关注，不会有即时的影响，但需要在天级别内进行响应。（偏差现象）

按报警层次分类

• 系统级：操作系统，硬件资源的报警。DBA只会特别关注CPU与磁盘报警，其他由运维负责。
• 数据库级：数据库本身的报警，DBA重点关注。由PG，PGB，Exporter本身的监控指标产生。
• 应用级：应用报警由业务方自己负责，但DBA会为QPS，TPS，Rollback，Seasonality等业务指标设置报警

按指标类型分类

• 错误：PG Down, PGB Down, Exporter Down, 流复制中断，单集簇多主
• 流量：QPS，TPS，Rollback，Seasonaility
• 延迟: 平均响应时间，复制延迟
• 饱和度：连接堆积，闲事务数，CPU，磁盘，年龄（事务号），缓冲区

报警可视化

Pigsty使用条状图呈现报警信息。横轴代表时间段，一段色条代表报警事件。只有处于 激发（Firing） 状态的报警才会显示在报警图表中。

报警规则详解

报警规则按类型可粗略分为四类：错误，延迟，饱和度，流量。其中：

• 错误：主要关注各个组件的存活性（Aliveness），以及网络中断，脑裂等异常情况，级别通常较高（P0|P1）。
• 延迟：主要关注查询响应时间，复制延迟，慢查询，长事务。
• 饱和度：主要关注CPU，磁盘（这两个属于系统监控但对于DB非常重要所以纳入），连接池排队，数据库后端连接数，年龄（本质是可用事物号的饱和度），SSD寿命等。
• 流量：QPS，TPS，Rollback（流量通常与业务指标有关属于业务监控范畴，但因为对于DB很重要所以纳入），QPS的季节性，TPS的突增。

错误报警

Postgres实例宕机区分主从，主库宕机触发P0报警，从库宕机触发P1报警。两者都需要立即介入，但从库通常有多个实例，且可以降级到主库上查询，有着更高的处理余量，所以从库宕机定为P1。

# primary|master instance down for 1m triggers a P0 alert
- alert: PG_PRIMARY_DOWN
  expr: pg_up{instance=~'.*master.*'}
  for: 1m
  labels:
    team: DBA
    urgency: P0
  annotations:
    summary: "P0 Postgres Primary Instance Down: {{$labels.instance}}"
    description: "pg_up = {{ $value }} {{$labels.instance}}"

# standby|slave instance down for 1m triggers a P1 alert
- alert: PG_STANDBY_DOWN
  expr: pg_up{instance!~'.*master.*'}
  for: 1m
  labels:
    team: DBA
    urgency: P1
  annotations:
    summary: "P1 Postgres Standby Instance Down: {{$labels.instance}}"
    description: "pg_up = {{ $value }} {{$labels.instance}}"

Pgbouncer实例因为与Postgres实例一一对应，其存活性报警规则与Postgres统一。

# primary pgbouncer down for 1m triggers a P0 alert
- alert: PGB_PRIMARY_DOWN
  expr: pgbouncer_up{instance=~'.*master.*'}
  for: 1m
  labels:
    team: DBA
    urgency: P0
  annotations:
    summary: "P0 Pgbouncer Primary Instance Down: {{$labels.instance}}"
    description: "pgbouncer_up = {{ $value }} {{$labels.instance}}"

# standby pgbouncer down for 1m triggers a P1 alert
- alert: PGB_STANDBY_DOWN
  expr: pgbouncer_up{instance!~'.*master.*'}
  for: 1m
  labels:
    team: DBA
    urgency: P1
  annotations:
    summary: "P1 Pgbouncer Standby Instance Down: {{$labels.instance}}"
    description: "pgbouncer_up = {{ $value }} {{$labels.instance}}"

Prometheus Exporter的存活性定级为P1，虽然Exporter宕机本身并不影响数据库服务，但这通常预示着一些不好的情况，而且监控数据的缺失也会产生某些相应的报警。Exporter的存活性是通过Prometheus自己的up指标检测的，需要注意某些单实例多DB的特例。

# exporter down for 1m triggers a P1 alert
- alert: PG_EXPORTER_DOWN
  expr: up{port=~"(9185|9127)"} == 0
  for: 1m
  labels:
    team: DBA
    urgency: P1
  annotations:
    summary: "P1 Exporter Down: {{$labels.instance}} {{$labels.port}}"
    description: "port = {{$labels.port}}, {{$labels.instance}}"

所有存活性检测的持续时间阈值设定为1分钟，对15s的默认采集周期而言是四个样本点。常规的重启操作通常不会触发存活性报警。

延迟报警

与复制延迟有关的报警有三个：复制中断，复制延迟高，复制延迟异常，分别定级为P1, P2, P3

• 其中复制中断是一种错误，使用指标：pg_repl_state_count{state="streaming"}进行判断，当前streaming状态的从库如果数量发生负向变动，则触发break报警。walsender会决定复制的状态，从库直接断开会产生此现象，缓冲区出现积压时会从streaming进入catchup状态也会触发此报警。此外，采用-Xs手工制作备份结束时也会产生此报警，此报警会在10分钟后自动Resolve。复制中断会导致客户端读到陈旧的数据，具有一定的场外影响，定级为P1。

• 复制延迟可以使用延迟时间或者延迟字节数判定。以延迟字节数为权威指标。常规状态下，复制延迟时间在百毫秒量级，复制延迟字节在百KB量级均属于正常。目前采用的是5s,15s的时间报警阈值。根据历史经验数据，这里采用了时间8秒与字节32MB的阈值，大致报警频率为每天个位数个。延迟时间更符合直觉，所以采用8s的P2报警，但并不是所有的从库都能有效取到该指标所以使用32MB的字节阈值触发P3报警补漏。

• 特例：antispam,stats,coredb均经常出现复制延迟。

      # replication break for 1m triggers a P0 alert. auto-resolved after 10 minutes.
      - alert: PG_REPLICATION_BREAK
        expr: pg_repl_state_count{state="streaming"} - (pg_repl_state_count{state="streaming"} OFFSET 10m) < 0
        for: 1m
        labels:
          team: DBA
          urgency: P0
        annotations:
          summary: "P0 Postgres Streaming Replication Break: {{$labels.instance}}"
          description: "delta = {{ $value }} {{$labels.instance}}"

      # replication lag greater than 8 second for 3m triggers a P1 alert
      - alert: PG_REPLICATION_LAG
        expr: pg_repl_replay_lag{application_name="walreceiver"} > 8
        for: 3m
        labels:
          team: DBA
          urgency: P1
        annotations:
          summary: "P1 Postgres Replication Lagged: {{$labels.instance}}"
          description: "lag = {{ $value }} seconds, {{$labels.instance}}"

      # replication diff greater than 32MB for 5m triggers a P3 alert
      - alert: PG_REPLICATOIN_DIFF
        expr: pg_repl_lsn{application_name="walreceiver"} - pg_repl_replay_lsn{application_name="walreceiver"} > 33554432
        for: 5m
        labels:
          team: DBA
          urgency: P3
        annotations:
          summary: "P3 Postgres Replication Diff Deviant: {{$labels.instance}}"
          description: "delta = {{ $value }} {{$labels.instance}}"

饱和度报警

饱和度指标主要资源，包含很多系统级监控的指标。主要包括：CPU，磁盘（这两个属于系统监控但对于DB非常重要所以纳入），连接池排队，数据库后端连接数，年龄（本质是可用事物号的饱和度），SSD寿命等。

堆积检测

堆积主要包含两类指标，一方面是PG本身的后端连接数与活跃连接数，另一方面是连接池的排队情况。

PGB排队是决定性的指标，它代表用户端可感知的阻塞已经出现，因此，配置排队超过15持续1分钟触发P0报警。

# more than 8 client waiting in queue for 1 min triggers a P0 alert
- alert: PGB_QUEUING
  expr: sum(pgbouncer_pool_waiting_clients{datname!="pgbouncer"}) by (instance,datname) > 8
  for: 1m
  labels:
    team: DBA
    urgency: P0
  annotations:
    summary: "P0 Pgbouncer {{ $value }} Clients Wait in Queue: {{$labels.instance}}"
    description: "waiting clients = {{ $value }} {{$labels.instance}}"

后端连接数是一个重要的报警指标，如果后端连接持续达到最大连接数，往往也意味着雪崩。连接池的排队连接数也能反映这种情况，但不能覆盖应用直连数据库的情况。后端连接数的主要问题是它与连接池关系密切，连接池在短暂堵塞后会迅速打满后端连接，但堵塞恢复后这些连接必须在默认约10min的Timeout后才被释放。因此收到短暂堆积的影响较大。同时外晚上1点备份时也会出现这种情况，容易产生误报。

注意后端连接数与后端活跃连接数不同，目前报警使用的是活跃连接数。后端活跃连接数通常在0～1，一些慢库在十几左右，离线库可能会达到20～30。但后端连接/进程数（不管活跃不活跃），通常均值可达50。后端连接数更为直观准确。

对于后端连接数，这里使用两个等级的报警：超过90持续3分钟P1，以及超过80持续10分钟P2，考虑到通常数据库最大连接数为100。这样做可以以尽可能低的误报率检测到雪崩堆积。

# num of backend exceed 90 for 3m
- alert: PG_BACKEND_HIGH
  expr: sum(pg_db_numbackends) by (node) > 90
  for: 3m
  labels:
    team: DBA
    urgency: P1
  annotations:
    summary: "P1 Postgres Backend Number High: {{$labels.instance}}"
    description: "numbackend = {{ $value }} {{$labels.instance}}"

# num of backend exceed 80 for 10m (avoid pgbouncer jam false alert)
- alert: PG_BACKEND_WARN
  expr: sum(pg_db_numbackends) by (node) > 80
  for: 10m
  labels:
    team: DBA
    urgency: P2
  annotations:
    summary: "P2 Postgres Backend Number Warn: {{$labels.instance}}"
    description: "numbackend = {{ $value }} {{$labels.instance}}"

空闲事务

目前监控使用IDEL In Xact的绝对数量作为报警条件，其实 Idle In Xact的最长持续时间可能会更有意义。因为这种现象其实已经被后端连接数覆盖了。长时间的空闲是我们真正关注的，因此这里使用所有空闲事务中最高的闲置时长作为报警指标。设置3分钟为P2报警阈值。经常出现IDLE的非Offline库有：moderation, location, stats,sms, device, moderationdevice

# max idle xact duration exceed 3m
- alert: PG_IDLE_XACT
  expr: pg_activity_max_duration{instance!~".*offline.*", state=~"^idle in transaction.*"} > 180
  for: 3m
  labels:
    team: DBA
    urgency: P2
  annotations:
    summary: "P2 Postgres Long Idle Transaction: {{$labels.instance}}"
    description: "duration = {{ $value }} {{$labels.instance}}"

资源报警

CPU, 磁盘，AGE

默认清理年龄为2亿，超过10Y报P1，既留下了充分的余量，又不至于让人忽视。

# age wrap around (progress in half 10Y) triggers a P1 alert
- alert: PG_XID_WRAP
  expr: pg_database_age{} > 1000000000
  for: 3m
  labels:
    team: DBA
    urgency: P1
  annotations:
    summary: "P1 Postgres XID Wrap Around: {{$labels.instance}}"
    description: "age = {{ $value }} {{$labels.instance}}"

磁盘和CPU由运维配置，不变

流量

因为各个业务的负载情况不一，为流量指标设置绝对值是相对困难的。这里只对TPS和Rollback设置绝对值指标。而且较为宽松。

Rollback OPS超过4则发出P3警告，TPS超过24000发P2，超过30000发P1

# more than 30k TPS lasts for 1m triggers a P1 (pgbouncer bottleneck)
- alert: PG_TPS_HIGH
  expr: rate(pg_db_xact_total{}[1m]) > 30000
  for: 1m
  labels:
    team: DBA
    urgency: P1
  annotations:
    summary: "P1 Postgres TPS High: {{$labels.instance}} {{$labels.datname}}"
    description: "TPS = {{ $value }} {{$labels.instance}}"

# more than 24k TPS lasts for 3m triggers a P2
- alert: PG_TPS_WARN
  expr: rate(pg_db_xact_total{}[1m]) > 24000
  for: 3m
  labels:
    team: DBA
    urgency: P2
  annotations:
    summary: "P2 Postgres TPS Warning: {{$labels.instance}} {{$labels.datname}}"
    description: "TPS = {{ $value }} {{$labels.instance}}"

# more than 4 rollback per seconds lasts for 5m
- alert: PG_ROLLBACK_WARN
  expr: rate(pg_db_xact_rollback{}[1m]) > 4
  for: 5m
  labels:
    team: DBA
    urgency: P2
  annotations:
    summary: "P2 Postgres Rollback Warning: {{$labels.instance}}"
    description: "rollback per sec = {{ $value }} {{$labels.instance}}"

QPS的指标与业务高度相关，因此不适合配置绝对值，可以为QPS突增配置一个报警项

短时间（和10分钟）前比突增30%会触发一个P2警报，同时避免小QPS下的突发流量，设置一个绝对阈值10k

# QPS > 10000 and have a 30% inc for 3m triggers P2 alert
- alert: PG_QPS_BURST
  expr: sum by(datname,instance)(rate(pgbouncer_stat_total_query_count{datname!="pgbouncer"}[1m]))/sum by(datname,instance) (rate(pgbouncer_stat_total_query_count{datname!="pgbouncer"}[1m] offset 10m)) > 1.3 and sum by(datname,instance) (rate(pgbouncer_stat_total_query_count{datname!="pgbouncer"}[1m])) > 10000
  for: 3m
  labels:
    team: DBA
    urgency: P1
  annotations:
    summary: "P2 Pgbouncer QPS Burst 30% and exceed 10000: {{$labels.instance}}"
    description: "qps = {{ $value }} {{$labels.instance}}"

Prometheus报警规则

完整的报警规则详见：参考-报警规则

4 - 供给方案

所谓供给方案（Provisioning Solution），指的是一套向用户交付数据库服务与监控系统的系统。

供给方案不是数据库，而是数据库工厂：

用户向供给系统提交一份配置，供给系统便会按照用户所需的规格在环境中创建出所需的数据库集群来。

这比较类似于向Kubernetes提交YAML文件，创建所需的各类资源。

定义数据库集群

例如，以下配置信息声明了一套名为pg-test的PostgreSQL数据库集群。

#-----------------------------
# cluster: pg-test
#-----------------------------
pg-test: # define cluster named 'pg-test'
  # - cluster members - #
  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_host: node-2}
    10.10.10.13: {pg_seq: 3, pg_role: offline, ansible_host: node-3}

  # - cluster configs - #
  vars:
    # basic settings
    pg_cluster: pg-test                 # define actual cluster name
    pg_version: 13                      # define installed pgsql version
    node_tune: tiny                     # tune node into oltp|olap|crit|tiny mode
    pg_conf: tiny.yml                   # tune pgsql into oltp/olap/crit/tiny mode

    # business users, adjust on your own needs
    pg_users:
      - name: test                      # example production user have read-write access
        password: test                  # example user's password
        roles: [dbrole_readwrite]       # dborole_admin|dbrole_readwrite|dbrole_readonly|dbrole_offline
        pgbouncer: true                 # production user that access via pgbouncer
        comment: default test user for production usage

    pg_databases:                       # create a business database 'test'
      - name: test                      # use the simplest form

    pg_default_database: test           # default database will be used as primary monitor target

    # proxy settings
    vip_mode: l2                        # enable/disable vip (require members in same LAN)
    vip_address: 10.10.10.3             # virtual ip address
    vip_cidrmask: 8                     # cidr network mask length
    vip_interface: eth1                 # interface to add virtual ip

当执行 数据库供给 脚本 ./pgsql.yml 时，供给系统会根据清单中的定义，在10.10.10.11，10.10.10.12，10.10.10.13这三台机器上生成一主两从的PostgreSQL集群pg-test。并创建名为test的用户与数据库。同时，Pigsty还会根据要求，声明一个10.10.10.3的VIP绑定在集群的主库上面。结构如下图所示。

定义基础设施

用户能够定义的不仅仅是数据库集群，还包括了整个基础设施。

Pigsty通过154个变量实现了对数据库运行时环境的完整表述。

详细的可配置项，请参考 配置指南

供给方案的职责

供给方案通常只负责集群的创建。一旦集群创建完毕，日常的管理应当由管控平台负责。

尽管如此，Pigsty目前不包含管控平台部分，因此也提供了简单的资源回收销毁脚本，并亦可用于资源的更新与管理。但须知此并非供给方案的本职工作。

4.1 - 数据库接入

Pigsty提供了丰富的接入方式，用户可以根据自己的基础设施情况与喜好自行选择接入模式。

数据库访问方式

用户可以通过多种方式访问数据库服务。

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

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

如何访问数据库，最终取决于数据库所使用的流量接入方案。

典型接入方案

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

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高可用。

方案示意

L2 VIP + Haproxy

方案简介

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

集群中的Haproxy采用Node Port的方式统一对外暴露 服务。每个Haproxy都是幂等的实例，提供完整的负载均衡与服务分发功能。而Haproxy本身的可用性则通过L2 VIP来保证。

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

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

方案优越性

• 无单点，高可用

• VIP固定绑定至主库，可以灵活访问

方案局限性

• 多一跳

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

• 所有候选主库必须位于同一二层网络。

  作为另一种备选变体，用户也可以通过使用L4 VIP绕开此限制，但相比L2 VIP会额外多一跳。

方案示意

L4 VIP + Haproxy

方案简介

接入方案1/2的另一种变体，通过L4 VIP确保Haproxy的高可用

方案优越性

• 无单点，高可用
• 可以同时使用所有的Haproxy实例，均匀承载流量。
• 所有候选主库不需要位于同一二层网络。
• 可以操作单一VIP完成流量切换（如果同时使用了多个Haproxy，不需要逐个调整）

方案局限性

• 多两跳，较为浪费，如果有条件可以直接使用方案4: L4 VIP直接接入。
• Client IP地址丢失，部分HBA策略无法正常生效

方案示意

L4 VIP

方案简介

大规模高性能生产环境建议使用 L4 VIP接入（FullNAT，DPVS）

方案优越性

• 性能好，吞吐量大
• 可以通过toa模块获取正确的客户端IP地址，HBA可以完整生效。

方案局限性

• 仍然多一条。
• 需要依赖外部基础设施，部署复杂。
• 未启用toa内核模块时，仍然会丢失客户端IP地址。
• 没有Haproxy屏蔽主从差异，集群中的每个节点不再“幂等”。

方案示意

Consul DNS

方案简介

L2 VIP并非总是可用，特别是所有候选主库必须位于同一二层网络的要求可能不一定能满足。

在这种情况下，可以使用DNS解析代替L2 VIP，进行

方案优越性

• 少一跳

方案局限性

• 依赖Consul DNS
• 用户需要合理配置DNS缓存策略

方案示意

Static DNS

方案简介

传统静态DNS接入方式

方案优越性

• 少一跳
• 实施简单

方案局限性

• 没有灵活性
• 主从切换时容易导致流量损失

方案示意

IP

方案简介

采用智能客户端直连数据库IP接入

方案优越性

• 直连数据库/连接池，少一条
• 不依赖额外组件进行主从区分，降低系统复杂性。

方案局限性

• 灵活性太差，集群扩缩容繁琐。

方案示意

4.2 - 数据库服务

服务（Service），是数据库集群对外提供功能的形式。通常来说，一个数据库集群至少应当提供两种服务：

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

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

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

默认服务

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

Primary服务

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

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

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

- 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

Replica服务

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

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

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

# 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`]"   # primary are used as backup server in replica service

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 }}-{{ service.name }}
  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 }}_replica
  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 进行定义。前者用于定义整个环境中通用的服务，后者用于定义集群特定的额外服务。两者都是由服务定义组成的数组，Pigsty默认服务的定义如下所示：

# 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

# 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`]"   # primary are used as backup server in replica service

# default service will route {ip|name}:5436 to primary postgres (5436->5432 primary)
- name: default           # service's actual name is {{ pg_cluster }}-{{ service.name }}
  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 service will route {ip|name}:5438 to offline postgres (5438->5432 offline)
- name: offline           # service name {{ pg_cluster }}_replica
  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

必选项目

• 名称（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）的专有配置项

4.3 - 高可用

Pigsty创建的数据库集群是分布式、高可用的数据库集群。

从效果上讲，只要集群中有任意实例存活，集群就可以对外提供完整的读写服务与只读服务。

数据库集群中的每个数据库实例在使用上都是幂等的，任意实例都可以通过内建负载均衡组件提供完整的读写服务。

数据库集群可以自动进行故障检测与主从切换，普通故障能在几秒到几十秒内自愈，且期间只读流量不受影响。

高可用

两个核心场景：Switchover，Failover

四个核心问题：故障检测，Fencing，选主，流量切换

关于高可用的核心场景演练，请参考 高可用演练 一节。

基于Patroni的高可用方案

基于 Patroni 的高可用方案部署简单，不需要使用特殊硬件，具有大量实际生产使用案例背书。

Pigsty的高可用方案基于Patroni，vip-manager，haproxy

Patroni基于DCS（etcd/consul/zookeeper）达成选主共识。

Patroni的故障检测采用心跳包保活，DCS租约机制实现。主库持有租约，秦失其鹿，则天下共逐之。

Patroni的Fencing基于Linux内核模块watchdog。

Patroni提供了主从健康检查，便于与外部负载均衡器相集成。

基于Haproxy与VIP的接入层方案

Pigsty沙箱默认使用基于L2 VIP与Haproxy的接入层方案。Pigsty提供多种可选的 数据库接入 方式。

Haproxy幂等地部署在集群的每个实例上，任何一个或多个Haproxy实例都可以作为集群的负载均衡器。

Haproxy采用类似Node Port的方式对外暴露服务，默认情况下，5433端口提供集群的读写服务，而5434端口提供集群的只读服务。

Haproxy本身的高可用性可通过以下几种方式达成：

• 使用智能客户端，利用Consul提供的DNS或服务发现机制连接至数据库。
• 使用智能客户端，利用Multi-Host特性填入集群中的所有实例。
• 使用绑定在Haproxy前的VIP（2层或4层）
• 使用外部负载均衡器保证
• 使用DNS轮询解析至多个Haproxy，客户端会在建连失败后重新执行DNS解析并重试。

Patroni在故障时的行为表现

合理配置Patroni可以应对绝大多数故障。不过DCS Down这种场景（Consul/Etcd宕机或网络不可达）会导致所有生产数据库集群不可写入，需要特别关注。必须确保DCS的可用性高于数据库的可用性。

Known Issue

请尽量确保服务器的时间同步服务先于Patroni启动。

4.4 - 目录结构

以下参数与Pigsty目录结构相关

• pg_dbsu_home：Postgres默认用户的家目录，默认为/var/lib/pgsql
• pg_bin_dir：Postgres二进制目录，默认为/usr/pgsql/bin/
• pg_data：Postgres数据库目录，默认为/pg/data
• pg_fs_main：Postgres主数据盘挂载点，默认为/export
• pg_fs_bkup：Postgres备份盘挂载点，默认为/var/backups（可选，也可以选择备份到主数据盘上）

概览

#------------------------------------------------------------------------------
# Create Directory
#------------------------------------------------------------------------------
# this assumes that
#   /pg is shortcut for postgres home
#   {{ pg_fs_main }} contains the main data             (MUST ALREADY MOUNTED)
#   {{ pg_fs_bkup }} contains archive and backup data   (MUST ALREADY MOUNTED)
#   cluster-version is the default parent folder for pgdata (e.g pg-test-12)
#------------------------------------------------------------------------------
# default variable:
#     pg_fs_main = /export           fast ssd
#     pg_fs_bkup = /var/backups      cheap hdd
#
#     /pg      -> /export/postgres/pg-test-12
#     /pg/data -> /export/postgres/pg-test-12/data
#------------------------------------------------------------------------------
- name: Create postgresql directories
  tags: pg_dir
  become: yes
  block:
    - name: Make sure main and backup dir exists
      file: path={{ item }} state=directory owner=root mode=0777
      with_items:
        - "{{ pg_fs_main }}"
        - "{{ pg_fs_bkup }}"

    # pg_cluster_dir:    "{{ pg_fs_main }}/postgres/{{ pg_cluster }}-{{ pg_version }}"
    - name: Create postgres directory structure
      file: path={{ item }} state=directory owner={{ pg_dbsu }} group=postgres mode=0700
      with_items:
        - "{{ pg_fs_main }}/postgres"
        - "{{ pg_cluster_dir }}"
        - "{{ pg_cluster_dir }}/bin"
        - "{{ pg_cluster_dir }}/log"
        - "{{ pg_cluster_dir }}/tmp"
        - "{{ pg_cluster_dir }}/conf"
        - "{{ pg_cluster_dir }}/data"
        - "{{ pg_cluster_dir }}/meta"
        - "{{ pg_cluster_dir }}/stat"
        - "{{ pg_cluster_dir }}/change"
        - "{{ pg_backup_dir }}/postgres"
        - "{{ pg_backup_dir }}/arcwal"
        - "{{ pg_backup_dir }}/backup"
        - "{{ pg_backup_dir }}/remote"

PG二进制目录结构

在RedHat/CentOS上，默认的Postgres发行版安装位置为

/usr/pgsql-${pg_version}/

安装剧本会自动创建指向当前安装版本的软连接，例如，如果安装了13版本的Postgres，则有：

/usr/pgsql -> /usr/pgsql-13

因此，默认的pg_bin_dir为/usr/pgsql/bin/，该路径会在/etc/profile.d/pgsql.sh中添加至所有用户的PATH环境变量中。

PG数据目录结构

Pigsty假设用于部署数据库实例的单个节点上至少有一块主数据盘（pg_fs_main），以及一块可选的备份数据盘（pg_fs_bkup）。通常主数据盘是高性能SSD，而备份盘是大容量廉价HDD。

#------------------------------------------------------------------------------
# Create Directory
#------------------------------------------------------------------------------
# this assumes that
#   /pg is shortcut for postgres home
#   {{ pg_fs_main }} contains the main data             (MUST ALREADY MOUNTED)
#   {{ pg_fs_bkup }} contains archive and backup data   (MAYBE ALREADY MOUNTED)
#   {{ pg_cluster }}-{{ pg_version }} is the default parent folder 
#    for pgdata (e.g pg-test-12)
#------------------------------------------------------------------------------
# default variable:
#     pg_fs_main = /export           fast ssd
#     pg_fs_bkup = /var/backups      cheap hdd
#
#     /pg      -> /export/postgres/pg-test-12
#     /pg/data -> /export/postgres/pg-test-12/data

PG数据库集簇目录结构

# basic
{{ pg_fs_main }}     /export                      # contains all business data (pg,consul,etc..)
{{ pg_dir_main }}    /export/postgres             # contains postgres main data
{{ pg_cluster_dir }} /export/postgres/pg-test-13  # contains cluster `pg-test` data (of version 13)
                     /export/postgres/pg-test-13/bin            # binary scripts
                     /export/postgres/pg-test-13/log            # misc logs
                     /export/postgres/pg-test-13/tmp            # tmp, sql files, records
                     /export/postgres/pg-test-13/conf           # configurations
                     /export/postgres/pg-test-13/data           # main data directory
                     /export/postgres/pg-test-13/meta           # identity information
                     /export/postgres/pg-test-13/stat           # stats information
                     /export/postgres/pg-test-13/change         # changing records

{{ pg_fs_bkup }}     /var/backups                      # contains all backup data (pg,consul,etc..)
{{ pg_dir_bkup }}    /var/backups/postgres             # contains postgres backup data
{{ pg_backup_dir }}  /var/backups/postgres/pg-test-13  # contains cluster `pg-test` backup (of version 13)
                     /var/backups/postgres/pg-test-13/backup   # base backup
                     /var/backups/postgres/pg-test-13/arcwal   # WAL archive
                     /var/backups/postgres/pg-test-13/remote   # mount NFS/S3 remote resources here

# links
/pg             -> /export/postgres/pg-test-12               # pg root link
/pg/data        -> /export/postgres/pg-test-12/data          # real data dir
/pg/backup      -> /var/backups/postgres/pg-test-13/backup   # base backup
/pg/arcwal      -> /var/backups/postgres/pg-test-13/arcwal   # WAL archive
/pg/remote      -> /var/backups/postgres/pg-test-13/remote   # mount NFS/S3 remote resources here

Pgbouncer配置文件结构

Pgbouncer使用Postgres用户运行，配置文件位于/etc/pgbouncer。配置文件包括：

• pgbouncer.ini，主配置文件
• userlist.txt：列出连接池中的用户
• pgb_hba.conf：列出连接池用户的访问权限
• database.txt：列出连接池中的数据库

4.5 - 访问控制

PostgreSQL提供了两类访问控制机制：认证（Authentication） 与 权限（Privileges）

Pigsty带有基本的访问控制模型，足以覆盖绝大多数应用场景。

用户体系

Pigsty的默认权限系统包含四个默认用户与四类默认角色 。

用户可以通过修改 pg_default_roles 来修改默认用户的名字，但默认角色的名字不建议新用户自行修改。

默认角色

Pigsty带有四个默认角色：

• 只读角色（dbrole_readonly）：只读
• 读写角色（dbrole_readwrite）：读写，继承dbrole_readonly
• 管理角色（dbrole_admin）：执行DDL变更，继承dbrole_readwrite
• 离线角色（dbrole_offline）：只读，用于执行慢查询/ETL/交互查询，仅允许在特定实例上访问。

默认用户

Pigsty带有四个默认用户：

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

相关配置

以下是8个默认用户/角色的相关变量

默认用户有专用的用户名与密码配置选项，会覆盖 pg_default_roles中的选项。因此无需在其中为默认用户配置密码。

出于安全考虑，不建议为DBSU配置密码，故pg_dbsu没有专门的密码配置项。如有需要，用户可以在pg_default_roles中为超级用户指定密码。

# - 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_admin               # system admin user
pg_admin_password: DBUser.Admin               # system admin password

# - default roles - #
# chekc http://pigsty.cc/zh/docs/concepts/provision/acl/ for more detail
pg_default_roles:

  # common production readonly user
  - name: dbrole_readonly                 # production read-only roles
    login: false
    comment: role for global readonly access

  # common production read-write user
  - name: dbrole_readwrite                # production read-write roles
    login: false
    roles: [dbrole_readonly]             # read-write includes read-only access
    comment: role for global read-write access

  # offline have same privileges as readonly, but with limited hba access on offline instance only
  # for the purpose of running slow queries, interactive queries and perform ETL tasks
  - name: dbrole_offline
    login: false
    comment: role for restricted read-only access (offline instance)

  # admin have the privileges to issue DDL changes
  - name: dbrole_admin
    login: false
    bypassrls: true
    comment: role for object creation
    roles: [dbrole_readwrite,pg_monitor,pg_signal_backend]

  # dbsu, name is designated by `pg_dbsu`. It's not recommend to set password for dbsu
  - name: postgres
    superuser: true
    comment: system superuser

  # default replication user, name is designated by `pg_replication_username`, and password is set by `pg_replication_password`
  - name: replicator
    replication: true
    roles: [pg_monitor, dbrole_readonly]
    comment: system replicator

  # default replication user, name is designated by `pg_monitor_username`, and password is set by `pg_monitor_password`
  - name: dbuser_monitor
    connlimit: 16
    comment: system monitor user
    roles: [pg_monitor, dbrole_readonly]

  # default admin user, name is designated by `pg_admin_username`, and password is set by `pg_admin_password`
  - name: dbuser_admin
    bypassrls: true
    comment: system admin user
    roles: [dbrole_admin]

  # default stats user, for ETL and slow queries
  - name: dbuser_stats
    password: DBUser.Stats
    comment: business offline user for offline queries and ETL
    roles: [dbrole_offline]

Pgbouncer用户

Pgbouncer的操作系统用户将与数据库超级用户保持一致，默认都使用postgres。

Pigsty默认会使用Postgres管理用户作为Pgbouncer的管理用户，使用Postgres的监控用户同时作为Pgbouncer的监控用户。

Pgbouncer的用户权限通过/etc/pgbouncer/pgb_hba.conf进行控制。

Pgbounce的用户列表通过/etc/pgbouncer/userlist.txt文件进行控制。

定义用户时，只有显式添加pgbouncer: true 的用户，才会被加入到Pgbouncer的用户列表中。

用户的定义

Pigsty中的用户可以通过以下两个参数进行声明，两者使用同样的形式：

• pg_default_roles：默认角色与用户
• pg_users：业务用户

用户的创建

Pigsty的用户可以通过 pgsql-createuser.yml 剧本完成创建

权限模型

默认情况下，角色拥有的权限如下所示：

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

其他业务用户默认都应当属于四种默认角色之一：只读，读写，管理员，离线访问。

所有用户都可以访问所有模式，只读用户可以读取所有表，读写用户可以对所有表进行DML操作，管理员可以执行DDL变更操作。离线用户与只读用户类似，但只允许访问pg_role == 'offline' 或带有 pg_offline_query = true 的实例。

数据库权限

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

pg_databases:
  - name: meta                      # name is the only required field for a database
    owner: postgres                 # optional, database owner
    template: template1             # optional, template1 by default
    encoding: UTF8                  # optional, UTF8 by default
    locale: C                       # optional, C by default
    allowconn: true                 # optional, true by default, false disable connect at all
    revokeconn: false               # optional, false by default, true revoke connect from public # (only default user and owner have connect privilege on database)
    tablespace: pg_default          # optional, 'pg_default' is the default tablespace
    connlimit: -1                   # optional, connection limit, -1 or none disable limit (default)
    extensions:                     # optional, extension name and where to create
      - {name: postgis, schema: public}
    parameters:                     # optional, extra parameters with ALTER DATABASE
      enable_partitionwise_join: true
    pgbouncer: true                 # optional, add this database to pgbouncer list? true by default
    comment: pigsty meta database   # optional, comment string for database

默认情况下，如果数据库没有配置属主，那么数据库超级用户dbsu将会作为数据库的默认OWNER，否则将为指定用户。

默认情况下，所有用户都具有对新创建数据库的CONNECT 权限，如果希望回收该权限，设置 revokeconn == true，则该权限会被回收。只有默认用户（dbsu|admin|monitor|replicator）与数据库的属主才会被显式赋予CONNECT权限。同时，admin|owner将会具有CONNECT权限的GRANT OPTION，可以将CONNECT权限转授他人。

如果希望实现不同数据库之间的访问隔离，可以为每一个数据库创建一个相应的业务用户作为owner，并全部设置revokeconn选项。这种配置对于多租户实例尤为实用。

创建新对象

默认情况下，出于安全考虑，Pigsty会撤销PUBLIC用户在数据库下CREATE新模式的权限，同时也会撤销PUBLIC用户在public模式下创建新关系的权限。数据库超级用户与管理员不受此限制，他们总是可以在任何地方执行DDL变更。

Pigsty非常不建议使用业务用户执行DDL变更，因为PostgreSQL的ALTER DEFAULT PRIVILEGE仅针对“由特定用户创建的对象”生效，默认情况下超级用户postgres和dbuser_admin创建的对象拥有默认的权限配置，如果用户希望授予业务用户dbrole_admin，请在使用该业务管理员执行DDL变更时首先执行：

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

在数据库中创建对象的权限与用户是否为数据库属主无关，这只取决于创建该用户时是否为该用户赋予管理员权限。

pg_users:
  - {name: test1, password: xxx , groups: [dbrole_readwrite]}  # 不能创建Schema与对象
  - {name: test2, password: xxx , groups: [dbrole_admin]}      # 可以创建Schema与对象

认证模型

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规则：

• 超级用户通过本地操作系统认证访问
• 其他用户可以从本地用密码访问
• 复制用户可以从局域网段通过密码访问
• 监控用户可以通过本地访问
• 所有人都可以在元节点上使用密码访问
• 管理员可以从局域网通过密码访问
• 所有人都可以从内网通过密码访问
• 读写用户（生产业务账号）可以通过本地（链接池）访问 （部分访问控制转交链接池处理）
• 在从库上：只读用户（个人）可以从本地（链接池）访问。 （意味主库上拒绝只读用户连接）
• 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
#===========================================================