上手路线
| 顺序 | 要解决的问题 | 入口 |
|---|---|---|
| 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 实例 |
| 使用 MinIO 存备份 | MINIO 模块 | MinIO 配置，备份仓库 |
| 查看监控告警 | 监控系统 | PGSQL 监控，PGSQL 仪表盘 |
| 排查数据库故障 | PGSQL 常见问题 | 故障排查，组件管理 |
| 扩容、缩容 PG 集群 | 集群实例配置 | 集群管理 |
| 升级 PostgreSQL | 版本升级 | 内核版本 |
| 安装或启用扩展 | 扩展插件 | 扩展管理 |
| 迁移已有数据库 | 数据迁移 | 迁移剧本 |
| 做安全加固 | 安全考量 | 访问控制，CA 与证书 |
| 管理域名与 Web 入口 | 域名管理 | Nginx 管理 |
| 维护基础设施 | INFRA 管理预案 | infra.yml，infra-rm.yml |
| 维护 Etcd | ETCD 配置 | ETCD 管理，ETCD FAQ |
| 部署应用模板 | 应用 | Docker 模块，./app.yml |
准备与部署
生产部署先看 架构规划 和 资源准备。这两篇解决节点数量、磁盘、文件系统、网络、VIP、域名、软件源这些问题。
机器准备好以后，看 管理机制：管理用户、免密 SSH、Sudo、可达性、防火墙都在这里。系统版本和架构看 Linux 兼容性。
第一次安装走 快速上手。多节点生产环境走 生产部署。没有互联网访问时，看 离线安装 和 软件仓库管理。
模板选择不用一开始想太复杂：单机默认看 meta；三节点 HA 看 ha/trio；更完整的 HA 看 ha/full；强调一致性看 ha/safe；资源紧张时看 ha/dual 和 ha/simu。
命名与配置
先分清三个名字：集群名、数据库名、服务名。
pg_cluster 是 Pigsty 管理 PostgreSQL 集群的顶层名字，会影响实例名、服务名、备份 stanza、监控标签和很多文件路径。它不是一个可以随手改的显示名。命名规则看 PGSQL 集群模型；不同实例角色看 集群实例配置；服务名和连接入口看 服务/接入。
数据库名和用户名是 PostgreSQL 里的逻辑对象。库名看 数据库配置 和 数据库管理；用户和角色看 用户/角色配置 和 用户管理；权限模型看 访问控制 与 ACL 配置。
经验上，集群名用小写字母、数字、短横线，例如 pg-meta、pg-test、pg-user-prod。数据库对象名用 snake_case，别用中文、空格、大小写混用和 SQL 关键字。更完整的命名背景可以读 数据库集群管理概念与实体命名规范 和 PostgreSQL 规约（2024版）。
配置变更遵循一个习惯：先改 pigsty.yml，再执行对应剧本。配置结构看 声明式配置 和 配置清单；参数含义看 配置参数 与 参数列表；剧本入口看 执行剧本 和 剧本列表。
日常管理
数据库管理的总入口是 PGSQL 日常管理。
| 操作 | 文档 |
|---|---|
| 创建、扩容、缩容、下线、克隆集群 | 集群管理 |
| 创建、修改、删除业务用户 | 用户管理 |
| 创建、修改、删除、重建数据库 | 数据库管理 |
| 刷新和排查 HBA | HBA 管理 |
| 查看 HA 状态、切换、重启、重做从库 | Patroni 管理 |
| 管理连接池 | Pgbouncer 管理 |
| 启停 PostgreSQL、Patroni、Pgbouncer、Exporter | 组件管理 |
| 管理备份、校验、清理、恢复 | pgBackRest 管理 |
| 配置备份、Vacuum、Analyze 等定时任务 | 定时任务 |
| 升级版本与扩展 | 版本升级，扩展管理 |
PostgreSQL 例行维护的背景文章可以看 PostgreSQL 例行维护。
高可用演练
理解 HA 先看 PG 高可用。不要只看“能不能自动切换”，还要看 RPO 和 RTO：前者是最多能丢多少数据，后者是多久恢复服务。
接入层看 HA 服务接入 和 服务/接入；组件关系看 PGSQL 架构；Etcd 的角色看 ETCD 配置。
演练入口集中在三处：主动切换看 Patroni 管理；服务状态看 组件管理；极端故障看 3坏2应急处理。需要 VIP 时，再看 配置 PG VIP。
背景文章可读 PostgreSQL 高可用到底怎么做？。
备份与恢复
PITR 先读 时间点恢复，再读 工作原理、实现架构、策略权衡 和 典型场景。
配置和维护看 备份恢复、备份策略、备份机制、备份仓库 和 备份管理命令。
真正恢复时，自动方式看 恢复操作，手工演练看 手工恢复。误删数据、表、库，看 误删处理。不想直接动原集群时，先看 克隆数据库集群 或 Fork 实例。
恢复前至少确认四件事：目标时间点或恢复点是否明确；备份和 WAL 是否连续；业务是否已经停写；是在原集群恢复，还是先拉一个新集群验数据。
背景文章可读 备份恢复手段概览 和 PgBackRest2中文文档。
监控与排障
监控总览看 监控系统。入口和域名看 图形界面。数据库指标、日志、告警看 PGSQL 监控 和 PGSQL 仪表盘。
非数据库模块的监控分别看 INFRA 监控、NODE 监控、ETCD 监控 和 MINIO 监控。
排障先看 PGSQL 常见问题，再看 故障排查。连接认证问题看 HBA 管理；HA 状态问题看 Patroni 管理；进程状态问题看 组件管理。
PostgreSQL 通用排障文章：PG 服务器日志常规配置、PostgreSQL 宏观查询优化之 pg_stat_statements、故障档案：PostgreSQL 事务号回卷、查找虚假索引 和 表膨胀治理。
扩缩容、升级、迁移
容量和拓扑设计看 架构规划、资源准备 和 PGSQL 集群模型。
按模块扩缩容时，PGSQL 看 集群管理；NODE 看 NODE 管理；ETCD 看 ETCD 管理；MINIO 看 MINIO 管理；INFRA 看 INFRA 管理预案；REDIS 看 REDIS 管理。
升级 PostgreSQL 看 版本升级 和 内核版本。扩展相关看 扩展插件、扩展管理、扩展仓库 和 软件包别名。
迁移已有 PostgreSQL 看 数据迁移 和 PGSQL 迁移剧本。低停机迁移的思路可以参考 迁移不停机。
需要水平扩展时，再读 Citus 集群部署 和 Citus 内核分支。
安全与入口
部署安全先看 安全考量，安全模型看 安全合规。PostgreSQL 权限看 访问控制 和 ACL 配置；认证规则看 HBA 配置 和 HBA 管理。
证书看 CA 与证书。域名、Nginx、Web 入口看 域名管理 和 Nginx 管理。
生产环境至少要改默认密码，收紧 HBA，明确业务用户和管理用户边界，确认备份仓库的保留、加密和访问权限。
应用接入
应用连接数据库前，先读 服务/接入 和 快速上手 PostgreSQL。连接池行为看 Pgbouncer 管理。
使用 Pigsty 托管数据库、再部署无状态应用时，看 应用模板 和 Docker 模块。
常见误区
| 误区 | 该看哪里 |
|---|---|
把 pg_cluster 当成可以随便改的显示名 | PGSQL 集群模型 |
| 把数据库名、集群名、服务名混为一谈 | 命名与配置，服务/接入 |
| 只部署主库，不演练恢复 | 手工恢复，恢复操作 |
| 以为 HA 就一定不丢数据 | RPO，RTO |
| 第一次故障切换直接在生产做 | 沙箱环境，3坏2应急处理 |
| 忽略 Etcd | ETCD 模块，ETCD FAQ |
| 只看备份成功，不验证恢复 | 备份恢复，克隆数据库集群 |
| 改 HBA、证书、服务入口时没有回滚路径 | 安全合规，HBA 管理，Nginx 管理 |
延伸阅读
| 主题 | 文章 |
|---|---|
| 命名与实体模型 | 数据库集群管理概念与实体命名规范 |
| PostgreSQL 使用规约 | PostgreSQL 规约（2024版） |
| 高可用 | PostgreSQL 高可用到底怎么做？ |
| 备份恢复 | 备份恢复手段概览，PgBackRest2中文文档 |
| 日常维护 | PostgreSQL 例行维护 |
| 连接池 | Pgbouncer 快速上手 |
| 查询与负载 | PostgreSQL 宏观查询优化之 pg_stat_statements，PostgreSQL 的 KPI |
| 日志与故障 | PG 服务器日志常规配置，故障档案：PostgreSQL 事务号回卷 |
| 生态与扩展 | PostgreSQL 正在吞噬数据库世界，小猪骑大象：PG内核与扩展包管理神器 |