这是本节的多页打印视图。点击此处打印.

管理预案

基础设施组件与 Infra 集群管理 SOP：创建，销毁，扩容，缩容，证书，仓库……

1: Ansible
2: 剧本
3: Nginx 管理
4: 软件仓库
5: 模块管理
6: 域名管理
7: CA 与证书

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

1 - Ansible

使用 Ansible 运行管理命令

所有 INFRA 节点上都默认安装了 Ansible，可以用于管理整套部署。

Pigsty 基于 Ansible 实现自动化管理，它遵循 基础设施即代码（Infrastructure-as-Code） 的理念。

对于管理数据库与基础设施而言，Ansible 的知识很有用，但并非必需。您只需知道如何执行 剧本（Playbook） —— 那些定义了一系列自动化任务的 YAML 文件即可。

安装

Pigsty 在引导过程中会尽力自动安装 ansible 及其依赖项。如需手动安装，请使用以下命令：

# Debian / Ubuntu
sudo apt install -y ansible python3-jmespath

# EL 10
sudo dnf install -y ansible python-jmespath

# EL 8/9
sudo dnf install -y ansible python3.12-jmespath

# EL 7
sudo yum install -y ansible python-jmespath

macOS

macOS 用户可使用 Homebrew 安装：

brew install ansible
pip3 install jmespath

基础用法

运行剧本只需执行 ./path/to/playbook.yml 即可。以下是最常用的 Ansible 命令行参数：

用途	参数	说明
在哪里	`-l` / `--limit <pattern>`	限定目标主机/分组/匹配模式
做什么	`-t` / `--tags <tags>`	仅运行带有指定标签的任务
怎么做	`-e` / `--extra-vars <vars>`	传递额外的命令行变量
用什么配置	`-i` / `--inventory <path>`	指定配置清单文件路径

限定主机

使用 -l|--limit <pattern> 参数可将执行范围限定到特定的分组、主机或匹配模式：

./node.yml                      # 在所有节点上执行
./pgsql.yml -l pg-test          # 仅在 pg-test 集群上执行
./pgsql.yml -l pg-*             # 在所有以 pg- 开头的集群上执行
./pgsql.yml -l 10.10.10.10      # 仅在特定 IP 的主机上执行

不指定主机限制直接运行剧本可能非常危险！缺省情况下，大多数剧本会在 所有（all） 主机上执行。务必谨慎使用！

限定任务

使用 -t|--tags <tags> 参数可仅执行带有指定标签的任务子集：

./infra.yml -t repo           # 仅执行创建本地仓库的任务
./infra.yml -t repo_upstream  # 仅执行添加上游仓库的任务
./node.yml -t node_pkg        # 仅执行安装节点软件包的任务
./pgsql.yml -t pg_hba         # 仅执行渲染 pg_hba.conf 的任务

传递变量

使用 -e|--extra-vars <key=value> 参数可在运行时覆盖变量：

./pgsql.yml -e pg_clean=true         # 强制清理现有的 PG 实例
./pgsql-rm.yml -e pg_rm_pkg=false    # 卸载时保留软件包
./node.yml -e '{"node_tune":"tiny"}' # 使用 JSON 格式传递变量
./pgsql.yml -e @/path/to/config.yml  # 从 YAML 文件加载变量

指定配置清单

默认情况下，Ansible 会使用当前目录下的 pigsty.yml 作为配置清单。使用 -i|--inventory <path> 参数可指定其他配置文件：

./pgsql.yml -i files/pigsty/full.yml -l pg-test

[!NOTE]
若要永久更改默认配置文件的路径，可修改 ansible.cfg 中的 inventory 参数。

2 - 剧本

Pigsty 内置的 Ansible 剧本

Pigsty 使用幂等的 Ansible 剧本实现管理控制。执行剧本需要将 ansible-playbook 添加到系统 PATH 中，用户需要先安装 Ansible 才能执行剧本。

可用剧本

模块	剧本	功能
INFRA	`install.yml`	一键式安装 Pigsty
INFRA	`infra.yml`	在基础设施节点上初始化 Pigsty 基础设施
INFRA	`infra-rm.yml`	从基础设施节点移除基础设施组件
INFRA	`cache.yml`	从目标节点制作离线安装包
INFRA	`cert.yml`	使用 Pigsty 自签名 CA 签发证书
NODE	`node.yml`	初始化节点，将节点配置到预期状态
NODE	`node-rm.yml`	从 Pigsty 中移除节点
PGSQL	`pgsql.yml`	初始化高可用 PostgreSQL 集群，或添加新从库
PGSQL	`pgsql-rm.yml`	移除 PostgreSQL 集群，或移除从库
PGSQL	`pgsql-db.yml`	向现有 PostgreSQL 集群添加新业务数据库
PGSQL	`pgsql-user.yml`	向现有 PostgreSQL 集群添加新业务用户
PGSQL	`pgsql-pitr.yml`	在现有 PostgreSQL 集群上执行时间点恢复（PITR）
PGSQL	`pgsql-monitor.yml`	使用本地导出器监控远程 PostgreSQL 实例
PGSQL	`pgsql-migration.yml`	为现有 PostgreSQL 生成迁移手册和脚本
PGSQL	`slim.yml`	以最小化组件安装 Pigsty
REDIS	`redis.yml`	初始化 Redis 集群/节点/实例
REDIS	`redis-rm.yml`	移除 Redis 集群/节点/实例
ETCD	`etcd.yml`	初始化 ETCD 集群，或添加新成员
ETCD	`etcd-rm.yml`	移除 ETCD 集群，或移除现有成员
MINIO	`minio.yml`	初始化 MinIO 集群
MINIO	`minio-rm.yml`	移除 MinIO 集群
DOCKER	`docker.yml`	在节点上安装 Docker
DOCKER	`app.yml`	使用 Docker Compose 安装应用
FERRET	`mongo.yml`	在节点上安装 Mongo/FerretDB

部署策略

install.yml 剧本会按照以下分组顺序协调各个专用剧本，完成完整部署：

infra：infra.yml（-l infra）
nodes：node.yml
etcd：etcd.yml（-l etcd）
minio：minio.yml（-l minio）
pgsql：pgsql.yml

循环依赖说明：NODE 和 INFRA 之间存在弱循环依赖：要将 NODE 注册到 INFRA，INFRA 必须已经存在；而 INFRA 模块又依赖 NODE 才能工作。解决方法是先初始化 infra 节点，然后再添加其他节点。如果希望一次性完成所有部署，使用 install.yml 即可。

安全须知

大多数剧本都是幂等的，这意味着某些部署剧本在未开启保护选项的情况下，可能会擦除现有数据库并创建新数据库。使用 pgsql、minio 和 infra 剧本时请特别小心。请仔细阅读文档，谨慎操作。

最佳实践

执行前仔细阅读剧本文档
发现异常时立即按 Ctrl-C 停止
先在非生产环境中进行测试
使用 -l 参数限定执行主机，避免影响非目标主机
使用 -t 参数指定特定标签，仅执行部分任务

预演模式

使用 --check --diff 选项可以预览将要进行的更改，而不实际执行：

# 预览将要进行的更改，但不实际执行
./pgsql.yml -l pg-test --check --diff

# 结合标签检查特定任务
./pgsql.yml -l pg-test -t pg_config --check --diff

3 - Nginx 管理

Nginx 管理，Web 门户配置，Web Server，暴露上游服务

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

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

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

基础配置

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

infra_portal:
  home: { domain: i.pigsty }

服务器参数

基本参数

参数	说明
`domain`	可选的代理域名
`endpoint`	上游服务地址（IP:PORT 或 socket）
`path`	静态内容的本地目录
`scheme`	协议类型（http/https/tcp/udp）

SSL/TLS 选项

参数	说明
`certbot`	启用 Let’s Encrypt 证书管理
`cert`	自定义证书文件路径
`key`	自定义私钥文件路径

高级设置

参数	说明
`conf`	自定义 Nginx 配置模板
`domains`	额外的域名列表
`index`	启用目录列表
`log`	自定义日志文件配置
`websocket`	启用 WebSocket 支持

配置示例

静态文件与目录列表

repo: { domain: repo.pigsty.cc, path: "/www/repo", index: true }

自定义 SSL 证书

secure_app: {
  domain: secure.pigsty.cc,
  endpoint: "${admin_ip}:8443",
  cert: "/etc/ssl/certs/custom.crt",
  key: "/etc/ssl/private/custom.key"
}

TCP 流代理

pg_primary: { domain: pg.pigsty.cc, endpoint: "10.10.10.11:5432", scheme: tcp }

管理命令

./infra.yml -t nginx           # 完整重新配置 Nginx
./infra.yml -t nginx_config    # 重新生成配置文件
./infra.yml -t nginx_launch    # 重启 Nginx 服务
./infra.yml -t nginx_cert      # 重新生成 SSL 证书

域名解析

有三种方式将域名解析到 Pigsty 服务器：

公网域名：通过 DNS 服务商配置
内网 DNS 服务器：配置内部 DNS 解析
本地 hosts 文件：修改 /etc/hosts

本地开发时，在 /etc/hosts 中添加：

<your_public_ip_address> i.pigsty g.pigsty p.pigsty a.pigsty

HTTPS 配置

通过 nginx_sslmode 参数配置 HTTPS：

模式	说明
`disable`	仅监听 HTTP（`nginx_port`）
`enable`	同时监听 HTTPS（`nginx_ssl_port`），默认签发自签名证书
`enforce`	强制跳转到 HTTPS，所有 80 端口请求都会 301 重定向

对于自签名证书，有以下几种访问方式：

在浏览器中信任自签名 CA
使用浏览器安全绕过（Chrome 中输入 “thisisunsafe”）
为生产环境配置正规 CA 签发的证书

最佳实践

使用域名而非 IP:PORT 访问
正确配置 DNS 解析或 hosts 文件
为实时服务启用 WebSocket
生产环境部署 HTTPS
使用有意义的子域名组织服务
监控证书过期时间
集中化代理管理
利用静态文件服务托管文档

4 - 软件仓库

管理本地 APT/YUM 软件仓库

Pigsty 支持创建和管理本地 APT/YUM 软件仓库，用于在离线环境中部署或加速软件包安装。

快速开始

向本地仓库添加软件包：

将软件包添加到 repo_packages（默认软件包）
将软件包添加到 repo_extra_packages（额外软件包）
执行构建命令：

./infra.yml -t repo_build   # 从上游构建本地仓库
./node.yml -t node_repo     # 刷新节点仓库缓存

软件包别名

Pigsty 预定义了常用的软件包组合，方便批量安装：

EL 系统（RHEL/CentOS/Rocky）

别名	说明
`node-bootstrap`	Ansible、Python3 工具、SSH 相关
`infra-package`	Nginx、etcd、HAProxy、监控导出器、MinIO 等
`pgsql-utility`	Patroni、pgBouncer、pgBackRest、PG 工具
`pgsql`	完整 PostgreSQL（服务端、客户端、扩展）
`pgsql-mini`	最小化 PostgreSQL 安装

Debian/Ubuntu 系统

别名	说明
`node-bootstrap`	Ansible、开发工具
`infra-package`	基础设施组件（使用 Debian 命名规范）
`pgsql-client`	PostgreSQL 客户端
`pgsql-server`	PostgreSQL 服务端及相关包

剧本任务

主要任务

任务	说明
`repo`	从互联网或离线包创建本地仓库
`repo_build`	如不存在则从上游构建
`repo_upstream`	添加上游仓库文件
`repo_pkg`	下载软件包及依赖
`repo_create`	创建/更新 YUM 或 APT 仓库
`repo_nginx`	启动 Nginx 文件服务器

完整任务列表

./infra.yml -t repo_dir          # 创建本地软件仓库目录
./infra.yml -t repo_check        # 检查本地仓库是否存在
./infra.yml -t repo_prepare      # 直接使用已有仓库
./infra.yml -t repo_build        # 从上游构建仓库
./infra.yml -t repo_upstream     # 添加上游仓库
./infra.yml -t repo_remove       # 删除现有仓库文件
./infra.yml -t repo_add          # 添加仓库到系统目录
./infra.yml -t repo_url_pkg      # 从互联网下载包
./infra.yml -t repo_cache        # 创建元数据缓存
./infra.yml -t repo_boot_pkg     # 安装引导包
./infra.yml -t repo_pkg          # 下载包及依赖
./infra.yml -t repo_create       # 创建本地仓库
./infra.yml -t repo_use          # 添加新建仓库到系统
./infra.yml -t repo_nginx        # 启动 Nginx 文件服务器

常用操作

添加新软件包

# 1. 配置上游仓库
./infra.yml -t repo_upstream

# 2. 下载软件包及依赖
./infra.yml -t repo_pkg

# 3. 构建本地仓库元数据
./infra.yml -t repo_create

刷新节点仓库

./node.yml -t node_repo    # 刷新所有节点的仓库缓存

完整重建仓库

./infra.yml -t repo        # 从互联网或离线包创建仓库

5 - 模块管理

Infra 模块本身的管理 SOP：定义，创建，销毁，扩容，缩容

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

安装 Infra 模块

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

./infra.yml     # 在 infra 分组上安装 INFRA 模块

卸载 Infra 模块

使用 infra-rm.yml 剧本从 infra 分组上卸载 INFRA 模块：

./infra-rm.yml  # 从 infra 分组上卸载 INFRA 模块

扩容 Infra 模块

在配置清单中为新节点分配 infra_seq 并加入 infra 分组：

all:
  children:
    infra:
      hosts:
        10.10.10.10: { infra_seq: 1 }  # 原有节点
        10.10.10.11: { infra_seq: 2 }  # 新节点

使用限制选项 -l 仅在新节点上执行剧本：

./infra.yml -l 10.10.10.11    # 在新节点上安装 INFRA 模块

管理本地软件仓库

本地软件仓库相关的管理任务：

./infra.yml -t repo              # 从互联网或离线包创建仓库
./infra.yml -t repo_upstream     # 添加上游仓库
./infra.yml -t repo_pkg          # 下载包及依赖
./infra.yml -t repo_create       # 创建本地 yum/apt 仓库

完整子任务列表：

./infra.yml -t repo_dir          # 创建本地软件仓库
./infra.yml -t repo_check        # 检查本地软件仓库是否存在
./infra.yml -t repo_prepare      # 直接使用已有仓库
./infra.yml -t repo_build        # 从上游构建仓库
./infra.yml -t repo_upstream     # 添加上游仓库
./infra.yml -t repo_remove       # 删除现有仓库文件
./infra.yml -t repo_add          # 添加仓库到系统目录
./infra.yml -t repo_url_pkg      # 从互联网下载包
./infra.yml -t repo_cache        # 创建元数据缓存
./infra.yml -t repo_boot_pkg     # 安装引导包
./infra.yml -t repo_pkg          # 下载包及依赖
./infra.yml -t repo_create       # 创建本地仓库
./infra.yml -t repo_use          # 添加新建仓库到系统
./infra.yml -t repo_nginx        # 启动 nginx 文件服务器

管理 Nginx

Nginx 相关的管理任务：

./infra.yml -t nginx                       # 重置 Nginx 组件
./infra.yml -t nginx_index                 # 重新渲染首页
./infra.yml -t nginx_config,nginx_reload   # 重新渲染配置并重载

申请 HTTPS 证书：

./infra.yml -t nginx_certbot,nginx_reload -e certbot_sign=true

管理基础设施组件

基础设施各组件的管理命令：

./infra.yml -t infra           # 配置基础设施
./infra.yml -t infra_env       # 配置环境变量
./infra.yml -t infra_pkg       # 安装软件包
./infra.yml -t infra_user      # 设置操作系统用户
./infra.yml -t infra_cert      # 颁发证书
./infra.yml -t dns             # 配置 DNSMasq
./infra.yml -t nginx           # 配置 Nginx
./infra.yml -t victoria        # 配置 VictoriaMetrics/Logs/Traces
./infra.yml -t alertmanager    # 配置 AlertManager
./infra.yml -t blackbox        # 配置 Blackbox Exporter
./infra.yml -t grafana         # 配置 Grafana
./infra.yml -t infra_register  # 注册到 VictoriaMetrics/Grafana

常用维护命令：

./infra.yml -t nginx_index                        # 重新渲染首页
./infra.yml -t nginx_config,nginx_reload          # 重新配置并重载
./infra.yml -t vmetrics_config,vmetrics_launch    # 重新生成 VictoriaMetrics 配置并重启
./infra.yml -t vlogs_config,vlogs_launch          # 更新 VictoriaLogs 配置
./infra.yml -t grafana_plugin                     # 下载 Grafana 插件

6 - 域名管理

配置本地或公网域名访问 Pigsty 服务

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

快速开始

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

10.10.10.10 i.pigsty g.pigsty p.pigsty a.pigsty

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

为什么使用域名

比 IP 地址更易于记忆
灵活指向不同 IP
通过 Nginx 统一管理服务
支持 HTTPS 加密
防止某些地区的 ISP 劫持
允许通过代理访问内部绑定的服务

DNS 机制

DNS 协议：将域名解析为 IP 地址。多个域名可以指向同一个 IP。

HTTP 协议：使用 Host 头将请求路由到同一端口（80/443）上的不同站点。

默认域名

Pigsty 预定义了以下默认域名：

域名	服务	端口	用途
`i.pigsty`	Nginx	80/443	默认首页、本地仓库与统一入口
`g.pigsty`	Grafana	3000	监控与可视化
`p.pigsty`	VictoriaMetrics	8428	VMUI/PromQL 入口
`a.pigsty`	AlertManager	9059	告警路由

解析方式

本地静态解析

在客户端机器的 /etc/hosts 中添加条目：

# Linux/macOS
sudo vim /etc/hosts

# Windows
notepad C:\Windows\System32\drivers\etc\hosts

添加内容：

10.10.10.10 i.pigsty g.pigsty p.pigsty a.pigsty

内网动态解析

在内部 DNS 服务器上配置这些域名记录。

公网域名

购买域名并添加 DNS A 记录指向公网 IP。

HTTPS 证书

Pigsty 默认使用自签名证书。可选方案包括：

忽略警告，使用 HTTP
信任自签名 CA 证书
使用真实 CA 或通过 Certbot 获取免费公网域名证书

详见 CA 与证书文档。

扩展域名

Pigsty 扩展预留了以下域名：

域名	用途
`adm.pigsty`	管理界面
`ddl.pigsty`	DDL 管理
`cli.pigsty`	命令行界面
`api.pigsty`	API 服务
`lab.pigsty`	实验环境
`git.pigsty`	Git 服务
`wiki.pigsty`	Wiki 文档
`noco.pigsty`	NocoDB
`supa.pigsty`	Supabase
`dify.pigsty`	Dify AI
`odoo.pigsty`	Odoo ERP
`mm.pigsty`	Mattermost

7 - CA 与证书

使用自签名或真实 HTTPS 证书

本文介绍如何使用 Certbot 和 Let’s Encrypt 为 Pigsty 获取和管理 HTTPS 证书。

前置条件

拥有公网域名
DNS 记录指向服务器的公网 IP
Nginx 已正确配置

配置步骤

第一步：域名配置

在 infra_portal 中配置需要证书的服务域名（Grafana、VictoriaMetrics、AlertManager、MinIO 等）：

infra_portal:
  home: { domain: pigsty.cc }
  grafana: { domain: g.pigsty.cc, endpoint: "${admin_ip}:3000", websocket: true }
  prometheus: { domain: p.pigsty.cc, endpoint: "${admin_ip}:8428" }
  alertmanager: { domain: a.pigsty.cc, endpoint: "${admin_ip}:9059" }

第二步：DNS 配置

通过 A 记录将所有域名指向服务器的公网 IP。使用 nslookup 或 dig 验证：

nslookup g.pigsty.cc
dig +short g.pigsty.cc

第三步：申请证书

交互式方式：

certbot --nginx -d pigsty.cc -d g.pigsty.cc -d p.pigsty.cc -d a.pigsty.cc

非交互式方式：

certbot --nginx --agree-tos --email admin@pigsty.cc -n \
  -d pigsty.cc -d g.pigsty.cc -d p.pigsty.cc -d a.pigsty.cc

第四步：Nginx 配置

在 portal 条目中添加 certbot: true 参数，然后重新生成配置：

./infra.yml -t nginx_config,nginx_launch

第五步：自动续期

测试续期（预演模式）：

certbot renew --dry-run

设置 cron 定时任务（每月 1 日凌晨 2 点）：

0 2 1 * * certbot renew --quiet

或启用 systemd 定时器：

systemctl enable certbot.timer

管理命令

命令	说明
`certbot certificates`	列出所有证书
`certbot renew --cert-name domain.com`	续期指定证书
`certbot delete --cert-name domain.com`	删除证书
`certbot revoke --cert-path /path/to/cert.pem`	吊销证书

故障排查

问题	解决方案
域名无法访问	验证 DNS 传播是否完成
端口 80 被阻止	确保验证时端口 80 开放
请求频率限制	避免短时间内多次申请证书
防火墙问题	开放 80 和 443 端口

最佳实践

使用通配符证书管理子域名
设置证书过期告警监控
定期测试续期流程
备份证书文件
记录域名配置文档