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

管理预案

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

1: Nginx 管理
2: 软件仓库
3: 域名管理
4: 模块管理
5: CA 与证书
6: Grafana 高可用部署：使用 PostgreSQL 后端数据库

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

1 - 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 }

infra_portal 是一个字典，每个键定义一个服务，值为服务的配置选项。只有定义了 domain 的服务才会生成对应的 Nginx 配置文件。

home：特殊的默认服务器，用于处理首页和内置监控组件的反向代理
代理服务：通过 endpoint 指定上游服务地址，进行反向代理
静态服务：通过 path 指定本地目录，提供静态文件服务

服务器参数

基本参数

参数	说明
`domain`	可选的代理域名
`endpoint`	上游服务地址（IP:PORT 或 socket）
`path`	静态内容的本地目录
`scheme`	协议类型（http/https），默认 http
`domains`	额外的域名列表（别名）

SSL/TLS 选项

参数	说明
`certbot`	启用 Let’s Encrypt 证书管理，值为证书名称
`cert`	自定义证书文件路径
`key`	自定义私钥文件路径
`enforce_https`	强制跳转 HTTPS（301 重定向）

高级设置

参数	说明
`config`	自定义 Nginx 配置片段
`index`	启用目录列表（用于静态服务）
`log`	自定义日志文件名称
`websocket`	启用 WebSocket 支持
`auth`	启用 Basic Auth 认证
`realm`	Basic Auth 认证提示语

配置示例

反向代理服务

grafana: { domain: g.pigsty, endpoint: "${admin_ip}:3000", websocket: true }
pgadmin: { domain: adm.pigsty, endpoint: "127.0.0.1:8885" }

静态文件与目录列表

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"

使用 Let’s Encrypt 证书

grafana:
  domain: demo.pigsty.cc
  endpoint: "${admin_ip}:3000"
  websocket: true
  certbot: pigsty.demo    # 证书名称，多个域名可共用同一证书

强制 HTTPS 跳转

web.io:
  domain: en.pigsty.cc
  path: "/www/web.io"
  certbot: pigsty.doc
  enforce_https: true

自定义配置片段

web.cc:
  domain: pigsty.cc
  path: "/www/web.cc"
  domains: [ zh.pigsty.cc ]
  certbot: pigsty.doc
  config: |
    # rewrite /zh/ to /
        location /zh/ {
            rewrite ^/zh/(.*)$ /$1 permanent;
        }

管理命令

./infra.yml -t nginx           # 完整重新配置 Nginx
./infra.yml -t nginx_config    # 重新生成配置文件
./infra.yml -t nginx_launch    # 重启 Nginx 服务
./infra.yml -t nginx_cert      # 重新生成 SSL 证书
./infra.yml -t nginx_certbot   # 使用 certbot 签发证书
./infra.yml -t nginx_reload    # 重新加载 Nginx 配置

域名解析

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

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

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

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

Pigsty 内置了 dnsmasq 服务，可以通过 dns_records 参数配置内部 DNS 解析。

HTTPS 配置

通过 nginx_sslmode 参数配置 HTTPS：

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

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

在浏览器中信任自签名 CA（下载地址 http://<ip>/ca.crt）
使用浏览器安全绕过（Chrome 中输入 “thisisunsafe”）
为生产环境配置正规 CA 签发的证书或使用 Let’s Encrypt

Certbot 证书

Pigsty 支持使用 Certbot 申请免费的 Let’s Encrypt 证书。

启用 Certbot

在 infra_portal 中为服务添加 certbot 参数，指定证书名称
配置 certbot_email 为有效的邮箱地址
设置 certbot_sign 为 true 在部署时自动签发

certbot_sign: true
certbot_email: your@email.com

手动签发证书

./infra.yml -t nginx_certbot   # 签发 Let's Encrypt 证书

或直接运行服务器上的脚本：

/etc/nginx/sign-cert           # 签发证书
/etc/nginx/link-cert           # 链接证书到 Nginx 配置目录

更多信息，请参阅 Certbot：申请与更新 HTTPS 证书

默认首页

Pigsty 的默认首页 home 服务器提供以下内置路由：

路径	说明
`/`	首页导航
`/zh`	中文首页
`/ui/`	Grafana 监控面板
`/vmetrics/`	VictoriaMetrics VMUI
`/vlogs/`	VictoriaLogs 日志查询
`/vtraces/`	VictoriaTraces 链路追踪
`/vmalert/`	VMAlert 告警规则
`/alertmgr/`	AlertManager 告警管理
`/blackbox/`	Blackbox Exporter
`/pev`	PostgreSQL Explain 可视化工具
`/haproxy/<cluster>/`	HAProxy 管理界面（如有）

这些路由允许通过单一入口访问所有监控组件，无需配置多个域名。

最佳实践

使用域名而非 IP:PORT 访问服务
正确配置 DNS 解析或 hosts 文件
为实时应用启用 WebSocket（如 Grafana、Jupyter）
生产环境启用 HTTPS
使用有意义的子域名组织服务
监控 Let’s Encrypt 证书过期时间
利用 config 参数添加自定义 Nginx 配置

完整示例

以下是 Pigsty 公开演示站点 demo.pigsty.cc 使用的 Nginx 配置：

infra_portal:
  home         : { domain: i.pigsty }
  cc           : { domain: pigsty.cc      ,path: "/www/pigsty.cc"   ,cert: /etc/cert/pigsty.cc.crt ,key: /etc/cert/pigsty.cc.key }
  minio        : { domain: m.pigsty.cc    ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
  postgrest    : { domain: api.pigsty.cc  ,endpoint: "127.0.0.1:8884" }
  pgadmin      : { domain: adm.pigsty.cc  ,endpoint: "127.0.0.1:8885" }
  pgweb        : { domain: cli.pigsty.cc  ,endpoint: "127.0.0.1:8886" }
  bytebase     : { domain: ddl.pigsty.cc  ,endpoint: "127.0.0.1:8887" }
  jupyter      : { domain: lab.pigsty.cc  ,endpoint: "127.0.0.1:8888" ,websocket: true }
  gitea        : { domain: git.pigsty.cc  ,endpoint: "127.0.0.1:8889" }
  wiki         : { domain: wiki.pigsty.cc ,endpoint: "127.0.0.1:9002" }
  noco         : { domain: noco.pigsty.cc ,endpoint: "127.0.0.1:9003" }
  supa         : { domain: supa.pigsty.cc ,endpoint: "10.10.10.10:8000" ,websocket: true }
  dify         : { domain: dify.pigsty.cc ,endpoint: "10.10.10.10:8001" ,websocket: true }
  odoo         : { domain: odoo.pigsty.cc ,endpoint: "127.0.0.1:8069"   ,websocket: true }
  mm           : { domain: mm.pigsty.cc   ,endpoint: "10.10.10.10:8065" ,websocket: true }

2 - 软件仓库

管理本地 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        # 从互联网或离线包创建仓库

3 - 域名管理

配置本地或公网域名访问 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	告警路由
`m.pigsty`	MinIO	9001	对象存储控制台

解析方式

本地静态解析

在客户端机器的 /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 m.pigsty

内网动态解析

Pigsty 内置了 dnsmasq 服务作为内网 DNS 服务器。配置被管理的节点使用 INFRA 节点作为 DNS 服务器：

node_dns_servers: ['${admin_ip}']   # 使用 INFRA 节点作为 DNS 服务器
node_dns_method: add                # 将其添加到现有 DNS 服务器列表

通过 dns_records 参数配置 dnsmasq 解析的域名记录：

dns_records:
  - "${admin_ip} i.pigsty"
  - "${admin_ip} m.pigsty sss.pigsty api.pigsty adm.pigsty cli.pigsty ddl.pigsty"

公网域名

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

在域名服务商处购买域名（如 example.com）
配置 A 记录指向服务器公网 IP
在 infra_portal 中使用真实域名

内置 DNS 服务

Pigsty 在 INFRA 节点上运行 dnsmasq 作为 DNS 服务器。

参数	默认值	说明
`dns_enabled`	`true`	是否启用 DNS 服务
`dns_port`	`53`	DNS 监听端口
`dns_records`	见下文	默认 DNS 记录列表

动态 DNS 注册

Pigsty 会自动为 PostgreSQL 集群和实例注册 DNS 记录：

实例级 DNS：<pg_instance> 指向实例 IP（如 pg-meta-1）
集群级 DNS：<pg_cluster> 指向主库 IP 或 VIP（如 pg-meta）

集群级 DNS 目标由 pg_dns_target 参数控制：

值	说明
`auto`	自动选择：有 VIP 用 VIP，否则用主库 IP
`primary`	始终指向主库 IP
`vip`	始终指向 VIP（需启用 VIP）
`none`	不注册集群 DNS
`<ip>`	指定固定 IP 地址

通过 pg_dns_suffix 可为集群 DNS 添加后缀。

节点 DNS 配置

Pigsty 管理被纳管节点的 DNS 配置。

静态 hosts 记录

通过 node_etc_hosts 配置静态 /etc/hosts 记录：

node_etc_hosts:
  - "${admin_ip} i.pigsty sss.pigsty"
  - "10.10.10.20 db.example.com"

DNS 服务器配置

参数	默认值	说明
`node_dns_method`	`add`	DNS 配置方式
`node_dns_servers`	`['${admin_ip}']`	DNS 服务器列表
`node_dns_options`	见下文	resolv.conf 选项

node_dns_method 可选值：

值	说明
`add`	添加到现有 DNS 服务器列表前面
`overwrite`	完全覆盖 DNS 服务器配置
`none`	不修改 DNS 配置

默认的 DNS 选项：

node_dns_options:
  - options single-request-reopen timeout:1

HTTPS 证书

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

忽略警告，使用 HTTP
信任自签名 CA 证书（下载地址 http://<ip>/ca.crt）
使用真实 CA 或通过 Certbot 获取免费公网域名证书

详见 CA 与证书文档。

扩展域名

Pigsty 扩展预留了以下域名用于各种应用服务：

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

使用这些域名需要在 infra_portal 中配置相应的服务。

管理命令

./infra.yml -t dns            # 完整配置 DNS 服务
./infra.yml -t dns_config     # 重新生成 dnsmasq 配置
./infra.yml -t dns_record     # 更新默认 DNS 记录
./infra.yml -t dns_launch     # 重启 dnsmasq 服务

./node.yml -t node_hosts      # 配置节点 /etc/hosts
./node.yml -t node_resolv     # 配置节点 DNS 解析器

./pgsql.yml -t pg_dns         # 注册 PostgreSQL DNS 记录
./pgsql.yml -t pg_dns_ins     # 仅注册实例级 DNS
./pgsql.yml -t pg_dns_cls     # 仅注册集群级 DNS

4 - 模块管理

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 插件

5 - CA 与证书

使用自签名 CA 或真实 HTTPS 证书

Pigsty 默认使用自签名证书颁发机构 (CA) 进行内部 SSL/TLS 加密。本文档包含：

自签名 CA：默认的 PKI 基础设施
签发证书：使用 cert.yml 签发额外证书
信任 CA 证书：在客户端机器上安装 CA
Let’s Encrypt：为公网服务使用真实证书

自签名 CA

Pigsty 在基础设施初始化 (infra.yml) 时自动创建自签名 CA。该 CA 用于签发以下证书：

PostgreSQL 服务器/客户端 SSL
Patroni REST API
etcd 集群通信
MinIO 集群通信
Nginx HTTPS（备用）
基础设施服务

PKI 目录结构

files/pki/
├── ca/
│   ├── ca.key                # CA 私钥（务必保管好！）
│   └── ca.crt                # CA 证书
├── csr/                      # 证书签名请求
├── misc/                     # 杂项证书（cert.yml 输出）
├── etcd/                     # ETCD 证书
├── pgsql/                    # PostgreSQL 证书
├── minio/                    # MinIO 证书
├── infra/                    # 基础设施证书
├── nginx/                    # Nginx 证书
└── mongo/                    # FerretDB 证书

CA 变量

变量	默认值	说明
`ca_create`	`true`	如果不存在则创建 CA，否则中止
`ca_cn`	`pigsty-ca`	CA 证书通用名称
`cert_validity`	`7300d`	签发证书的默认有效期

证书有效期

证书类型	有效期	控制参数
CA 证书	100 年	硬编码（36500 天）
服务器/客户端	20 年	`cert_validity`（7300d）
Nginx HTTPS	~1 年	`nginx_cert_validity`（397d）

注意：浏览器厂商限制超过 398 天的证书信任。Nginx 使用较短有效期以保证浏览器兼容性。

使用外部 CA

如需使用企业自有 CA 而非自动生成的 CA：

在配置中设置 ca_create: false

在运行 playbook 之前放置 CA 文件：

mkdir -p files/pki/ca
cp /path/to/your/ca.key files/pki/ca/ca.key
cp /path/to/your/ca.crt files/pki/ca/ca.crt
chmod 600 files/pki/ca/ca.key
chmod 644 files/pki/ca/ca.crt

运行 ./infra.yml

备份 CA 文件

CA 私钥至关重要，请安全备份：

# 带时间戳备份
tar -czvf pigsty-ca-$(date +%Y%m%d).tar.gz files/pki/ca/

警告：如果丢失 CA 私钥，由其签发的所有证书都将无法验证。您需要重新生成所有内容。

签发证书

使用 cert.yml 签发由 Pigsty CA 签名的额外证书。

基本用法

# 为数据库用户签发证书（客户端证书）
./cert.yml -e cn=dbuser_dba

# 为监控用户签发证书
./cert.yml -e cn=dbuser_monitor

默认情况下，证书生成在 files/pki/misc/<cn>.{key,crt}。

参数说明

参数	默认值	说明
`cn`	`pigsty`	通用名称（必填）
`san`	`[DNS:localhost, IP:127.0.0.1]`	主题备用名称
`org`	`pigsty`	组织名称
`unit`	`pigsty`	组织单位名称
`expire`	`7300d`	证书有效期（20 年）
`key`	`files/pki/misc/<cn>.key`	私钥输出路径
`crt`	`files/pki/misc/<cn>.crt`	证书输出路径

高级示例

# 签发带自定义 SAN（DNS 和 IP）的证书
./cert.yml -e cn=myservice \
  -e '{"san":["DNS:myservice.local","DNS:myservice","IP:10.10.10.10"]}'

# 签发自定义有效期（10 年）的证书
./cert.yml -e cn=shortlived -e expire=3650d

# 签发到自定义路径
./cert.yml -e cn=custom \
  -e key=/tmp/custom.key \
  -e crt=/tmp/custom.crt

# 签发带自定义组织的证书
./cert.yml -e cn=external \
  -e org="My Company" \
  -e unit="IT Department"

使用场景

PostgreSQL 客户端证书

用于 SSL 客户端认证（pg_hba.conf 中的 cert 认证方式）：

# 为 DBA 用户签发证书
./cert.yml -e cn=dbuser_dba

# 复制到客户端机器
scp files/pki/misc/dbuser_dba.{key,crt} user@client:~/.postgresql/
scp files/pki/ca/ca.crt user@client:~/.postgresql/root.crt

# 使用客户端证书连接
psql "host=pg-test port=5432 dbname=postgres user=dbuser_dba sslmode=verify-full sslcert=~/.postgresql/dbuser_dba.crt sslkey=~/.postgresql/dbuser_dba.key sslrootcert=~/.postgresql/root.crt"

服务间 TLS

用于需要双向 TLS 的内部服务：

./cert.yml -e cn=myapp -e '{"san":["DNS:myapp.service.local","IP:10.10.10.50"]}'

信任 CA 证书

在客户端机器上信任自签名 CA：

Linux (Debian/Ubuntu)

sudo cp files/pki/ca/ca.crt /usr/local/share/ca-certificates/pigsty-ca.crt
sudo update-ca-certificates

Linux (RHEL/Rocky/Alma)

sudo cp files/pki/ca/ca.crt /etc/pki/ca-trust/source/anchors/pigsty-ca.crt
sudo update-ca-trust

macOS

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain files/pki/ca/ca.crt

Windows

Import-Certificate -FilePath files\pki\ca\ca.crt -CertStoreLocation Cert:\LocalMachine\Root

从 Nginx 下载

CA 证书也可通过 Nginx 在 http://<infra_ip>/ca.crt 获取：

curl -o ca.crt http://10.10.10.10/ca.crt

Let’s Encrypt

对于公网服务，您可以通过 Certbot 使用 Let’s Encrypt 的真实证书。

前置条件

拥有公网域名
DNS 记录指向服务器的公网 IP
Nginx 已正确配置
80 和 443 端口可访问

第一步：域名配置

在 infra_portal 中配置服务域名：

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 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 命令

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

OpenSSL 命令

# 查看证书详情
openssl x509 -in files/pki/ca/ca.crt -text -noout

# 查看证书过期时间
openssl x509 -in files/pki/pgsql/pg-meta-1.crt -enddate -noout

# 验证证书是否由 CA 签发
openssl verify -CAfile files/pki/ca/ca.crt files/pki/pgsql/pg-meta-1.crt

# 检查证书链
openssl s_client -connect 10.10.10.10:5432 -starttls postgres </dev/null

故障排查

问题	解决方案
证书过期	重新运行 playbook 重新生成，或使用 `cert.yml`
CA 不被信任	在客户端安装 CA 证书（参见信任 CA 章节）
域名无法访问	验证 DNS 传播是否完成
端口 80 被阻止	确保 Let’s Encrypt 验证时端口 80 开放
请求频率限制	避免短时间内多次申请 Let’s Encrypt 证书
权限被拒绝	检查文件权限（密钥：0600，证书：0644）

最佳实践

备份 CA 密钥：将 files/pki/ca/ca.key 安全地离线存储
使用适当的有效期：nginx 用短期（浏览器兼容），内部服务用长期
轮换证书：定期重新运行 playbook 刷新证书
监控过期：设置证书过期告警
公网用 Let’s Encrypt：内部用自签名，公网服务用真实证书
记录配置：跟踪哪些服务使用哪些证书

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

使用 PostgreSQL 而不是 SQLite 作为 Grafana 后端使用的远程存储数据库，获取更好的性能与可用性。

您可以使用 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

定义集群

如果需要创建新的专用数据库集群pg-grafana，部署在10.10.10.11，10.10.10.12两台机器上，可以使用以下配置文件：

pg-grafana: 
  hosts: 
    10.10.10.11: {pg_seq: 1, pg_role: primary}
    10.10.10.12: {pg_seq: 2, pg_role: replica}
  vars:
    pg_cluster: pg-grafana
    pg_databases:
      - name: grafana
        owner: dbuser_grafana
        revokeconn: true
        comment: grafana primary database
    pg_users:
      - name: dbuser_grafana
        password: DBUser.Grafana
        pgbouncer: true
        roles: [dbrole_admin]
        comment: admin user for grafana database

创建集群

使用以下命令完成数据库集群pg-grafana的创建：pgsql.yml。

./pgsql.yml -l pg-grafana    # 初始化pg-grafana集群

该命令是 Ansible Playbook pgsql.yml，用于创建数据库集群。

定义在 pg_users 与 pg_databases 中的业务用户与业务数据库会在集群初始化时自动创建，因此使用该配置时，集群创建完毕后，（在没有DNS支持的情况下）您可以使用以下连接串访问数据库（任一即可）：

postgres://dbuser_grafana:DBUser.Grafana@10.10.10.11:5432/grafana # 主库直连
postgres://dbuser_grafana:DBUser.Grafana@10.10.10.11:5436/grafana # 直连default服务
postgres://dbuser_grafana:DBUser.Grafana@10.10.10.11:5433/grafana # 连接串读写服务

postgres://dbuser_grafana:DBUser.Grafana@10.10.10.12:5432/grafana # 主库直连
postgres://dbuser_grafana:DBUser.Grafana@10.10.10.12:5436/grafana # 直连default服务
postgres://dbuser_grafana:DBUser.Grafana@10.10.10.12:5433/grafana # 连接串读写服务

因为默认情况下Pigsty安装在单个元节点上，接下来的步骤我们会在已有的pg-meta数据库集群上创建Grafana所需的用户与数据库，而并非使用这里创建的pg-grafana集群。

创建Grafana业务用户

通常业务对象管理的惯例是：先创建用户，再创建数据库。因为如果为数据库配置了owner，数据库对相应的用户存在依赖。

定义用户

要在pg-meta集群上创建用户dbuser_grafana，首先将以下用户定义添加至pg-meta的集群定义中：

添加位置：all.children.pg-meta.vars.pg_users

- name: dbuser_grafana
  password: DBUser.Grafana
  comment: admin user for grafana database
  pgbouncer: true
  roles: [ dbrole_admin ]

如果您在这里定义了不同的密码，请在后续步骤中将相应参数替换为新密码

创建用户

使用以下命令完成dbuser_grafana用户的创建（任一均可）。

bin/pgsql-user pg-meta dbuser_grafana # 在pg-meta集群上创建`dbuser_grafana`用户

实际上调用了 Ansible Playbook pgsql-user.yml 创建用户

./pgsql-user.yml -l pg-meta -e pg_user=dbuser_grafana  # Ansible

dbrole_admin 角色具有在数据库中执行DDL变更的权限，这正是Grafana所需要的。

创建Grafana业务数据库

定义数据库

创建业务数据库的方式与业务用户一致，首先在pg-meta的集群定义中添加新数据库grafana的定义。

添加位置：all.children.pg-meta.vars.pg_databases

- { name: grafana, owner: dbuser_grafana, revokeconn: true }

创建数据库

使用以下命令完成grafana数据库的创建（任一均可）。

bin/pgsql-db pg-meta grafana # 在`pg-meta`集群上创建`grafana`数据库

实际上调用了 Ansible Playbook pgsql-db.yml 创建数据库

./pgsql-db.yml -l pg-meta -e pg_database=grafana # 实际执行的Ansible剧本

使用Grafana业务数据库

检查连接串可达性

您可以使用不同的服务或接入方式访问数据库，例如：

postgres://dbuser_grafana:DBUser.Grafana@meta:5432/grafana # 直连
postgres://dbuser_grafana:DBUser.Grafana@meta:5436/grafana # default服务
postgres://dbuser_grafana:DBUser.Grafana@meta:5433/grafana # primary服务

这里，我们将使用通过负载均衡器直接访问主库的 Default服务访问数据库。

首先检查连接串是否可达，以及是否有权限执行DDL命令。

psql postgres://dbuser_grafana:DBUser.Grafana@meta:5436/grafana -c \
  'CREATE TABLE t(); DROP TABLE t;'

直接修改Grafana配置

为了让Grafana使用 Postgres 数据源，您需要编辑 /etc/grafana/grafana.ini，并修改配置项：

[database]
;type = sqlite3
;host = 127.0.0.1:3306
;name = grafana
;user = root
# If the password contains # or ; you have to wrap it with triple quotes. Ex """#password;"""
;password =
;url =

将默认的配置项修改为：

[database]
type = postgres
url =  postgres://dbuser_grafana:DBUser.Grafana@meta/grafana

随后重启Grafana即可：

systemctl restart grafana-server

从监控系统中看到新增的 grafana 数据库已经开始有活动，则说明Grafana已经开始使用Postgres作为首要后端数据库了。但一个新的问题是，Grafana中原有的Dashboards与Datasources都消失了！这里需要重新导入监控面板与Postgres数据源

管理Grafana监控面板

您可以使用管理用户前往 Pigsty 目录下的 files/grafana 目录，执行 grafana.py init 重新加载 Pigsty 监控面板。

cd ~/pigsty/files/grafana
./grafana.py init    # 使用当前目录下的Dashboards初始化Grafana监控面板

执行结果：

vagrant@meta:~/pigsty/files/grafana
$ ./grafana.py init
Grafana API: admin:pigsty @ http://10.10.10.10:3000
init dashboard : home.json
init folder pgcat
init dashboard: pgcat / pgcat-table.json
init dashboard: pgcat / pgcat-bloat.json
init dashboard: pgcat / pgcat-query.json
init folder pgsql
init dashboard: pgsql / pgsql-replication.json
init dashboard: pgsql / pgsql-table.json
init dashboard: pgsql / pgsql-activity.json
init dashboard: pgsql / pgsql-cluster.json
init dashboard: pgsql / pgsql-node.json
init dashboard: pgsql / pgsql-database.json
init dashboard: pgsql / pgsql-xacts.json
init dashboard: pgsql / pgsql-overview.json
init dashboard: pgsql / pgsql-session.json
init dashboard: pgsql / pgsql-tables.json
init dashboard: pgsql / pgsql-instance.json
init dashboard: pgsql / pgsql-queries.json
init dashboard: pgsql / pgsql-alert.json
init dashboard: pgsql / pgsql-service.json
init dashboard: pgsql / pgsql-persist.json
init dashboard: pgsql / pgsql-proxy.json
init dashboard: pgsql / pgsql-query.json
init folder pglog
init dashboard: pglog / pglog-instance.json
init dashboard: pglog / pglog-analysis.json
init dashboard: pglog / pglog-session.json

该脚本会侦测当前的环境（安装时定义于~/pigsty），获取Grafana的访问信息，并将监控面板中的URL连接占位符域名（*.pigsty）替换为真实使用的域名。

export GRAFANA_ENDPOINT=http://10.10.10.10:3000
export GRAFANA_USERNAME=admin
export GRAFANA_PASSWORD=pigsty

export NGINX_UPSTREAM_YUMREPO=yum.pigsty
export NGINX_UPSTREAM_CONSUL=c.pigsty
export NGINX_UPSTREAM_PROMETHEUS=p.pigsty
export NGINX_UPSTREAM_ALERTMANAGER=a.pigsty
export NGINX_UPSTREAM_GRAFANA=g.pigsty
export NGINX_UPSTREAM_HAPROXY=h.pigsty

题外话，使用grafana.py clean会清空目标监控面板，使用grafana.py load会加载当前目录下所有监控面板，当Pigsty的监控面板发生变更，可以使用这两个命令升级所有的监控面板。

管理Postgres数据源

当使用 pgsql.yml 创建新 PostgreSQL 集群，或使用 pgsql-db.yml 创建新业务数据库时，Pigsty会在Grafana中注册新的PostgreSQL数据源，您可以使用默认的监控用户通过Grafana直接访问目标数据库实例。应用pgcat的绝大部分功能有赖于此。

要注册 Postgres 数据库，可以使用 pgsql.yml 中的 register_grafana 任务：

./pgsql.yml -t register_grafana             # 重新注册当前环境中所有Postgres数据源
./pgsql.yml -t register_grafana -l pg-test  # 重新注册 pg-test 集群中所有的数据库

一步到位更新Grafana

您可以直接通过修改 Pigsty 配置文件，更改 Grafana 使用的后端数据源，一步到位的完成切换 Grafana 后端数据库的工作。编辑 pigsty.yml 中 grafana_pgurl 参数，将其修改为：

grafana_pgurl: postgres://dbuser_grafana:DBUser.Grafana@meta:5436/grafana

然后重新执行 infra.yml 中的 grafana 任务，即可完成 Grafana 升级

./infra.yml -t grafana

管理预案

1 - Nginx 管理

基础配置

服务器参数

基本参数

SSL/TLS 选项

高级设置

配置示例

反向代理服务

静态文件与目录列表

自定义 SSL 证书

使用 Let’s Encrypt 证书

强制 HTTPS 跳转

自定义配置片段

管理命令

域名解析

HTTPS 配置

Certbot 证书

启用 Certbot

手动签发证书

默认首页

最佳实践

完整示例

2 - 软件仓库

快速开始

软件包别名

EL 系统（RHEL/CentOS/Rocky）

Debian/Ubuntu 系统

剧本任务

主要任务

完整任务列表

常用操作

添加新软件包

刷新节点仓库

完整重建仓库

3 - 域名管理

快速开始

为什么使用域名

DNS 机制

默认域名

解析方式

本地静态解析

内网动态解析

公网域名

内置 DNS 服务

相关参数

动态 DNS 注册

节点 DNS 配置

静态 hosts 记录

DNS 服务器配置

HTTPS 证书

扩展域名

管理命令

4 - 模块管理

安装 Infra 模块

卸载 Infra 模块

扩容 Infra 模块

管理本地软件仓库

管理 Nginx

管理基础设施组件

5 - CA 与证书

自签名 CA

PKI 目录结构

CA 变量

证书有效期

使用外部 CA

备份 CA 文件

签发证书

基本用法

参数说明

高级示例

使用场景

信任 CA 证书

Linux (Debian/Ubuntu)

Linux (RHEL/Rocky/Alma)

macOS

Windows

从 Nginx 下载

Let’s Encrypt

前置条件