Pigsty v4.5.0 Docker Compose 部署指南

目标：在一台 Linux 服务器上用 Docker Compose 拉起 Pigsty v4.5.0 单节点演示栈，完成 PostgreSQL + Patroni 高可用 + Grafana/VictoriaMetrics 监控 + pgBackRest 备份的全栈部署，并验证数据库连接与监控面板可用。本篇已在 Debian 13 实例内实测通过（2026-10-25）。

一、环境信息

操作系统：Debian 13 (trixie)，x86_64
Pigsty 版本：v4.5.0
PostgreSQL 版本：18.6
pig CLI 版本：1.8.0
实例 docker 镜像：pgsty/pigsty:v4.5.0（单实例内含 systemd，跑完整栈）
对外端口：HTTP 80 / HTTPS 443 / PostgreSQL 5432 / SSH 22
数据目录：/data（持久化挂载到宿主机）
内存要求：至少 2GB（完整监控栈有一定开销）
磁盘要求：至少 20GB 可用

二、docker 镜像选型说明

Pigsty 官方提供开箱即用的单实例 docker 镜像 pgsty/pigsty:<version>，实例内自带 systemd，一次启动即可运行 PostgreSQL、Patroni、HAProxy、Grafana、VictoriaMetrics、VictoriaLogs、Alertmanager、pg_exporter 等全部组件。

docker 镜像	说明	适用场景
`pgsty/pigsty:v4.5.0`	官方全栈 docker 镜像，含全部组件	本地体验、开发测试、功能验证
自行构建	基于 `docker/Dockerfile` 定制	需要裁剪组件或换基础系统时

⚠️ 单实例形态不提供跨节点高可用，仅用于开发与体验；生产环境请使用裸机/虚机 Ansible 部署 3 节点以上集群。

三、前置条件

服务器需满足：

Docker 20.10+ 与 Docker Compose v2 已安装。
端口空闲：宿主机 80、443、5432、22（或自定义映射端口）未被占用。
资源：至少 1 核 CPU、2GB 内存、20GB 磁盘。

docker --version
docker compose version
free -h
df -h /

四、部署步骤

4.1 获取编排文件

Pigsty 官方仓库的 docker/ 目录提供了 docker-compose.yml、Makefile 与 .env。克隆仓库并进入 docker 目录：

git clone https://github.com/pgsty/pigsty.git
cd pigsty/docker

说明：如果服务器无法直连 GitHub，可走代理 https://192.168.1.62:7897 克隆，或直接从 Release 下载 pigsty-v4.5.0.tar.gz 解压。

4.2 配置端口与版本

.env 文件控制 docker 镜像版本与端口映射，可按需修改：

cat .env

回显：

PIGSTY_VERSION=v4.5.0
PIGSTY_SSH_PORT=2222
PIGSTY_HTTP_PORT=8080
PIGSTY_HTTPS_PORT=8443
PIGSTY_PG_PORT=5432

若宿主机 8080 被占用，修改 PIGSTY_HTTP_PORT 即可（如改为 8140）。

4.3 启动实例

make up

回显（节选）：

 Container pigsty  Creating
 Container pigsty  Created
 Container pigsty  Starting
 Container pigsty  Started

实例启动后，内部 systemd 会拉起全部服务。等待约 10 秒，确认 systemd 就绪：

docker exec pigsty systemctl is-system-running

回显：

running

4.4 生成配置（含随机密码）

make config

该命令等价于在实例内执行 ./configure -c docker -g --ip 127.0.0.1，生成 pigsty.yml 配置并随机生成所有密码。回显（节选）：

configure pigsty v4.5.0 begin
[ OK ] region = default
[ OK ] kernel  = Linux
[ OK ] machine = x86_64
[ OK ] package = deb,apt
[ OK ] vendor  = debian (Debian GNU/Linux)
[ OK ] version = 13 (13)
[ OK ] sudo = root ok
[ OK ] ssh = root@127.0.0.1 ok
[ OK ] primary_ip = 127.0.0.1 (from argument)
[ OK ] mode = docker (manually set)
[ OK ] generating random passwords...
    grafana_admin_password  : YGjgMRQRZKdrt79QaDoHbLqe
    pg_admin_password       : aEOXT5W3Td2JTrFAAXgycElT
    pg_monitor_password     : A5E3PHes0Rxc84q4WdWQdY6B
    pg_replication_password : pN2C56sfHgBW59t2YihqBLnF
    patroni_password        : 4r5x2vXBmGWxboHpm0GV8OKO
    haproxy_admin_password  : NZ8Biq7KSLmPzZyRjvx1MqTf
    minio_secret_key        : xnbgUaGkxC3MOOD9299VeEIQ
    etcd_root_password      : XiURY3GazvzRn8XXrXqja10D
[ OK ] random passwords generated, check and save them
[ OK ] ansible = ready
[ OK ] pigsty configured
proceed with ./deploy.yml

💡 请妥善保存这些随机密码。可用 make pass 随时查看。

4.5 执行部署

make deploy

该命令在实例内执行 ./deploy.yml（Ansible playbook），完成节点初始化、基础设施（Etcd、Grafana、VictoriaMetrics 等）、PostgreSQL、Patroni、HAProxy、pgBouncer、pg_exporter、备份等全部组件的安装与配置。

回显尾部（成功标志）：

PLAY RECAP *********************************************************************
127.0.0.1                  : ok=267  changed=118  unreachable=0    failed=0    skipped=113  rescued=0    ignored=0

failed=0 表示部署成功。

4.6 一键启动（up + config + deploy）

如果是全新环境，也可以直接用一条命令完成全部步骤：

make launch

等价于依次执行 make up → make config → make deploy。

五、验证部署

5.1 验证 PostgreSQL

PGPASSWORD=<pg_admin_password> psql -h 127.0.0.1 -p 5432 -U dbuser_dba -d postgres -c "SELECT version();"

回显：

                                                      version
--------------------------------------------------------------------------------------------------------------------
 PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
(1 row)

5.2 验证数据库列表

PGPASSWORD=<pg_admin_password> psql -h 127.0.0.1 -p 5432 -U dbuser_dba -d postgres -c "\l"

回显（节选）：

   Name    |  Owner   | Encoding | Collate |  Ctype  | Locale  |    Access privileges
-----------+----------+----------+---------+---------+---------+-------------------------
 meta      | postgres | UTF8     | C.UTF-8 | C.UTF-8 | C.UTF-8 | =Tc/postgres           +
           |          |          |         |         |         | postgres=CTc/postgres  +
           |          |          |         |         |         | dbrole_admin=C/postgres
 postgres  | postgres | UTF8     | C.UTF-8 | C.UTF-8 | C.UTF-8 |
 template0 | postgres | UTF8     | C.UTF-8 | C.UTF-8 | C.UTF-8 | =c/postgres            +
 template1 | postgres | UTF8     | C.UTF-8 | C.UTF-8 | C.UTF-8 | =Tc/postgres           +
(4 rows)

5.3 验证 Patroni 集群状态

pig patroni list

回显：

+ Cluster: pgsql (7700577068637988872) --+----+-------------+-----+------------+-----+-------------------+
| Member  | Host      | Role   | State   | TL | Receive LSN | Lag | Replay LSN | Lag | Tags              |
+---------+-----------+--------+---------+----+-------------+-----+------------+-----+-------------------+
| pgsql-1 | 127.0.0.1 | Leader | running |  1 |             |     |            |     | clonefrom: true   |
|         |           |        |         |    |             |     |            |     | conf: oltp.yml    |
|         |           |        |         |    |             |     |            |     | spec: 6C.24G.443G |
|         |           |        |         |    |             |     |            |     | version: '18'     |
+---------+-----------+--------+---------+----+-------------+-----+------------+-----+-------------------+

5.4 验证监控服务

systemctl is-active grafana-server pg_exporter haproxy vmetrics vlogs alertmanager

回显：

active
active
active
active
active
active

5.5 验证 Web 门户

浏览器访问 http://<宿主机IP>:8080，应返回 Pigsty Web 门户首页（HTTP 200）。Grafana 面板地址为 http://<宿主机IP>:8080/ui，用户名 admin，密码为 grafana_admin_password。

六、数据持久化说明

实例内 /data 目录通过 bind mount 挂载到宿主机 ./data，包含：

/pg/data：PostgreSQL 数据目录
/var/lib/backrest：pgBackRest 备份
/var/lib/victoria-metrics：监控指标数据
/var/log：各类服务日志

销毁实例后重建，数据不会丢失（只要不删除 ./data 目录）。

七、环境变量表

.env 文件中的变量：

变量	默认值	说明
`PIGSTY_VERSION`	`v4.5.0`	docker 镜像版本，与 Pigsty 版本一致
`PIGSTY_SSH_PORT`	`2222`	宿主机 SSH 端口映射到实例 22
`PIGSTY_HTTP_PORT`	`8080`	宿主机 HTTP 端口映射到实例 80
`PIGSTY_HTTPS_PORT`	`8443`	宿主机 HTTPS 端口映射到实例 443
`PIGSTY_PG_PORT`	`5432`	宿主机 PG 端口映射到实例 5432

八、配置参数说明

Pigsty 的全部配置集中在实例内 /root/pigsty/pigsty.yml（Ansible inventory）。常用配置项：

配置项	默认值	说明
`version`	`v4.5.0`	Pigsty 版本标识
`admin_ip`	`127.0.0.1`	管理节点 IP
`pg_version`	`18`	PostgreSQL 主版本号（14-18 可选）
`pg_conf`	`oltp.yml`	PG 调优模板（oltp/olap/tiny/crit）
`pg_extensions`	`[pg18-main, ...]`	预装扩展组列表
`pg_users`	见配置	声明式创建的数据库用户
`pg_databases`	见配置	声明式创建的数据库
`node_tune`	`oltp`	节点调优模式
`grafana_admin_password`	随机生成	Grafana 管理员密码
`pg_admin_password`	随机生成	PG 管理员密码

完整配置参数说明见《Pigsty v4.5.0 配置参数详解》。

九、配置文件挂载

如需持久化自定义配置，可在 docker-compose.yml 中额外挂载 pigsty.yml：

volumes:
  - ./data:/data
  - ./pigsty.yml:/root/pigsty/pigsty.yml

修改宿主机上的 pigsty.yml 后，在实例内重新执行 ./deploy.yml 即可收敛配置。

十、等价 docker run

不用 Compose 时，也可直接 docker run：

docker run -d --privileged \
  --name pigsty \
  --hostname pigsty \
  -v "$(pwd)/data:/data" \
  -p 2222:22 \
  -p 8080:80 \
  -p 8443:443 \
  -p 5432:5432 \
  pgsty/pigsty:v4.5.0

启动后进入实例执行配置与部署：

docker exec -it pigsty /bin/bash -l
cd /root/pigsty
./configure -c docker -g --ip 127.0.0.1
./deploy.yml

十一、常用运维命令

操作	命令
启动实例	`make up`
停止实例	`make stop`
重启实例	`make restart`
停止并删除实例	`make down`
进入实例	`make exec`
查看密码	`make pass`
查看实例日志	`make log`
重新拉取 docker 镜像	`make pull`
重新部署（配置变更后）	`make deploy`

十二、常见问题

12.1 部署失败：`usermod: user postgres is currently used by process`

现象：./deploy.yml 在 pgsql 角色执行 usermod 修改 postgres 用户属性时报错，提示 postgres 用户正被某个进程占用。

原因：上一次部署已启动 pg_exporter（以 postgres 用户运行），导致 usermod 无法修改该用户。

解决：停止 pg_exporter 与所有 postgres 用户进程，再重跑部署：

systemctl stop pg_exporter
pkill -u postgres
cd /root/pigsty && ./deploy.yml

12.2 部署失败：`postgresql-18-duckdb-fdw : Conflicts: postgresql-18-pg-duckdb`

现象：install postgres extensions 任务失败，APT 报 postgresql-18-duckdb-fdw 与 postgresql-18-pg-duckdb 包冲突。

原因：Pigsty v4.5.0 的 pg18-olap 扩展组同时包含这两个互相冲突的 DuckDB 扩展包，是已知打包问题。

解决：从 pigsty.yml 的 pg_extensions 列表中移除 pg18-olap 组，重新部署：

sed -i 's/,pg18-olap//g' /root/pigsty/pigsty.yml
cd /root/pigsty && ./deploy.yml

说明：移除后只是不装 OLAP 类扩展（Citus、DuckDB、Hydra 等），核心 PG 与监控栈不受影响。如需 Citus 等扩展，可部署后单独 pig install postgresql-18-citus 安装。

12.3 `make pass` 看不到密码

原因：pigsty.yml 尚未生成（未执行 make config），或密码字段被注释。

解决：先执行 make config 生成配置，再 make pass。

12.4 Grafana 面板无数据

排查：

确认 pg_exporter 服务正常：systemctl is-active pg_exporter
确认 VictoriaMetrics 正在采集：curl -s http://127.0.0.1:8428/api/v1/query?query=up | head
确认 Grafana 数据源已加载：登录 Grafana → Connections → Data sources，应有 pgsql-127.0.0.1

十三、卸载与清理

make down          # 停止并删除实例
rm -rf ./data      # 删除数据目录（可选，会丢失所有数据）

如需彻底清理 docker 镜像：

docker rmi pgsty/pigsty:v4.5.0

十四、参考链接

官方 Docker 部署文档：https://pigsty.io/docs/setup/docker/
官方仓库 docker 目录：https://github.com/pgsty/pigsty/tree/main/docker
在线演示：https://demo.pigsty.cc/

Pigsty v4.5.0 Docker Compose 部署指南

Pigsty v4.5.0 Docker Compose 部署指南

一、环境信息

二、docker 镜像选型说明

三、前置条件

四、部署步骤

4.1 获取编排文件

4.2 配置端口与版本

4.3 启动实例

4.4 生成配置（含随机密码）

4.5 执行部署

4.6 一键启动（up + config + deploy）

五、验证部署

5.1 验证 PostgreSQL

5.2 验证数据库列表

5.3 验证 Patroni 集群状态

5.4 验证监控服务

5.5 验证 Web 门户

六、数据持久化说明

七、环境变量表

八、配置参数说明

九、配置文件挂载

十、等价 docker run

十一、常用运维命令

十二、常见问题

12.1 部署失败：usermod: user postgres is currently used by process

12.2 部署失败：postgresql-18-duckdb-fdw : Conflicts: postgresql-18-pg-duckdb

12.3 make pass 看不到密码

12.4 Grafana 面板无数据

十三、卸载与清理

十四、参考链接

12.1 部署失败：`usermod: user postgres is currently used by process`

12.2 部署失败：`postgresql-18-duckdb-fdw : Conflicts: postgresql-18-pg-duckdb`

12.3 `make pass` 看不到密码