历史文档 on PIGSTY

Pigsty v1.5.1 文档

Mon, 01 Jan 0001 00:00:00 +0000

v1.5.1 中文文档

开箱即用的开源数据库发行版

最新版本: v1.5.1 | Github项目 | 公开Demo

文档地址: 英文文档 | 中文文档 | Github Pages文档

Pigsty是什么？

Pigsty入门指南

Mon, 01 Jan 0001 00:00:00 +0000

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

新用户

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

Pigsty 快速上手

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

单机安装

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

Pigsty亮点特性

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

FAQ: 常见问题

Mon, 01 Jan 0001 00:00:00 +0000

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

准备

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

概念导览

Mon, 01 Jan 0001 00:00:00 +0000

Index

模块	概念	部署	配置	剧本
`INFRA`	概念: INFRA	部署: INFRA	配置: INFRA	剧本: INFRA
`NODES`	概念: NODES	部署: NODES	配置: NODES	剧本: NODES
`PGSQL`	概念: PGSQL	部署: PGSQL	配置: PGSQL	剧本: PGSQL
`REDIS`	概念: REDIS	部署: REDIS	配置: REDIS	剧本: REDIS

Glossary

节点

架构

Mon, 01 Jan 0001 00:00:00 +0000

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

模块

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

基础设施

Mon, 01 Jan 0001 00:00:00 +0000

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

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

概念：节点

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

PGSQL 概念

Mon, 01 Jan 0001 00:00:00 +0000

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

PGSQL集群

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

Redis 概念

Mon, 01 Jan 0001 00:00:00 +0000

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

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

实体概念模型

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

PGSQL服务与接入

Mon, 01 Jan 0001 00:00:00 +0000

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

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

单机用户

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

PGSQL业务用户与数据库

Mon, 01 Jan 0001 00:00:00 +0000

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

用户

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

PGSQL 权限认证与访问控制

Mon, 01 Jan 0001 00:00:00 +0000

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

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

角色

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

Pigsty部署

Mon, 01 Jan 0001 00:00:00 +0000

部署Pigsty分为三步：部署准备，修改配置，执行剧本

Pigsty的资源准备、下载安装、部署扩容缩容均为一键傻瓜式，真正的灵魂在于配置。

准备工作

安装Pigsty前，您需要准备符合要求的资源：物理机/虚拟机节点，管理用户，下载Pigsty软件。

准备工作

Mon, 01 Jan 0001 00:00:00 +0000

如何准备Pigsty部署所需的资源：

节点置备
元节点置备
管理用户置备
软件置备
- Pigsty源代码
- Pigsty离线软件包
- Vagrant （沙箱）
- Virtualbox （沙箱）

节点置备

在部署Pigsty前，用户需要准备机器节点资源，包括至少一个元节点，与任意数量的普通节点。

沙箱环境

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty支持使用本地沙箱与云端沙箱两种方式，可用于快速在本机或云端准备标准的1/4节点演示环境。

尽管安装Pigsty已经非常简单了，但是搭建满足要求虚拟机仍然是比较费事的，您可能需要用到各类虚拟机软件。

监控系统部署

Mon, 01 Jan 0001 00:00:00 +0000

如何使用Pigsty监控已有PostgreSQL实例？

对于由Pigsty所创建的实例，所有监控组件均已自动配置妥当。但对于非Pigsty所创建的现存Pigsty实例，若希望使用Pigsty监控系统的部分对其监控，则需一些额外的配置。

PostgreSQL集群部署

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍使用Pigsty部署PostgreSQL集群的几种不同方式：PGSQL相关剧本与配置请参考相关文档。

身份参数：介绍定义标准PostgreSQL高可用集群所需的身份参数。
单机部署：定义一个单实例的PostgreSQL集群
主从集群：定义一个一主一从的标准可用性集群。
同步从库：定义一个同步复制，RPO = 0 的高一致性集群。
法定人数同步提交：定义数据一致性更高的集群：多数从库成功方返回提交。
离线从库：用于单独承载OLAP分析，ETL，交互式个人查询的专用实例
备份集群：制作现有集群的实时在线克隆，用于异地灾备或延迟从库。
延迟从库：用于应对误删表删库等软件/人为故障，比PITR更快。
级联复制：用于搭建一个集群内的级联复制，针对大量从库场景（20+），降低主库复制压力。
Citus集群部署：部署Citus分布式数据库集群
MatrixDB集群部署：部署Greenplum7/PostgreSQL12兼容的时序数据仓库。

身份参数

核心身份参数是定义 PostgreSQL 数据库集群时必须提供的信息，包括：

部署与监控Redis

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty是一个PostgreSQL发行版，也是一个通用应用运行时。您可以用它管理、部署、监控其他应用与数据库，例如Redis。

与PostgreSQL类似，部署Redis同样需要两个步骤：

MatrixDB部署与监控

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty可用于部署与监控MatrixDB（等于Greenplum 7+时序数据库)

因为目前MatrixDB使用的是PostgreSQL 12的内核，而原生Greenplum仍然使用9.6内核，因此优先使用MatrixDB替代Greenplum实现，后续将添加原生的Greenplum支持。

Pigsty剧本

Mon, 01 Jan 0001 00:00:00 +0000

了解Pigsty提供的预置剧本，功能、使用方式与注意事项。

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

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

剧本概览

剧本	功能	链接
infra	在元节点上完整安装Pigsty	`src`
`infra-demo`	一次性完整初始化四节点演示沙箱环境的特殊剧本	`src`
`infra-jupyter`	在元节点上加装可选数据分析服务组件Jupyter Lab	`src`
nodes	节点置备，将节点纳入Pigsty管理，可用于后续数据库部署	`src`
`nodes-remove`	节点移除，卸载节点DCS与监控，不再纳入Pigsty管理	`src`
pgsql	部署PostgreSQL集群，或集群扩容	`src`
`pgsql-remove`	下线PostgreSQL集群，或集群缩容	`src`
`pgsql-createuser`	创建PostgreSQL业务用户	`src`
`pgsql-createdb`	创建PostgreSQL业务数据库	`src`
`pgsql-monly`	仅监控模式，接入现存PostgreSQL实例或RDS	`src`
`pgsql-migration`	生成PostgreSQL半自动数据库迁移方案（Beta）	`src`
`pgsql-matrixdb`	复用PG角色部署一套MatrixDB数据仓库集群（Beta）	`src`
redis	部署集群/主从/Sentinel模式的Redis数据库	`src`
`redis-remove`	Redis集群/节点下线	`src`

典型使用流程如下：

剧本：INFRA

Mon, 01 Jan 0001 00:00:00 +0000

使用 infra 系列剧本在当前元节点上安装Pigsty，并加装可选功能。

剧本	功能	链接
`infra`	在元节点上完整安装Pigsty	`src`
`infra-demo`	一次性完整初始化四节点演示沙箱环境的特殊剧本	`src`
`infra-remove`	在元节点上卸载Pigsty	`src`
`infra-jupyter`	在元节点上加装可选数据分析服务组件组件Jupyter Lab	`src`

`infra`

infra.yml 剧本会在元节点 （默认为当前节点）上完成Pigsty的安装与部署。

剧本：NODES

Mon, 01 Jan 0001 00:00:00 +0000

使用 NODES 系列剧本将更多节点纳入Pigsty管理，将节点调整至配置描述的状态。

当您使用 infra.yml 在元节点上完成Pigsty的完整安装后，您可以进一步使用 nodes.yml 将更多节点添加至Pigsty中，或者使用 nodes-remove.yml 将节点从环境中移除。

剧本	功能	链接
`nodes`	节点置备，将节点纳入Pigsty管理，可用于后续数据库部署	`src`
`nodes-remove`	节点移除，卸载节点DCS与监控，不再纳入Pigsty管理	`src`

`nodes`

nodes.yml 剧本将更多节点添加至Pigsty中。该剧本需要在 元节点 上发起，针对目标节点执行。

剧本：PGSQL

Mon, 01 Jan 0001 00:00:00 +0000

使用PGSQL系列剧本，拉起定义好的高可用PostgreSQL数据库集群

剧本概览

剧本	功能	链接
`pgsql`	部署PostgreSQL集群，或集群扩容	`src`
`pgsql-remove`	下线PostgreSQL集群，或集群缩容	`src`
`pgsql-createuser`	创建PostgreSQL业务用户	`src`
`pgsql-createdb`	创建PostgreSQL业务数据库	`src`
`pgsql-monly`	仅监控模式，接入现存PostgreSQL实例或RDS	`src`
`pgsql-migration`	生成PostgreSQL半自动数据库迁移方案（Beta）	`src`
`pgsql-matrixdb`	复用PG角色部署一套MatrixDB数据仓库集群（Beta）	`src`

`pgsql`

完成了基础设施初始化后，用户可以 pgsql.yml 完成数据库集群的初始化。

剧本：REDIS

Mon, 01 Jan 0001 00:00:00 +0000

使用REDIS系列剧本，定义并拉起传统主从、集群、Sentinel模式的Redis数据库。

剧本	功能	链接
`redis`	部署集群/主从/Sentinel模式的Redis数据库	`src`
`redis-remove`	Redis集群/节点下线	`src`

`redis`

用于在节点上部署Redis集群，节点，实例。

配置Pigsty

Mon, 01 Jan 0001 00:00:00 +0000

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

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

配置：Infra

Mon, 01 Jan 0001 00:00:00 +0000

使用 INFRA剧本，部署PGSQL集群，将集群状态调整至 PGSQL配置所描述的状态。

配置Pigsty基础设施，由INFRA系列剧本使用。

基础设施配置主要处理此类问题：本地Yum源，机器节点基础服务：DNS，NTP，内核模块，参数调优，管理用户，安装软件包，DCS Server的架设，监控基础设施的安装与初始化（Grafana，Prometheus，Alertmanager），全局流量入口Nginx的配置等等。

配置：Nodes

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty提供了完整的主机置备与监控功能，执行 nodes.yml 剧本即可将对应节点配置为对应状态，并纳入Pigsty监控系统。

NODE_IDENTITY : 节点身份参数与主机名
NODE_DNS : 节点域名解析，配置静态DNS记录与动态解析
NODE_PACKAGE : 节点软件源与软件包
NODE_TUNE : 节点功能特性与参数调优
NODE_ADMIN : 节点管理员
NODE_TIME : 节点时区/NTP/定时任务
DOCKER : 节点Docker管理
NODE_EXPORTER : 节点指标暴露器
PROMTAIL : 节点日志收集组件

ID	Name	Section	Type	Level	Comment
300	`meta_node`	`NODE_IDENTITY`	bool	C	表示此节点为元节点
301	`nodename`	`NODE_IDENTITY`	string	I	指定节点实例标识
302	`node_cluster`	`NODE_IDENTITY`	string	C	节点集群名，默认名为nodes
303	`nodename_overwrite`	`NODE_IDENTITY`	bool	C	用Nodename覆盖机器HOSTNAME
304	`nodename_exchange`	`NODE_IDENTITY`	bool	C	是否在剧本节点间交换主机名
310	`node_etc_hosts`	`NODE_DNS`	string[]	C/I	同上，用于集群实例层级
311	`node_etc_hosts_default`	`NODE_DNS`	string[]	C	写入机器的静态DNS解析
312	`node_dns_method`	`NODE_DNS`	enum	C	如何配置DNS服务器？
313	`node_dns_servers`	`NODE_DNS`	string[]	C	配置动态DNS服务器列表
314	`node_dns_options`	`NODE_DNS`	string[]	C	配置/etc/resolv.conf
320	`node_repo_method`	`NODE_PACKAGE`	enum	C	节点使用Yum源的方式
321	`node_repo_remove`	`NODE_PACKAGE`	bool	C	是否移除节点已有Yum源
322	`node_repo_local_urls`	`NODE_PACKAGE`	url[]	C	本地源的URL地址
331	`node_packages`	`NODE_PACKAGE`	string[]	C	节点额外安装的软件列表
330	`node_packages_default`	`NODE_PACKAGE`	string[]	C	节点安装软件列表
332	`node_packages_meta`	`NODE_PACKAGE`	string[]	G	元节点所需的软件列表
333	`node_packages_meta_pip`	`NODE_PACKAGE`	string	G	元节点上通过pip3安装的软件包
340	`node_disable_firewall`	`NODE_TUNE`	bool	C	关闭节点防火墙
341	`node_disable_selinux`	`NODE_TUNE`	bool	C	关闭节点SELINUX
342	`node_disable_numa`	`NODE_TUNE`	bool	C	关闭节点NUMA
343	`node_disable_swap`	`NODE_TUNE`	bool	C	关闭节点SWAP
344	`node_static_network`	`NODE_TUNE`	bool	C	是否使用静态DNS服务器
345	`node_disk_prefetch`	`NODE_TUNE`	bool	C	是否启用磁盘预读
346	`node_kernel_modules`	`NODE_TUNE`	string[]	C	启用的内核模块
347	`node_tune`	`NODE_TUNE`	enum	C	节点调优模式
348	`node_sysctl_params`	`NODE_TUNE`	dict	C	操作系统内核参数
350	`node_data_dir`	`NODE_ADMIN`	path	G	节点的数据盘挂载路径
351	`node_admin_enabled`	`NODE_ADMIN`	bool	G	是否创建管理员用户
352	`node_admin_uid`	`NODE_ADMIN`	int	G	管理员用户UID
353	`node_admin_username`	`NODE_ADMIN`	string	G	管理员用户名
354	`node_admin_ssh_exchange`	`NODE_ADMIN`	bool	C	在实例间交换管理员SSH密钥
355	`node_admin_pk_current`	`NODE_ADMIN`	bool	A	是否将当前用户的公钥加入管理员账户
356	`node_admin_pk_list`	`NODE_ADMIN`	key[]	C	可登陆管理员的公钥列表
360	`node_timezone`	`NODE_TIME`	string	C	NTP时区设置
361	`node_ntp_enabled`	`NODE_TIME`	bool	C	是否配置NTP服务？
362	`node_ntp_service`	`NODE_TIME`	enum	C	NTP服务类型：ntp或chrony
363	`node_ntp_servers`	`NODE_TIME`	string[]	C	NTP服务器列表
364	`node_crontab_overwrite`	`NODE_TIME`	bool	C/I	是否覆盖/etc/crontab
365	`node_crontab`	`NODE_TIME`	string[]	C/I	主机定时任务列表
370	`docker_enabled`	`DOCKER`	bool	C	dockerd是否启用?
371	`docker_cgroups_driver`	`DOCKER`	string	C	docker cgroup驱动
372	`docker_registry_mirrors`	`DOCKER`	string[]	C	docker镜像仓库地址
373	`docker_image_cache`	`DOCKER`	path	C	docker镜像缓存包地址
380	`node_exporter_enabled`	`NODE_EXPORTER`	bool	C	启用节点指标收集器
381	`node_exporter_port`	`NODE_EXPORTER`	int	C	节点指标暴露端口
382	`node_exporter_options`	`NODE_EXPORTER`	string	C/I	节点指标采集选项
390	`promtail_enabled`	`PROMTAIL`	bool	C	是否启用Promtail日志收集服务
391	`promtail_clean`	`PROMTAIL`	bool	C/A	是否在安装promtail时移除已有状态信息
392	`promtail_port`	`PROMTAIL`	int	G	promtail使用的默认端口
393	`promtail_options`	`PROMTAIL`	string	C/I	promtail命令行参数
394	`promtail_positions`	`PROMTAIL`	string	C	promtail状态文件位置

`NODE_IDENTITY`

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

配置：PGSQL

Mon, 01 Jan 0001 00:00:00 +0000

使用 PGSQL剧本，部署PGSQL集群，将集群状态调整至 PGSQL配置所描述的状态。

您需要通过配置，向Pigsty表达自己对数据库的需求。Pigsty提供了100+参数来对PostgreSQL集群进行完备的描述。但用户通常只需要关心身份参数与业务对象中的个别参数即可：前者表达数据库集群“是谁？在哪？”，后者表达这个数据库“啥样？有啥？”。

配置：REDIS

Mon, 01 Jan 0001 00:00:00 +0000

配置 Redis数据库集群，控制REDIS剧本行为，详情参考Redis部署与监控教程

REDIS_IDENTITY : REDIS身份参数
REDIS_NODE : REDIS节点准备
REDIS_PROVISION : REDIS集群/实例置备

ID	Name	Section	Type	Level	Comment
700	`redis_cluster`	`REDIS_IDENTITY`	string	C	Redis数据库集群名称
701	`redis_node`	`REDIS_IDENTITY`	int	I	Redis节点序列号
702	`redis_instances`	`REDIS_IDENTITY`	instance[]	I	Redis实例定义
723	`redis_fs_main`	`REDIS_NODE`	path	C	Redis主数据盘挂载点
741	`redis_exporter_enabled`	`REDIS_NODE`	bool	C	是否启用Redis Exporter
742	`redis_exporter_port`	`REDIS_NODE`	int	C	Redis Exporter监听端口
743	`redis_exporter_options`	`REDIS_NODE`	string	C/I	Redis Exporter命令参数
726	`redis_safeguard`	`REDIS_PROVISION`	bool	C	禁止抹除现存的Redis
725	`redis_clean`	`REDIS_PROVISION`	bool	C	初始化Redis是否抹除现存实例
726	`redis_rmdata`	`REDIS_PROVISION`	bool	C	清除Redis时是否抹除数据
721	`redis_mode`	`REDIS_PROVISION`	enum	C	Redis集群模式
722	`redis_conf`	`REDIS_PROVISION`	string	C	Redis配置文件模板
724	`redis_bind_address`	`REDIS_PROVISION`	ip	C	Redis监听地址
727	`redis_max_memory`	`REDIS_PROVISION`	size	C/I	Redis可用的最大内存
728	`redis_mem_policy`	`REDIS_PROVISION`	enum	C	内存逐出策略
729	`redis_password`	`REDIS_PROVISION`	string	C	Redis密码
730	`redis_rdb_save`	`REDIS_PROVISION`	string[]	C	RDB保存指令
731	`redis_aof_enabled`	`REDIS_PROVISION`	bool	C	是否启用AOF
732	`redis_rename_commands`	`REDIS_PROVISION`	object	C	重命名危险命令列表
740	`redis_cluster_replicas`	`REDIS_PROVISION`	int	C	集群每个主库带几个从库

`REDIS_IDENTITY`

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

定制：PGSQL深度定制与修改

Mon, 01 Jan 0001 00:00:00 +0000

Patroni模板用于定制PostgreSQL集群的规格配置，而Postgres模板用于定制PostgreSQL集群的内容。

Pigsty默认提供了近100关于PGSQL的参数，描述用户所需的PostgreSQL集群，通常可以满足绝大多数用户需求。

但如果您对Pigsty创建的数据库集群进行更深一步的定制，则可以参考本文内容，对Patroni模板与Postgres模板进行定制

Patroni模板

Pigsty使用 Patroni 管理与初始化Postgres数据库集群。如果用户希望修改PostgreSQL数据库集群的默认配置参数，规格与调优方案，高可用策略，DCS访问，管控API，可以通过修改Patroni模板的方式实现。

Pigsty Dashboards

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty由提供了专业且易用的PostgreSQL监控系统，浓缩了业界监控的最佳实践。

用户可以方便地进行修改与定制；复用监控基础设施，或与其他监控系统相集成。

服务发现

Mon, 01 Jan 0001 00:00:00 +0000

服务发现有多种用途，本文介绍Pigsty监控系统Prometheus用于发现监控对象的机制。

服务发现的基础是身份标识，关于身份标识详情，请参阅实体一节

监控指标

Mon, 01 Jan 0001 00:00:00 +0000

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

指标形式

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

告警系统

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty有两套并行的告警系统：

Prometheus + AlertManager （主）
Grafana（备），默认不启用

两套系统功能等效，侧重能力不同，可同时使用，互为备份补充。

告警

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

扩展应用

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty除了用于部署、监控PostgreSQL，还可以用于制作，分发数据类应用（Application）。

Pigsty提供了几个样例应用：

pglog，分析PostgreSQL CSV日志样本。
covid，可视化WHO COVID-19数据，查阅各国疫情数据。
pglog， NOAA ISD，可以查询全球30000个地表气象站从1901年来的气象观测记录。

应用的结构

一个Pigsty应用通常包括以下内容中的至少一样或全部：

容器指南

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty v1.5.1 带有Docker与Docker Compose部署支持，其中，Docker Daemon将默认在元节点上启用，以供安装更多SaaS服务

您可以使用Docker，快速部署启动软件应用，在容器中，您可以直接使用连接串访问部署于宿主机上的PostgreSQL/Redis数据库。

升级Grafana后端数据库

Mon, 01 Jan 0001 00:00:00 +0000

您可以使用 postgres 作为Grafana后端使用的数据库。

这是了解Pigsty部署系统使用方式的好机会，完成此教程，您会了解：

如何创建新数据库集群
如何在已有数据库集群中创建新业务用户
如何在已有数据库集群中创建新业务数据库
如何访问Pigsty所创建的数据库
如何管理Grafana中的监控面板
如何管理Grafana中的PostgreSQL数据源
如何一步到位完成Grafana数据库升级

太长不看

vi pigsty.yml # 取消注释DB/User定义：dbuser_grafana  grafana
bin/createuser  pg-meta  dbuser_grafana
bin/createdb    pg-meta  grafana

psql postgres://dbuser_grafana:DBUser.Grafana@meta:5436/grafana -c \
  'CREATE TABLE t(); DROP TABLE t;' # 检查连接串可用性

vi /etc/grafana/grafana.ini # 修改 [database] type url
systemctl restart grafana-server

创建数据库集群

我们可以在pg-meta上定义一个新的数据库grafana，也可以在新的机器节点上创建一个专用于Grafana的数据库集群：pg-grafana

部署教程：Jupyter Lab数据分析环境

Mon, 01 Jan 0001 00:00:00 +0000

太长不看

./infra-jupyter.yml # 在管理节点上安装 Jupyter Lab，使用8888端口，OS用户jupyter，默认密码 pigsty
./infra-jupyter.yml -e jupyter_port=8887 # 使用另一个端口（默认为8888）
./infra-jupyter.yml -e jupyter_username=osuser_jupyter jupyter_password=pigsty2 # 使用不同的操作系统用户与密码

Jupyter配置

ID	Name	Section	Type	Level
220	`jupyter_port`	`JUPYTER`	G	是否启用JupyterLab
221	`jupyter_username`	`JUPYTER`	G	Jupyter使用的操作系统用户
222	`jupyter_password`	`JUPYTER`	G	Jupyter Lab的密码

Jupyter Lab 是基于 IPython Notebook 的完整数据科学研发环境，可用于数据分析与可视化。默认安装，但不会启用Web Server。

备份与恢复

Mon, 01 Jan 0001 00:00:00 +0000

备份是DBA的安身立命之本，也是数据库管理中最为关键的工作之一。

故障大体可以分为两类：硬件故障/资源不足（坏盘/宕机），软件缺陷/人为错误（删库/删表）。基于主从复制的物理复制用于应对前者，延迟从库与冷备份通常用于应对后者。

离线安装

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty是一个复杂的软件系统，为了确保系统的稳定，Pigsty会在初始化过程中从互联网下载所有依赖的软件包并建立本地仓库 （本地Yum源）。

所有依赖的软件总大小约1GB左右，下载速度取决于用户的网络情况。尽管Pigsty已经尽量使用镜像源以加速下载，但少量包的下载仍可能受到防火墙的阻挠，可能出现非常慢的情况。用户可以通过 proxy_env 配置项设置下载代理，以完成首次下载。

使用CMDB

Mon, 01 Jan 0001 00:00:00 +0000

您可以使用 postgres 作为 Pigsty 的配置源，替代静态配置文件。

使用 CMDB 作为 Ansible 的动态 Inventory具有一些优点：元数据以高度结构化的方式以数据表的形式呈现，并通过数据库约束确保一致性。同时CMDB允许您使用第三方的工具来编辑管理Pigsty元数据，便于与外部系统相互集成。

数据库迁移教程

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty内置了一个数据库在线迁移的辅助脚本：pgsql-migration.yml ，提供了一个开箱即用的基于逻辑复制的不停机数据库迁移方案。

填入源集群与宿集群相关信息，该剧本即会自动创建出迁移中所需的脚本，在数据库迁移时只需要依次执行即可，包括：

SOP: 标准操作流程

Mon, 01 Jan 0001 00:00:00 +0000

本文给出了Pigsty中PGSQL数据库相关的常用运维操作命令

大多数集群管理操作都需要使用到元节点上的管理用户，并在Pigsty根目录执行相应Ansible Playbook。以下示例如无特殊说明，均以沙箱环境，三节点集群 pg-test作为演示对象。

目录结构

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty目录结构

#------------------------------------------------------------------------------
# pigsty
#  ^-----@app                    # extra demo application resources
#  ^-----@bin                    # bin scripts
#  ^-----@docs                   # document (can be docsified)
#  ^-----@files                  # ansible file resources
#            ^-----@conf         # config template files
#            ^-----@rule         # soft link to prometheus rules
#            ^-----@ui           # soft link to grafana dashboards
#  ^-----@roles                  # ansible business logic
#  ^-----@templates              # ansible templates
#  ^-----@vagrant                # sandbox resources
#  ^-----configure               # configure wizard script
#  ^-----ansible.cfg             # default ansible config file
#  ^-----pigsty.yml              # default config file
#  ^-----*.yml                   # ansible playbooks

#------------------------------------------------------------------------------
# /etc/pigsty/
#  ^-----@targets                # file based service discovery targets definition
#  ^-----@dashboards             # static grafana dashboards
#  ^-----@datasources            # static grafana datasources
#  ^-----@playbooks              # extra ansible playbooks
#------------------------------------------------------------------------------

Prometheus目录结构

#------------------------------------------------------------------------------
# Config FHS
#------------------------------------------------------------------------------
# /etc/prometheus/
#  ^-----prometheus.yml              # prometheus main config file
#  ^-----alertmanager.yml            # alertmanger main config file
#  ^-----@bin                        # util scripts: check,reload,status,new
#  ^-----@rules                      # record & alerting rules definition
#            ^-----@infra            # infrastructure rules & alert
#            ^-----@nodes            # nodes rules & alert
#            ^-----@pgsql            # pgsql rules & alert
#            ^-----@redis            # redis rules & alert
#            ^-----@..........       # etc...
#  ^-----@targets                    # file based service discovery targets definition
#            ^-----@infra            # infra static targets definition
#            ^-----@nodes            # nodes static targets definition
#            ^-----@pgsql            # pgsql static targets definition
#            ^-----@redis            # redis static targets definition
#            ^-----@.....            # other targets
#------------------------------------------------------------------------------

Postgres目录结构

以下参数与PostgreSQL数据库目录相关

数据库高可用场景演练

Mon, 01 Jan 0001 00:00:00 +0000

您可以通过高可用场景演练，来加强对集群高可用能力的信心。

以下列出了24种典型的高可用故障场景，分为主库故障，从库故障，DCS故障三类，每类8个具体场景。

数据库常见故障诊断与处理

Mon, 01 Jan 0001 00:00:00 +0000

硬件故障

编号	名称	症状	处理
H01	Primary节点宕机	pg_up = 0 持续1-3分钟	无需立即介入。事后补充实例从接入域名摘除执行 Case 8：集群角色调整
H02	Replica节点宕机	pg_up = 0 持续1-3分钟	无需立即介入。事后补充实例，从接入域名摘除执行 Case 8：集群角色调整
H03	Primary节点网络分区	失去主实例所有监控数据，网路不可达	确认Failover情况必要时强制Fencing旧主库
H04	Replica节点网络分区	失去从实例所有监控数据，网路不可达	通常无影响，等待恢复联系运维与网络工程师处理
H05	TCP重传率过高	TCP Retrans长时间居高不下，大量Conn Reset，大量查询请求失败	找运维与网络工程师处理
H06	节点内存错误	EDAC计数器增长，系统错误日志	确认从库内存无错后执行Case 10：集群主从切换
H07	磁盘坏块，数据腐坏	查询结果与日志出现 can’t read block 等错误信息	执行Case 10：集群主从切换使用数据恢复工具，人工恢复数据
R01	CPU使用率高	CPU / Load / Pressure指标高	top确认大CPU占比程序并清理如为雪崩，执行杀查询止损。
R02	出现OOM	出现进程Failure，OOM消息，内存使用高，开始使用SWAP	确认内存，确认SWAP top确认大内存占用程序并清理重新拉起被杀进程紧急添加SWAP分区
R03	磁盘满	磁盘写满数据库Crash 大量shell命令无法执行	移除 `/pg/dummy` 释放应急空间检查并处理WAL堆积检查并处理大量Log文件确认业务是否有可清理数据
R06	磁盘/网卡IO过高	磁盘/网卡 BandWidth过大磁盘 > 2GB/s 网络 > 1 GB/s	检查使用网络/磁盘的应用程序，如备份，添加限速。

软件故障

编号	名称	症状	处理
SP1	数据库进程中止	`ps aux` 找不到postgres进程	检查Postgres，Patroni状态确认Failover结果，或手工执行Failover
SP2	连接池进程中止	`systemctl status pgbouncer` Failure	重启服务组件或重置服务组件
SP3	Primary Patroni进程中止	`systemctl status patroni` Failure	同上，进入维护模式，重启或重置 Patroni
SP4	Primary Consul进程中止	`systemctl status consul` Failure	同上，进入维护模式，重启或重置 Consul
S05	HAProxy进程中止	`systemctl status haproxy` Failure	同上，重启或重置 Haproxy
S06	连接池污染	出现类似于 Cannot execute xxx on readonly transactions 的报错	重启Pgbouncer连接池或配置 `server_reset_query`
S07	连接池无法连接至数据库	pgbouncer can not connect to server	检查用户、密码、HBA配置是否正确执行 Case 4：集群业务用户创建刷新用户
S08	连接池达到QPS瓶颈	PGbouncer QPS 达到 3～4W，CPU使用率达到100%	使用多个Pgbouncer（不推荐）使用Default服务绕开Pgbouncer 通知业务方限速
S09	DCS Server不可用	自动切换模式下，所有主库将在TTL后进入不可写状态	立即将所有集群设置为维护模式
S10	DCS Agent不可用	若为从库无影响，若为主库，会降级为从库，集群不可写入	立即将该集群设置为维护模式
S11	XID Wraparound	年龄剩余1000w时，进入保护模式。	应通过监控提前避免此问题定位年龄过大的数据库与表，执行紧急清理迅速定位阻塞Vacuum的原因并解决进入单用户模式下恢复
S12	WAL堆积	WAL大小持续增长	多次执行`CHECKPOINT` 确认WAL归档状态确认从库上是否有未结束超长事务确认是否有复制槽阻止WAL回收

人为问题

编号	名称	症状	处理
M01	误删数据库集群	数据库集群没了	使用冷备恢复集群准备跑路
M02	误将某实例提升为主库	脑裂	自动模式下无需处理，否则脑裂
M03	误删数据	数据没了	停止VACUUM，使用 `pg_dirtyread`提取。从延迟备库中提取从冷备份中提取并恢复
M04	误删表	表没了	从延迟备库中提取从冷备份中提取并恢复
M05	整型序列号溢出	Sequence超出INTMAX	参考整型主键在线升级手册处理
M06	插入数据因主键序列号重复而冲突	violate constratint …	增长序列号值（如+100000）
M07	慢查询堆积/雪崩	大量慢查询日志	使用 pg_terminate_backend 周期性清理慢查询（如每1秒）
M08	死锁堆积/雪崩	锁堆积	使用 pg_terminate_backend 周期性清理查询（如每1秒）
M09	HBA拒绝访问	no hba entry for xxx	Case 6：集群HBA规则调整
M10	用户密码错误	password auth failure for xxx	Case 4：集群业务用户创建
M11	访问权限不足	permission denied for x	检查用户是否使用正确的管理员创建对象参考 Default Privilege 手工修正对象权限

社区

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty有一个活跃的用户社群，搜索微信号 pigsty-cc ，添加 Pigsty小助手入群。

大多数问题都可以在常见问题/FAQ 中找到解答，如果这里没有解决您的问题，可以在社群求助。询问时请详细描述以下内容：

路线图

Mon, 01 Jan 0001 00:00:00 +0000

历史

时间	说明	版本
2019-05-15	概念验证	v0.0.1
2020-04-30	首次提交	v0.0.2
2020-06-20	测试环境验证	v0.1.0
2020-06-22	界面增强	v0.0.3
2020-07-10	PGSQL 监控 v6 正式可用	v0.2.0
2020-07-27	将剧本重构为 Ansible 角色	v0.0.4
2020-08-19	离线安装模式	v0.0.5
2020-10-22	置备方案正式可用	v0.3.0
2020-12-14	支持 PostgreSQL 13，发布正式文档	v0.4.0
2021-01-07	数据库定制模板	v0.5.0
2021-02-19	架构增强	v0.6.0
2021-03-01	仅监控部署	v0.7.0
2021-03-28	服务置备	v0.8.0
2021-04-04	GUI、CLI 与日志集成	v0.9.0
2021-04-20	可访问性与扩展性增强	v0.9.1
2021-07-26	v1 正式版，监控系统重构	v1.0.0
2021-10-12	主页、JupyterLab、PGWeb、Pev2 与 Pgbadger	v1.1.0
2021-11-03	默认 PostgreSQL 14，支持监控已有 PG	v1.2.0
2021-11-30	PGCAT 重构、PGSQL 增强与 Redis Beta	v1.3.0
2022-03-31	MatrixDB；拆分 INFRA、NODES、PGSQL、REDIS	v1.4.0
2022-04-20	缺陷修复与英文文档完整翻译	v1.4.1
2022-05-31	Docker 应用	v1.5.0
2022-06-18	PostgreSQL 14.4 与 Grafana 安全更新	v1.5.1

时间线

开发日志与发布说明

Mon, 01 Jan 0001 00:00:00 +0000

本页根据 v1.5.1 产品标签、冻结版本的英文开发日志，以及同一站点的中文发布档案重建。v1.5 分支的当前正式版本为 v1.5.1。

Pigsty v1.5.1

亮点

重要：修复了 PG14.0-14.3 中 CREATE INDEX|REINDEX CONCURRENTLY 可能导致索引数据损坏的问题。

为什么使用 Pigsty

Mon, 01 Jan 0001 00:00:00 +0000

为什么要使用Pigsty？

我们的理念是：用好数据库，用好数据库，让天下没有难用的数据库！

数据库是信息系统的核心组件，关系型数据库是数据库的绝对主力，PostgreSQL是世界上最先进的开源关系型数据库。

用户界面

Mon, 01 Jan 0001 00:00:00 +0000

用户界面

完成安装后，可以通过浏览器访问Pigsty提供的图形用户界面。

http://g.pigsty -> http://10.10.10.10:80 (nginx) -> http://10.10.10.10:3000 (grafana)

访问 http://<node_ip>:3000 即可浏览 Pigsty 主页 (用户名: admin, 密码: pigsty)

Pigsty部署

Mon, 01 Jan 0001 00:00:00 +0000

部署Pigsty分为三步：准备工作，修改配置，执行剧本

Pigsty在部署前需要进行一些准备工作：配置带有正确权限配置的节点，下载安装相关软件。置备完成后，用户应当按照自己的需求修改配置，并执行剧本将系统调整至配置描述的状态。其中，配置是部署Pigsty的重点所在。

部署方式

标准部署：您自己准备全新节点，完成标准Pigsty部署流程。
沙箱部署：通过预制的vagrant模板一键拉起本地虚拟机沙箱环境。
多云部署：使用terraform模板在云服务供应商处拉起所需虚拟机资源，并执行部署。
仅监控部署：使用单节点Pigsty监控现有数据库集群。

无论何种部署，其流程都分为三步：准备资源，修改配置，执行剧本。Pigsty在部署前需要进行一些准备工作：配置带有正确权限配置的节点，下载安装相关软件。置备完成后，用户应当按照自己的需求修改配置，并执行剧本将系统调整至配置描述的状态。其中准备与执行这两个步骤非常简单，配置是部署Pigsty的关键点所在。

定制 PostgreSQL 模板

Mon, 01 Jan 0001 00:00:00 +0000

Patroni模板用于定制PostgreSQL集群的规格配置，而Postgres模板用于定制PostgreSQL集群的内容。

Pigsty默认提供了近100关于PGSQL的参数，描述用户所需的PostgreSQL集群，通常可以满足绝大多数用户需求。

但如果您对Pigsty创建的数据库集群进行更深一步的定制，则可以参考本文内容，对Patroni模板与Postgres模板进行定制

Patroni模板

部署与监控Redis

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty是一个PostgreSQL发行版，也是一个通用应用运行时。您可以用它管理、部署、监控其他应用与数据库，例如Redis。

与PostgreSQL类似，部署Redis同样需要两个步骤：

PGWeb

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty v1.5.1 已不再提供旧 infra-pgweb.yml 剧本，也没有 pgweb_enabled / pgweb_username 清单参数；该标签通过 app/pgweb 提供 PGWeb Docker 应用。

运行 PGWeb

v1.5.1 随附清单默认在元节点启用 Docker。使用标签内的应用定义启动 PGWeb：

使用TimescaleDB存储Prometheus数据

Mon, 01 Jan 0001 00:00:00 +0000

您可以使用 postgres 作为 Prometheus 后端使用的远程存储数据库。

虽然这并不是推荐的行为，但这是了解Pigsty部署系统使用方式的好机会。

准备Postgres数据库

vi pigsty.yml # 取消注释DB/User定义：dbuser_prometheus  prometheus

pg_databases:                           # define business users/roles on this cluster, array of user definition
  - { name: prometheus, owner: dbuser_prometheus , revokeconn: true, comment: prometheus primary database }
pg_users:                           # define business users/roles on this cluster, array of user definition
  - {name: dbuser_prometheus , password: DBUser.Prometheus ,pgbouncer: true , createrole: true,  roles: [dbrole_admin], comment: admin user for prometheus database }

创建 Prometheus 业务数据库与业务用户。