任务 on Pigsty v5.0

管理 PostgreSQL 数据库集群

Mon, 01 Jan 0001 00:00:00 +0000

速查手册

操作	快捷命令	说明
创建集群	`bin/pgsql-add <cls>`	创建新的 PostgreSQL 集群
扩容集群	`bin/pgsql-add <cls> <ip...>`	为现有集群添加从库副本
缩容集群	`bin/pgsql-rm <cls> <ip...>`	从集群中移除指定实例
销毁集群	`bin/pgsql-rm <cls>`	销毁整个 PostgreSQL 集群
刷新服务	`bin/pgsql-svc <cls> [ip...]`	重载集群的负载均衡配置
刷新HBA	`bin/pgsql-hba <cls> [ip...]`	重载集群的 HBA 访问规则
克隆集群	-	通过备份集群或 PITR 克隆

其他管理任务，请参考：高可用管理，管理用户，管理数据库。

管理 PostgreSQL 业务用户

Mon, 01 Jan 0001 00:00:00 +0000

快速上手

Pigsty 使用声明式管理方式，首先在 配置清单 中 定义用户，然后使用 bin/pgsql-user <cls> <username> 创建或修改用户。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_users: [{ name: dbuser_app, password: 'DBUser.App', pgbouncer: true }]  # <--- 在这里定义用户列表！

脚本

bin/pgsql-user <cls> <username>    # 在 <cls> 集群上创建/修改 <username> 用户

剧本

./pgsql-user.yml -l pg-meta -e username=dbuser_app    # 直接使用剧本在 <cls> 集群上创建/修改 <username> 用户

示例

bin/pgsql-user pg-meta dbuser_app    # 在 pg-meta 集群上创建/修改 dbuser_app 用户

关于用户定义参数的完整参考，请查阅 用户配置。角色与权限模型参见 访问控制，认证与凭据管理参见 身份认证。

管理 PostgreSQL 业务数据库

Mon, 01 Jan 0001 00:00:00 +0000

快速上手

Pigsty 使用声明式管理方式，首先在 配置清单 中 定义数据库，然后使用 bin/pgsql-db <cls> <dbname> 创建或修改数据库。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_databases: [{ name: some_db }]  # <--- 在这里定义数据库列表！

脚本

bin/pgsql-db <cls> <dbname>    # 在 <cls> 集群上创建/修改 <dbname> 数据库

剧本

./pgsql-db.yml -l pg-meta -e dbname=some_db    # 直接使用剧本在 <cls> 集群上创建/修改 <dbname> 数据库

示例

bin/pgsql-db pg-meta some_db    # 在 pg-meta 集群上创建/修改 some_db 数据库

关于数据库定义参数的完整参考，请查阅 数据库配置。数据库访问权限见 访问控制：数据库隔离。

管理 Patroni 高可用

Mon, 01 Jan 0001 00:00:00 +0000

概览

Pigsty 使用 Patroni 管理 PostgreSQL 集群，它可以用来修改集群配置，查看集群状态，执行主从切换，重启集群，重做从库等操作。

要使用 Patroni 进行管理，您需要有以下两种身份之一：

管理 PostgreSQL HBA 认证规则

Mon, 01 Jan 0001 00:00:00 +0000

快速上手

Pigsty 使用声明式管理方式，首先在 配置清单 中 定义 HBA 规则，然后使用 bin/pgsql-hba <cls> 刷新规则。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_hba_rules:                            # <--- 在这里定义 HBA 规则列表！
      - {user: dbuser_app, db: app, addr: intra, auth: pwd, title: 'app access'}
      - {user: dbuser_api, db: all, addr: world, auth: ssl, title: 'api ssl access'}

脚本

bin/pgsql-hba <cls>              # 刷新集群的 PostgreSQL 和 Pgbouncer HBA 规则
bin/pgsql-hba <cls> <ip>...      # 刷新集群中特定实例的 HBA 规则

剧本

./pgsql.yml -l <cls> -t pg_hba,pg_reload                 # 仅刷新 PostgreSQL HBA
./pgsql.yml -l <cls> -t pgbouncer_hba,pgbouncer_reload   # 仅刷新 Pgbouncer HBA
./pgsql.yml -l <cls> -t pg_hba,pg_reload,pgbouncer_hba,pgbouncer_reload  # 同时刷新两者

示例

bin/pgsql-hba pg-meta                      # 刷新 pg-meta 集群的 HBA 规则
bin/pgsql-hba pg-meta 10.10.10.10          # 仅刷新特定实例
bin/pgsql-hba pg-meta 10.10.10.11 10.10.10.12  # 刷新多个实例

关于规则语法，请查阅 HBA 配置；关于认证方法、默认边界与凭据管理，请参考 身份认证。

Pgbouncer 连接池管理

Mon, 01 Jan 0001 00:00:00 +0000

概览

Pigsty 使用 Pgbouncer 作为 PostgreSQL 的连接池中间件，默认监听 6432 端口，代理访问本机 5432 端口上的 PostgreSQL 实例。

这是一个 可选组件，如果您并没有海量连接，也不需要事务池化与查询监控指标，可以关闭连接池，直连数据库，或者保留但不使用。

管理 PostgreSQL 组件服务

Mon, 01 Jan 0001 00:00:00 +0000

概述

Pigsty 的 PGSQL 模块由多个组件构成，每个组件都以 systemd 服务的形式运行在节点上。（pgbackrest 除外）

了解这些组件及其管理方式，对于维护生产环境中的 PostgreSQL 集群非常重要。

管理 PostgreSQL 定时任务

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 使用 crontab 来管理定时任务，用于执行例行备份，冻结老化事务，重整膨胀表索引等维护工作。

速查手册

操作	快捷命令	说明
配置定时任务	`./pgsql.yml -t pg_crontab -l <cls>`	应用 pg_crontab 配置
查看定时任务	`crontab -l`	以 postgres 用户查看
物理备份	`pg-backup [full\|diff\|incr]`	使用 pgBackRest 执行备份
事务冻结	`pg-vacuum [database...]`	冻结老化事务，预防 XID 回卷
膨胀治理	`pg-repack [database...]`	在线重整膨胀的表与索引

其他管理任务，请参考：备份管理，监控系统，高可用管理。

升级 PostgreSQL 大小版本

Mon, 01 Jan 0001 00:00:00 +0000

快速上手

PostgreSQL 版本升级分为两种类型：小版本升级 和 大版本升级，两者的风险和复杂度差异很大。

类型	示例	停机时间	数据兼容性	风险等级
小版本升级	17.2 → 17.3	秒级（滚动重启）	完全兼容	低
大版本升级	17 → 18	分钟级	需要升级数据目录	中

小版本

# 滚动升级：先从库后主库
ansible <cls> -b -a 'yum upgrade -y postgresql17*'
pg restart --role replica --force <cls>
pg switchover <cls>
pg restart <cls> <old-primary> --force

大版本

# 推荐：逻辑复制迁移
bin/pgsql-add pg-new              # 创建新版本集群
# 配置逻辑复制同步数据...
# 切换流量到新集群

扩展

ansible <cls> -b -a 'yum upgrade -y postgis36_17*'
psql -c 'ALTER EXTENSION postgis UPDATE;'

关于在线迁移的详细流程，请参考 在线迁移 文档。

管理 PostgreSQL 扩展插件

Mon, 01 Jan 0001 00:00:00 +0000

快速上手

Pigsty 提供 575 扩展，使用扩展涉及四个步骤：下载、安装、配置、启用。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_extensions: [ postgis, timescaledb, pgvector ]           # <--- 安装扩展软件包
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain'    # <--- 配置预加载扩展
    pg_databases:
      - name: meta
        extensions: [ postgis, timescaledb, vector ]            # <--- 在数据库中启用

脚本

bin/pgsql-ext <cls>           # 在 <cls> 集群上安装配置中定义的扩展
bin/pgsql-ext <cls> [ext...]  # 在 <cls> 集群上安装命令行参数给出的扩展

剧本

./pgsql.yml -l pg-meta -t pg_ext    # 使用剧本安装扩展

示例

bin/pgsql-ext pg-meta                         # 在 pg-meta 集群上安装定义的扩展
bin/pgsql-ext pg-meta pg_duckdb pg_mooncake   # 安装指定扩展

关于扩展的完整参考，请查阅 扩展插件 章节。关于可用扩展列表，请参考 扩展目录。

日常管理

Mon, 01 Jan 0001 00:00:00 +0000

备份恢复

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 使用 pgBackRest 管理 PostgreSQL 备份 —— 这可能是 PostgreSQL 生态中最强大的开源备份工具，支持增量备份、并行处理、加密、Silo/S3 对象存储等众多特性。每个 PGSQL 集群默认都预配置了备份与 WAL 归档，开箱即用。

故障排查

Mon, 01 Jan 0001 00:00:00 +0000

本文档列举了 PostgreSQL 和 Pigsty 中可能出现的故障，以及定位、处理、分析问题的 SOP。

磁盘空间写满

磁盘空间写满是最常见的故障类型。

现象

当数据库所在磁盘空间耗尽时，PostgreSQL 将无法正常工作，可能出现以下现象：数据库日志反复报错"no space left on device"（磁盘空间不足），新数据无法写入，甚至 PostgreSQL 可能触发 PANIC 强制关闭。

误删处理

Mon, 01 Jan 0001 00:00:00 +0000

误删数据

如果是小批量 DELETE 误操作，可以考虑使用 pg_surgery 或者 pg_dirtyread 扩展进行原地手术恢复。

-- 立即关闭此表上的 Auto Vacuum 并中止 Auto Vacuum 本表的 worker 进程
ALTER TABLE public.some_table SET (autovacuum_enabled = off, toast.autovacuum_enabled = off);

CREATE EXTENSION pg_dirtyread;
SELECT * FROM pg_dirtyread('tablename') AS t(col1 type1, col2 type2, ...);

如果被删除的数据已经被 VACUUM 回收，那么使用通用的误删处理流程。

数据迁移

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 内置了一个剧本 pgsql-migration.yml，基于逻辑复制来实现在线数据库迁移。

通过预生成的自动化脚本，应用停机时间可以缩减到几秒内。但请注意，逻辑复制需要 PostgreSQL 10 以上的版本才能工作。

当然如果您有充足的停机时间预算，那么总是可以使用 pg_dump | psql 的方式进行停机迁移。

备份机制

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 的备份恢复功能，最终都会落实为 pgBackRest 命令的执行。所以要真正掌握这套系统，需要理解两件事：pgBackRest 本身的概念体系（stanza、仓库、备份链、保留、时间线），以及 Pigsty 各层封装如何映射到它（参数如何变成命令行选项）。本页依次讲清这两部分。

备份策略

Mon, 01 Jan 0001 00:00:00 +0000

备份策略要回答三个问题：何时备份（调度计划）、何处存放（备份仓库）、 保留多久（保留策略）。本页给出两套久经考验的预设策略及其量化推演 —— 背后的权衡逻辑请参阅概念层文档 策略权衡。

备份仓库

Mon, 01 Jan 0001 00:00:00 +0000

备份存储在哪里，由两个参数决定：pgbackrest_repo 定义所有候选仓库， pgbackrest_method 选择实际使用哪一个。仓库定义中的键值会 按固定规则 渲染为 pgbackrest 的 repo1-* 配置项，因此 pgBackRest 支持的任何仓库选项 都可以直接写入。 v4.5.0 每次只把 pgbackrest_method 选中的一个字典项渲染为 repo1；候选项同时存在并不等于多仓备份。

管理命令

Mon, 01 Jan 0001 00:00:00 +0000

备份管理命令应以数据库超级用户（pg_dbsu，默认 postgres）身份在数据库节点上执行。您可以按习惯选择三种等价的入口：

pig pb：pig 命令行工具 的封装 —— 自动检测 stanza、自动切换 DBSU 身份、带安全检查，推荐使用
pb：登录 shell 的别名函数，自动填充 --stanza 后转发给 pgbackrest
pgbackrest：原生命令，完整选项参阅 pgBackRest 命令参考

命令一览

pig 命令	别名	对应 pgbackrest 命令	说明
`pig pb info`	`i`	`info`	查看备份与归档状态
`pig pb list`	`ls`	—	列出仓库中的 stanza 与备份
`pig pb backup [full/diff/incr]`	`b`	`backup`	执行备份（自动检查主库角色）
`pig pb restore`	`r`	`restore`	恢复（显示计划并确认，详见恢复操作）
`pig pb expire`	`e`	`expire`	按保留策略清理过期备份（`--plan` 预览）
`pig pb create`	`c`	`stanza-create`	创建 stanza
`pig pb upgrade`	`u`	`stanza-upgrade`	升级 stanza（版本升级或克隆善后）
`pig pb delete`	`d`	`stanza-delete`	删除 stanza 及其全部备份
`pig pb check`	`ck`	`check`	校验备份配置与归档链路
`pig pb start`	`up`	`start`	恢复 pgbackrest 操作
`pig pb stop`	`dw`	`stop`	暂停 pgbackrest 操作
`pig pb log [list/show/tail]`	`l`	—	查看 pgbackrest 日志

启用备份

如果集群创建时 pgbackrest_enabled 为 true（默认），备份已自动启用。若创建时禁用了备份，或修改了仓库配置，可用 pg_backup 子任务补充配置：

恢复操作

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供三个层次的恢复入口，共用 同一套参数语义，按场景选用：

入口	适用场景	特点
`pgsql-pitr.yml` 剧本	生产集群恢复	编排整个集群：HA 暂停、多节点、etcd 清理、恢复控制信息输出
`pig pitr` 命令	单节点集群 / 节点本机操作	无需管理节点，在数据库节点上直接编排执行
`pig pb restore` 原语	非 Patroni 托管的实例	pgbackrest restore 的直接封装，最精细的控制

手把手的沙箱演练教程请参阅 手工恢复；用恢复克隆出新集群（不影响生产的推荐姿势）请参阅 克隆数据库集群。

克隆数据库集群

Mon, 01 Jan 0001 00:00:00 +0000

克隆是恢复能力最有价值的用法：不动生产集群，把它的历史状态恢复到另一套集群上。误删数据后从克隆库中导回、定期演练验证备份可用性、审计取证查看历史状态、把测试环境重置为生产某刻的快照 —— 这些场景的操作方式完全相同，本页给出完整流程。

手工 PITR 演练

Mon, 01 Jan 0001 00:00:00 +0000

本教程在 Pigsty v4.5.0 的四节点沙箱中演练 PostgreSQL 时间点恢复。核心路径使用 pgsql-pitr.yml 的 down → pitr → up 三阶段，让操作者在覆盖数据、提升时间线和重建 HA 之前分别停下来验证。

如果只恢复当前节点，可使用 pig pitr；如果需要直接控制 pgBackRest，可参考 pg-pitr 低层工具。

克隆与旁路恢复 PostgreSQL 实例

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty v4.5.0 提供两个本机 Shell 工具：

pg-fork：复制一个 PostgreSQL 数据目录，并为副本设置独立端口。
pg-pitr：调用 pgBackRest，将一个 已停止 的数据目录恢复到指定目标。

它们适合沙箱演练、旁路取证和临时测试，不是完整的 Patroni 集群恢复编排器。托管实例优先使用 pig pitr；多节点集群优先使用分阶段的 pgsql-pitr.yml。

为 PostgreSQL 集群启用 HugePage

Mon, 01 Jan 0001 00:00:00 +0000

使用 node_hugepage_count 和 node_hugepage_ratio 或 /pg/bin/pg-tune-hugepage

如果你计划启用大页（HugePage），请考虑使用 node_hugepage_count 和 node_hugepage_ratio，并配合 ./node.yml -t node_tune 进行应用。

大页对于数据库来说有利有弊，利是内存是专门管理的，不用担心被挪用，降低数据库 OOM 风险。缺点是某些场景下可能对性能由负面影响。

任务教程

Sat, 11 Jan 2025 00:00:00 +0000

3坏2应急处理

Sat, 11 Jan 2025 00:00:00 +0000

如果经典3节点高可用部署同时出现两台（多数主体）故障，系统通常无法自动完成故障切换，需要人工介入：

首先判断另外两台服务器的情况，如果短时间内可以拉起，优先选择拉起另外两台服务。否则进入 紧急止血流程

使用 VIP-Manager 为 PostgreSQL 集群配置二层 VIP

Mon, 01 Jan 0001 00:00:00 +0000

您可以在 PostgreSQL 集群上绑定一个可选的 L2 VIP —— 前提条件是：集群中的所有节点都在一个二层网络中。

这个 L2 VIP 强制使用 Master - Backup 模式，Master 始终指向在数据库集群主库实例所在的节点。

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供了一系列剧本，用于集群上下线扩缩容，用户/数据库管理，监控、备份恢复或迁移已有实例。

剧本	功能
`pgsql.yml`	初始化 PostgreSQL 集群或添加新的从库
`pgsql-rm.yml`	移除 PostgreSQL 集群，或移除某个实例
`pgsql-user.yml`	在现有的 PostgreSQL 集群中添加新的业务用户
`pgsql-db.yml`	在现有的 PostgreSQL 集群中添加新的业务数据库
`pgsql-monitor.yml`	将远程 PostgreSQL 实例纳入监控中
`pgsql-migration.yml`	为现有的 PostgreSQL 集群生成迁移手册和脚本
`pgsql-pitr.yml`	执行 PostgreSQL 时间点恢复 (PITR)

保护机制

使用 PGSQL 剧本时需要 特别注意，剧本 pgsql.yml 与 pgsql-rm.yml 使用不当会有误删数据库的风险！

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供了三个与 INFRA 模块相关的剧本：

deploy.yml：在所有节点上一次性部署 NODE、INFRA、ETCD、MINIO 与 PGSQL 核心模块
infra.yml：在 infra 节点上初始化 pigsty 基础设施
infra-rm.yml：从 infra 节点移除基础设施组件

`deploy.yml`

在所有节点上一次性部署 NODE、INFRA、ETCD、MINIO 与 PGSQL 核心模块，解决 INFRA/NODE 循环依赖问题。

管理预案

Mon, 01 Jan 0001 00:00:00 +0000

本章节介绍 Pigsty 部署的日常管理和运维操作。

Nginx 管理

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 在 INFRA 节点上安装 Nginx 作为所有 Web 服务的入口，默认监听在 80/443 标准端口上。

在 Pigsty 中，你可以通过修改配置清单，让 nginx 对外提供多种服务：

对外暴露 Grafana、VictoriaMetrics（VMUI）、Alertmanager、VictoriaLogs 等监控组件的 Web 界面
提供静态文件服务（如软件仓库、文档站，网站等）
代理自定义的应用服务（如内部应用、数据库管理界面，Docker 应用的界面等）
自动签发自签名的 HTTPS 证书，或者使用 certbot 申请免费的 Let’s Encrypt 证书
通过不同的子域名，使用单一端口对外暴露服务

基础配置

您可以通过 infra_portal 参数定制 Nginx 的行为：

软件仓库

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 的 REPO 角色会下载所需软件包，并在 /www/pigsty 创建可由 Nginx 提供服务的本地 YUM/APT 仓库。当前候选软件包版本为 SOW 0.3.0，源码统一使用 SOW 生成两类仓库元数据，不再分别调用 createrepo_c、modifyrepo_c 或 dpkg-scanpackages。

域名管理

Mon, 01 Jan 0001 00:00:00 +0000

使用域名代替 IP 地址访问 Pigsty 的各项 Web 服务。

快速开始

将以下静态解析记录添加到 /etc/hosts：

10.10.10.10 i.pigsty

将 IP 地址替换为实际 Pigsty 节点的 IP。

模块管理

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍 INFRA 模块的日常管理操作，包括安装、卸载、扩容、以及各组件的管理维护。

安装 Infra 模块

使用 infra.yml 剧本在 infra 分组上安装 INFRA 模块：

CA 与证书

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 默认在管理节点维护一套自签名证书颁发机构（CA），为 PostgreSQL、Patroni、etcd、Silo、Nginx 和其他内部服务签发证书。面向公网的 Nginx 入口可以按 infra_portal 配置改用 Certbot/Let’s Encrypt 证书。

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供两个与 NODE 模块相关的剧本：

node.yml：纳管节点，调整节点到期望状态
node-rm.yml：从 Pigsty 中移除纳管节点

另提供两个包装命令工具：bin/node-add 与 bin/node-rm，用于快速调用剧本。

`node.yml`

向 Pigsty 添加节点的 node.yml 包含以下子任务：

管理预案

Mon, 01 Jan 0001 00:00:00 +0000

下面是 Node 模块中常用的管理操作：

更多问题请参考 FAQ：NODE

添加节点

要将节点添加到 Pigsty，您需要对该节点具有无密码的 ssh/sudo 访问权限。

管理预案

Mon, 01 Jan 0001 00:00:00 +0000

以下是一些常见的 etcd 管理任务 SOP（预案）：

创建集群：如何初始化 etcd 集群？
销毁集群：如何销毁 etcd 集群？
环境变量：如何配置 etcd 客户端，以访问 etcd 服务器集群？
RBAC 认证：如何使用 etcd 的 RBAC 认证？
重载配置：如何更新客户端使用的 etcd 服务器成员列表？
添加成员：如何向现有 etcd 集群添加新成员？
移除成员：如何从 etcd 集群移除老成员？
便捷脚本：使用 bin/etcd-add 和 bin/etcd-rm 简化操作

更多问题请参考 FAQ：ETCD。

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

Etcd 模块提供了两个核心剧本：etcd.yml 用于安装与配置 Etcd 集群，etcd-rm.yml 用于移除 Etcd 集群或成员。

架构变化：Pigsty v3.6+

自 Pigsty v3.6 起，etcd.yml 剧本专注于集群安装和成员添加，所有移除操作已迁移至独立的 etcd-rm.yml 剧本和 etcd_remove 角色。

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

MINIO 模块提供两个内置剧本：

minio.yml：安装并配置 Silo
minio-rm.yml：移除 Silo、配置和可选数据

`minio.yml`

minio.yml 以 hosts: all 运行，但会在预任务阶段跳过没有定义 minio_cluster 的主机。进入角色后还会校验：

管理预案

Mon, 01 Jan 0001 00:00:00 +0000

创建集群

要创建一个集群，在配置清单中定义好后，执行 minio.yml 剧本即可。

minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio, minio_type: silo } }

例如，上面的配置定义了一个 SNSD 单机单盘 Silo 集群，使用以下命令即可创建所选对象存储集群：

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

REDIS 模块提供了两个剧本，用于部署/移除 Redis 集群/节点/实例：

redis.yml：部署 Redis 集群/节点/实例
redis-rm.yml：移除 Redis 集群/节点/实例

`redis.yml`

用于部署 Redis 的 redis.yml 剧本包含以下子任务：

管理预案

Mon, 01 Jan 0001 00:00:00 +0000

以下是一些常见的 Redis 管理任务 SOP（预案）：

REDIS 模块默认使用 redis_type: redis；选择 redis_type: valkey 时，服务端与客户端命令分别改为 valkey-server / valkey-cli。本文命令行示例使用默认的 redis-cli，Valkey 集群请替换为 valkey-cli；剧本内部会自动选择正确的 CLI。

Grafana 高可用部署：使用 PostgreSQL 后端数据库

Mon, 01 Jan 0001 00:00:00 +0000

您可以使用 PostgreSQL 作为 Grafana 后端使用的数据库。

这是了解 Pigsty 部署系统使用方式的好机会，完成此教程，您会了解：

如何创建新数据库集群
如何在已有数据库集群中创建新业务用户
如何在已有数据库集群中创建新业务数据库
如何访问Pigsty所创建的数据库
如何管理Grafana中的监控面板
如何管理 Grafana 中的 PostgreSQL数据源
如何一步到位完成 Grafana数据库升级

太长不看

vi pigsty.yml # 取消注释DB/User定义：dbuser_grafana  grafana 
bin/pgsql-user  pg-meta  dbuser_grafana
bin/pgsql-db    pg-meta  grafana

psql postgres://dbuser_grafana:DBUser.Grafana@meta:5436/grafana -c \
  'CREATE TABLE t(); DROP TABLE t;' # 检查连接串可用性
  
vi /etc/grafana/grafana.ini # 修改 [database] type url
systemctl restart grafana-server

创建数据库集群

我们可以在 pg-meta 上定义一个新的数据库 grafana，也可以在新的机器节点上创建一个专用于 Grafana 的数据库集群：pg-grafana

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

Docker 模块提供了一个默认的剧本 docker.yml，用于安装 Docker Daemon 与 Docker Compose。

`docker.yml`

剧本原始文件：docker.yml 中

执行本剧本，将会在带有 docker_enabled: true 标记的目标节点上安装 docker-ce 与 docker-compose-plugin，启用 dockerd 服务

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

JUICE 模块提供 juice.yml 剧本，用于部署与移除 JuiceFS 实例。

`juice.yml`

juice.yml 的任务结构如下：

juice_id        : 校验配置、检查端口冲突
juice_install   : 安装 juicefs 软件包
juice_cache     : 创建共享缓存目录
juice_clean     : 移除实例（state=absent）
juice_instance  : 创建实例（state=create）
  - juice_init  : 格式化文件系统（--no-update）
  - juice_dir   : 创建挂载点目录
  - juice_config: 渲染环境文件与 systemd 服务单元
  - juice_launch: 启动服务并等待指标端口就绪
juice_register  : 注册到 VictoriaMetrics 目标文件

运行粒度

粒度	限制参数	说明
节点	`-l <host>`	部署该节点所有实例
实例	`-l <host> -e fsname=<name>`	只处理指定实例

示例：

管理预案

Mon, 01 Jan 0001 00:00:00 +0000

常见运维场景如下：

更多问题参见 FAQ。

初始化实例

./juice.yml -l <host>
./juice.yml -l <host> -e fsname=<name>

初始化流程：

安装 juicefs 软件包
创建共享缓存目录（默认 /data/juice）
执行 juicefs format --no-update（仅首次创建有效）
创建挂载点目录并设置权限
渲染 systemd 单元与环境文件
启动服务并等待指标端口就绪
注册到 VictoriaMetrics（若存在 infra 节点）

重新配置

修改配置后，建议执行以下命令（更新配置并确保服务在线）：

日常管理

Mon, 01 Jan 0001 00:00:00 +0000

KAFKA 模块把 Kafka 安装在 /opt/kafka，使用 Systemd 管理服务，并把持久意图保存在 pigsty.yml。节点上的生成文件不应手工修改。

以下 Kafka CLI 示例都使用角色生成的 /etc/kafka/admin.properties。即使当前是 plaintext 也建议始终保留 --command-config：切换到 scram 管理通道时命令结构不变。将 <broker>:9092 替换为可达的 inventory_hostname 与端口。

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

KAFKA 模块提供两个剧本：kafka.yml 用于部署 Apache Kafka 4.1+ 动态 KRaft 集群并收敛其安全、资源与监控状态；kafka-rm.yml 用于下线集群或移除成员。

集群完整性约束

每个被选中的 kafka_cluster 必须包含其全部成员：部分选择会在写入前失败；选择一个集群、多个完整集群或不加 -l 裸跑全部集群都是允许的。先对完全相同的目标执行 --check；真实运行前仍需人工核验备份/重建意图、容量、业务窗口、回退方案与变更批准。