常见问题
Module:
这里列出了Pigsty用户在下载、安装、部署时常遇到的问题，如果您遇到了难以解决的问题，可以提交 Issue 或者联系我们。
如何获取Pigsty软件源码包？
使用以下命令一键安装 Pigsty： bash -c "$(curl -fsSL https://get.pigsty.cc/latest)"
上述命令会自动下载最新的稳定版本 pigsty.tgz 并解压到 ~/pigsty 目录。您也可以从以下位置手动下载 Pigsty 源代码的特定版本。
如果您需要在没有互联网的环境中安装，可以提前在有网络的环境中下载好，并通过 scp/sftp 或者 CDROM/USB 传输至生产服务器。
如何加速从上游仓库下载 RPM ?
考虑使用本地仓库镜像，仓库镜像在repo_upstream 参数中配置，你可以选择 region 来使用不同镜像站。
例如，您可以设置 region = china，这样将使用 baseurl 中键为 china 的 URL 而不是 default。
如果防火墙或GFW屏蔽了某些仓库，考虑使用proxy_env 来绕过。
软件包安装失败如何解决？
请注意，Pigsty 的预制 离线软件包 是针对 特定操作系统发行版小版本 打包的，因此如果您使用的操作系统版本没有精确对齐，我们不建议使用离线软件安装包，而是直接从上游下载符合当前操作系统实际情况的软件包版本。
如果在线安装无法解决包冲突问题，您首先可以尝试修改 Pigsty 使用的上游软件源。例如在 EL 系操作系统中， Pigsty 默认的上游软件源中使用 $releasever 这样的大版本占位符，它将被解析为具体的 7，8，9 大版本号，但是许多操作系统发行版都提供了 Vault，允许您使用特定某一个版本的软件包镜像。
因此，您可以将 repo_upstream 参数中的 BaseURL 前段替换为具体的 Vault 小版本仓库，例如：
https://mirrors.aliyun.com/rockylinux/$releasever/（原始 BaseURL 前缀，不带vault）https://mirrors.tuna.tsinghua.edu.cn/centos-vault/7.6.1810/（使用 7.6 而不是默认的 7.9）https://mirrors.aliyun.com/rockylinux-vault/8.6/（使用 8.6 而不是默认的 8.9）https://mirrors.aliyun.com/rockylinux-vault/9.2/（使用 9.2 而不是默认的 9.3）
在替换前请注意目标软件源的路径是否真实存在，例如 EPEL 不提供小版本特定的软件源。支持这种方式的上游源包括：base, updates, extras, centos-sclo, centos-sclo-rh, baseos, appstream, extras, crb, powertools, pgdg-common, pgdg1*
repo_upstream:
- { name: pigsty-local ,description: 'Pigsty Local' ,module: local ,releases: [7,8,9] ,baseurl: { default: 'http://${admin_ip}/pigsty' }} # used by intranet nodes
- { name: pigsty-infra ,description: 'Pigsty INFRA' ,module: infra ,releases: [7,8,9] ,baseurl: { default: 'https://repo.pigsty.io/rpm/infra/$basearch' ,china: 'https://repo.pigsty.cc/rpm/infra/$basearch' }}
- { name: pigsty-pgsql ,description: 'Pigsty PGSQL' ,module: pgsql ,releases: [7,8,9] ,baseurl: { default: 'https://repo.pigsty.io/rpm/pgsql/el$releasever.$basearch' ,china: 'https://repo.pigsty.cc/rpm/pgsql/el$releasever.$basearch' }}
- { name: nginx ,description: 'Nginx Repo' ,module: infra ,releases: [7,8,9] ,baseurl: { default: 'https://nginx.org/packages/centos/$releasever/$basearch/' }}
- { name: docker-ce ,description: 'Docker CE' ,module: infra ,releases: [7,8,9] ,baseurl: { default: 'https://download.docker.com/linux/centos/$releasever/$basearch/stable' ,china: 'https://mirrors.aliyun.com/docker-ce/linux/centos/$releasever/$basearch/stable' ,europe: 'https://mirrors.xtom.de/docker-ce/linux/centos/$releasever/$basearch/stable' }}
- { name: base ,description: 'EL 7 Base' ,module: node ,releases: [7 ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/os/$basearch/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/centos/$releasever/os/$basearch/' ,europe: 'https://mirrors.xtom.de/centos/$releasever/os/$basearch/' }}
- { name: updates ,description: 'EL 7 Updates' ,module: node ,releases: [7 ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/updates/$basearch/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/centos/$releasever/updates/$basearch/' ,europe: 'https://mirrors.xtom.de/centos/$releasever/updates/$basearch/' }}
- { name: extras ,description: 'EL 7 Extras' ,module: node ,releases: [7 ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/extras/$basearch/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/centos/$releasever/extras/$basearch/' ,europe: 'https://mirrors.xtom.de/centos/$releasever/extras/$basearch/' }}
- { name: epel ,description: 'EL 7 EPEL' ,module: node ,releases: [7 ] ,baseurl: { default: 'http://download.fedoraproject.org/pub/epel/$releasever/$basearch/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/epel/$releasever/$basearch/' ,europe: 'https://mirrors.xtom.de/epel/$releasever/$basearch/' }}
- { name: centos-sclo ,description: 'EL 7 SCLo' ,module: node ,releases: [7 ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/sclo/$basearch/sclo/' ,china: 'https://mirrors.aliyun.com/centos/$releasever/sclo/$basearch/sclo/' ,europe: 'https://mirrors.xtom.de/centos/$releasever/sclo/$basearch/sclo/' }}
- { name: centos-sclo-rh ,description: 'EL 7 SCLo rh' ,module: node ,releases: [7 ] ,baseurl: { default: 'http://mirror.centos.org/centos/$releasever/sclo/$basearch/rh/' ,china: 'https://mirrors.aliyun.com/centos/$releasever/sclo/$basearch/rh/' ,europe: 'https://mirrors.xtom.de/centos/$releasever/sclo/$basearch/rh/' }}
- { name: baseos ,description: 'EL 8+ BaseOS' ,module: node ,releases: [ 8,9] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/BaseOS/$basearch/os/' ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/BaseOS/$basearch/os/' ,europe: 'https://mirrors.xtom.de/rocky/$releasever/BaseOS/$basearch/os/' }}
- { name: appstream ,description: 'EL 8+ AppStream' ,module: node ,releases: [ 8,9] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/AppStream/$basearch/os/' ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/AppStream/$basearch/os/' ,europe: 'https://mirrors.xtom.de/rocky/$releasever/AppStream/$basearch/os/' }}
- { name: extras ,description: 'EL 8+ Extras' ,module: node ,releases: [ 8,9] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/extras/$basearch/os/' ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/extras/$basearch/os/' ,europe: 'https://mirrors.xtom.de/rocky/$releasever/extras/$basearch/os/' }}
- { name: crb ,description: 'EL 9 CRB' ,module: node ,releases: [ 9] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/CRB/$basearch/os/' ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/CRB/$basearch/os/' ,europe: 'https://mirrors.xtom.de/rocky/$releasever/CRB/$basearch/os/' }}
- { name: powertools ,description: 'EL 8 PowerTools' ,module: node ,releases: [ 8 ] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/PowerTools/$basearch/os/' ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/PowerTools/$basearch/os/' ,europe: 'https://mirrors.xtom.de/rocky/$releasever/PowerTools/$basearch/os/' }}
- { name: epel ,description: 'EL 8+ EPEL' ,module: node ,releases: [ 8,9] ,baseurl: { default: 'http://download.fedoraproject.org/pub/epel/$releasever/Everything/$basearch/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/epel/$releasever/Everything/$basearch/' ,europe: 'https://mirrors.xtom.de/epel/$releasever/Everything/$basearch/' }}
- { name: pgdg-common ,description: 'PostgreSQL Common' ,module: pgsql ,releases: [7,8,9] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/redhat/rhel-$releasever-$basearch' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-extras ,description: 'PostgreSQL Extra' ,module: pgsql ,releases: [7,8,9] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-el8fix ,description: 'PostgreSQL EL8FIX' ,module: pgsql ,releases: [ 8 ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-x86_64/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-x86_64/' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-x86_64/' } }
- { name: pgdg-el9fix ,description: 'PostgreSQL EL9FIX' ,module: pgsql ,releases: [ 9] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-x86_64/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-x86_64/' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-x86_64/' }}
- { name: pgdg15 ,description: 'PostgreSQL 15' ,module: pgsql ,releases: [7 ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/15/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/15/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/15/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg16 ,description: 'PostgreSQL 16' ,module: pgsql ,releases: [ 8,9] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/16/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' }}
- { name: timescaledb ,description: 'TimescaleDB' ,module: pgsql ,releases: [7,8,9] ,baseurl: { default: 'https://packagecloud.io/timescale/timescaledb/el/$releasever/$basearch' }}
在 Pigsty 配置文件中显式定义并覆盖 repo_upstream 后，（可清除 /www/pigsty/repo_complete 标记后）再次尝试安装。如果上游软件源与镜像源的软件没有解决问题，你可以考虑将上面的源替换为操作系统自带的软件源，再次尝试从上游直接安装。
最后如果以上手段都没有解决问题，你可以考虑移除 node_packages， infra_packages， pg_packages，pg_extensions 中出现冲突的软件包。或者移除、升级现有系统上的冲突软件包。
准备 / bootstrap 过程是干什么的？
检测环境是否就绪、用各种手段确保后续安装所必需的工具 ansible 被正确安装。
当你下载 Pigsty 源码后，可以进入目录并执行 bootstrap 脚本。它会检测你的节点环境，如果没有发现离线软件包，它会询问你要不要从互联网下载。
你可以选择“是”，直接使用离线软件包安装又快又稳定。你也可以选“否”跳过，在安装时直接从互联网上游下载最新的软件包，这样会极大减少出现 RPM/DEB 包冲突的概率。
如果使用了离线软件包，bootstrap 会直接从离线软件包中安装 ansible，否则会从上游下载 ansible 并安装，如果你没有互联网访问，又没有 DVD，或者内网软件源，那就只能用离线软件包来安装了。
配置 / configure 过程是干什么的？
配置 / configure 过程会检测你的节点环境并为你生成一个 pigsty 配置文件：pigsty.yml，默认根据你的操作系统（EL 7/8/9）选用相应的单机安装模板。
所有默认的配置模板都在 files/pigsty中，你可以使用 -m 直接指定想要使用的配置模板。如果您已经知道如何配置 Pigsty 了，那么完全可以跳过这一步，直接编辑 Pigsty 配置文件。
Pigsty配置文件是干什么的？
Pigsty主目录下的 pigsty.yml 是默认的配置文件，可以用来描述整套部署的环境，在 files/pigsty 有许多配置示例供你参考。
当执行剧本时，你可以使用 -i <path> 参数，选用其他位置的配置文件。例如，你想根据另一个专门的配置文件 redis.yml 来安装 redis：./redis.yml -i files/pigsty/redis.yml
如何使用 CMDB 作为配置清单？
默认的配置文件路径在 ansible.cfg 中指定为：inventory = pigsty.yml
你可以使用 bin/inventory_cmdb 切换到动态的 CMDB 清单，
使用 bin/inventory_conf 返回到本地配置文件。
你还需要使用 bin/inventory_load 将当前的配置文件清单加载到 CMDB。
如果使用 CMDB，你必须从数据库而不是配置文件中编辑清单配置，这种方式适合将 Pigsty 与外部系统相集成。
配置文件中的IP地址占位符是干什么的？
Pigsty 使用 10.10.10.10 作为当前节点 IP 的占位符，配置过程中会用当前节点的主 IP 地址替换它。
当 configure 检测到当前节点有多个 NIC 带有多个 IP 时，配置向导会提示使用哪个主要 IP，即 用户用于从内部网络访问节点的 IP，此 IP 将用于在配置文件模板中替换占位符 10.10.10.10。
请注意：不要使用公共 IP 作为主 IP，因为 Pigsty 会使用主 IP 来配置内部服务，例如 Nginx，Prometheus，Grafana，Loki，AlertManager，Chronyd，DNSMasq 等，除了 Nginx 之外的服务不应该对外界暴露端口。
配置文件中的哪些参数需要用户特殊关注？
Pigsty 提供了 280+ 配置参数，可以对整个环境与各个模块 infra/node/etcd/minio/pgsql 进行细致入微的定制。
通常在单节点安装中，你不需要对默认生成的配置文件进行任何调整。但如果需要，可以关注以下这些参数：
- 当访问 web 服务组件时，域名由
infra_portal指定，有些服务只能通过 Nginx 代理使用域名访问。 - Pigsty 假定存在一个
/data目录用于存放所有数据；如果数据磁盘的挂载点与此不同，你可以使用node_data调整这些路径。 - 进行生产部署时，不要忘记在配置文件中更改密码，更多细节请参考 安全考量。
在默认单机安装时，到底都安装了什么东西？
当您执行 make install 时，实际上是调用 Ansible 剧本 install.yml，根据配置文件中的参数，安装以下内容：
INFRA模块：提供本地软件源，Nginx Web接入点，DNS服务器，NTP服务器，Prometheus与Grafana可观测性技术栈。NODE模块，将当前节点纳入 Pigsty 管理，部署 HAProxy 与 监控。ETCD模块，部署一个单机 etcd 集群，作为 PG 高可用的 DCSMINIO模块是默认不安装的，它可以作为 PG 的备份仓库。PGSQL模块，一个单机 PostgreSQL 数据库实例。
安装遇到RPM冲突怎么办？
在安装 node/infra/pgsql 软件包期间，可能有微小的几率出现 rpm 冲突。特别是，如果您使用的 EL 7-9 小版本不同于 7.9, 8.9, 9.3 ，或者使用了一些冷门换皮魔改发行版的话，可能会出现这种情况。
解决这个问题的最简单方法是：不使用离线包进行安装，这将直接从上游仓库中下载最合适您当前系统的软件包。如果只有少数几个 RPM 包有问题，你可以使用一个小技巧快速修复：
rm -rf /www/pigsty/repo_complete # 删除 repo_complete 标记文件，以标记此仓库为不完整（这样会重新从上游下载软件）
rm -rf SomeBrokenRPMPackages # 删除有问题的 RPM 包
./infra.yml -t repo_upstream # 写入上游仓库。你也可以使用 /etc/yum.repos.d/backup/*
./infra.yml -t repo_pkg # 根据你当前的操作系统下载软件包
如何使用 Vagrant 创建本地虚拟机？
当你第一次使用 Vagrant 启动某个特定的操作系统仓库时，它会下载相应的 Box/Img 镜像文件，Pigsty 沙箱默认使用 generic/rocky9 镜像。
使用代理可能会增加下载速度。Box/Img 只需下载一次，在重建沙箱时会被重复使用。
阿里云上 CentOS 7.9 特有的 RPM 冲突问题
阿里云的 CentOS 7.9 额外安装的 nscd 可能会导致 RPM 冲突问题："Error: Package: nscd-2.17-307.el7.1.x86_64 (@base)"
遇见安装失败，RPM冲突报错不要慌，这是一个DNS缓存工具，把这个包卸载了就可以了：sudo yum remove nscd，或者使用 ansible 命令批量删除所有节点上的 nscd：
ansible all -b -a 'yum remove -y nscd'
腾讯云上 Rocky 9.x 特有的 RPM 冲突问题
腾讯云的 Rocky 9.x 需要额外的 annobin 软件包才可以正常完成 Pigsty 安装。
遇见安装失败，RPM冲突报错不要慌，进入 /www/pigsty 把这几个包手动下载下来就好了。
./infra.yml -t repo_upstream # add upstream repos
cd /www/pigsty; # download missing packages
repotrack annobin gcc-plugin-annobin libuser
./infra.yml -t repo_create # create repo
Ansible命令超时（Timeout waiting for xxx）
Ansible 命令的默认 ssh 超时时间是10秒。由于网络延迟或其他原因，某些命令可能需要超过这个时间。
你可以在 ansible 配置文件 ansible.cfg 中增加超时参数：
[defaults]
timeout = 10 # 将其修改为 60，120 或更高。
如果你的SSH连接非常慢，通常会是 DNS的问题，请检查sshd配置确保 UseDNS no。
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.