快速上手

如何快速下载、配置、安装 Pigsty ？

安装 Pigsty 有四个步骤：下载, Bootstrap, 配置 and 安装.

快速上手

准备一个使用 Linux x86_64 EL 7，8，9 兼容系统的全新节点，使用带有免密 sudo 权限的用户执行：

1. curl http://download.pigsty.cc/get | bash

该命令会下载并解压 Pigsty 源码至家目录，按提示完成 Bootstrap，配置，安装三个步骤即可完成安装。

1. cd ~/pigsty      # 进入 Pigsty 源码目录，完成后续 准备、配置、安装 三个步骤
2. ./bootstrap      # 确保 Ansible 正常安装，如果存在 /tmp/pkg.tgz 离线软件包，便使用它。
3. ./configure      # 执行环境检测，并生成相应的推荐配置文件，如果你知道如何配置 Pigsty 可以跳过
4. ./install.yml    # 根据生成的配置文件开始在当前节点上执行安装，使用离线安装包大概需要10分钟完成

安装完成后，您可以通过 80 端口访问 WEB 界面，通过 5432 端口访问默认的 PostgreSQL 数据库服务。

安装脚本的输出样例

1. $ curl http://download.pigsty.cc/get | bash
2. ...
3. [Checking] ===========================================
4. [ OK ] SOURCE from CDN due to GFW
5. FROM CDN    : bash -c "$(curl -fsSL http://download.pigsty.cc/get)"
6. FROM GITHUB : bash -c "$(curl -fsSL https://raw.githubusercontent.com/Vonng/pigsty/master/bin/get)"
7. [Downloading] ===========================================
8. [ OK ] download pigsty source code from CDN
9. [ OK ] $ curl -SL http://download.pigsty.cc/v2.0.2/pigsty-v2.0.2.tgz
10. ...
11. MD5: 78a6ae5ff9ab0b8aa3848805aeadd1d8  /tmp/pigsty-v2.0.2.tgz
12. [Extracting] ===========================================
13. [ OK ] extract '/tmp/pigsty-v2.0.2.tgz' to '/root/pigsty'
14. [ OK ] $ tar -xf /tmp/pigsty-v2.0.2.tgz -C ~;
15. cd ~/pigsty      # entering pigsty home directory before proceeding
16. [Proceeding] ===========================================
17. ./bootstrap      # install ansible & download the optional offline packages
18. ./configure      # preflight-check and generate config according to your env
19. ./install.yml    # install pigsty on this node and init it as the admin node
20. [Reference] ===========================================
21. Get Started:     https://vonng.github.io/pigsty/#/INSTALL
22. Documentation:   https://vonng.github.io/pigsty
23. Github Repo:     https://github.com/Vonng/pigsty
24. Public Demo:     http://demo.pigsty.cc
25. Official Site:   https://pigsty.cc

环境要求

操作系统

  • Linux RHEL 或其他兼容的操作系统发行版
  • Vendor: RHEL, CentOS, Rocky, AlmaLinux, …
  • Version: el7, el8, el9, 或其他兼容的版本
  • 请使用全新的节点，以避免无谓的麻烦，1核云虚拟机也就几毛钱一小时。
  • 建议使用 RockyLinux 9.0 / RockyLinux 8.6 / CentOS 7.9 ，这是 Pigsty 的构建与测试环境。

机器节点

  • x86_64 架构 (目前暂不支持 aarch64/arm 等架构)
  • 管理节点最低1核2G，自动根据节点规格优化，支持到 128C 512G 规格节点。
  • 普通节点最低 1核1G，推荐 2C4G 以上，支持到 128C 512G 规格节点。
  • 需要有公钥免密的 ssh 访问，且在目标节点上有免密sudo或root权限。
  • 一个严肃的生产部署最少需要三个节点，目前最大部署规模为 1000+ 节点。

Ansible

  • Ansible 是Pigsty的核心依赖，会在 Bootstrap 过程中自动安装
  • 你也可以使用 yum 直接手动安装，但需要先启用 epel-release 源

下载

您可以使用以下命令获取 Pigsty 源码包：

1. curl http://download.pigsty.cc/get  | bash

提示: 如果您需要下载最新的测试版本（Alpha/Beta/RC），请使用 getb 替代 get

如果您的安装环境没有互联网访问，您也可以提前下载好特定版本的源码包手工上传。

1. # 从 CDN 或 Github 下载源码包
2. curl -L http://download.pigsty.cc/v2.0.2/pigsty-v2.0.2.tgz
3. curl -L https://github.com/Vonng/pigsty/releases/download/v2.0.2/pigsty-v2.0.2.tgz

5. # 如果 curl 不可用，git clone 也可以
6. git clone https://github.com/Vonng/pigsty; cd pigsty; git checkout v2.0.2

离线软件包

正常情况下，Pigsty 会从互联网上游下载所需的 RPM 包，但如果您的安装环境没有互联网访问，您可以提前下载好特定版本的离线软件包手工上传。

离线软件包可以极快地加速 Pigsty 的安装过程，省却几十分钟的下载时间，对于没有互联网访问的环境更是有用。它里面包含了 Pigsty 所需的软件及其依赖，大小在 1GB 左右。

Pigsty 会在 bootstrap 时，提示下载对应的离线软件包，您也可以手工下载对应系统的离线软件包以加速安装。下载后的软件包应当放置于 /tmp/pkg.tgz。

1. # CDN EL 7,8,9
2. curl -L http://download.pigsty.cc/v2.0.2/pigsty-pkg-v2.0.2.el9.x86_64.tgz -o /tmp/pkg.tgz  # EL9
3. curl -L http://download.pigsty.cc/v2.0.2/pigsty-pkg-v2.0.2.el8.x86_64.tgz -o /tmp/pkg.tgz  # EL8
4. curl -L http://download.pigsty.cc/v2.0.2/pigsty-pkg-v2.0.2.el7.x86_64.tgz -o /tmp/pkg.tgz  # EL7

6. # GITHUB EL 7,8,9
7. curl -L https://github.com/Vonng/pigsty/releases/download/v2.0.2/pigsty-pkg-v2.0.2.el9.x86_64.tgz -o /tmp/pkg.tgz  # EL9
8. curl -L https://github.com/Vonng/pigsty/releases/download/v2.0.2/pigsty-pkg-v2.0.2.el8.x86_64.tgz -o /tmp/pkg.tgz  # EL8
9. curl -L https://github.com/Vonng/pigsty/releases/download/v2.0.2/pigsty-pkg-v2.0.2.el7.x86_64.tgz -o /tmp/pkg.tgz  # EL7

Bootstrap

bootstrap 脚本的核心任务是确保：ansible 能用，并尽可能尝试使用离线软件包搭建本地 Yum 源。

Bootstrap 过程会用各种方式安装 ansible，如果需要的话，会提示您下载离线软件包（Ansible本身亦包含其中）。

1. ./boostrap [-p <path>=/tmp/pkg.tgz]   # 离线软件包的下载地址 (默认是/tmp/pkg.tgz，通常不需修改)
2. [-y|--yes] [-n|--no]       # 直接决定 是/否 下载离线软件包 (如果不指定，会交互式询问)

提示: 如果您决定直接从上游（互联网）安装所有软件包，bootstrap 过程是可选的。

Bootstrap 的详细逻辑如下：

  1. 检查安装的前提条件是否满足

  2. 检查本地离线安装包（/tmp/pkg.tgz）是否存在？

  3. 是 -> 解压到 /www/pigsty 并通过 /etc/yum.repos.d/pigsty-local.repo 来启用它

  4. 否 -> 进一步决定是否从互联网下载离线软件包？
  5. 是 -> 从 Github 或 CDN 下载离线软件包并解压
  6. 否 -> 是否添加操作系统基础的上游源地址以供从互联网下载 ?
    • 是 -> 根据地区与EL版本写入对应的上游源：/etc/yum.repos.d/
    • 否 -> 用户自己搞定，或者当前系统的默认配置就带有 Ansible
  7. 现在，我们有了一个可用的 yum repo，可以用来安装 pigsty 所需的软件包了，特别是 Ansible。

  8. 优先级顺序: 本地的 pkg.tgz > 下载的 pkg.tgz > 原始上游 > 默认配置

  9. 从上一步配置的软件源中，安装一些基本的重要软件，不同版本的软件略有不同：

  10. el7: ansible createrepo_c unzip wget yum-utils createrepo_c sshpass

  11. el8: ansible python39-jmespath createrepo_c unzip wget yum-utils createrepo_c sshpass modulemd-tools

  12. el8: ansible python3-jmespath createrepo_c unzip wget yum-utils createrepo_c sshpass modulemd-tools

  13. 检查 ansible 是否成功安装。

从本地离线软件包 Bootstrap 的样例输出

如果离线软件包存在于 /tmp/pkg.tgz， bootstrap 会直接使用它：

1. bootstrap pigsty v2.0.2 begin
2. [ OK ] region = china
3. [ OK ] kernel = Linux
4. [ OK ] machine = x86_64
5. [ OK ] release = 7.9.2009
6. [ OK ] sudo = vagrant ok
7. [ OK ] cache = /tmp/pkg.tgz exists
8. [ OK ] repo = extract from /tmp/pkg.tgz
9. [ OK ] repo file = use /etc/yum.repos.d/pigsty-local.repo
10. [ OK ] repo cache = created
11. [ OK ] install el7 utils
12. ....(yum install ansible output)
13. [ OK ] ansible = ansible 2.9.27
14. [ OK ] boostrap pigsty complete
15. proceed with ./configure
16. ``` 从互联网下载离线软件包的 Bootstrap 样例输出

18. 从 Github/CDN 下载 `pkg.tgz` 并解压使用：

bootstrap pigsty v2.0.2 begin [ OK ] region = china [ OK ] kernel = Linux [ OK ] machine = x86_64 [ OK ] release = 7.9.2009 [ OK ] sudo = vagrant ok [ IN ] Cache /tmp/pkg.tgz not exists, download? (y/n): => y [ OK ] download from Github http://download.pigsty.cc/v2.0.2/pigsty-pkg-v2.0.2.el7.x86_64.tgz to /tmp/pkg.tgz % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 913M 100 913M 0 0 661k 0 0:23:33 0:23:33 —:—:— 834k [ OK ] repo = extract from /tmp/pkg.tgz [ OK ] repo file = use /etc/yum.repos.d/pigsty-local.repo [ OK ] repo cache = created [ OK ] install el7 utils

…… (yum install createrepo_c sshpass unzip output)

Package Arch Version Repository Size

Installing: createrepo_c x86_64 0.10.0-20.el7 pigsty-local 65 k sshpass x86_64 1.06-2.el7 pigsty-local 21 k unzip x86_64 6.0-24.el7_9 pigsty-local 172 k Installing for dependencies: createrepo_c-libs x86_64 0.10.0-20.el7 pigsty-local 89 k

Transaction Summary

…… (yum install ansible output)

Package Arch Version Repository Size

Installing: ansible noarch 2.9.27-1.el7 pigsty-local 17 M Installing for dependencies: PyYAML x86_64 3.10-11.el7 pigsty-local 153 k libyaml x86_64 0.1.4-11.el7_0 pigsty-local 55 k python-babel noarch 0.9.6-8.el7 pigsty-local 1.4 M python-backports x86_64 1.0-8.el7 pigsty-local 5.8 k python-backports-ssl_match_hostname noarch 3.5.0.1-1.el7 pigsty-local 13 k python-cffi x86_64 1.6.0-5.el7 pigsty-local 218 k python-enum34 noarch 1.0.4-1.el7 pigsty-local 52 k python-idna noarch 2.4-1.el7 pigsty-local 94 k python-ipaddress noarch 1.0.16-2.el7 pigsty-local 34 k python-jinja2 noarch 2.7.2-4.el7 pigsty-local 519 k python-markupsafe x86_64 0.11-10.el7 pigsty-local 25 k python-paramiko noarch 2.1.1-9.el7 pigsty-local 269 k python-ply noarch 3.4-11.el7 pigsty-local 123 k python-pycparser noarch 2.14-1.el7 pigsty-local 104 k python-setuptools noarch 0.9.8-7.el7 pigsty-local 397 k python-six noarch 1.9.0-2.el7 pigsty-local 29 k python2-cryptography x86_64 1.7.2-2.el7 pigsty-local 502 k python2-httplib2 noarch 0.18.1-3.el7 pigsty-local 125 k python2-jmespath noarch 0.9.4-2.el7 pigsty-local 41 k python2-pyasn1 noarch 0.1.9-7.el7 pigsty-local 100 k

Transaction Summary

… Complete! [ OK ] ansible = ansible 2.9.27 [ OK ] boostrap pigsty complete proceed with ./configure

2. ---

4. ## 配置

6. [configure](https://pigsty.cc/en/docs/config) 会根据您当前的环境，自动生成一个 [pigsty.yml](https://github.com/Vonng/pigsty/blob/master/pigsty.yml) 配置文件。

./configure [-n|—non-interactive] [-i|—ip ] [-m|—mode ] [-r|—region ]

2. -   `-m|--mode`: 直接指定配置[模板](https://github.com/Vonng/pigsty/tree/master/files/pigsty) : (`auto|demo|sec|citus|el8|el9|...`)
3. -   `-i|--ip`: 用于替换IP地址占位符 `10.10.10.10` 的IP地址，即当前主机的首要内网IP地址（特别是在有多块网卡与多个IP地址时）
4. -   `-r|--region`: 用于指定上游源的区域： (`default|china|europe`)
5. -   `-n|--non-interactive`: 直接使用命令行参数提供首要IP地址，跳过交互式向导。

7. 当使用 `-n|--non-interactive` 参数时，您需要使用 `-i|--ip <ipaddr>` 指定当前节点的首要IP地址，特别是在有多块网卡与多个IP地址时。

9. > 提示: 如果您已经了解了如何配置 Pigsty， `configure` 这个步骤是可选的。

11. 请注意，在一个严肃的生产部署中，您应当修改配置文件中所有 `password` 类的参数。

13. configure 的样例输出

[vagrant@meta pigsty]$ ./configure configure pigsty v2.0.2 begin [ OK ] region = china [ OK ] kernel = Linux [ OK ] machine = x86_64 [ OK ] sudo = vagrant ok [ OK ] ssh = vagrant@127.0.0.1 ok [WARN] Multiple IP address candidates found: (1) 10.0.2.15 inet 10.0.2.15/24 brd 10.0.2.255 scope global noprefixroute dynamic eth0 (2) 10.10.10.10 inet 10.10.10.10/24 brd 10.10.10.255 scope global noprefixroute eth1 [ OK ] primary_ip = 10.10.10.10 (from demo) [ OK ] admin = vagrant@10.10.10.10 ok [ OK ] mode = demo (vagrant demo) [ OK ] config = demo @ 10.10.10.10 [ OK ] ansible = ansible 2.9.27 [ OK ] configure pigsty done proceed with ./install.yml

2. ---

4. ## 安装

6. 使用 [install.yml](https://github.com/Vonng/pigsty/blob/master/pigsty.yml) 剧本，默认在当前节点上完成标准的单节点 Pigsty 安装。

./install.yml # install everything in one-pass

2. 这是一个标准的 Ansible 剧本，您可以使用以下参数控制其执行的目标、任务、并传递额外的命令参数：

4. -   `-l`: 限制执行的目标对象
5. -   `-t`: 限制要执行的任务
6. -   `-e`: 传入额外的命令行参数
7. -   …

9. > 警告： 在已经初始化的环境中再次运行 [install.yml](https://github.com/Vonng/pigsty/blob/master/install.yml) 会重置整个环境，所以请小心谨慎。
10. >
11. > 您可以 `chmod a-x install.yml` 避免误执行此剧本。

13. 安装过程的样例输出

[vagrant@meta pigsty]$ ./install.yml

PLAY [IDENTITY] ********************

TASK [node_id : get node fact] ***************** changed: [10.10.10.12] changed: [10.10.10.11] changed: [10.10.10.13] changed: [10.10.10.10] … … PLAY RECAP ************************** 10.10.10.10 : ok=288 changed=215 unreachable=0 failed=0 skipped=64 rescued=0 ignored=0 10.10.10.11 : ok=263 changed=194 unreachable=0 failed=0 skipped=88 rescued=0 ignored=1 10.10.10.12 : ok=263 changed=194 unreachable=0 failed=0 skipped=88 rescued=0 ignored=1 10.10.10.13 : ok=153 changed=121 unreachable=0 failed=0 skipped=53 rescued=0 ignored=1 localhost : ok=3 changed=0 unreachable=0 failed=0 skipped=4 rescued=0 ignored=0

2. ---

4. ## 用户界面

6. 当安装完成后，当前节点会安装有四个模块： [INFRA](https://pigsty.cc/en/docs/infra), [NODE](https://pigsty.cc/en/docs/node), [ETCD](https://pigsty.cc/en/docs/etcd) , [PGSQL](https://pigsty.cc/en/docs/pgsql) 。

8. -   [INFRA](https://pigsty.cc/en/docs/infra): Pigsty Web界面可以通过80端口访问 `http://<ip>:80` （如果第一次访问提示错误，请多刷新几次页面）
9. -   [PGSQL](https://pigsty.cc/en/docs/pgsql): 您可以使用默认连接串访问PGSQL数据库: `postgres://dbuser_meta:DBUser.Meta@<ip>:5432/meta`

11. 一些基础设施服务组件会使用 Nginx 对外暴露 WebUI ( 可通过参数 [infra\_portal](https://pigsty.cc/en/docs/param#infra_portal) 进行配置):

13. &lt;table>&lt;thead>&lt;tr>&lt;th>组件&lt;/th>&lt;th>端口&lt;/th>&lt;th>域名&lt;/th>&lt;th>说明&lt;/th>&lt;th>Demo地址&lt;/th>&lt;/tr>&lt;/thead>&lt;tbody>&lt;tr>&lt;td>Nginx&lt;/td>&lt;td>80&lt;/td>&lt;td>&lt;code>h.pigsty&lt;/code>&lt;/td>&lt;td>Web Service Portal, Repo&lt;/td>&lt;td>&lt;a href="http://home.pigsty.cc">home.pigsty.cc&lt;/a>&lt;/td>&lt;/tr>&lt;tr>&lt;td>AlertManager&lt;/td>&lt;td>9093&lt;/td>&lt;td>&lt;code>a.pigsty&lt;/code>&lt;/td>&lt;td>Alter Aggregator&lt;/td>&lt;td>&lt;a href="http://a.pigsty.cc">a.pigsty.cc&lt;/a>&lt;/td>&lt;/tr>&lt;tr>&lt;td>Grafana&lt;/td>&lt;td>3000&lt;/td>&lt;td>&lt;code>g.pigsty&lt;/code>&lt;/td>&lt;td>Grafana Dashboard Home&lt;/td>&lt;td>&lt;a href="http://demo.pigsty.cc">demo.pigsty.cc&lt;/a>&lt;/td>&lt;/tr>&lt;tr>&lt;td>Prometheus&lt;/td>&lt;td>9090&lt;/td>&lt;td>&lt;code>p.pigsty&lt;/code>&lt;/td>&lt;td>Prometheus Web UI&lt;/td>&lt;td>&lt;a href="http://p.pigsty.cc">p.pigsty.cc&lt;/a>&lt;/td>&lt;/tr>&lt;/tbody>&lt;/table>

15. 您可以通过 IP地址 + 端口的方式直接访问这些服务，也可以通过域名来访问。我们强烈建议您通过 Nginx 域名代理访问所有组件，并对所有的端口权限进行访问控制，以避免未经授权的访问。

17. 使用域名访问 Pigsty WebUI 时，您需要配置 DNS 服务器，或者修改 `/etc/hosts` 文件， 如果您使用本地沙箱， `sudo make dns` 会将所需的本地域名写入 `/etc/hosts`

19. 例如，当您使用 `http://g.pigsty` 访问 Grafana 监控主页时，实际上是通过 Nginx 代理访问了 Grafana 的 WebUI：

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

2. > Grafana 的默认密码为: username: `admin`, password: `pigsty`

4. 如何使用 HTTPS 访问 Pigsty WebUI

6. Pigsty默认使用自动生成的自签名的CA证书为Nginx启用SSL，如果您希望使用 HTTPS 访问这些页面，而不弹窗提示"不安全"，通常有三个选择：

8. -   在您的浏览器或操作系统中信任Pigsty自签名的CA证书： `files/pki/ca/ca.crt`
9. -   如果您使用 Chrome，可以在提示不安全的窗口键盘输入 `thisisunsafe` 跳过提示
10. -   您可以考虑使用 Let’s Encrypt 或其他免费的CA证书服务，为 Pigsty Nginx 生成正式的CA证书

12. ---

14. ## 更多

16. 你可以使用 Pigsty 部署更多的集群，管理更多的节点，例如

bin/node-add pg-test # 将集群 pg-test 的3个节点纳入 Pigsty 管理 bin/pgsql-add pg-test # 初始化一个3节点的 pg-test 高可用PG集群 bin/redis-add redis-ms # 初始化 Redis 集群： redis-ms ```

更多细节请参见： PGSQL, NODE, and REDIS.

最后修改 2023-04-07: bump en docs to v2.0.2 (5a16652)