多页打印视图 点击此处打印.

返回常规视图.

入门

快速了解Pigsty所解决的问题,采用的技术,适用的场景。

1 - Pigsty入门指南

从哪里开始?

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

新用户

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

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

开发者(Dev)

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

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

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

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

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

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

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

运维人员 (OPS)

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

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

管理员(DBA)

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

监控系统教程

日常维护管理

专业用户

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

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

2 - Pigsty快速上手

三行命令拉起Pigsty

Pigsty有两种典型使用模式:单机安装集群管理,集群管理只是在单机安装上多做了几步工作。

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


单机安装

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

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

bash -c "$(curl -fsSL http://download.pigsty.cc/get)"  # 下载最新pigsty源代码
./download pkg                                         # 可选,下载离线软件包加速
cd ~/pigsty; ./configure                               # 根据当前环境生成配置
./infra.yml                                            # 在当前节点上完成安装

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

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

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

访问 http://g.pigstyhttp://<primary_ip>:3000 即可浏览 Pigsty监控系统主页

(用户名: admin, 密码: pigsty)


集群管理

Pigsty还可以用作大规模生产环境的集群/数据库管理。您可以从单机安装Pigsty的节点(将作为集群的元节点,或称作元节点/Meta)上发起控制,将更多的 机器节点 纳入Pigsty的管理与监控中。

更重要的是,Pigsty还可以在这些节点上部署并管理各式各样的数据库集群与应用:创建高可用的PostgreSQL数据库集群;创建不同类型的Redis集簇;部署 Greenplum/MatrixDB 数据仓库,并获取关于节点、数据库与应用的实时洞察。

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

3 - Pigsty用户界面

Pigsty提供的图形界面

完成安装后,可以通过浏览器访问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)

您可以访问 http://demo.pigsty.cc 来查看公开Pigsty Demo,并浏览Pigsty监控系统提供的功能。

Web服务

Pigsty会通过Nginx 80端口统一代理Web类服务的访问,默认的域名与上游端口为:

组件 端口 默认域名 说明
Grafana 3000 g.pigsty Pigsty监控系统图形界面
Prometheus 9090 p.pigsty 监控时序数据库
Loki 3100 l.pigsty 日志收集服务端(无界面)
AlertManager 9093 a.pigsty 报警聚合管理组件
Consul 8500 c.pigsty 分布式配置管理,服务发现
Nginx 80 pigsty 所有服务的入口代理
Yum Repo 80 yum.pigsty 本地Yum源

更多详情,请参考 INFRA -> 配置 -> nginx_upstream

关于域名

用户可以为这些服务配置自己已有的域名,或使用make dns快捷方式将默认的域名写入/etc/hosts

用户仍然可以使用 IP:Port 的方式直接访问大部分服务,例如,Pigsty监控系统的入口即为元节点IP+3000端口。

更多关于准备域名的详情,请参考:部署 -> 准备 -> DNS域名配置

4 - Pigsty FAQ

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

准备

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

机器节点要求

最小规格 1C/2GB,节点处理器为x86_64架构,目前不支持 ARM 架构。

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

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

操作系统要求

Pigsty强烈建议使用CentOS 7.8操作系统,可以节省大量无意义的DEBUG时间。

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

软件版本策略

请使用特定版本的Release,不要直接使用Github Master分支,该开发分支有可能处于不一致的状态。

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

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

沙箱虚拟机置备

使用Vagrant一键拉起基于本地虚拟机的本地沙箱,或使用Terraform在公有云厂商创建云端沙箱

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

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

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

下载

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

如何下载Pigsty源码包

bash -c "$(curl -fsSL http://download.pigsty.cc/get)"

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

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

下载其他Pigsty软件包

./download pigsty pkg app matrix

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

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

如何下载Pigsty离线软件包

./download pkg 或在配置过程中根据提示自动下载。

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

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

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

离线软件包出现RPM冲突

不用离线包直接从上游下载,或仅删除问题包并从可用源补缺

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

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


配置

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

配置过程做了些什么

检测环境,生成配置,启用离线软件包(可选),安装基本工具Ansible。

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

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

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

Pigsty的配置文件在哪

源码根目录下 pigsty.yml 是默认的、唯一的配置源。

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

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

配置文件中的占位IP地址

Pigsty使用10.10.10.10作为当前节点IP地址占位符,将在配置过程中被替换为当前节点的首要IP地址。

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

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

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

单机部署通常啥配置也不用改,会自动调整,绝大多数参数都有合适的默认值。

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

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

安装

安装时执行了什么?

执行make install安装时,会调用ansible-playbook执行预置剧本 infra.yml,在元节点上完成安装。

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

下载RPM包速度太慢

如果直接从上游下不动,最好还是使用离线软件包,或者配置代理服务器,和可用本地镜像源。

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

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

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

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

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

通过主机实例级 ansible连接参数,指定不一样的端口。

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

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

远端节点SSH与SUDO需要密码

使用 -k-K参数,在提示符时输入密码,参考管理用户置备

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


沙箱

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

Vagrant沙箱首次启动太慢

第一次使用Vagrant拉起某个操作系统镜像,会下载对应BOX。

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

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

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

阿里云CentOS 7.8 RPM报错

阿里云CentOS 7.8 服务器默认安装了DNS缓存服务 nscd,移除即可。

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

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

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

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

虚拟机时间失去同步

sudo ntpdate -u pool.ntp.org 或使用 make sync4

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

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

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

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

使用Docker/Kubernetes盛放数据库仍然不成熟

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

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


监控

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

监控查询开销微不足道,百毫秒量级,10秒一次,普通实例约产生2k ~ 5k时间序列。

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

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

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

Pigsty不承诺对外部实例的监控质量:Pigsty创建的PostgreSQL在绝大多数情况下表现显著优于土法手造实例

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

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

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

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

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

使用 pgsql-remove.yml 剧本移除监控目标


INFRA

基础设施包括哪些组件?

Pigsty提供了一套完整的PaaS环境,详情请参考系统架构:基础设施

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

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

Pigsty默认会在元节点上提供DCS服务,但更推荐使用外部的多个节点组成的高可用DCS服务集群。

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

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


NODES

Abort because consul instance already exists

Pigsty提供了DCS误删保护机制,配置dcs_clean = true 可以硬干。

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

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

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

./nodes.yml -e dcs_clean=true

PGSQL

Abort because postgres instance already exists

Pigsty提供了数据库误删保护机制,配置pg_clean = true 可以硬干。

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

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

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

./pgsql.yml -e pg_clean=true

PostgreSQL数据库如何保证高可用

Patroni 作为HA Agent,Consul作为DCS,Haproxy作为默认流量分发器,详见高可用集群

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

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

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

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

使用pg_conf: crit.yml 模板,或手工启用同步复制。

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

数据损坏导致拖从库失败

找到问题机器,修改 patroni 配置文件clonefrom: false并重载生效

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