# 快速上手 Pigsty 单机部署 > 快速上手 Pigsty，从一台全新的 Linux 主机开始，完成单机安装部署！ --- LLMS 索引： [llms.txt](/zh/llms.txt) --- 本文是 Pigsty 单节点安装指南 **单节点**，生产环境的多节点高可用部署请参考 [**部署**](/docs/deploy/) 文档。 Pigsty 单机安装分为三步走：[**安装**](#安装)，[**配置**](#配置) 与 [**部署**](#部署)。 ---------------- ## 摘要 [**准备**](/docs/deploy/prepare) 一台具有 [**SSH 权限**](/docs/deploy/admin#ssh) 的 [**节点**](/docs/deploy/prepare#节点)， 安装 [**兼容的 Linux 系统**](/docs/ref/linux/)，使用具有免密 [**`ssh`**](/docs/deploy/admin#ssh) 和 [**`sudo`**](/docs/deploy/admin#sudo) 权限的 [**管理用户**](/docs/deploy/admin) 执行： **选择 Pigsty 下载镜像：** ```bash {tab="pigsty.cc（中国）" group="download-mirror" value="china" copy="all"} curl -fsSL https://repo.pigsty.cc/get | bash ``` ```bash {tab="pigsty.io（全球）" value="global" copy="all"} curl -fsSL https://repo.pigsty.io/get | bash ``` 该命令会执行 [**安装**](#安装) 脚本，下载并提取 Pigsty 源码至家目录并安装依赖，接下来依次完成 [**配置**](#配置) 与 [**部署**](#部署) 即可完成交付。 ### 进入源码目录 ```bash {title="Terminal" copy="all"} cd ~/pigsty ``` ### 生成配置清单 ```bash {title="Terminal" copy="all"} ./configure -g ``` 如果你已经准备好 `pigsty.yml`，可以跳过这一步。 ### 执行部署剧本 ```bash {title="Terminal" copy="all"} ./deploy.yml ``` 安装完成后，您可以通过 IP / 域名 + `80/443` 端口访问 [**Web 用户界面**](/docs/setup/webui/)， 并通过 `5432` 端口访问 [**PostgreSQL 服务**](/docs/setup/pgsql/)。 完整流程根据服务器规格/网络条件需 3~10 分钟，[**离线安装**](/docs/setup/offline/) 时能够显著加速；无需监控时可使用 [**精简安装**](/docs/setup/slim/) 进一步加速。 **视频样例：在线单机安装（Debian 13, x86_64）**
demo/install-hero.cast
---------------- ## 准备 安装 Pigsty 涉及一些 [**准备工作**](/docs/deploy/)，以下是简略检查清单，单机部署时，许多限制可以放宽。 | 项目 | 要求 | 项目 | 要求 | |:------------------------------------:|:--------------------------------------------------|:-----------------------------------:|:----------------------------| | [**节点**](/docs/deploy/prepare#节点) | **单节点**，至少 `1C2G`，上不封顶 | [**磁盘**](/docs/deploy/prepare#磁盘) | `/data` 作为默认主挂载点，建议使用 `xfs` | | [**系统**](/docs/deploy/prepare#linux) | `Linux` `x86_64` / `aarch64`，EL / Debian / Ubuntu | [**网络**](/docs/deploy/prepare#网络) | 静态 IPv4 内网地址 | | [**SSH**](/docs/deploy/admin#ssh) | 通过公钥 `nopass` SSH 登陆纳管节点 | [**SUDO**](/docs/deploy/admin#sudo) | sudo 权限，最好带有 `nopass` 免密选项 | {.full-width} 通常您只需要关注本机 **IP 地址** —— 作为特例，单机部署时，如果没有静态 IP 地址，可使用 `127.0.0.1` 作为逃生窗口。 ---------------- ## 安装 您可以使用以下命令自动安装 Pigsty 源码包至 `~/pigsty` 目录（推荐），部署所需依赖（Ansible）会自动安装。 **选择 Pigsty 下载镜像：** ```bash {tab="pigsty.cc（中国）" group="download-mirror" value="china" copy="all"} curl -fsSL https://repo.pigsty.cc/get | bash # 安装当前默认版本 curl -fsSL https://repo.pigsty.cc/get | bash -s v4.5.0 # 显式安装当前公开稳定版 ``` ```bash {tab="pigsty.io（全球）" value="global" copy="all"} curl -fsSL https://repo.pigsty.io/get | bash # 安装当前默认版本 curl -fsSL https://repo.pigsty.io/get | bash -s v4.5.0 # 显式安装当前公开稳定版 ``` 如果您不希望执行远程脚本，可以手动 [**下载**](https://github.com/pgsty/pigsty/releases) 或克隆源码。使用 `git` 克隆安装时，请务必检出特定版本后再使用。 ```bash {title="Terminal" copy="all" label="从 Git 安装 Pigsty"} git clone https://github.com/pgsty/pigsty; cd pigsty; git checkout v4.5.0; # 使用 git 安装时，请务必检出已发布的 tag ``` 手工下载克隆安装时，请额外执行 [**`bootstrap`**](/docs/setup/offline#bootstrap) 脚本以手动安装 Ansible 等部署依赖，您也可以 [**自行安装**](/docs/setup/playbook#安装-ansible)。 ```bash {title="Terminal" copy="all"} ./bootstrap # 安装 ansible，用于执行后续部署 ``` ---------------- ## 配置 在 Pigsty 中，部署的蓝图细节由 [**配置清单**](/docs/setup/config/) 所定义，也就是 [**`pigsty.yml`**](https://github.com/pgsty/pigsty/blob/main/pigsty.yml) 配置文件，您可以通过声明式配置进行定制。 Pigsty 提供了 [**`configure`**](https://github.com/pgsty/pigsty/blob/main/configure) 脚本作为可选的 [**配置向导**](/docs/concept/iac/configure)， 它将根据您的环境和输入，生成具有良好默认值的 [**配置清单**](/docs/concept/iac/inventory/)： ```bash {title="Terminal" copy="all" label="运行 Pigsty 配置向导"} ./configure -g # 使用配置向导生成配置文件，并且生成随机密码 ``` 配置过程生成的配置文件默认位于：`~/pigsty/pigsty.yml`，您可以在安装前进行检查，按需修改与定制。 有许多 [**配置模板**](/docs/concept/iac/template/) 供您参考与使用，但您也完全可以跳过配置向导，直接编辑 `pigsty.yml` 配置文件进行定制。 ```bash {title="Terminal" copy="all" collapse=6 label="常用 configure 命令"} ./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）的输出；若安装其他版本，首行会显示对应版本号。 > [!DETAILS]- 当前 main 分支的 configure 样例输出 > ```console {title="configure output" copy="command" collapse=12 label="configure 样例输出" num="1" caption="当前 main 分支的 configure 样例输出" #configure-output} > 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` 指定 [**配置模板**](/docs/conf/)，填写相对于 `conf/` 目录且不带 `.yml` 后缀的名称。 - `-v | --version` — `integer` 指定 PostgreSQL 大版本 `14`～`19`；PG19 当前为 Beta，建议使用专用 [`pg19`](/docs/conf/pg19/) 模板。 - `-r | --region` — `enum`; default: `default` 指定上游软件源区域以加速下载：`default`、`china` 或 `europe`。 - `-n | --non-interactive` — `boolean`; default: `false` 直接使用命令行参数提供首要 IP 地址，跳过交互式向导。 - `-x | --proxy` — `boolean`; default: `false` 使用当前环境变量配置 [`proxy_env`](/docs/infra/param#proxy_env) 变量。 如果您的机器网卡绑定了多个 IP 地址，那么需要使用 `-i|--ip ` 显式指定一个当前节点的首要 IP 地址，或在交互式问询中提供。 该脚本将把 IP 占位符 `10.10.10.10` 替换为当前节点的主 IPv4 地址。选用的地址应为静态 IP 地址，请勿使用公网 IP 地址。 > [!WARNING] 修改默认密码！ > 我们强烈建议您在安装前，事先修改配置文件中使用的默认密码与凭据，详情参考 [**安全建议**](/docs/setup/security/)。 -------- ## 部署 Pigsty 的 [**`deploy.yml`**](/docs/setup/playbook/) [**剧本**](/docs/setup/playbook/) 会将 [**配置**](#配置) 中生成的蓝图应用至目标节点。 ```bash {title="Terminal" copy="all" label="执行 Pigsty 部署剧本"} ./deploy.yml # 一次性部署核心链路中已定义的模块 ``` > [!DETAILS]- 部署过程的样例输出 > ```console {title="deploy output" copy=false collapse=10 label="Pigsty 部署输出"} > ...... > > 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` 等字样，说明安装已经完成！ > [!WARNING] 上游软件仓库变更可能导致在线安装失败！ > Pigsty 使用的上游软件仓库（如 Linux / PGDG 仓库）可能会因为不恰当的更新，进入崩溃状态并导致部署失败（有过多次先例）！ > 您可以选择等待上游仓库修复后安装，或者使用预制的 [**离线软件包**](/docs/setup/offline#离线软件包) 解决这个问题。 > [!WARNING] 避免重复执行部署剧本！ > 警告： 在已经完成部署的环境中再次完整运行 [**`deploy.yml`**](https://github.com/pgsty/pigsty/blob/main/deploy.yml) 可能会重启相关服务并覆盖配置，请务必注意！ -------- ## 界面 Pigsty 单机安装完成后，您在当前节点上通常会安装有四个功能模块： [**`PGSQL`**](/docs/pgsql/)、[**`INFRA`**](/docs/infra/)、[**`NODE`**](/docs/node/) 和 [**`ETCD`**](/docs/etcd/)。 | ID | [NODE](/docs/node/) | [PGSQL](/docs/pgsql/) | [INFRA](/docs/infra/) | [**ETCD**](/docs/etcd/) | |:--:|:-------------------:|:---------------------:|:---------------------:|:-----------------------:| | 1 | `10.10.10.10` | `pg-meta-1` | `infra-1` | `etcd-1` | {.full-width} [**`INFRA`**](/docs/infra) 模块通过浏览器提供了一个 [**图形化管理界面**](/docs/setup/webui)，您可以直接通过这台节点上的 Nginx 的 **80/443** 端口访问。 [**`PGSQL`**](/docs/pgsql/) 模块提供了一个 [**PostgreSQL 数据库服务器**](/docs/setup/pgsql)，监听 **5432** 端口，也可通过 Pgbouncer / HAProxy [**代理访问**](/docs/pgsql/service)。 [![Pigsty 在线演示首页](/img/pigsty/home.png)](https://demo.pigsty.cc/zh) ---------------- ## 更多 您可以以当前节点作为基础，部署和监控 [**更多集群**](/docs/conf/full)：向 [**配置清单**](/docs/setup/config/) 添加数据库集群的定义并运行： ```bash 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`**](/docs/node/) 模块。查看可用的 [**模块**](/docs/ref/module/) 了解详情： [**`PGSQL`**](/docs/pgsql/)、[**`INFRA`**](/docs/infra/)、[**`NODE`**](/docs/node/)、[**`ETCD`**](/docs/etcd/)、 [**`MINIO`**](/docs/minio/)、[**`REDIS`**](/docs/redis/)、[**`DOCKER`**](/docs/docker/)……