分类: 教程

Citus 是一个 PostgreSQL 扩展，可以将 PostgreSQL 原地转换为一个分布式数据库，并实现在多个节点上水平扩展，以处理大量数据和大量查询。 Patroni 在 v3.0 后，提供了对 Citus 原生高可用的支持，简化了 Citus 集群的搭建，Pigsty 也对此提供了原生支持。 Citus 是什么 Patroni Citus 支持 说明 Citus 13.x 支持 PostgreSQL 18、17、16、15、14 五个大版本。Pigsty 扩展仓库提供了 Citus …

本教程从一个最小单节点集群开始，完成 Topic 创建与消息读写；随后部署一套独立的三节点安全集群，配置应用用户、ACL、Quota 和生产 Topic；最后演示核心参数修改、客户端接入、监控验证与上线检查。 教程范围 这里的“从零开始”是指从尚未部署 Kafka 开始。您需要先有一套可用的 Pigsty 管理节点，并已部署基础 INFRA 服务；如果还没有，请先完成 Pigsty 快速安装。目标节点需要 SSH/Sudo 权限，并可被 NODE 模块纳管。 学习路径 阶段 目标 最终结果 1 …

Pigsty 使用操作系统的包管理器（yum/apt）安装扩展软件包。 相关参数 两个参数用于指定要安装的扩展： 参数 用途 默认行为 pg_packages 全局通用软件包 确保存在（不升级） pg_extensions 集群特定扩展 安装最新版本 pg_packages 通常用于指定所有集群都需要的基础组件（PostgreSQL 内核、Patroni、pgBouncer 等）和必选扩展。 pg_extensions 用于指定特定集群需要的扩展。 pg_packages: # 全局基础包 - …

在 Pigsty 中使用扩展需要四个步骤：下载、安装、配置、启用。 下载：将扩展软件包下载到本地仓库（默认本地仓库只保证基础内核与 pgsql-main 包集） 安装：在集群节点上安装扩展软件包 配置：部分扩展需要预加载或配置参数 启用：在数据库中执行 CREATE EXTENSION 创建扩展 声明式配置 在 Pigsty 配置清单中声明扩展，集群初始化时自动完成安装与启用： pg-meta: hosts: { 10.10.10.10: { pg_seq: 1, pg_role: …

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

Pigsty 默认配置面向受信内网中的开发、测试和演示。生产部署需要根据实际威胁模型完成凭据、网络、认证、证书、备份和审计配置。 安全机制及其边界见 安全与合规，可执行检查项见 合规实践。ha/safe 是加固配置示例，不替代逐项审查。 机密性 重要文件 重点保护以下资产： pigsty.yml 与其他 inventory：通常包含系统和业务凭据； files/pki/ca/ca.key：可以签发受部署信任的证书； 管理用户 SSH 私钥：默认可以在纳管节点上执行 sudo； 客户端证书私钥与备 …

Terraform 是一个流行的"基础设施即代码"工具，您可以使用它在公有云上一键创建虚拟机。 Pigsty 当前提供阿里云、AWS（全球与中国区）、Azure、GCP、腾讯云、Hetzner、Vultr、DigitalOcean 与 Linode 的 Terraform 示例模板；其中 aliyun-s3.tf 还会为 S3/pgBackRest 场景创建私有 OSS Bucket 与专用 RAM 读写凭据。 快速开始 安装 Terraform 在 macOS 上，您可以使用 Homebrew …

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 版本。 安装依赖 首先，确保您的系统中已经安装了 …

Pigsty 提供了一个标准的四节点 沙箱环境，用于学习、测试与功能演示。 沙箱使用固定的 IP 地址和预定义的身份标识符，便于复现各种演示用例。 环境描述 默认的沙箱环境由 4 个节点组成，默认使用配置文件 ha/full.yml。 ID IP 地址 节点名 PostgreSQL INFRA ETCD MINIO 1 10.10.10.10 meta pg-meta-1 infra-1 etcd-1 minio-1 2 10.10.10.11 node-1 pg-test-1 3 …

Pigsty 需要一个在所有被管理节点上具有免密 SSH 和 Sudo 权限的操作系统 管理用户。 这个用户需要能够通过 ssh 访问到所有被管理节点，并且能够在这些节点上执行 sudo 命令。 要想将节点纳入 Pigsty 中管理， 用户 通常我们会选择 dba 或 admin 这样的用户名称，并避免使用 root 与 postgres： 使用 root 进行部署是可行的，但不符合生产最佳实践。 使用 postgres （pg_dbsu）作为管理员用户是严格禁止的。 免密码 如果您可以接受为每 …

Pigsty 采用 模块化架构，您可以像搭积木一样组合出自己想要的部署方案，并用简单的 声明式配置 表达您的意图。 常见方案 这里有一些常见的组合模式供您参考，您可以根据自己的需求进行进一步的定制与调整： 方案 INFRA ETCD PGSQL MINIO 说明 单机部署（meta） 1 1 1 单机部署 默认配置，经典方案 单机部署（slim） 1 1 不要监控设施，只要数据库 基础设施（infra） 1 只要监控基础设施 单机部署（rich） 1 1 1 1 单机 + 对象存储 + 本地仓库 …

Pigsty 运行在节点（物理机或虚拟机）之上，本文档介绍硬件相关的规划与准备。 节点 Pigsty 目前运行在 Linux 内核和 x86_64 / aarch64 架构的节点上。 "节点" 指的是 SSH 可访问 且提供裸 Linux 操作系统环境的资源。 它可以是物理机、虚拟机或配备 systemd、sudo 和 sshd 的类似操作系统的容器。 部署 Pigsty 至少需要 1 个节点，您可以准备更多，并在 执行部署剧本 中一次性部署所有节点，或稍后添加并单独部署。 最小节点规格要求是 …

本文是 Pigsty 生产环境多节点部署指南，部署单机版本 Demo/Dev 环境可以参考 快速上手 文档。 摘要 准备 几台 具有 SSH 权限 的 节点， 安装 兼容的 Linux 系统，使用具有免密 ssh 和 sudo 权限的 管理用户 执行： pigsty.cc（中国） curl -fsSL https://repo.pigsty.cc/get | bash; pigsty.io（全球） curl -fsSL https://repo.pigsty.io/get | bash; 该命令 …

默认配置适用于本地演示和受信内网中的开发测试。只要部署可能被其他主机访问，就应至少完成凭据、网络和关键文件三项检查。 生产环境还应参考 安全模型、合规实践 和 安全考量。 密码 Pigsty 的默认凭据公开记录在源码和文档中，不能直接用于生产。 配置向导可以随机化其识别的内置参数和示例凭据： ./configure -g configure -g 不会替换以下内容： pgBackRest 的 cipher_pass； ha/safe 中的 Silo 用户和部分示例口令； 用户自行添加的数据库、对 …

如果您只想要高可用 PostgreSQL 数据库集群本身，而不需要监控、基础设施等功能，请考虑 精简安装。 精简安装没有 INFRA 模块，没有监控，没有 本地仓库，只有 ETCD 和 PGSQL 以及部分 NODE 功能。 精简安装适合以下场景 只需要 PostgreSQL 数据库本身，不需要可观测性基础设施。 资源极度受限的环境，不愿意承担基础设施开销（单机约 0.2 vCPU / 500MB 开销） 已有外部监控系统，希望统一使用自己的监控管理体系。 不需要 Grafana 可视化看板组件 …

Pigsty 默认从互联网上游 安装 所需软件包，但有些环境与互联网隔离。 为了解决这个问题，Pigsty 支持使用 离线软件包 进行离线安装。 您可以将其视作 Linux- 原生版本的 Docker 镜像。 概览 离线软件包 打包了所有需要的 RPM/DEB 软件包及其依赖；它是常规 安装 后的本地 APT / YUM 仓库的快照。 在 严肃的生产环境部署 中，我们 强烈推荐 您使用离线安装包进行安装。 它可以确保后续所有新节点的软件版本与现有环境保持一致， 并且可以避免上游变动导致的在线安装 …

Pigsty 使用 Ansible 对集群进行管理，这是在 SRE 群体中非常流行的大规模/批量化/自动化运维工具。 Ansible 可以使用 声明式 的方式对服务器进行配置管理，所有模块的部署都是通过一系列幂等的 Ansible 剧本 实现的。 例如，在单机部署时，您会用到 deploy.yml 剧本。Pigsty 还有更多 内置剧本，您可以根据需要选择使用。 了解 Ansible 基础知识有助于更好的使用 Pigsty，但这 并非必须，特别是在单机部署时。 部署剧本 Pigsty 提供了一个 …

除了使用 配置向导 自动生成配置，您也可以从零开始手工编写 Pigsty 配置文件。 本教程将指导您从头开始，逐步构建一个复杂的 配置清单。 如果您事先在 配置清单 中定义好 NODE、INFRA、ETCD、MINIO 与 PGSQL，那么 deploy.yml 可以一次性完成这条核心链路的部署，但它隐藏了所有细节。Docker、Redis、Kafka、原生 MySQL、JUICE 与 VIBE 等可选模块需要另行执行各自的剧本。 所以本文档会把所有模块与剧本拆解开来，介绍如何从一个简单的配置， …

PostgreSQL（简称 PG）是世界上最先进、最流行的开源关系型数据库，你可以用它来存储和检索多模态数据。 本指南面向有基础 Linux 基本命令行操作经验、但对 PostgreSQL 不太熟悉的开发者，带你快速上手 Pigsty 中的 PG。 我们假设您是个人用户，使用默认单机模式进行部署。关于生产环境多节点高可用集群的使用，请参考 生产服务接入。 基本知识 默认 单机安装 模板下，您将在当前节点上创建一个名为 pg-meta 的 PostgreSQL 数据库集群，只有一个主库实例。 …

Pigsty 单机安装 完成后，您在当前节点上将安装有 INFRA 模块，它带有一套开箱即用的 Nginx Web 服务器。 其中的默认服务器配置提供了一个 WebUI 图形界面，用于展示监控仪表盘，并统一代理访问其他组件的 Web 界面。 访问 您可以通过在浏览器中键入部署节点 IP 地址来访问这个图形界面。在默认配置下，Nginx 将通过 80/443 标准端口对外提供服务。 IP 直接访问 域名（HTTP） 域名（HTTPS） Demo http://10.10.10.10 …

Pigsty 旨在运行于原生 Linux 系统上，但也可以在带有 systemd 的 Linux 容器环境中运行。 如果您没有原生 Linux 环境（例如 macOS 或 Windows 用户），可以使用 Docker 快速拉起一个本地单机 Pigsty 环境进行测试与体验。 快速开始 进入 Pigsty 源码包的 docker/ 目录，使用以下一键命令启动 Pigsty： cd ~/pigsty/docker make launch # 启动容器 + 生成配置 + 执行部署 部署完成后，您可以 …

本文是 Pigsty 单节点安装指南 单节点，生产环境的多节点高可用部署请参考 部署 文档。 Pigsty 单机安装分为三步走：安装，配置 与 部署。 摘要 准备 一台具有 SSH 权限 的 节点， 安装 兼容的 Linux 系统，使用具有免密 ssh 和 sudo 权限的 管理用户 执行： 选择 Pigsty 下载镜像： pigsty.cc（中国） curl -fsSL https://repo.pigsty.cc/get | bash pigsty.io（全球） curl -fsSL …

每一套 Pigsty 部署都对应着一份 配置清单 （Inventory），描述了基础设施与数据库集群的关键属性。 配置文件 Pigsty 默认使用 Ansible YAML 配置格式， 使用一个单一 YAML 配置文件 pigsty.yml 作为配置清单。 ~/pigsty ^---- pigsty.yml # <---- 默认配置文件 您可以直接修改该配置文件来定制您的部署，或者使用 Pigsty 提供的 配置向导 configure 脚本自动生成合适的配置文件。 配置结构 配置清单使用标准的 …

与 快速上手 不同，企业生产环境 Pigsty 部署需要更多 架构规划 与 准备工作。 本章将帮助您理解 Pigsty 的完整部署流程，并提供生产环境部署的最佳实践建议。 我们建议您在真实的生产环境部署之前，使用 Pigsty 提供的 沙箱环境 进行测试与演练，确保对部署流程有充分的了解。 您可以使用 Vagrant 在本地快速创建一个四节点的 Pigsty 沙箱环境用于测试，或者利用 Terraform 在云端置备一个更大规模的仿真环境。 对于生产环境部署，您通常需要准备至少三个 节点 以实现 …

Pigsty 采用可伸缩的架构设计，既可用于 超大规模生产环境，也可用于 单机开发演示环境，本文关注后者。 如果您打算学习了解 Pigsty，可以从 快速上手 单机部署开始。一台 1C/2G 的 Linux 虚拟机即可运行 Pigsty。 您可以利用一台 Linux MiniPC，云厂商提供的免费/优惠虚拟机，Windows 的 WSL，或者在自己的笔记本上创建虚拟机用于 Pigsty 部署。 Pigsty 提供了开箱即用的 Vagrant 模板与 Terraform 模版，可以帮助您一键在本地 …