update pig docs

Vonng · Vonng · commit 183b4ad3c1ec · 2026-01-31T14:30:28.000+08:00
diff --git a/content/pig/cmd/pb.md b/content/pig/cmd/pb.md
@@ -7,6 +7,43 @@ weight: 670
 
 The `pig pgbackrest` command (alias `pig pb`) manages pgBackRest backup and point-in-time recovery (PITR). It wraps common `pgbackrest` operations for simplified backup management. All commands execute as database superuser (default `postgres`).
 
+```bash
+pig pb - Manage pgBackRest backup and point-in-time recovery.
+
+Information:
+  pig pb info                      show backup info
+  pig pb ls                        list backups
+  pig pb ls repo                   list configured repositories
+  pig pb ls stanza                 list all stanzas
+
+Backup & Restore:
+  pig pb backup                    create backup (auto: full/incr)
+  pig pb backup full               create full backup
+  pig pb restore                   restore from backup (PITR)
+  pig pb restore -t "..."          restore to specific time
+  pig pb expire                    cleanup expired backups
+
+Stanza Management:
+  pig pb create                    create stanza (first-time setup)
+  pig pb upgrade                   upgrade stanza (after PG upgrade)
+  pig pb delete                    delete stanza (DANGEROUS!)
+
+Control:
+  pig pb check                     verify backup integrity
+  pig pb start                     enable pgBackRest operations
+  pig pb stop                      disable pgBackRest operations
+  pig pb log                       view pgBackRest logs
+
+Examples:
+  pig pb info                      # show all backup info
+  pig pb backup                    # auto: full if none, else incr
+  pig pb backup full               # full backup
+  pig pb restore                   # restore to latest (default)
+  pig pb restore -t "2025-01-01 12:00:00+08"  # restore to time
+  pig pb create                    # initialize stanza
+  pig pb expire                    # cleanup per retention policy
+```
+
 ------
 
 ## Command Overview
diff --git a/content/pig/cmd/pb.zh.md b/content/pig/cmd/pb.zh.md
@@ -7,6 +7,43 @@ weight: 660
 
 `pig pgbackrest` 命令（别名 `pig pb`）用于管理 pgBackRest 备份和时间点恢复（PITR）。它封装了常用的 `pgbackrest` 操作，提供简化的备份管理体验。所有命令均以数据库超级用户身份执行。
 
+```bash
+pig pb - 管理 pgBackRest 备份和时间点恢复
+
+信息查询：
+  pig pb info                      显示备份信息
+  pig pb ls                        列出备份
+  pig pb ls repo                   列出已配置的仓库
+  pig pb ls stanza                 列出所有 stanza
+
+备份与恢复：
+  pig pb backup                    创建备份（自动：全量/增量）
+  pig pb backup full               创建全量备份
+  pig pb restore                   从备份恢复（PITR）
+  pig pb restore -t "..."          恢复到指定时间
+  pig pb expire                    清理过期备份
+
+Stanza 管理：
+  pig pb create                    创建 stanza（首次设置）
+  pig pb upgrade                   升级 stanza（PG 升级后）
+  pig pb delete                    删除 stanza（危险！）
+
+控制命令：
+  pig pb check                     验证备份完整性
+  pig pb start                     启用 pgBackRest 操作
+  pig pb stop                      禁用 pgBackRest 操作
+  pig pb log                       查看 pgBackRest 日志
+
+示例：
+  pig pb info                      # 显示所有备份信息
+  pig pb backup                    # 自动：无备份则全量，否则增量
+  pig pb backup full               # 全量备份
+  pig pb restore                   # 恢复到最新（默认）
+  pig pb restore -t "2025-01-01 12:00:00+08"  # 恢复到指定时间
+  pig pb create                    # 初始化 stanza
+  pig pb expire                    # 按保留策略清理
+```
+
 
 ## 命令概览
 
diff --git a/content/pig/cmd/pg.md b/content/pig/cmd/pg.md
@@ -7,6 +7,45 @@ weight: 650
 
 The `pig pg` command (alias `pig postgres`) manages local PostgreSQL server and databases. It wraps native tools like `pg_ctl`, `psql`, `vacuumdb`, providing a simplified server management experience.
 
+```bash
+pig pg - Manage local postgres server (pg_ctl, psql, vacuumdb)
+
+Control Commands (via pg_ctl or systemctl):
+  pig pg init                      initialize postgres data directory
+  pig pg start                     start postgres server
+  pig pg stop                      stop postgres server
+  pig pg restart                   restart postgres server
+  pig pg reload                    reload postgres server
+  pig pg status                    show postgres server status
+  pig pg promote                   promote replica to primary
+  pig pg role                      detect and print postgres role
+
+Connection & Query (via psql):
+  pig pg psql [db] [-c sql]        connect to postgres
+  pig pg ps                        show current connections
+  pig pg kill [-a] [-x] [-u user] [-d db] [-q sql] [-w secs]
+
+Maintenance (via vacuumdb & pg_repack):
+  pig pg vacuum  [db] [-a]         vacuum database
+  pig pg analyze [db] [-a]         analyze database
+  pig pg freeze  [db] [-a]         vacuum freeze tables
+  pig pg repack  [db] [-a]         online repack database
+
+Log Commands:
+  pig pg log list                  list log files
+  pig pg log tail <logfile>        tail -f log file
+  pig pg log cat  <logfile>        cat log file
+  pig pg log less <logfile>        less log file
+  pig pg log grep <logfile> <pat>  grep log file
+
+Service Management (via systemctl):
+  pig pg svc start                 start postgres service
+  pig pg svc stop                  stop postgres service
+  pig pg svc restart               restart postgres service
+  pig pg svc reload                reload postgres service
+  pig pg svc status                show postgres service status
+```
+
 ------
 
 ## Command Overview
diff --git a/content/pig/cmd/pg.zh.md b/content/pig/cmd/pg.zh.md
@@ -7,6 +7,45 @@ weight: 640
 
 `pig pg` 命令（别名 `pig postgres`）用于管理本地 PostgreSQL 服务器和数据库。它封装了 `pg_ctl`、`psql`、`vacuumdb` 等原生工具，提供简化的服务器管理体验。
 
+```bash
+pig pg - 管理本地 PostgreSQL 服务器（pg_ctl, psql, vacuumdb）
+
+控制命令（通过 pg_ctl 或 systemctl）：
+  pig pg init                      初始化 PostgreSQL 数据目录
+  pig pg start                     启动 PostgreSQL 服务器
+  pig pg stop                      停止 PostgreSQL 服务器
+  pig pg restart                   重启 PostgreSQL 服务器
+  pig pg reload                    重载 PostgreSQL 服务器配置
+  pig pg status                    显示 PostgreSQL 服务器状态
+  pig pg promote                   将备库提升为主库
+  pig pg role                      检测并打印 PostgreSQL 角色
+
+连接与查询（通过 psql）：
+  pig pg psql [db] [-c sql]        连接到 PostgreSQL
+  pig pg ps                        显示当前连接
+  pig pg kill [-a] [-x] [-u user] [-d db] [-q sql] [-w secs]
+
+维护命令（通过 vacuumdb 和 pg_repack）：
+  pig pg vacuum  [db] [-a]         清理数据库
+  pig pg analyze [db] [-a]         分析数据库
+  pig pg freeze  [db] [-a]         冻结清理表
+  pig pg repack  [db] [-a]         在线重整数据库
+
+日志命令：
+  pig pg log list                  列出日志文件
+  pig pg log tail <logfile>        tail -f 查看日志
+  pig pg log cat  <logfile>        cat 查看日志
+  pig pg log less <logfile>        less 查看日志
+  pig pg log grep <logfile> <pat>  grep 搜索日志
+
+服务管理（通过 systemctl）：
+  pig pg svc start                 启动 postgres 服务
+  pig pg svc stop                  停止 postgres 服务
+  pig pg svc restart               重启 postgres 服务
+  pig pg svc reload                重载 postgres 服务
+  pig pg svc status                显示 postgres 服务状态
+```
+
 ## 命令概览
 
 **服务控制**（pg_ctl 封装）：
diff --git a/content/pig/cmd/pitr.md b/content/pig/cmd/pitr.md
@@ -7,6 +7,39 @@ weight: 680
 
 The `pig pitr` command performs **Orchestrated Point-In-Time Recovery**. Unlike `pig pb restore`, this command automatically coordinates Patroni, PostgreSQL, and pgBackRest to complete the full PITR workflow.
 
+```bash
+pig pitr - Perform PITR with automatic Patroni/PostgreSQL lifecycle management.
+
+This command orchestrates a complete PITR workflow:
+  1. Stop Patroni service (if running)
+  2. Ensure PostgreSQL is stopped (with retry and fallback)
+  3. Execute pgbackrest restore
+  4. Start PostgreSQL
+  5. Provide post-restore guidance
+
+Recovery Targets (at least one required):
+  --default, -d      Recover to end of WAL stream (latest)
+  --immediate, -I    Recover to backup consistency point
+  --time, -t         Recover to specific timestamp
+  --name, -n         Recover to named restore point
+  --lsn, -l          Recover to specific LSN
+  --xid, -x          Recover to specific transaction ID
+
+Time Format:
+  - Full: "2025-01-01 12:00:00+08"
+  - Date only: "2025-01-01" (defaults to 00:00:00)
+  - Time only: "12:00:00" (defaults to today)
+
+Examples:
+  pig pitr -d                      # Recover to latest (most common)
+  pig pitr -t "2025-01-01 12:00"   # Recover to specific time
+  pig pitr -I                      # Recover to backup consistency point
+  pig pitr -d --dry-run            # Show execution plan without running
+  pig pitr -d -y                   # Skip confirmation (for automation)
+  pig pitr -d --skip-patroni       # Skip Patroni management
+  pig pitr -d --no-restart         # Don't auto-start PostgreSQL after restore
+```
+
 
 ## Overview
 
diff --git a/content/pig/cmd/pitr.zh.md b/content/pig/cmd/pitr.zh.md
@@ -7,6 +7,39 @@ weight: 670
 
 `pig pitr` 命令用于执行**编排式时间点恢复**（Orchestrated Point-In-Time Recovery）。与 `pig pb restore` 不同，此命令会自动协调 Patroni、PostgreSQL 和 pgBackRest，完成完整的 PITR 工作流。
 
+```bash
+pig pitr - 执行编排式 PITR（自动管理 Patroni/PostgreSQL 生命周期）
+
+此命令编排完整的 PITR 工作流：
+  1. 停止 Patroni 服务（如果正在运行）
+  2. 确保 PostgreSQL 已停止（带重试和降级策略）
+  3. 执行 pgbackrest restore
+  4. 启动 PostgreSQL
+  5. 提供恢复后操作指引
+
+恢复目标（至少需要指定一个）：
+  --default, -d      恢复到 WAL 流末尾（最新数据）
+  --immediate, -I    恢复到备份一致性点
+  --time, -t         恢复到指定时间戳
+  --name, -n         恢复到命名还原点
+  --lsn, -l          恢复到指定 LSN
+  --xid, -x          恢复到指定事务 ID
+
+时间格式：
+  - 完整格式: "2025-01-01 12:00:00+08"
+  - 仅日期: "2025-01-01"（默认为 00:00:00）
+  - 仅时间: "12:00:00"（默认为今天）
+
+示例：
+  pig pitr -d                      # 恢复到最新（最常用）
+  pig pitr -t "2025-01-01 12:00"   # 恢复到指定时间
+  pig pitr -I                      # 恢复到备份一致性点
+  pig pitr -d --dry-run            # 仅显示执行计划
+  pig pitr -d -y                   # 跳过确认（用于自动化）
+  pig pitr -d --skip-patroni       # 跳过 Patroni 管理
+  pig pitr -d --no-restart         # 恢复后不自动启动 PostgreSQL
+```
+
 
 ## 命令概览
 
diff --git a/content/pig/cmd/pt.md b/content/pig/cmd/pt.md
@@ -7,6 +7,33 @@ weight: 660
 
 The `pig patroni` command (alias `pig pt`) manages Patroni service and PostgreSQL HA clusters. It wraps common `patronictl` and `systemctl` operations for simplified cluster management.
 
+```bash
+pig pt - Manage Patroni cluster using patronictl commands.
+
+Cluster Operations (via patronictl):
+  pig pt list                      list cluster members
+  pig pt restart [member]          restart PostgreSQL (rolling restart)
+  pig pt reload                    reload PostgreSQL config
+  pig pt reinit <member>           reinitialize a member
+  pig pt pause                     pause automatic failover
+  pig pt resume                    resume automatic failover
+  pig pt switchover                perform planned switchover
+  pig pt failover                  perform manual failover
+  pig pt config <action>           manage cluster config
+
+Service Management (via systemctl):
+  pig pt status                    show comprehensive patroni status
+  pig pt start                     start patroni service (shortcut)
+  pig pt stop                      stop patroni service (shortcut)
+  pig pt svc start                 start patroni service
+  pig pt svc stop                  stop patroni service
+  pig pt svc restart               restart patroni service
+  pig pt svc status                show patroni service status
+
+Logs:
+  pig pt log [-f] [-n 100]         view patroni logs
+```
+
 ------
 
 ## Command Overview
diff --git a/content/pig/cmd/pt.zh.md b/content/pig/cmd/pt.zh.md
@@ -7,6 +7,33 @@ weight: 650
 
 `pig patroni` 命令（别名 `pig pt`）用于管理 Patroni 服务和 PostgreSQL HA 集群。它封装了常用的 `patronictl` 和 `systemctl` 操作，提供简化的集群管理体验。
 
+```bash
+pig pt - 使用 patronictl 命令管理 Patroni 集群
+
+集群操作（通过 patronictl）：
+  pig pt list                      列出集群成员
+  pig pt restart [member]          重启 PostgreSQL（滚动重启）
+  pig pt reload                    重载 PostgreSQL 配置
+  pig pt reinit <member>           重新初始化成员
+  pig pt pause                     暂停自动故障切换
+  pig pt resume                    恢复自动故障切换
+  pig pt switchover                执行计划内主从切换
+  pig pt failover                  执行手动故障切换
+  pig pt config <action>           管理集群配置
+
+服务管理（通过 systemctl）：
+  pig pt status                    显示 Patroni 综合状态
+  pig pt start                     启动 Patroni 服务（快捷方式）
+  pig pt stop                      停止 Patroni 服务（快捷方式）
+  pig pt svc start                 启动 Patroni 服务
+  pig pt svc stop                  停止 Patroni 服务
+  pig pt svc restart               重启 Patroni 服务
+  pig pt svc status                显示 Patroni 服务状态
+
+日志：
+  pig pt log [-f] [-n 100]         查看 Patroni 日志
+```
+
 
 ## 命令概览
 
diff --git a/content/pig/cmd/repo.md b/content/pig/cmd/repo.md
@@ -7,6 +7,37 @@ weight: 610
 
 The `pig repo` command is a comprehensive tool for managing package repositories on Linux systems. It provides functionality to add, remove, create, and manage software repositories for both RPM-based (RHEL/CentOS/Rocky/Alma) and Debian-based (Debian/Ubuntu) distributions. This command is essential for setting up the required repositories to install PostgreSQL and its extensions.
 
+```bash
+pig repo - Manage Linux software repo (apt/dnf)
+
+Usage: pig repo <command>
+
+Commands:
+  add       Add new repository
+  set       Wipe and overwrite and update repository
+  rm        Remove repository
+  list      Print available repo and module list
+  info      Get repo detailed information
+  status    Show current repo status
+  update    Update repo cache
+  create    Create local YUM/APT repository
+  cache     Create offline package from local repo
+  boot      Bootstrap repo from offline package
+  reload    Refresh repo catalog
+
+Flags:
+  -h, --help   help for repo
+
+Global Flags:
+      --debug              enable debug mode
+  -H, --home string        pigsty home path
+  -i, --inventory string   config inventory path
+      --log-level string   log level: debug, info, warn, error, fatal, panic (default "info")
+      --log-path string    log file path, terminal by default
+
+Use "pig repo [command] --help" for more information about a command.
+```
+
 ------
 
 ## Subcommands
diff --git a/content/pig/cmd/repo.zh.md b/content/pig/cmd/repo.zh.md
