Pigsty v4.5.0 常用 CLI 命令与工具详解

目标：把 Pigsty v4.5.0 自带的 pig 命令行工具的核心子命令讲清楚——每个命令的作用、参数、实测回显。本篇基于 Debian 13 + PostgreSQL 18.6 + pig 1.8.0 实测，所有输出均为真实回显（2026-10-25）。

一、环境信息

pig 版本：1.8.0
构建信息：HEAD 67dac09 2026-08-14T15:30:52Z
Pigsty 版本：v4.5.0
PostgreSQL 版本：18.6
操作系统：Debian 13 (trixie)，x86_64
可执行路径：/usr/bin/pig
配置文件：/root/.pig/config.yml
Inventory 路径：/root/pigsty/pigsty.yml

二、工具概览

pig（PostgreSQL Extension Manager）是 Pigsty 自带的命令行工具，定位是「PostgreSQL 的 apt/yum + 运维工具箱」。它整合了三类能力：

扩展与包管理：pig install、pig ext、pig repo——像系统包管理器一样安装 PG 扩展与内核。
Pigsty 运维管理：pig sty、pig inventory、pig patroni、pig postgres、pig pgbackrest、pig pitr、pig pg_exporter——管理部署、清单、集群、备份等。
状态查询：pig status、pig context、pig version——查看环境状态。

查看版本：

pig version

回显：

pig version 1.8.0 linux/amd64
build: HEAD 67dac09 2026-08-14T15:30:52Z

查看顶层帮助：

pig --help

回显（节选）：

pig - the Linux Package Manager for PostgreSQL

PostgreSQL Extension Manager
  build       Build Postgres Extension
  ext         Manage PostgreSQL Extensions (pgext)
  repo        Manage Linux software repositories

Pigsty Management Commands
  context     Show environment context snapshot
  do          run admin tasks
  inventory   Inspect, edit, validate, check, and exchange Pigsty Inventory
  patroni     Run patronictl with Pigsty service and config helpers
  pg_exporter Manage pg_exporter and metrics
  pgbackrest  Manage pgBackRest backup & restore
  pitr        Point-in-time recovery using pgBackRest
  postgres    Manage local PostgreSQL server & databases
  sty         Manage Pigsty installation and controller services

Additional Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  install     Install packages using native package manager
  status      Show Environment Status
  update      Upgrade pig itself
  version     Show pig version info

三、前置条件

Pigsty 已部署完成，PostgreSQL 运行中。
以 root 或具备 sudo 权限的用户执行（部分子命令如 repo add、install 需 root）。
pig 已在 PATH 中（Pigsty 部署后自动安装到 /usr/bin/pig）。

四、状态查询命令

4.1 pig status

显示当前环境的完整状态：配置、操作系统、PostgreSQL、Pigsty、网络。

pig status

回显：

# [Configuration] ================================
Pig Version      : 1.8.0
Pig Config       : /root/.pig/config.yml
Log Level        : info
Log Path         : stderr

# [OS Environment] ===============================
OS Distro Code   : d13
OS OSArch        : amd64
OS Package Type  : deb
OS Vendor ID     : debian
OS Version       : 13
OS Version Full  : 13
OS Version Code  : trixie

# [PG Environment] ===============================
Installed:
- PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2)  506 Extensions

Active:
PG Version      :  PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2)
Config Path     :  /usr/bin/pg_config
Binary Path     :  /usr/lib/postgresql/18/bin
Library Path    :  /usr/lib/postgresql/18/lib
Extension Path  :  /usr/share/postgresql/18/extension

# [Pigsty Environment] ===========================
Inventory Path   : /root/pigsty/pigsty.yml
Pigsty Home      : /root/pigsty

# [Network Conditions] ===========================
pigsty.cc  ping ok: 472 ms
pigsty.io  unreachable
google.com request error
Internet Access   :  true
Pigsty Repo       :  pigsty.cc
Inferred Region   :  china
Latest Pigsty Ver :  v4.5.0

用途：一键确认当前环境的版本、PG 安装情况、网络与仓库可用性，是排障的起点。

4.2 pig context

显示精简的环境上下文快照，适合快速巡检。

pig context

回显：

=== PIG CONTEXT ===
Host: pigsty (d13/amd64)
  OS: linux  Kernel: 7.0.0-38-generic

PostgreSQL: ● Available

Patroni: ● Available

pgBackRest: ● Available

Extensions: ● Available

用途：快速确认 PostgreSQL、Patroni、pgBackRest、扩展是否可用，比 pig status 更简洁。

五、扩展与包管理命令

5.1 pig install

安装 PostgreSQL 扩展或软件包，自动做包名翻译。

pig install --help

回显（节选）：

pig install - Install packages using native package manager with alias translation

Examples:
  pig install pg_duckdb                # install extension with translation
  pig install postgresql17             # install directly without translation
  pig install pg17                     # translate pg17 alias to postgresql packages
  pig ins nginx htop                   # install multiple packages
  pig i pg_vector -y                   # auto confirm installation
  pig install somepackage -n           # disable translation, use package name as-is
  pig install pg17 --plan              # preview install plan without executing

常用示例：

命令	作用
`pig install pgvector`	安装 pgvector 向量扩展（自动翻译包名）
`pig install pg17`	安装 PostgreSQL 17 内核包
`pig install pgvector -y`	自动确认安装
`pig install pg17 --plan`	预览安装计划，不实际执行

💡 pig install 会把 PG 扩展别名（如 pgvector）翻译成系统包名（如 postgresql-18-pgvector），无需记忆发行版包命名规则。

5.2 pig ext

管理 PostgreSQL 扩展：列出、查询、安装、扫描。

pig ext --help

回显（节选）：

pig ext - Manage PostgreSQL Extensions

  pig ext list    [query]      # list & search extension
  pig ext info    [ext...]     # get information of a specific extension
  pig ext status  [-v]         # show installed extension and pg status
  pig ext add     [ext...]     # install certain extension

pig ext status

查看已安装扩展统计。

pig ext status

回显（节选）：

✓ PostgreSQL 18: 506 extensions installed (437 shown)
PostgreSQL 18: PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2)
  Binary: /usr/lib/postgresql/18/bin
  Extension: /usr/share/postgresql/18/extension

Extension Stat: 437 Installed (PGDG 99, PIGSTY 338) + 69 CONTRIB = 506 Total

pig ext list <query>

按关键词搜索扩展目录。

pig ext list vector

回显：

✓ Found 1 extensions matching 'vector'
Name    Status     Version  Cate  Flags   License     Repo  PGVer  Package                 Description
─────────────────────────────────────────────────────────────────────────────────────────────────────
vector  installed  0.8.6    RAG   -ds--r  PostgreSQL  PGDG  14-18  postgresql-18-pgvector  vector data type and ivfflat and hnsw access methods

5.3 pig repo

管理 APT/RPM 软件仓库。

pig repo --help

回显（节选）：

pig repo - Manage Linux APT/RPM Repositories

  pig repo list                    # available repo list
  pig repo info   [repo|module...] # show repo info
  pig repo status                  # show current repo status
  pig repo add    [repo|module...] # add repo and modules
  pig repo rm     [repo|module...] # remove repo & modules
  pig repo update                  # update repo pkg cache
  pig repo create                  # create repo on current system
  pig repo boot                    # boot repo from offline package
  pig repo cache                   # cache repo as offline package

pig repo status

查看当前已启用的仓库。

pig repo status

回显：

✓ Repository status: deb
Repo Dir: /etc/apt/sources.list.d
Repo Files:
  /etc/apt/sources.list.d/infra.list
  /etc/apt/sources.list.d/node.list
  /etc/apt/sources.list.d/pgsql.list
Active Repos:
  https://mirrors.cloud.tencent.com/docker-ce/linux/debian
  https://repo.pigsty.cc/apt/infra
  https://mirrors.cloud.tencent.com/postgresql/repos/apt
  https://repo.pigsty.cc/apt/pgsql/trixie
  https://mirrors.cloud.tencent.com/debian-security
  https://mirrors.cloud.tencent.com/debian

六、Pigsty 运维管理命令

6.1 pig inventory

查看与校验 Pigsty 清单（pigsty.yml）。

pig inventory list

回显（节选）：

✓ inventory listed
PATH                                           OBJECT    VALUE KIND
───────────────────────────────────────────────────────────────────
/                                              document  mapping
/all                                           group     mapping
/all/children                                  groups    mapping
/all/children/infra                            group     mapping
/all/children/infra/hosts                      hosts     mapping
/all/children/infra/hosts/127.0.0.1            host      mapping
/all/children/infra/hosts/127.0.0.1/infra_seq  value     scalar
/all/children/etcd                             group     mapping
/all/children/etcd/hosts                       hosts     mapping
/all/children/etcd/hosts/127.0.0.1             host      mapping
/all/children/pgsql                            group     mapping
/all/children/pgsql/hosts                      hosts     mapping
/all/children/pgsql/hosts/127.0.0.1            host      mapping
/all/vars                                      vars      mapping
/all/vars/version                              value     scalar

常用子命令：

命令	作用
`pig inventory list`	列出清单拓扑结构
`pig inventory show`	显示完整清单 YAML（含密码，谨慎）
`pig inventory validate`	校验清单语法与完整性
`pig inventory check`	检查控制器与目标节点就绪状态
`pig inventory edit`	交互式编辑清单片段

6.2 pig patroni（别名 pig pt）

封装 patronictl，管理 Patroni 集群。

pig patroni --help

回显（节选）：

pig pt transparently launches the installed patronictl binary.

  pig pt set KEY=VALUE...       update PostgreSQL or scalar Patroni settings
  pig pt start|stop             manage the local patroni service
  pig pt service <action>       start, stop, restart, reload, or show service
  pig pt status                 show local and cluster status
  pig pt log ...                view local Patroni logs

pig patroni list

查看集群成员状态。

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'     |
+---------+-----------+--------+---------+----+-------------+-----+------------+-----+-------------------+

pig patroni set <KEY=VALUE>

修改 PostgreSQL 或 Patroni 参数（详见《Pigsty v4.5.0 配置参数详解》第三章）。

echo y | pig patroni set work_mem=32MB

回显：

-    work_mem: 64MB
+    work_mem: 32MB
Apply these changes? [y/N]: Configuration changed
If the change was applied, verify with:
$ pig pt list

pig patroni reload <cluster>

重载 PostgreSQL 配置（对 sighup/superuser context 参数生效）。

pig patroni reload pgsql

pig patroni restart <cluster>

重启 PostgreSQL（对 postmaster context 参数生效）。

pig patroni restart pgsql

6.3 pig postgres（别名 pig pg）

管理本地 PostgreSQL 实例。

pig postgres --help

回显（节选）：

Local PostgreSQL primitives (pg_ctl / psql / local files).

Server Control (via pg_ctl):
  pig pg init     [-v ver] [-D datadir]     initialize data directory
  pig pg start    [-D datadir]              start PostgreSQL server
  pig pg stop     [-D datadir] [-m fast]    stop PostgreSQL server
  pig pg restart  [-D datadir] [-m fast]    restart PostgreSQL server
  pig pg reload   [-D datadir]              reload configuration
  pig pg status   [-D datadir]              show server status
  pig pg promote  [-D datadir]              promote standby to primary
  pig pg role     [-D datadir] [-V]         detect instance role (primary/replica)

Connection & Query:
  pig pg psql     [db] [-c cmd]             connect to database via psql
  pig pg ps       [-a] [-u user]            show current connections
  pig pg kill     [-x] [-u user]            terminate connections (dry-run by default)

pig postgres status

查看 PostgreSQL 服务状态。

pig postgres status

回显（节选）：

══════════════════════════════════════════════════════════════════
 PostgreSQL Status Summary
══════════════════════════════════════════════════════════════════

[pg_ctl status]
$ /usr/lib/postgresql/18/bin/pg_ctl status -D /pg/data
pg_ctl: server is running (PID: 59616)
/usr/lib/postgresql/18/bin/postgres "-D" "/pg/data" ...

pig postgres role

检测当前实例角色（主库/从库）。

pig postgres role

回显：

primary

pig postgres psql

连接数据库执行查询。

pig postgres psql 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)

pig postgres ps

查看当前连接。

pig postgres ps

6.4 pig sty

管理 Pigsty 安装与部署。

pig sty --help

回显（节选）：

Manage the local Pigsty installation, releases, configuration, deployment.

  pig sty init                         # install Pigsty (~/pigsty by default)
  pig sty boot                         # install Ansible and prepare offline pkg
  pig sty conf                         # generate pigsty.yml through Inventory APIs
  pig sty deploy                       # immediately run the deployment playbook
  pig sty list [version]               # list available Pigsty releases
  pig sty get [version]                # download a Pigsty source tarball
  pig sty grafana [info|list|boot|init|load|dump|clean|lang|style]

常用命令：

命令	作用
`pig sty init`	安装 Pigsty 到 `~/pigsty`
`pig sty boot`	安装 Ansible 与依赖，准备离线包
`pig sty conf`	生成 `pigsty.yml` 配置
`pig sty deploy`	执行 `deploy.yml` 部署
`pig sty list`	列出可用 Pigsty 版本

6.5 pig pgbackrest / pig pitr

管理 pgBackRest 备份与时间点恢复。

pig pgbackrest --help
pig pitr --help

常用命令：

命令	作用
`pig pgbackrest info`	查看备份信息
`pig pgbackrest backup --stanza=pgsql --type=full`	执行全量备份
`pig pitr --time "2026-10-25 12:00:00"`	恢复到指定时间点

6.6 pig pg_exporter

管理 pg_exporter 指标采集。

pig pg_exporter --help

常用命令：

命令	作用
`pig pg_exporter status`	查看 pg_exporter 状态
`pig pg_exporter restart`	重启 pg_exporter
`pig pg_exporter log`	查看 pg_exporter 日志

七、注意事项

pig patroni set 需确认：默认会弹出 Apply these changes? [y/N]:，非交互场景用 echo y | pig patroni set ...。
pig install 需 root：安装系统包需要 root 权限。
参数 context 决定生效方式：pig patroni set 修改后，user context 即时生效，sighup/superuser 需重载，postmaster 需重启。详见《Pigsty v4.5.0 配置参数详解》第三章。
集群名参数：pig patroni reload/restart 需带集群名（默认 pgsql），可通过 pig patroni list 查看。
pig inventory show 含密码：会输出完整清单包括明文密码，谨慎在共享环境执行。

八、常见问题

8.1 `pig patroni set` 报 `unknown flag`

原因：用了 --version 等 pig 全局参数但子命令不支持。

解决：查看子命令帮助 pig patroni --help，只用该子命令支持的参数。

8.2 `pig install pgvector` 找不到包

原因：Pigsty 仓库未添加或 apt 缓存未更新。

解决：先 pig repo add -ru 添加所有仓库并更新缓存，再重试。

8.3 `pig status` 显示 `No PostgreSQL installation found`

原因：PostgreSQL 未安装或 PATH 中找不到 pg_config。

解决：确认 Pigsty 已部署（./deploy.yml 成功），或手动 pig install pg18 安装内核。

8.4 `pig patroni list` 报 `connection refused`

原因：Patroni 服务未运行或 Etcd 不可达。

解决：systemctl is-active patroni 确认服务状态；检查 Etcd：systemctl is-active etcd。

九、参考链接

官方 pig 文档：https://pigsty.io/docs/pig/
扩展目录：https://pigsty.io/ext/
Patroni 文档：https://patroni.readthedocs.io/

Pigsty v4.5.0 常用 CLI 命令与工具详解

Pigsty v4.5.0 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、状态查询命令

4.1 pig status

4.2 pig context

五、扩展与包管理命令

5.1 pig install

5.2 pig ext

pig ext status

pig ext list <query>

5.3 pig repo

pig repo status

六、Pigsty 运维管理命令

6.1 pig inventory

6.2 pig patroni（别名 pig pt）

pig patroni list

pig patroni set <KEY=VALUE>

pig patroni reload <cluster>

pig patroni restart <cluster>

6.3 pig postgres（别名 pig pg）

pig postgres status

pig postgres role

pig postgres psql

pig postgres ps

6.4 pig sty

6.5 pig pgbackrest / pig pitr

6.6 pig pg_exporter

七、注意事项

八、常见问题

8.1 pig patroni set 报 unknown flag

8.2 pig install pgvector 找不到包

8.3 pig status 显示 No PostgreSQL installation found

8.4 pig patroni list 报 connection refused

九、参考链接

8.1 `pig patroni set` 报 `unknown flag`

8.2 `pig install pgvector` 找不到包

8.3 `pig status` 显示 `No PostgreSQL installation found`

8.4 `pig patroni list` 报 `connection refused`