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本地沙箱：

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

下载

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

如何下载Pigsty源码包

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

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

  1. https://github.com/Vonng/pigsty/releases/download/v1.5.1/pigsty.tgz   # Github Release 
  2. http://download.pigsty.cc/v1.5.1/pigsty.tgz                           # 中国大陆用加速CDN
  3. 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 会自动下载并提取离线软件包。

  1. # download to /tmp/*.tgz
  2. ./download pigsty.tgz   # download pigsty source tarball
  3. ./download pkg.tgz      # download pigsty offline pkgs
  4. ./download app.tgz      # download extra pigsty apps
  5. ./download matrix.tgz   # download matrixdb packages
  6. # download and extract
  7. ./download pigsty       # download and extract pigsty to ~/pigsty
  8. ./download pkg          # download and extract pkg    to /www/pigsty
  9. ./download app          # download and extract app    to ~/app
  10. ./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，则安装时会自动使用。

  1. curl https://github.com/Vonng/pigsty/releases/download/v1.5.1/pkg.tgz -o /tmp/pkg.tgz
  2. curl http://download.pigsty.cc/v1.5.1/pkg.tgz -o /tmp/pkg.tgz         # China CDN
  3. 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。

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

远端节点SSH与SUDO需要密码

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

执行部署与变更时，您所使用的管理用户必须拥有所有节点的ssh与sudo权限。免密码并非必需，您总是可以在执行剧本时通过-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依赖错误。

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

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

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

虚拟机时间失去同步

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

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

  1. sudo ntpdate -u pool.ntp.org
  2. make sync4 # 使用NTP POOL时间同步快捷方式
  3. 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环境，详情请参考系统架构：基础设施

常见问题 - 图1

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 中修改这些参数，也可以直接在执行剧本时，通过额外参数机制指定：

  1. ./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 中修改这些参数，也可以直接在执行剧本时，通过额外参数机制指定：

  1. ./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，以避免从损坏的实例上拉取数据。

最后修改 2022-06-18: v1.5.1 (8de4142)