快速上手 Pigsty 单机部署

快速上手 Pigsty，从一台全新的 Linux 主机开始，完成单机安装部署！

教程

PIGSTY

本文是 Pigsty 单节点安装指南单节点，生产环境的多节点高可用部署请参考部署文档。

Pigsty 单机安装分为三步走：安装，配置与部署。

摘要

准备一台具有 SSH 权限 的节点，安装 兼容的 Linux 系统，使用具有免密 ssh 和 sudo 权限的 管理用户 执行：

选择 Pigsty 下载镜像：

pigsty.cc（中国）

curl -fsSL https://repo.pigsty.cc/get | bash

pigsty.io（全球）

curl -fsSL https://repo.pigsty.io/get | bash

该命令会执行安装脚本，下载并提取 Pigsty 源码至家目录并安装依赖，接下来依次完成配置与部署即可完成交付。

进入源码目录

cd ~/pigsty

生成配置清单

./configure -g

如果你已经准备好 pigsty.yml，可以跳过这一步。

执行部署剧本

./deploy.yml

安装完成后，您可以通过 IP / 域名 + 80/443 端口访问 Web 用户界面，并通过 5432 端口访问 PostgreSQL 服务。

完整流程根据服务器规格/网络条件需 3~10 分钟，离线安装 时能够显著加速；无需监控时可使用 精简安装 进一步加速。

视频样例：在线单机安装（Debian 13, x86_64）

demo/install-hero.cast

准备

安装 Pigsty 涉及一些 准备工作，以下是简略检查清单，单机部署时，许多限制可以放宽。

项目	要求	项目	要求
节点	单节点，至少 `1C2G`，上不封顶	磁盘	`/data` 作为默认主挂载点，建议使用 `xfs`
系统	`Linux` `x86_64` / `aarch64`，EL / Debian / Ubuntu	网络	静态 IPv4 内网地址
SSH	通过公钥 `nopass` SSH 登陆纳管节点	SUDO	sudo 权限，最好带有 `nopass` 免密选项

通常您只需要关注本机 IP 地址 —— 作为特例，单机部署时，如果没有静态 IP 地址，可使用 127.0.0.1 作为逃生窗口。

安装

您可以使用以下命令自动安装 Pigsty 源码包至 ~/pigsty 目录（推荐），部署所需依赖（Ansible）会自动安装。

选择 Pigsty 下载镜像：

pigsty.cc（中国）

curl -fsSL https://repo.pigsty.cc/get | bash            # 安装当前默认版本
curl -fsSL https://repo.pigsty.cc/get | bash -s v4.5.0  # 显式安装当前公开稳定版

pigsty.io（全球）

curl -fsSL https://repo.pigsty.io/get | bash            # 安装当前默认版本
curl -fsSL https://repo.pigsty.io/get | bash -s v4.5.0  # 显式安装当前公开稳定版

如果您不希望执行远程脚本，可以手动下载或克隆源码。使用 git 克隆安装时，请务必检出特定版本后再使用。

git clone https://github.com/pgsty/pigsty; cd pigsty;
git checkout v4.5.0;  # 使用 git 安装时，请务必检出已发布的 tag

手工下载克隆安装时，请额外执行 bootstrap 脚本以手动安装 Ansible 等部署依赖，您也可以 自行安装。

./bootstrap           # 安装 ansible，用于执行后续部署

配置

在 Pigsty 中，部署的蓝图细节由 配置清单 所定义，也就是 pigsty.yml 配置文件，您可以通过声明式配置进行定制。

Pigsty 提供了 configure 脚本作为可选的 配置向导，它将根据您的环境和输入，生成具有良好默认值的 配置清单：

./configure -g                # 使用配置向导生成配置文件，并且生成随机密码

配置过程生成的配置文件默认位于：~/pigsty/pigsty.yml，您可以在安装前进行检查，按需修改与定制。

有许多 配置模板 供您参考与使用，但您也完全可以跳过配置向导，直接编辑 pigsty.yml 配置文件进行定制。

./configure                  # 使用默认模板，安装默认的 PG 18，带有必要扩展
./configure -v 17            # 使用 PG 17 的版本，而非默认的 PG18
./configure -c rich          # 创建本地软件仓库，下载所有扩展，安装主要扩展
./configure -c slim          # 最小安装模板，与 ./slim.yml 剧本一起使用
./configure -c app/supa      # 使用 app/supa 自托管 supabase 配置模板
./configure -c ivory         # 使用 ivorysql 内核而非原生 PG
./configure -i 10.11.12.13   # 显式指定主 IP 地址
./configure -r china         # 使用中国镜像而非默认仓库
./configure -c ha/full -s    # 使用 4 节点沙箱配置模板，不进行 IP 替换和探测

下面展示的是当前 main 分支（v5.0.0-preview）的输出；若安装其他版本，首行会显示对应版本号。

当前 main 分支的 configure 样例输出

示例 1 当前 main 分支的 configure 样例输出

vagrant@meta:~/pigsty$ ./configure
configure pigsty v4.5.0 begin
[ OK ] region = china
[ OK ] kernel  = Linux
[ OK ] machine = x86_64
[ OK ] package = deb,apt
[ OK ] vendor  = ubuntu (Ubuntu)
[ OK ] version = 22 (22.04)
[ OK ] sudo = vagrant ok
[ OK ] ssh = vagrant@127.0.0.1 ok
[WARN] Multiple IP address candidates found:
    (1) 192.168.121.38	    inet 192.168.121.38/24 metric 100 brd 192.168.121.255 scope global dynamic eth0
    (2) 10.10.10.10	    inet 10.10.10.10/24 brd 10.10.10.255 scope global eth1
[ OK ] primary_ip = 10.10.10.10 (from demo)
[ OK ] admin = vagrant@10.10.10.10 ok
[ OK ] mode = meta (ubuntu22.04)
[ OK ] locale  = C.UTF-8
[ OK ] ansible = ready
[ OK ] pigsty configured
[WARN] don't forget to check it and change passwords!
proceed with ./deploy.yml

配置脚本常用参数

-i | --ip , IPv4: 当前主机的首要内网 IP 地址，用于替换配置文件中的 IP 地址占位符 10.10.10.10。
-c | --conf , string: 指定 配置模板，填写相对于 conf/ 目录且不带 .yml 后缀的名称。
-v | --version , integer: 指定 PostgreSQL 大版本 14～19；PG19 当前为 Beta，建议使用专用 pg19 模板。
-r | --region , enum , defaultdefault: 指定上游软件源区域以加速下载：default、china 或 europe。
-n | --non-interactive , boolean , defaultfalse: 直接使用命令行参数提供首要 IP 地址，跳过交互式向导。
-x | --proxy , boolean , defaultfalse: 使用当前环境变量配置 proxy_env 变量。

如果您的机器网卡绑定了多个 IP 地址，那么需要使用 -i|--ip <ipaddr> 显式指定一个当前节点的首要 IP 地址，或在交互式问询中提供。该脚本将把 IP 占位符 10.10.10.10 替换为当前节点的主 IPv4 地址。选用的地址应为静态 IP 地址，请勿使用公网 IP 地址。

修改默认密码！

我们强烈建议您在安装前，事先修改配置文件中使用的默认密码与凭据，详情参考 安全建议。

部署

Pigsty 的 deploy.yml 剧本会将配置中生成的蓝图应用至目标节点。

./deploy.yml     # 一次性部署核心链路中已定义的模块

部署过程的样例输出

......

TASK [pgsql : pgsql init done] *************************************************
ok: [10.10.10.11] => {
    "msg": "postgres://10.10.10.11/postgres | meta  | dbuser_meta dbuser_view "
}
......

TASK [pg_monitor : load grafana datasource meta] *******************************
changed: [10.10.10.11]

PLAY RECAP *********************************************************************
10.10.10.11                : ok=302  changed=232  unreachable=0    failed=0    skipped=65   rescued=0    ignored=1
localhost                  : ok=6    changed=3    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

当您看到输出尾部如果带有 pgsql init done，PLAY RECAP 等字样，说明安装已经完成！

上游软件仓库变更可能导致在线安装失败！

Pigsty 使用的上游软件仓库（如 Linux / PGDG 仓库）可能会因为不恰当的更新，进入崩溃状态并导致部署失败（有过多次先例）！您可以选择等待上游仓库修复后安装，或者使用预制的 离线软件包 解决这个问题。

避免重复执行部署剧本！

警告：在已经完成部署的环境中再次完整运行 deploy.yml 可能会重启相关服务并覆盖配置，请务必注意！

界面

Pigsty 单机安装完成后，您在当前节点上通常会安装有四个功能模块： PGSQL、INFRA、NODE 和 ETCD。

ID	NODE	PGSQL	INFRA	ETCD
1	`10.10.10.10`	`pg-meta-1`	`infra-1`	`etcd-1`

INFRA 模块通过浏览器提供了一个 图形化管理界面，您可以直接通过这台节点上的 Nginx 的 80/443 端口访问。

PGSQL 模块提供了一个 PostgreSQL 数据库服务器，监听 5432 端口，也可通过 Pgbouncer / HAProxy 代理访问。

您可以以当前节点作为基础，部署和监控 更多集群：向 配置清单 添加数据库集群的定义并运行：

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

大多数模块都需要先安装 NODE 模块。查看可用的模块了解详情：

PGSQL、INFRA、NODE、ETCD、 MINIO、REDIS、DOCKER……