教程 on Pigsty v5.0

上手

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

Pigsty 采用可伸缩的架构设计，既可用于 超大规模生产环境，也可用于 单机开发演示环境，本文关注后者。

如果您打算学习了解 Pigsty，可以从 快速上手 单机部署开始。一台 1C/2G 的 Linux 虚拟机即可运行 Pigsty。

您可以利用一台 Linux MiniPC，云厂商提供的免费/优惠虚拟机，Windows 的 WSL，或者在自己的笔记本上创建虚拟机用于 Pigsty 部署。 Pigsty 提供了开箱即用的 Vagrant 模板与 Terraform 模版，可以帮助您一键在本地或云端置备 Linux 虚拟机。

部署

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

与 快速上手 不同，企业生产环境 Pigsty 部署需要更多 架构规划 与 准备工作。

本章将帮助您理解 Pigsty 的完整部署流程，并提供生产环境部署的最佳实践建议。

我们建议您在真实的生产环境部署之前，使用 Pigsty 提供的 沙箱环境 进行测试与演练，确保对部署流程有充分的了解。您可以使用 Vagrant 在本地快速创建一个四节点的 Pigsty 沙箱环境用于测试，或者利用 Terraform 在云端置备一个更大规模的仿真环境。

配置清单

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

每一套 Pigsty 部署都对应着一份 配置清单 （Inventory），描述了基础设施与数据库集群的关键属性。

配置文件

Pigsty 默认使用 Ansible YAML 配置格式，使用一个单一 YAML 配置文件 pigsty.yml 作为配置清单。

快速上手 Pigsty 单机部署

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

本文是 Pigsty 单节点安装指南单节点，生产环境的多节点高可用部署请参考部署文档。

Pigsty 单机安装分为三步走：安装，配置与部署。

摘要

准备一台具有 SSH 权限 的节点，安装 兼容的 Linux 系统，使用具有免密 ssh 和 sudo 权限的 管理用户 执行：

Docker 部署

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

Pigsty 旨在运行于原生 Linux 系统上，但也可以在带有 systemd 的 Linux 容器环境中运行。如果您没有原生 Linux 环境（例如 macOS 或 Windows 用户），可以使用 Docker 快速拉起一个本地单机 Pigsty 环境进行测试与体验。

从浏览器访问图形用户界面

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

Pigsty 单机安装 完成后，您在当前节点上将安装有 INFRA 模块，它带有一套开箱即用的 Nginx Web 服务器。

其中的默认服务器配置提供了一个 WebUI 图形界面，用于展示监控仪表盘，并统一代理访问其他组件的 Web 界面。

快速上手 PostgreSQL

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

PostgreSQL（简称 PG）是世界上最先进、最流行的开源关系型数据库，你可以用它来存储和检索多模态数据。

本指南面向有基础 Linux 基本命令行操作经验、但对 PostgreSQL 不太熟悉的开发者，带你快速上手 Pigsty 中的 PG。

通过配置清单定制 Pigsty 部署

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

除了使用 配置向导 自动生成配置，您也可以从零开始手工编写 Pigsty 配置文件。本教程将指导您从头开始，逐步构建一个复杂的 配置清单。

如果您事先在 配置清单 中定义好 NODE、INFRA、ETCD、MINIO 与 PGSQL，那么 deploy.yml 可以一次性完成这条核心链路的部署，但它隐藏了所有细节。Docker、Redis、Kafka、原生 MySQL、JUICE 与 VIBE 等可选模块需要另行执行各自的剧本。

使用 Ansible 剧本完成部署

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

Pigsty 使用 Ansible 对集群进行管理，这是在 SRE 群体中非常流行的大规模/批量化/自动化运维工具。

Ansible 可以使用 声明式 的方式对服务器进行配置管理，所有模块的部署都是通过一系列幂等的 Ansible 剧本 实现的。

离线安装

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

Pigsty 默认从互联网上游安装所需软件包，但有些环境与互联网隔离。为了解决这个问题，Pigsty 支持使用 离线软件包 进行离线安装。您可以将其视作 Linux- 原生版本的 Docker 镜像。

概览

离线软件包 打包了所有需要的 RPM/DEB 软件包及其依赖；它是常规安装后的本地 APT / YUM 仓库的快照。

精简安装

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

如果您只想要高可用 PostgreSQL 数据库集群本身，而不需要监控、基础设施等功能，请考虑 精简安装。

精简安装没有 INFRA 模块，没有监控，没有 本地仓库，只有 ETCD 和 PGSQL 以及部分 NODE 功能。

精简安装适合以下场景

只需要 PostgreSQL 数据库本身，不需要可观测性基础设施。
资源极度受限的环境，不愿意承担基础设施开销（单机约 0.2 vCPU / 500MB 开销）
已有外部监控系统，希望统一使用自己的监控管理体系。
不需要 Grafana 可视化看板组件。

精简安装的局限性

没有 基础设施模块，无法使用 WebUI 和本地软件仓库功能。
离线安装 仅限单机模式使用，多节点精简安装只能在线安装。

概览

使用精简安装，您需要：

安全建议

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

默认配置适用于本地演示和受信内网中的开发测试。只要部署可能被其他主机访问，就应至少完成凭据、网络和关键文件三项检查。

生产环境还应参考 安全模型、合规实践 和 安全考量。

密码

Pigsty 的默认凭据公开记录在源码和文档中，不能直接用于生产。

生产部署

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

本文是 Pigsty 生产环境多节点部署指南，部署单机版本 Demo/Dev 环境可以参考 快速上手 文档。

摘要

准备几台具有 SSH 权限 的节点，安装 兼容的 Linux 系统，使用具有免密 ssh 和 sudo 权限的 管理用户 执行：

资源准备

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

Pigsty 运行在节点（物理机或虚拟机）之上，本文档介绍硬件相关的规划与准备。

节点

Pigsty 目前运行在 Linux 内核和 x86_64 / aarch64 架构的节点上。 "节点" 指的是 SSH 可访问 且提供裸 Linux 操作系统环境的资源。它可以是物理机、虚拟机或配备 systemd、sudo 和 sshd 的类似操作系统的容器。

架构规划

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

Pigsty 采用 模块化架构，您可以像搭积木一样组合出自己想要的部署方案，并用简单的 声明式配置 表达您的意图。

常见方案

这里有一些常见的组合模式供您参考，您可以根据自己的需求进行进一步的定制与调整：

方案	INFRA	ETCD	PGSQL	MINIO	说明
单机部署（`meta`）	1	1	1		单机部署默认配置，经典方案
单机部署（`slim`）		1	1		不要监控设施，只要数据库
基础设施（`infra`）	1				只要监控基础设施
单机部署（`rich`）	1	1	1	1	单机 + 对象存储 + 本地仓库/扩展

多节点方案	INFRA	ETCD	PGSQL	MINIO	说明
双节点（`dual`）	1	1	2		2节点半 HA，可容忍坏特定一个
三节点（`trio`）	3	3	3		标准3节点 HA，可容忍坏一个
四节点（`full`）	1	1	1+3		演示专用，1 INFRA/ETCD
生产部署（`simu`）	2	3	n	n	2个 INFRA，3个 ETCD
大规模生产（自定义）	3	5	n	n	3个 INFRA，5个 ETCD

使用什么样的架构规划方案，取决于您对数据库可靠性的要求，以及手头可用的资源。通常来说，严肃的生产环境部署至少需要 3 个节点以实现 高可用配置。如果您只有 2 个节点，则可以使用 半高可用配置。

管理机制

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

Pigsty 需要一个在所有被管理节点上具有免密 SSH 和 Sudo 权限的操作系统 管理用户。

这个用户需要能够通过 ssh 访问到所有被管理节点，并且能够在这些节点上执行 sudo 命令。

要想将节点纳入 Pigsty 中管理，

沙箱环境

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

Pigsty 提供了一个标准的四节点 沙箱环境，用于学习、测试与功能演示。

沙箱使用固定的 IP 地址和预定义的身份标识符，便于复现各种演示用例。

环境描述

默认的沙箱环境由 4 个节点组成，默认使用配置文件 ha/full.yml。

Vagrant

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

Vagrant 是一个流行的本地虚拟化工具，可以按照声明式的方式创建本地虚拟机。

Pigsty 需要 Linux 环境运行，您可以使用 Vagrant 轻松在本地创建 Linux 虚拟机进行测试。

当前推荐并验证的基线为 Rocky Linux 9.8 / 10.2、Debian 12.15 / 13.6，以及 Ubuntu 22.04.5 / 24.04.4 / 26.04.0；Vagrant 的大版本别名会映射到对应的固定 Box 版本。

Terraform

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

Terraform 是一个流行的"基础设施即代码"工具，您可以使用它在公有云上一键创建虚拟机。

Pigsty 当前提供阿里云、AWS（全球与中国区）、Azure、GCP、腾讯云、Hetzner、Vultr、DigitalOcean 与 Linode 的 Terraform 示例模板；其中 aliyun-s3.tf 还会为 S3/pgBackRest 场景创建私有 OSS Bucket 与专用 RAM 读写凭据。

安全考量

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

Pigsty 默认配置面向受信内网中的开发、测试和演示。生产部署需要根据实际威胁模型完成凭据、网络、认证、证书、备份和审计配置。

安全机制及其边界见 安全与合规，可执行检查项见 合规实践。ha/safe 是加固配置示例，不替代逐项审查。

关于

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

运维 SOP 索引

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

上手路线

顺序	要解决的问题	入口
1	Pigsty 由哪些模块组成？	积木式架构，PGSQL 架构，PGSQL 集群模型
2	怎么先跑起来？	快速上手，图形界面，快速上手 PostgreSQL
3	配置文件该怎么看？	声明式配置，配置清单，配置参数
4	生产部署要准备什么？	架构规划，资源准备，管理机制
5	怎么部署多节点集群？	生产部署，执行剧本，PGSQL 剧本
6	日常怎么管库？	PGSQL 日常管理，集群管理，用户管理，数据库管理
7	怎么验证可靠性？	PG 高可用，Patroni 管理，备份恢复，恢复操作

任务索引

任务	先看	操作入口
准备服务器、磁盘、网络、VIP	资源准备，架构规划，Linux 兼容性	生产部署
准备 SSH、Sudo、管理用户	管理机制	生产部署
本地或云上搭沙箱	沙箱环境	Vagrant，Terraform
单机体验	快速上手	`./configure -g`，`./deploy.yml`
多节点生产部署	部署，生产部署	`./deploy.yml`，`./pgsql.yml`
离线环境部署	离线安装	软件仓库管理
选择配置模板	配置模板，模板列表	`./configure -c <template>`
规划集群名、库名、用户名	PGSQL 集群模型	`pg_cluster`，`pg_databases`，`pg_users`
创建数据库集群	集群实例配置	集群管理，`./pgsql.yml -l <cluster>`
新增业务用户	用户/角色配置	用户管理，`./pgsql-user.yml -l <cluster>`
新增业务数据库	数据库配置	数据库管理，`./pgsql-db.yml -l <cluster>`
配置访问入口	服务/接入	`pg_services`，`pg_default_services`
修改 HBA	HBA 配置	HBA 管理
主从切换	Patroni 管理	`patronictl switchover`
HA 故障演练	PG 高可用，RPO，RTO	3坏2应急处理
配置 VIP	HA 服务接入	配置 PG VIP
配置备份策略	备份策略	备份管理命令
做 PITR 时间点恢复	时间点恢复	恢复操作
误删数据、表、库	误删处理	手工恢复
克隆恢复集群	克隆数据库集群	Fork 实例
使用 Silo 存备份	MINIO 模块	Silo 配置，备份仓库
查看监控告警	监控系统	PGSQL 监控，PGSQL 仪表盘
排查数据库故障	PGSQL 常见问题	故障排查，组件管理
扩容、缩容 PG 集群	集群实例配置	集群管理
升级 PostgreSQL	版本升级	内核版本
安装或启用扩展	扩展插件	扩展管理
迁移已有数据库	数据迁移	迁移剧本
做安全加固	安全考量	访问控制，CA 与证书
管理域名与 Web 入口	域名管理	Nginx 管理
维护基础设施	INFRA 管理预案	`infra.yml`，`infra-rm.yml`
维护 Etcd	ETCD 配置	ETCD 管理，ETCD FAQ
部署应用模板	应用	Docker 模块，`./app.yml`

准备与部署

生产部署先看 架构规划 和 资源准备。这两篇解决节点数量、磁盘、文件系统、网络、VIP、域名、软件源这些问题。

配置指南

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

Citus 集群部署

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

Citus 是一个 PostgreSQL 扩展，可以将 PostgreSQL 原地转换为一个分布式数据库，并实现在多个节点上水平扩展，以处理大量数据和大量查询。

Patroni 在 v3.0 后，提供了对 Citus 原生高可用的支持，简化了 Citus 集群的搭建，Pigsty 也对此提供了原生支持。

快速开始

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

在 Pigsty 中使用扩展需要四个步骤：下载、安装、配置、启用。

下载：将扩展软件包下载到本地仓库（默认本地仓库只保证基础内核与 pgsql-main 包集）
安装：在集群节点上安装扩展软件包
配置：部分扩展需要预加载或配置参数
启用：在数据库中执行 CREATE EXTENSION 创建扩展

声明式配置

在 Pigsty 配置清单中声明扩展，集群初始化时自动完成安装与启用：

安装扩展

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

Pigsty 使用操作系统的包管理器（yum/apt）安装扩展软件包。

参数	用途	默认行为
`pg_packages`	全局通用软件包	确保存在（不升级）
`pg_extensions`	集群特定扩展	安装最新版本

快速上手

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

本教程从一个最小单节点集群开始，完成 Topic 创建与消息读写；随后部署一套独立的三节点安全集群，配置应用用户、ACL、Quota 和生产 Topic；最后演示核心参数修改、客户端接入、监控验证与上线检查。

教程 on Pigsty v5.0

上手

部署

配置清单

配置文件

快速上手 Pigsty 单机部署

摘要

Docker 部署

从浏览器访问图形用户界面

快速上手 PostgreSQL

通过配置清单定制 Pigsty 部署

使用 Ansible 剧本完成部署

离线安装

概览

精简安装

概览

安全建议

密码

生产部署

摘要

资源准备

节点

架构规划

常见方案

管理机制

沙箱环境

环境描述

Vagrant

Terraform

安全考量

关于

运维 SOP 索引

上手路线

任务索引

准备与部署

配置指南

Citus 集群部署

快速开始

声明式配置

安装扩展

相关参数

快速上手