模块：INFRA

• 1: 集群配置
• 2: 参数列表
• 3: 预置剧本
• 4: 监控告警
• 5: 指标列表
• 6: 常见问题
• 7: 管理预案
  • 7.1: Nginx 管理
  • 7.2: 软件仓库
  • 7.3: 域名管理
  • 7.4: 模块管理
  • 7.5: CA 与证书
  • 7.6: Grafana 高可用部署：使用 PostgreSQL 后端数据库

infra_portal:  # domain names and upstream servers
  home         : { domain: i.pigsty }
  grafana      : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" , websocket: true }
  vmetrics     : { domain: p.pigsty ,endpoint: "${admin_ip}:8428" }   # VMUI
  alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9059" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  vmalert      : { endpoint: "${admin_ip}:8880" }
  #logs         : { domain: logs.pigsty ,endpoint: "${admin_ip}:9428" }
  #minio        : { domain: m.pigsty    ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }

curl -L http://i.pigsty/pigsty.repo -o /etc/yum.repos.d/pigsty.repo

[pigsty-local]
name=Pigsty local $releasever - $basearch
baseurl=file:///www/pigsty/
enabled=1
gpgcheck=0

# 配置单个 INFRA 节点
infra: { hosts: { 10.10.10.10: { infra_seq: 1 } }}

# 配置两个 INFRA 节点
infra:
  hosts:
    10.10.10.10: { infra_seq: 1 }
    10.10.10.11: { infra_seq: 2 }

./infra.yml     # 在 infra 分组上安装 INFRA 模块
./infra-rm.yml  # 全量移除 INFRA（包括数据与软件包）

./infra.yml -t repo              #从互联网或离线包中创建本地软件源

./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     # 处理 /etc/yum.repos.d 中的上游仓库文件
./infra.yml     -t repo_remove       # 如果 repo_remove == true，则删除现有的仓库文件
./infra.yml     -t repo_add          # 将上游仓库文件添加到 /etc/yum.repos.d （或 /etc/apt/sources.list.d）
./infra.yml     -t repo_url_pkg      # 从由 repo_url_packages 定义的互联网下载包
./infra.yml     -t repo_cache        # 使用 yum makecache / apt update 创建上游软件源元数据缓存
./infra.yml     -t repo_boot_pkg     # 安装 SOW，以及 dnf/yum 下载工具
./infra.yml     -t repo_pkg          # 从上游仓库下载包 & 依赖项
./infra.yml     -t repo_create       # 使用 sow create --pigsty 原子创建 RPM/APT 元数据
./infra.yml     -t repo_use          # 将新建的仓库添加到 /etc/yum.repos.d | /etc/apt/sources.list.d 用起来
./infra.yml -t repo_nginx        # 如果没有 nginx 在服务，启动一个 nginx 作为 Web Server

./infra.yml     -t repo_upstream     # 向 INFRA 节点添加 repo_upstream 中定义的上游软件源
./infra.yml     -t repo_pkg          # 从上游仓库下载包及其依赖项。
./infra.yml     -t repo_create       # 使用 SOW 创建/更新本地 RPM/APT 仓库元数据

./infra.yml -t infra           # 配置基础设施
./infra.yml -t infra_user      # 设置 infra 操作系统用户组
./infra.yml -t infra_dir       # 创建基础设施数据、配置与运行目录
./infra.yml -t infra_env       # 配置管理节点环境：env_patroni, env_pg, env_pgadmin, env_etcd, env_pglog, env_var
./infra.yml -t infra_pkg       # 安装 INFRA 所需的软件包：infra_packages
./infra.yml -t infra_cert      # 为 infra 组件颁发证书
./infra.yml -t dns             # 配置 DNSMasq：dns_config, dns_record, dns_launch
./infra.yml -t nginx           # 配置 Nginx：nginx_config, nginx_cert, nginx_static, nginx_launch, nginx_certbot, nginx_reload, nginx_exporter
./infra.yml -t victoria        # 配置 VictoriaMetrics/Logs/Traces：vmetrics|vlogs|vtraces|vmalert
./infra.yml -t alertmanager    # 配置 AlertManager：alertmanager_config, alertmanager_launch
./infra.yml -t blackbox        # 配置 Blackbox Exporter：blackbox_config, blackbox_launch
./infra.yml -t grafana         # 配置 Grafana：grafana_clean, grafana_config, grafana_launch, grafana_provision
./infra.yml -t infra_register  # 将 infra 组件注册到 VictoriaMetrics / Grafana

./infra.yml -t nginx_index                        # 重新渲染 Nginx 首页内容
./infra.yml -t nginx_config,nginx_reload          # 重新渲染 Nginx 网站门户配置，对外暴露新的上游服务。
./infra.yml -t vmetrics_config,vmetrics_launch    # 重新生成 VictoriaMetrics 主配置文件，并重启服务
./infra.yml -t vlogs_config,vlogs_launch          # 重新渲染 VictoriaLogs 配置
./infra.yml -t vmetrics_clean                     # 清理 VictoriaMetrics 存储数据目录
./infra.yml -t grafana_provision                  # 重新加载 Grafana 仪表盘与数据源定义

./infra-rm.yml               # 全量移除：注销、停服、删配置/环境/数据并卸载软件包
./infra-rm.yml -t deregister # 仅注销监控目标、数据源与日志采集
./infra-rm.yml -t service    # 停止 INFRA 上的基础设施服务
./infra-rm.yml -t data       # 移除 INFRA 数据
./infra-rm.yml -t package    # 卸载软件包

1 - 集群配置

配置说明

INFRA 主要用于提供 监控 基础设施，对于 PostgreSQL 数据库是 可选项。

除非手工配置了对 INFRA 节点上 DNS/NTP 服务的依赖，否则 INFRA 模块故障通常不影响 PostgreSQL 数据库集群运行。

单个 INFRA 节点足以应对绝大部分场景。生产环境建议使用 2～3 个 INFRA 节点实现高可用。

通常出于提高资源利用率的考虑，PostgreSQL 高可用依赖的 ETCD 模块可以与 INFRA 模块共用节点。

使用 3 个以上的 INFRA 节点意义不大，但可以使用更多 ETCD 节点（如 5 个）提高 DCS 服务可用性。

配置样例

在配置清单中的 infra 分组加入节点 IP，并分配 Infra 实例号 infra_seq。

默认单个 INFRA 节点配置：

all:
  children:
    infra: { hosts: { 10.10.10.10: { infra_seq: 1 } }}

默认情况下，10.10.10.10 占位符在配置过程中被替换为当前节点首要 IP 地址。

使用 infra.yml 剧本在节点上初始化 INFRA 模块。

更多节点

两个 INFRA 节点配置：

all:
  children:
    infra:
      hosts:
        10.10.10.10: { infra_seq: 1 }
        10.10.10.11: { infra_seq: 2 }

三个 INFRA 节点配置（含参数）：

all:
  children:
    infra:
      hosts:
        10.10.10.10: { infra_seq: 1 }
        10.10.10.11: { infra_seq: 2, repo_enabled: false }
        10.10.10.12: { infra_seq: 3, repo_enabled: false }
      vars:
        grafana_clean: false
        vmetrics_clean: false
        vlogs_clean: false
        vtraces_clean: false

Infra 高可用

Infra 模块中的大部分组件都属于"无状态/相同状态"，对于这类组件，高可用只需要操心"负载均衡"问题。

高可用可通过 Keepalived L2 VIP 或 HAProxy 四层负载均衡实现。二层互通网络推荐使用 Keepalived L2 VIP。

配置示例：

infra:
  hosts:
    10.10.10.10: { infra_seq: 1 }
    10.10.10.11: { infra_seq: 2 }
    10.10.10.12: { infra_seq: 3 }
  vars:
    vip_enabled: true
    vip_vrid: 128
    vip_address: 10.10.10.8
    vip_interface: eth1

    infra_portal:
      home         : { domain: i.pigsty }
      grafana      : { domain: g.pigsty ,endpoint: "10.10.10.8:3000" , websocket: true }
      vmetrics     : { domain: p.pigsty ,endpoint: "10.10.10.8:8428" }
      alertmanager : { domain: a.pigsty ,endpoint: "10.10.10.8:9059" }
      blackbox     : { endpoint: "10.10.10.8:9115" }
      vmalert      : { endpoint: "10.10.10.8:8880" }

需要设置 VIP 相关参数并在 infra_portal 中修改各 Infra 服务端点。

Nginx配置

请参阅 Nginx 参数配置 与 Nginx 管理。

本地仓库配置

请参阅 Repo 参数配置。

DNS配置

请参阅 DNS 参数配置 与 教程：DNS。

NTP配置

请参阅 NTP 参数配置。

2 - 参数列表

INFRA 模块负责配置 Pigsty 的基础设施组件：本地软件源、Nginx、DNSMasq、VictoriaMetrics、VictoriaLogs、Grafana、Alertmanager、Blackbox Exporter 等监控告警基础设施。

Pigsty v4.x 使用 VictoriaMetrics 替代 Prometheus，使用 VictoriaLogs 替代 Loki，实现了更优秀的可观测性方案。

参数概览

META 参数组用于定义 Pigsty 的元信息，包括版本号、管理节点 IP、软件源区域、默认语言以及代理设置。

CA 参数组用于配置 Pigsty 自签名 CA 证书管理，包括是否创建 CA、CA 名称以及证书有效期。

INFRA_ID 参数组用于定义基础设施节点的身份标识，包括节点序号、服务门户配置以及数据目录。

REPO 参数组用于配置本地软件仓库，包括仓库启用开关、目录路径、上游源定义以及要下载的软件包列表。

INFRA_PACKAGE 参数组用于定义在基础设施节点上安装的软件包（RPM/DEB）。

NGINX 参数组用于配置 Nginx Web 服务器与反向代理，包括启用开关、端口、SSL 模式、证书以及基础认证。

DNS 参数组用于配置 DNSMasq 域名解析服务，包括启用开关、监听端口以及动态 DNS 记录。

VICTORIA 参数组用于配置 VictoriaMetrics/Logs/Traces 可观测性套件，包括启用开关、端口、数据保留策略等。

PROMETHEUS 参数组用于配置 Alertmanager 与 Blackbox Exporter，提供告警管理和网络探测功能。

GRAFANA 参数组用于配置 Grafana 可视化平台，包括启用开关、端口、管理员凭据以及数据源配置。

META

这一小节指定了一套 Pigsty 部署的元数据：包括版本号，管理员节点 IP 地址，软件源镜像上游 区域，默认语言，以及下载软件包时使用的 http(s) 代理。

version: v4.5.0                   # pigsty 版本号
admin_ip: 10.10.10.10             # 管理节点IP地址
region: default                   # 上游镜像区域：default,china,europe
language: en                      # 默认语言: en 或 zh
proxy_env:                        # 全局HTTPS代理，用于下载、安装软件包。
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
  # http_proxy:  # set your proxy here: e.g http://user:pass@proxy.xxx.com
  # https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
  # all_proxy:   # set your proxy here: e.g http://user:pass@proxy.xxx.com

version

参数名称： version， 类型： string， 层次：G

Pigsty 版本号字符串，当前源码默认值为：v4.5.0。

Pigsty 内部会使用版本号进行功能控制与内容渲染，请勿随意修改此参数。

Pigsty 使用语义化版本号，版本号字符串通常以字符 v 开头，例如 v4.5.0。

admin_ip

参数名称： admin_ip， 类型： ip， 层次：G

管理节点的 IP 地址，默认为占位符 IP 地址：10.10.10.10

由该参数指定的节点将被视为管理节点，通常指向安装 Pigsty 时的第一个节点，即中控节点。

默认值 10.10.10.10 是一个占位符，会在 configure 过程中被替换为实际的管理节点 IP 地址。

许多参数都会引用此参数，例如：

• infra_portal
• repo_endpoint
• repo_upstream
• dns_records
• node_default_etc_hosts
• node_etc_hosts

在这些参数中，字符串 ${admin_ip} 会被替换为 admin_ip 的真实取值。使用这种机制，您可以为不同的节点指定不同的中控管理节点。

region

参数名称： region， 类型： enum， 层次：G

上游镜像的区域，默认可选值为：default、 china、 europe，默认为： default

如果一个不同于 default 的区域被设置，且在 repo_upstream 中有对应的条目，将会使用该条目对应 baseurl 代替 default 中的 baseurl。

例如，如果您的区域被设置为 china，那么 Pigsty 会尝试使用中国地区的上游软件镜像站点以加速下载，如果某个上游软件仓库没有对应的中国地区镜像，那么会使用默认的上游镜像站点替代。 同时，在 repo_url_packages 中定义的 URL 地址，也会进行从 repo.pigsty.io 到 repo.pigsty.cc 的替换，以使用国内的镜像源。

language

参数名称： language， 类型： enum， 层次：G

默认语言设置，可选值为 en（英文） 或 zh（中文），默认为 en。

此参数会影响 Pigsty 生成的部分配置与内容的语言偏好，例如 Grafana 面板的初始语言设置等。

如果您是中国用户，建议将此参数设置为 zh，以获得更好的中文支持体验。

proxy_env

参数名称： proxy_env， 类型： dict， 层次：G

下载包时使用的全局代理环境变量，默认值指定了 no_proxy，即不使用代理的地址列表：

proxy_env:
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
  #http_proxy: 'http://username:password@proxy.address.com'
  #https_proxy: 'http://username:password@proxy.address.com'
  #all_proxy: 'http://username:password@proxy.address.com'

当您在中国大陆地区从互联网上游安装时，特定的软件包可能会被墙，您可以使用代理来解决这个问题。

请注意，如果使用了 Docker 模块，那么这里的代理服务器配置也会写入 Docker Daemon 配置文件中。

请注意，如果在 ./configure 过程中指定了 -x 参数，那么当前环境中的代理配置信息将会被自动填入到生成的 pigsty.yaml 文件中。

CA

Pigsty 使用自签名 CA 证书，用于支持高级安全特性，例如 HTTPS 访问、PostgreSQL SSL 连接等。

ca_create: true                   # CA 私钥缺失时是否允许创建？默认为 true
ca_cn: pigsty-ca                  # CA CN名称，固定为 pigsty-ca
cert_validity: 7300d              # 证书有效期，默认为 20 年

ca_create

参数名称： ca_create， 类型： bool， 层次：G

如果 CA 私钥不存在，是否允许创建？默认值为 true。

当设置为 true 时，如果 files/pki/ca/ca.key 不存在，Pigsty 将自动创建新的 CA 私钥；如果 ca.crt 不存在，则使用现有或新建的私钥签发 CA 证书。

如果您已经有了一对 CA 公私钥对，可以将其复制到 files/pki/ca 目录下：

• files/pki/ca/ca.crt：CA 公钥证书
• files/pki/ca/ca.key：CA 私钥文件

Pigsty 将复用现有的 CA 公私钥对。如果私钥不存在且此参数设置为 false，则会报错终止；仅缺少 ca.crt 时仍会用现有私钥重新签发证书。因此，请始终把匹配的 ca.key 与 ca.crt 成对备份和恢复，避免出现证书与私钥不匹配的状态。

请务必保留并备份好部署过程中新生成的 CA 私钥文件，这对于后续签发新证书至关重要。

ca_cn

参数名称： ca_cn， 类型： string， 层次：G

CA CN（Common Name）名称，固定为 pigsty-ca，不建议修改。

你可以使用以下命令来查看节点上的 Pigsty CA 证书详情：

openssl x509 -text -in /etc/pki/ca.crt

cert_validity

参数名称： cert_validity， 类型： interval， 层次：G

签发证书的有效期，默认为 20 年，对绝大多数场景都足够了。默认值为： 7300d

此参数影响由 Pigsty CA 签发的所有证书的有效期，包括：

• PostgreSQL 服务器证书
• Patroni API 证书
• etcd 服务器/客户端证书
• 其他内部服务证书

注意：Nginx 使用的 HTTPS 证书有效期由 nginx_cert_validity 单独控制，因为现代浏览器对网站证书有效期有更严格的要求（最长 397 天）。

INFRA_ID

基础设施身份标识与门户定义。

#infra_seq: 1                     # 基础设施节点序号，必选身份参数
infra_portal:                     # 通过 Nginx 门户暴露的基础设施服务
  home : { domain: i.pigsty }     # 默认首页服务器定义
infra_data: /data/infra           # 基础设施默认数据目录
infra_services: [...]             # 首页内置导航入口
infra_extra_services: []          # 追加到首页的导航入口

infra_seq

参数名称： infra_seq， 类型： int， 层次：I

基础设施节点序号，必选身份参数，必须在基础设施节点上显式指定，所以不提供默认值。

此参数用于在多个基础设施节点的部署中唯一标识每个节点，通常使用从 1 开始的正整数。

示例配置：

infra:
  hosts:
    10.10.10.10: { infra_seq: 1 }
    10.10.10.11: { infra_seq: 2 }

infra_portal

参数名称： infra_portal， 类型： dict， 层次：G

通过 Nginx 门户暴露的基础设施服务列表。v4.x 的默认值非常简洁：

infra_portal:
  home : { domain: i.pigsty }     # 默认首页服务器定义

Pigsty 会根据实际启用的组件自动配置相应的反向代理，用户通常只需要定义首页域名即可。

每条记录由一个 Key 与一个 Value 字典组成，name 作为键，代表组件名称，value 是一个可以配置以下参数的对象：

• name: 必填，指定 Nginx 服务器的名称
  • 默认记录：home 是固定名称，请不要修改。
  • 作为 Nginx 配置文件名称的一部分，对应配置文件：/etc/nginx/conf.d/<name>.conf
  • 没有 domain 字段的 Nginx 服务器不会生成配置文件，但会被用作引用。
• domain: 可选，当服务需要通过 Nginx 对外暴露时为 必填 字段，指定使用的域名
  • 在 Pigsty 自签名 Nginx HTTPS 证书中，域名将被添加到 Nginx SSL 证书的 SAN 字段
  • Pigsty 网页交叉引用将使用这里的默认域名
• endpoint：通常作为 path 的替代，指定上游服务器地址。设置 endpoint 表示这是一个反向代理服务器
  • 配置中可以使用 ${admin_ip} 作为占位符，在部署时会被动态替换为 admin_ip
  • 默认反向代理服务器使用 endpoint.conf 作为配置模板
  • 反向代理服务器还可以配置 websocket 和 scheme 参数
• path：通常作为 endpoint 的替代，指定本地文件服务器路径。设置 path 表示这是一个本地 Web 服务器
  • 本地 Web 服务器使用 path.conf 作为配置模板
  • 本地 Web 服务器还可以配置 index 参数，是否启用文件索引页
• certbot：Certbot 证书名称，如果配置，将使用 Certbot 申请证书
  • 如果多个服务器指定相同的 certbot，Pigsty 会合并证书申请，最终证书名称为此 certbot 的值
• cert：证书文件路径，如果配置，将覆盖默认证书路径
• key：证书密钥文件路径，如果配置，将覆盖默认证书密钥路径
• websocket：是否启用 WebSocket 支持
  • 只有反向代理服务器可以配置此参数，如果启用将允许上游使用 WebSocket 连接
• scheme：上游服务器使用的协议，如果配置，将覆盖默认协议
  • 默认为 http，如果配置为 https 将强制使用 HTTPS 连接到上游服务器
• index：是否启用文件索引页
  • 只有本地 Web 服务器可以配置此参数，如果启用将启用 autoindex 配置自动生成目录索引页
• log：Nginx 日志文件路径
  • 如果指定，访问日志将写入此文件，否则根据服务器类型使用默认日志文件
  • 反向代理服务器使用 /var/log/nginx/<name>.log 作为默认日志文件路径
  • 本地 Web 服务器使用默认 Access 日志
• conf：Nginx 配置文件路径
  • 显式指定使用的配置模板文件，位于 roles/infra/templates/nginx 或 templates/nginx 目录
  • 如果未指定此参数，将使用默认配置模板
• config：Nginx 配置代码块
  • 直接注入到 Nginx Server 配置块中的配置文本
• enforce_https：将 HTTP 重定向到 HTTPS
  • 可以通过 nginx_sslmode: enforce 指定全局配置
  • 此配置不影响默认的 home 服务器，它将始终同时监听 80 和 443 端口以确保兼容性

infra_data

参数名称： infra_data， 类型： path， 层次：G

基础设施数据目录，默认值为 /data/infra。

此目录用于存放基础设施组件的数据文件，包括：

• VictoriaMetrics 时序数据库数据
• VictoriaLogs 日志数据
• VictoriaTraces 追踪数据
• 其他基础设施组件的持久化数据

建议将此目录放置在独立的数据盘上，以便于管理和扩展。

infra_services

参数名称：infra_services，类型：service[]，层次：G

Pigsty 首页的内置导航入口列表。当前默认入口包括 Metrics、Logs、Traces、Monitor Targets、Alert Rules、Alert Manager、CA Certificate、Software Repo 与 Explain Visualizer。

每项可使用 name、url、desc、icon 以及对应中文字段 name_cn、desc_cn 定义显示内容。此参数会整体覆盖默认列表；只想增加入口时应优先使用 infra_extra_services。

infra_extra_services

参数名称：infra_extra_services，类型：service[]，层次：G

追加到 infra_services 后的首页导航入口列表，默认值为 []。其项目结构与 infra_services 相同，例如：

infra_extra_services:
  - { name: My Service, url: 'https://example.com', desc: 'External Service', icon: 'database' }

REPO

本节配置是关于本地软件仓库的。 Pigsty 默认会在基础设施节点上启用一个本地软件仓库（APT / YUM）。

在初始化过程中，Pigsty 会从互联网上游仓库（由 repo_upstream 指定）下载所有软件包及其依赖项（由 repo_packages 指定）到 {{ nginx_home }} / {{ repo_name }} （默认为 /www/pigsty），所有软件及其依赖的总大小约为 1GB 左右。

当前候选软件包版本为 SOW 0.3.0，源码使用 SOW 统一生成 RPM/APT 元数据。创建成功后，仓库目录中的 repo_complete 同时是 SHA-256 校验清单与完成标记；检测到该文件时，Pigsty 默认跳过下载和重建，直接使用已有仓库。强制重建需要执行 ./infra.yml -t repo_build -e repo_build=true。

repo_create 与 cache_create 都直接调用 sow create --pigsty，不再回退到 createrepo_c 或 dpkg-scanpackages。旧离线包或旧本地仓库若不含 SOW，必须先刷新介质或从 Pigsty INFRA 仓库安装 SOW。

如果某些软件包的下载速度太慢，您可以通过使用 proxy_env 配置项来设置下载代理来完成首次下载，或直接下载预打包的 离线软件包，离线软件包本质上就是在同样操作系统上构建好的本地软件源。

repo_enabled: true                # 在此 Infra 节点上创建本地软件仓库？
repo_home: /www                   # 软件仓库主目录，默认为 /www
repo_name: pigsty                 # 软件仓库名称，默认为 pigsty
repo_endpoint: http://${admin_ip}:80 # 仓库访问端点
repo_remove: true                 # 移除现有上游仓库定义
repo_modules: infra,node,pgsql    # 启用的上游仓库模块
#repo_upstream: []                # 上游仓库定义（从操作系统变量继承）
#repo_packages: []                # 要下载的软件包（从操作系统变量继承）
#repo_extra_packages: []          # 额外要下载的软件包
repo_url_packages: []             # 通过 URL 下载的额外软件包

repo_enabled

参数名称： repo_enabled， 类型： bool， 层次：G/I

是否在当前的基础设施节点上启用本地软件源？默认为： true，即所有 Infra 节点都会设置一个本地软件仓库。

如果您有多个基础设施节点，可以只保留 1～2 个节点作为软件仓库，其他节点可以通过设置此参数为 false 来避免重复软件下载构建。

repo_home

参数名称： repo_home， 类型： path， 层次：G

本地软件仓库的家目录，默认为 Nginx 的根目录，也就是： /www。

全新安装且该路径不存在时，角色会创建指向 nginx_data 的软链接；已经存在的目录或软链接会原样保留。通常不建议修改此目录；如需修改，应与 nginx_home 保持一致。

repo_name

参数名称： repo_name， 类型： string， 层次：G

本地仓库名称，默认为 pigsty，更改此仓库的名称是不明智的行为。

最终的仓库路径为 {{ repo_home }}/{{ repo_name }}，默认为 /www/pigsty。

repo_endpoint

参数名称： repo_endpoint， 类型： url， 层次：G

其他节点访问此仓库时使用的端点，默认值为：http://${admin_ip}:80。

Pigsty 默认会在基础设施节点 80/443 端口启动 Nginx，对外提供本地软件源（静态文件）服务。

如果您修改了 nginx_port 与 nginx_ssl_port，或者使用了不同于中控节点的基础设施节点，请相应调整此参数。

如果您使用了域名，可以在 node_default_etc_hosts、node_etc_hosts、或者 dns_records 中添加解析。

repo_remove

参数名称： repo_remove， 类型： bool， 层次：G/A

在构建本地软件源时，是否移除现有的上游仓库定义？默认值： true。

当启用此参数时，/etc/yum.repos.d 中所有已有仓库文件会被移动备份至 /etc/yum.repos.d/backup，在 Debian 系上是移除 /etc/apt/sources.list 和 /etc/apt/sources.list.d，将文件备份至 /etc/apt/backup 中。

因为操作系统已有的源内容不可控，使用 Pigsty 验证过的上游软件源可以提高从互联网下载软件包的成功率与速度。

但在一些特定情况下（例如您的操作系统是某种 EL/Deb 兼容版，许多软件包使用了自己的私有源），您可能需要保留现有的上游仓库定义，此时可以将此参数设置为 false。

repo_modules

参数名称： repo_modules， 类型： string， 层次：G/A

哪些上游仓库模块会被添加到本地软件源中，默认值： infra,node,pgsql

当 Pigsty 尝试添加上游仓库时，会根据此参数的值来过滤 repo_upstream 中的条目，只有 module 字段与此参数值匹配的条目才会被添加到本地软件源中。

构建阶段会自动把 infra 加入实际模块列表，以确保可以安装 SOW；即使用户覆盖 repo_modules 时漏写 infra，该引导依赖仍会被补齐。

模块以逗号分隔，可用的模块列表请参考 repo_upstream 中的定义，常见模块包括：

• local：本地 Pigsty 仓库
• infra：基础设施软件包（Nginx、Docker 等）
• node：操作系统基础软件包
• pgsql：PostgreSQL 相关软件包
• extra：额外的 PostgreSQL 扩展
• docker：Docker 相关
• redis：Redis 相关
• mongo：MongoDB 相关
• mysql：MySQL 相关
• 等等…

repo_upstream

参数名称： repo_upstream， 类型： upstream[]， 层次：G

构建本地软件源时，从哪里下载上游软件包？本参数没有默认值，如果用户不在配置文件中显式指定，则会从根据当前节点的操作系统族，从定义于 roles/node_id/vars 中的 repo_upstream_default 变量中加载获取。

Pigsty 为当前支持的操作系统版本（EL 8/9/10、Debian 12/13、Ubuntu 22/24/26）预置了完整的上游仓库定义，包括：

• 操作系统基础仓库（BaseOS、AppStream、EPEL 等）
• PostgreSQL 官方 PGDG 仓库
• Pigsty 扩展仓库
• 各种第三方软件仓库（Docker、Nginx、Grafana 等）

每个上游仓库定义包含以下字段：

- name: pigsty-pgsql              # 仓库名称
  description: 'Pigsty PGSQL'     # 仓库描述
  module: pgsql                   # 所属模块
  releases: [8,9,10]              # 支持的操作系统版本
  arch: [x86_64, aarch64]         # 支持的 CPU 架构
  baseurl:                        # 仓库 URL，按区域配置
    default: 'https://repo.pigsty.io/yum/pgsql/el$releasever.$basearch'
    china: 'https://repo.pigsty.cc/yum/pgsql/el$releasever.$basearch'
  # meta: { module_hotfixes: 1 } # 仅在明确替代 EL 模块流时启用

RPM 上游仓库默认保留系统原生 DNF 模块过滤；只有确实要替代模块流的软件源才应显式设置 meta.module_hotfixes。Pigsty 聚合本地仓库自身会以 module_hotfixes=1 使用，但不会生成伪造的 modules.yaml / ModuleMD 元数据。

用户通常不需要修改此参数，除非有特殊的仓库需求。详细的仓库定义请参考 roles/node_id/vars/ 目录下对应操作系统的配置文件。

repo_packages

参数名称： repo_packages， 类型： string[]， 层次：G

字符串数组类型，每一行都是 由空格分隔 的软件包列表字符串，指定将要使用 repotrack 或 apt download 下载到本地的软件包（及其依赖）。

本参数没有默认值，即默认值为未定义状态。如果该参数没有被显式定义，那么 Pigsty 会从 roles/node_id/vars 中定义的 repo_packages_default 变量中加载获取默认值，默认值为：

[ node-bootstrap, infra-package, infra-addons, node-package1, node-package2, node-package3, pgsql-utility, extra-modules ]

该参数中的每个元素，都会在上述文件中定义的 package_map 中，根据特定的操作系统发行版大版本进行翻译。例如在 EL 系统上会翻译为：

node-bootstrap:          "ansible python3 python3-requests python3-jmespath python3-cryptography dnf-utils sow sshpass"
infra-package:           "nginx dnsmasq etcd haproxy vip-manager node-exporter keepalived-exporter pg-exporter pgbackrest-exporter redis-exporter redis valkey silo mcli sow pig"
infra-addons:            "grafana grafana-plugins grafana-victoriametrics-ds grafana-victorialogs-ds victoria-metrics victoria-logs victoria-traces vlogscli vmutils vector alertmanager"

作为一个使用约定，repo_packages 中通常包括了那些与 PostgreSQL 大版本号无关的软件包（例如 Infra，Node 和 PGDG Common 等部分），而 PostgreSQL 大版本相关的软件包（内核，扩展），通常在 repo_extra_packages 中指定，方便用户切换 PG 大版本。

repo_extra_packages

参数名称： repo_extra_packages， 类型： string[]， 层次：G/C/I

用于在不修改 repo_packages 的基础上，指定额外需要下载的软件包（通常是 PG 大版本相关的软件包），默认值为空列表。

如果该参数没有被显式定义，那么 Pigsty 会从 roles/node_id/vars 中定义的 repo_extra_packages_default 变量中加载获取默认值，默认值为：

[ pgsql-main ]

该参数中的元素会进行包名翻译，其中 $v 会被替换为 pg_version，即当前 PG 大版本号（默认为 18）。

这里的 pgsql-main 在 EL 系统上会翻译为：

postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl postgresql$v-llvmjit pg_repack_$v* wal2json_$v* pgvector_$v*

通常用户可以在这里指定 PostgreSQL 大版本相关的软件包，而不影响 repo_packages 中定义的其他 PG 大版本无关的软件包。

repo_url_packages

参数名称： repo_url_packages， 类型： object[] | string[]， 层次：G

直接使用 URL 从互联网上下载的软件包，默认为空数组： []

您可以直接在本参数中使用 URL 字符串作为数组元素，也可以使用对象结构，显式指定 URL 与文件名称。

请注意，本参数会受到 region 变量的影响，如果您在中国大陆地区，Pigsty 会自动将 URL 替换为国内镜像站点，即将 URL 里的 repo.pigsty.io 替换为 repo.pigsty.cc。

INFRA_PACKAGE

这些软件包只会在 INFRA 节点上安装。

infra_packages

参数名称： infra_packages， 类型： string[]， 层次：G

字符串数组类型，每一行都是 由空格分隔 的软件包列表字符串，指定将要在 Infra 节点上安装的软件包列表。

本参数没有单一的跨平台默认值。如果用户不显式指定，Pigsty 会根据操作系统版本与 CPU 架构，从 roles/node_id/vars 对应的平台文件中加载 infra_packages_default。

例如，当前 EL 9 x86_64 的平台映射值为：

infra_packages_default:
  - grafana,grafana-plugins,grafana-victorialogs-ds,grafana-victoriametrics-ds,victoria-metrics,victoria-logs,victoria-traces,vmutils,vlogscli,alertmanager
  - node-exporter,blackbox-exporter,nginx-exporter,pg-exporter,pev2,nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli,restic,certbot,python3-certbot-nginx

当前 Debian 13 x86_64 的平台映射值为：

infra_packages_default:
  - grafana,grafana-plugins,grafana-victorialogs-ds,grafana-victoriametrics-ds,victoria-metrics,victoria-logs,victoria-traces,vmutils,vlogscli,alertmanager
  - node-exporter,blackbox-exporter,nginx-exporter,pg-exporter,pev2,nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli,restic,certbot,python3-certbot-nginx

NGINX

Pigsty 会通过 Nginx 代理所有的 Web 服务访问：Home Page、Grafana、VictoriaMetrics 等等。 以及其他可选的工具，如 PGWeb、Jupyter Lab、Pgadmin、Bytebase 等等，还有一些静态资源和报告，如 pev、schemaspy 和 pgbadger。

最重要的是，Nginx 还作为本地软件仓库（Yum/Apt）的 Web 服务器，用于存储和分发 Pigsty 的软件包。

nginx_enabled: true               # 在此 Infra 节点上启用 Nginx？
nginx_clean: false                # 初始化时清理现有 Nginx 配置？
nginx_exporter_enabled: true      # 启用 nginx_exporter？
nginx_exporter_port: 9113         # nginx_exporter 监听端口
nginx_sslmode: enable             # SSL 模式：disable,enable,enforce
nginx_cert_validity: 397d         # 自签名证书有效期
nginx_home: /www                  # Nginx 内容目录（软链接）
nginx_data: /data/nginx           # Nginx 实际数据目录
nginx_users: {}                   # 基础认证用户字典
nginx_port: 80                    # HTTP 端口
nginx_ssl_port: 443               # HTTPS 端口
certbot_sign: false               # 使用 certbot 签署证书？
certbot_email: your@email.com     # certbot 邮箱
certbot_options: ''               # certbot 额外选项

nginx_enabled

参数名称： nginx_enabled， 类型： bool， 层次：G/I

是否在当前的 Infra 节点上启用 Nginx？默认值为： true。

Nginx 是 Pigsty 基础设施的核心组件，负责：

• 提供本地软件仓库服务
• 反向代理 Grafana、VictoriaMetrics 等 Web 服务
• 托管静态文件和报告

nginx_clean

参数名称： nginx_clean， 类型： bool， 层次：G/A

初始化时是否清理现有的 Nginx 配置？默认值为： false。

当设置为 true 时，在 Nginx 初始化过程中会删除 /etc/nginx/conf.d/ 下的所有现有配置文件，确保一个干净的起点。

如果您是首次部署或希望完全重建 Nginx 配置，可以将此参数设置为 true。

nginx_exporter_enabled

参数名称： nginx_exporter_enabled， 类型： bool， 层次：G/I

在此基础设施节点上启用 nginx_exporter？默认值为： true。

如果禁用此选项，还会一并禁用 /nginx 健康检查 stub，当您安装使用的 Nginx 版本不支持此功能时可以考虑关闭此开关。

nginx_exporter_port

参数名称： nginx_exporter_port， 类型： port， 层次：G

nginx_exporter 监听端口，默认值为 9113。

nginx_exporter 用于收集 Nginx 的运行指标，供 VictoriaMetrics 抓取监控。

nginx_sslmode

参数名称： nginx_sslmode， 类型： enum， 层次：G

Nginx 的 SSL 工作模式？有三种选择：disable , enable , enforce， 默认值为 enable，即启用 SSL，但不强制使用。

• disable：只监听 nginx_port 指定的端口服务 HTTP 请求。
• enable：同时会监听 nginx_ssl_port 指定的端口服务 HTTPS 请求。
• enforce：所有链接都会被渲染为默认使用 https://
  • 同时会将 infra_portal 中非默认服务器的 80 端口重定向到 443 端口

nginx_cert_validity

参数名称： nginx_cert_validity， 类型： duration， 层次：G

Nginx 自签名证书的有效期，默认值为 397d（约13个月）。

现代浏览器要求网站证书的有效期最多为 397 天，因此这是默认值。不建议设置更长的有效期，否则浏览器可能会拒绝信任该证书。

nginx_home

参数名称： nginx_home， 类型： path， 层次：G

Nginx 服务器静态文件目录，默认为： /www

这是一个软链接，实际指向 nginx_data 目录。此目录包含静态资源和软件仓库文件。

最好不要随意修改此参数，修改时需要与 repo_home 参数保持一致。

nginx_data

参数名称： nginx_data， 类型： path， 层次：G

Nginx 实际数据目录，默认为 /data/nginx。

这是 Nginx 静态文件的实际存储位置，nginx_home 是指向此目录的软链接。

建议将此目录放置在数据盘上，以便于管理大量的软件包文件。

nginx_users

参数名称： nginx_users， 类型： dict， 层次：G

Nginx 基础认证（Basic Auth）用户字典，默认为空字典 {}。

格式为 { username: password } 的键值对，例如：

nginx_users:
  admin: pigsty
  viewer: readonly

这些用户可用于保护某些需要认证的 Nginx 端点。

nginx_port

参数名称： nginx_port， 类型： port， 层次：G

Nginx 默认监听的端口（提供 HTTP 服务），默认为 80 端口，最好不要修改这个参数。

当您的服务器 80 端口被占用时，可以考虑修改此参数，但需要同时修改 repo_endpoint 并确保相关节点能够通过新的端口访问本地软件仓库。

nginx_ssl_port

参数名称： nginx_ssl_port， 类型： port， 层次：G

Nginx SSL 默认监听的端口，默认为 443，最好不要修改这个参数。

certbot_sign

参数名称： certbot_sign， 类型： bool， 层次：G/A

是否在安装过程中使用 certbot 签署 Nginx 证书？默认值为 false。

当设置为 true 时，Pigsty 会在执行 infra.yml 和 deploy.yml 剧本（nginx 角色）期间使用 certbot 自动从 Let’s Encrypt 申请免费 SSL 证书。

在 infra_portal 定义的域名中，如果定义了 certbot 参数，Pigsty 将使用 certbot 为 domain 域名申请证书，证书名称将是 certbot 参数的值。如果多个服务器/域名指定了相同的 certbot 参数，Pigsty 会合并并为这些域名申请一个证书，使用 certbot 参数的值作为证书名称。

启用此选项需要：

• 当前节点可以通过公共域名访问，并且 DNS 解析已正确指向当前节点的公网 IP
• 当前节点可以访问 Let’s Encrypt API 接口

此选项默认禁用，您可以在安装后手动执行 make cert 命令来手动执行，它实际上调用渲染好的 /etc/nginx/sign-cert 脚本，使用 certbot 更新或申请证书。

certbot_email

参数名称： certbot_email， 类型： string， 层次：G/A

用于接收证书过期提醒邮件的电子邮件地址，默认值为 your@email.com。

当 certbot_sign 设置为 true 时，建议提供此参数。Let’s Encrypt 会在证书即将过期时向此邮箱发送提醒邮件。

certbot_options

参数名称： certbot_options， 类型： string， 层次：G/A

传递给 certbot 的额外配置参数，默认值为空字符串。

您可以通过此参数向 certbot 传递额外的命令行选项，例如 --dry-run，则 certbot 不会实际申请证书，而是进行预览和测试。

DNS

Pigsty 默认会在 Infra 节点上启用 DNSMASQ 服务，用于解析一些辅助域名，例如 i.pigsty、m.pigsty、supa.pigsty、api.pigsty 等。

解析记录会记录在 Infra 节点的 /etc/dnsmasq.d/pigsty/default 文件中。 要使用这个 DNS 服务器，您必须将 nameserver <ip> 添加到 /etc/resolv.conf 中，node_dns_servers 参数可以解决这个问题。

dns_enabled: true                 # 在此 Infra 节点上设置 dnsmasq？
dns_port: 53                      # DNS 服务器监听端口
dns_records:                      # 动态 DNS 记录
  - "${admin_ip} i.pigsty"
  - "${admin_ip} m.pigsty supa.pigsty api.pigsty adm.pigsty cli.pigsty ddl.pigsty"

dns_enabled

参数名称： dns_enabled， 类型： bool， 层次：G/I

是否在这个 Infra 节点上启用 DNSMASQ 服务？默认值为： true。

如果你不想使用默认的 DNS 服务器（比如你已经有了外部的 DNS 服务器，或者您的供应商不允许您使用 DNS 服务器）可以将此值设置为 false 来禁用它。 并使用 node_default_etc_hosts 和 node_etc_hosts 静态解析记录代替。

dns_port

参数名称： dns_port， 类型： port， 层次：G

DNSMASQ 的默认监听端口，默认是 53，不建议修改 DNS 服务默认端口。

dns_records

参数名称： dns_records， 类型： string[]， 层次：G

由 dnsmasq 负责解析的动态 DNS 记录，一般用于将一些辅助域名解析到管理节点。这些记录会被写入到基础设施节点的 /etc/dnsmasq.d/pigsty/default 文件中。

v4.x 默认值：

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

这里使用 ${admin_ip} 占位符，在部署时会被替换为实际的 admin_ip 值。

常见的域名用途：

• i.pigsty：Pigsty 首页
• m.pigsty：常用于 Silo 控制台（可选）
• p.pigsty：常用于 VictoriaMetrics Web UI（当在 infra_portal 中显式配置时）
• api.pigsty：API 服务
• adm.pigsty：管理服务
• 其他根据实际部署需求自定义

VICTORIA

Pigsty v4.x 使用 VictoriaMetrics 套件替代 Prometheus 和 Loki，提供更优秀的可观测性解决方案：

• VictoriaMetrics：替代 Prometheus，作为时序数据库存储监控指标
• VictoriaLogs：替代 Loki，作为日志聚合存储
• VictoriaTraces：分布式追踪存储
• VMAlert：替代 Prometheus Alerting，进行告警规则评估

vmetrics_enabled: true            # 启用 VictoriaMetrics？
vmetrics_clean: false             # 初始化时清理数据？
vmetrics_port: 8428               # 监听端口
vmetrics_scrape_interval: 10s     # 全局抓取间隔
vmetrics_scrape_timeout: 8s       # 全局抓取超时
vmetrics_options: >-
  -retentionPeriod=15d
  -promscrape.fileSDCheckInterval=5s
vlogs_enabled: true               # 启用 VictoriaLogs？
vlogs_clean: false                # 初始化时清理数据？
vlogs_port: 9428                  # 监听端口
vlogs_options: >-
  -retentionPeriod=15d
  -retention.maxDiskSpaceUsageBytes=50GiB
  -insert.maxLineSizeBytes=1MB
  -search.maxQueryDuration=120s
vtraces_enabled: true             # 启用 VictoriaTraces？
vtraces_clean: false              # 初始化时清理数据？
vtraces_port: 10428               # 监听端口
vtraces_options: >-
  -retentionPeriod=15d
  -retention.maxDiskSpaceUsageBytes=50GiB
vmalert_enabled: true             # 启用 VMAlert？
vmalert_port: 8880                # 监听端口
vmalert_options: ''               # 额外命令行参数

vmetrics_enabled

参数名称： vmetrics_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 VictoriaMetrics？默认值为 true。

VictoriaMetrics 是 Pigsty v4.x 的核心监控组件，替代 Prometheus 作为时序数据库，负责：

• 从各个 Exporter 抓取监控指标
• 存储时序数据
• 提供 PromQL 兼容的查询接口
• 支持 Grafana 数据源

vmetrics_clean

参数名称： vmetrics_clean， 类型： bool， 层次：G/A

初始化 VictoriaMetrics 时是否清理现有数据？默认值为 false。

当设置为 true 时，在初始化过程中会删除已有的时序数据。谨慎使用此选项，除非您确定要重建监控数据。

vmetrics_port

参数名称： vmetrics_port， 类型： port， 层次：G

VictoriaMetrics 监听端口，默认值为 8428。

此端口用于：

• HTTP API 访问
• Web UI 访问
• Prometheus 兼容的远程写入/读取
• Grafana 数据源连接

vmetrics_scrape_interval

参数名称： vmetrics_scrape_interval， 类型： interval， 层次：G

VictoriaMetrics 全局指标抓取周期，默认值为 10s。

在生产环境，10秒 - 30秒是一个较为合适的抓取周期。如果您需要更精细的监控数据粒度，可以调整此参数，但会增加存储和 CPU 开销。

vmetrics_scrape_timeout

参数名称： vmetrics_scrape_timeout， 类型： interval， 层次：G

VictoriaMetrics 全局抓取超时，默认为 8s。

设置抓取超时可以有效避免监控系统查询导致的雪崩，设置原则是本参数必须小于并接近 vmetrics_scrape_interval，确保每次抓取时长不超过抓取周期。

vmetrics_options

参数名称： vmetrics_options， 类型： arg， 层次：G

VictoriaMetrics 的额外命令行参数，默认值：

vmetrics_options: >-
  -retentionPeriod=15d
  -promscrape.fileSDCheckInterval=5s

常用参数说明：

• -retentionPeriod=15d：数据保留期限，默认 15 天
• -promscrape.fileSDCheckInterval=5s：文件服务发现刷新间隔

您可以根据需要添加其他 VictoriaMetrics 支持的参数。

vlogs_enabled

参数名称： vlogs_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 VictoriaLogs？默认值为 true。

VictoriaLogs 替代 Loki 作为日志聚合存储，负责：

• 接收来自 Vector 的日志数据
• 存储和索引日志
• 提供日志查询接口
• 支持 Grafana VictoriaLogs 数据源

vlogs_clean

参数名称： vlogs_clean， 类型： bool， 层次：G/A

初始化 VictoriaLogs 时是否清理现有数据？默认值为 false。

vlogs_port

参数名称： vlogs_port， 类型： port， 层次：G

VictoriaLogs 监听端口，默认值为 9428。

vlogs_options

参数名称： vlogs_options， 类型： arg， 层次：G

VictoriaLogs 的额外命令行参数，默认值：

vlogs_options: >-
  -retentionPeriod=15d
  -retention.maxDiskSpaceUsageBytes=50GiB
  -insert.maxLineSizeBytes=1MB
  -search.maxQueryDuration=120s

常用参数说明：

• -retentionPeriod=15d：日志保留期限，默认 15 天
• -retention.maxDiskSpaceUsageBytes=50GiB：最大磁盘使用量
• -insert.maxLineSizeBytes=1MB：单行日志最大大小
• -search.maxQueryDuration=120s：查询最大执行时间

vtraces_enabled

参数名称： vtraces_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 VictoriaTraces？默认值为 true。

VictoriaTraces 用于分布式追踪数据的存储和查询，支持 Jaeger、Zipkin 等追踪协议。

vtraces_clean

参数名称： vtraces_clean， 类型： bool， 层次：G/A

初始化 VictoriaTraces 时是否清理现有数据？默认值为 false。

vtraces_port

参数名称： vtraces_port， 类型： port， 层次：G

VictoriaTraces 监听端口，默认值为 10428。

vtraces_options

参数名称： vtraces_options， 类型： arg， 层次：G

VictoriaTraces 的额外命令行参数，默认值：

vtraces_options: >-
  -retentionPeriod=15d
  -retention.maxDiskSpaceUsageBytes=50GiB

vmalert_enabled

参数名称： vmalert_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 VMAlert？默认值为 true。

VMAlert 负责告警规则评估，替代 Prometheus Alerting 功能，与 Alertmanager 配合使用。

vmalert_port

参数名称： vmalert_port， 类型： port， 层次：G

VMAlert 监听端口，默认值为 8880。

vmalert_options

参数名称： vmalert_options， 类型： arg， 层次：G

VMAlert 的额外命令行参数，默认值为空字符串。

PROMETHEUS

此部分现在主要包含 Blackbox Exporter 和 Alertmanager 的配置。

blackbox_enabled: true            # 启用 blackbox_exporter？
blackbox_port: 9115               # blackbox_exporter 监听端口
blackbox_options: ''              # 额外命令行参数
alertmanager_enabled: true        # 启用 alertmanager？
alertmanager_port: 9059           # alertmanager 监听端口
alertmanager_options: ''          # 额外命令行参数
exporter_metrics_path: /metrics   # exporter 指标路径

blackbox_enabled

参数名称： blackbox_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 BlackboxExporter？默认值为 true。

BlackboxExporter 会向节点 IP 地址、VIP 地址、PostgreSQL VIP 地址发送 ICMP 报文测试网络连通性，还可以进行 HTTP、TCP、DNS 等探测。

blackbox_port

参数名称： blackbox_port， 类型： port， 层次：G

Blackbox Exporter 监听端口，默认值为 9115。

blackbox_options

参数名称： blackbox_options， 类型： arg， 层次：G

BlackboxExporter 的额外命令行参数，默认值：空字符串。

alertmanager_enabled

参数名称： alertmanager_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 AlertManager？默认值为 true。

AlertManager 负责接收来自 VMAlert 的告警通知，并进行告警分组、抑制、静默、路由等处理。

alertmanager_port

参数名称： alertmanager_port， 类型： port， 层次：G

AlertManager 监听端口，默认值为 9059。

如果您修改了此端口，请确保相应更新 infra_portal 中 alertmanager 条目的 endpoint 配置（如果有定义的话）。

alertmanager_options

参数名称： alertmanager_options， 类型： arg， 层次：G

AlertManager 的额外命令行参数，默认值：空字符串。

exporter_metrics_path

参数名称： exporter_metrics_path， 类型： path， 层次：G

监控 exporter 暴露指标的 HTTP 端点路径，默认为： /metrics，不建议修改此参数。

此参数定义了所有 Exporter 暴露监控指标的标准路径。

GRAFANA

Pigsty 使用 Grafana 作为监控系统前端。它也可以作为数据分析与可视化平台，或者用于低代码数据应用开发，制作数据应用原型等目的。

grafana_enabled: true             # 启用 Grafana？
grafana_port: 3000                # Grafana 监听端口
grafana_clean: false              # 初始化时清理数据？
grafana_admin_username: admin     # 管理员用户名
grafana_admin_password: pigsty    # 管理员密码
grafana_auth_proxy: false         # 启用身份代理？
grafana_pgurl: ''                 # 外部 PostgreSQL URL
grafana_view_password: DBUser.Viewer  # PG 数据源密码

grafana_enabled

参数名称： grafana_enabled， 类型： bool， 层次：G/I

是否在 Infra 节点上启用 Grafana？默认值为： true，即所有基础设施节点默认都会安装启用 Grafana。

grafana_port

参数名称： grafana_port， 类型： port， 层次：G

Grafana 监听端口，默认值为 3000。

如果您需要直接访问 Grafana（不通过 Nginx 反向代理），可以使用此端口。

grafana_clean

参数名称： grafana_clean， 类型： bool， 层次：G/A

是否在初始化 Grafana 时一并清理其数据文件？默认为：false。

如果设置为 true，初始化 Grafana 时会移除 /var/lib/grafana/grafana.db，确保 Grafana 是一个全新安装。

如果您希望保留现有的 Grafana 配置（如仪表盘、用户、数据源等），请将此参数保留为 false。

grafana_admin_username

参数名称： grafana_admin_username， 类型： username， 层次：G

Grafana 管理员用户名，默认为 admin。

grafana_admin_password

参数名称： grafana_admin_password， 类型： password， 层次：G

Grafana 管理员密码，默认为 pigsty。

重要提示：请务必在生产部署中修改此密码参数！

grafana_auth_proxy

参数名称： grafana_auth_proxy， 类型： bool， 层次：G

是否启用 Grafana 身份代理？默认为 false。

当启用时，Grafana 会信任反向代理（Nginx）传递的用户身份信息，实现单点登录（SSO）功能。

这通常用于与外部身份认证系统集成的场景。

grafana_pgurl

参数名称： grafana_pgurl， 类型： url， 层次：G

外部 PostgreSQL 数据库 URL，用于 Grafana 持久化存储。默认为空字符串。

如果指定，Grafana 将使用此 PostgreSQL 数据库替代默认的 SQLite 数据库存储其配置数据。

格式示例：postgres://grafana:password@pg-meta:5432/grafana?sslmode=disable

这对于需要 Grafana 高可用部署或数据持久化的场景非常有用。

grafana_view_password

参数名称： grafana_view_password， 类型： password， 层次：G

Grafana 元数据库 PG 数据源使用的只读用户密码，默认为 DBUser.Viewer。

此密码用于 Grafana 连接 PostgreSQL CMDB 数据源，以只读方式查询元数据。

3 - 预置剧本

Pigsty 提供了三个与 INFRA 模块相关的剧本：

• deploy.yml：在所有节点上一次性部署 NODE、INFRA、ETCD、MINIO 与 PGSQL 核心模块
• infra.yml：在 infra 节点上初始化 pigsty 基础设施
• infra-rm.yml：从 infra 节点移除基础设施组件

deploy.yml

在所有节点上一次性部署 NODE、INFRA、ETCD、MINIO 与 PGSQL 核心模块，解决 INFRA/NODE 循环依赖问题。

该剧本会交叉执行 infra.yml 与 node.yml 的子任务，按以下顺序完成核心组件的部署：

1. id：生成节点与 PostgreSQL 身份标识
2. ca：在本地创建自签名 CA 证书
3. repo：在 infra 节点上创建本地软件仓库
4. node-init：初始化节点与 HAProxy
5. infra：初始化 Nginx、DNS、VictoriaMetrics、Grafana 等
6. node-monitor：初始化 node-exporter、vector
7. etcd：初始化 etcd（PostgreSQL 高可用必需）
8. minio：初始化 Silo（可选）
9. pgsql：初始化 PostgreSQL 集群并配置 PostgreSQL 监控

该剧本等效于依次执行以下五个剧本：

./infra.yml -l infra    # 在 infra 分组上部署基础设施
./node.yml              # 在所有节点上初始化节点
./etcd.yml              # 初始化 etcd 集群
./minio.yml             # 初始化 MINIO（Silo）集群（可选）
./pgsql.yml             # 初始化 PostgreSQL 集群

deploy.yml 当前不部署 Docker 模块；需要 Docker 时，应另行设置 docker_enabled: true 并单独执行 docker.yml。

infra.yml

在配置文件的 infra 分组所定义的 Infra 节点 上初始化基础设施模块。

执行该剧本将完成以下任务：

• 配置 Infra 节点 的目录与环境变量
• 下载并创建本地软件仓库，加速后续安装
• 将当前 Infra 节点 作为普通节点纳入 Pigsty 管理
• 部署基础设施组件（VictoriaMetrics/Logs/Traces、VMAlert、Grafana、Alertmanager、Blackbox Exporter 等）

剧本注意事项：

• 本剧本为幂等剧本，重复执行默认不会清理历史数据与 Grafana 数据
• 如需保留历史监控数据，请先将 vmetrics_clean、vlogs_clean、vtraces_clean 设置为 false
• 如果设置 grafana_clean 为 true，Grafana 数据库会被清理，原有仪表盘与配置会丢失
• 当本地软件仓库 /www/pigsty/repo_complete 存在时，本剧本会跳过互联网下载；该文件是 SOW 生成的 SHA-256 清单与完成标记
• 完整执行该剧本耗时约1～3分钟，视机器配置与网络条件而异

可用任务列表

# ca: create self-signed CA on localhost files/pki
#   - ca_dir        : create CA directory
#   - ca_private    : generate ca private key: files/pki/ca/ca.key
#   - ca_cert       : signing ca cert: files/pki/ca/ca.crt
#
# id: generate node identity
#
# repo: bootstrap a local yum repo from internet or offline packages
#   - repo_dir      : create repo directory
#   - repo_check    : check repo exists
#   - repo_prepare  : use existing repo if exists
#   - repo_build    : build repo from upstream if not exists
#     - repo_upstream    : handle upstream repo files in /etc/yum.repos.d
#       - repo_remove    : remove existing repo file if repo_remove == true
#       - repo_add       : add upstream repo files to /etc/yum.repos.d
#     - repo_url_pkg     : download packages from internet defined by repo_url_packages
#     - repo_cache       : make upstream yum cache with yum makecache
#     - repo_boot_pkg    : install sow and dnf/yum download utilities
#     - repo_pkg         : download packages & dependencies from upstream repo
#     - repo_create      : atomically create RPM/APT metadata with sow create --pigsty
#     - repo_use         : add newly built repo into /etc/yum.repos.d
#   - repo_nginx    : launch a nginx for repo if no nginx is serving
#
# node/haproxy/monitor: setup infra node as a common node
#   - node_name, node_hosts, node_resolv, node_firewall, node_ca, node_repo, node_pkg
#   - node_feature, node_kernel, node_tune, node_sysctl, node_profile, node_ulimit
#   - node_data, node_admin, node_timezone, node_ntp, node_crontab, node_vip
#   - haproxy_install, haproxy_config, haproxy_launch, haproxy_reload
#   - haproxy_register, node_exporter, node_register, vector
#
# infra: setup infra components
#   - infra_user     : setup infra os user group
#   - infra_dir      : create infra data/config/runtime directories
#   - infra_env      : env_patroni, env_pg, env_pgadmin, env_etcd, env_pglog, env_var
#   - infra_pkg      : install infra packages
#   - infra_cert     : issue cert for infra components
#   - dns            : dns_config, dns_record, dns_launch
#   - nginx          : nginx_dir, nginx_config, nginx_cert, nginx_static, nginx_launch, nginx_certbot, nginx_reload, nginx_exporter
#   - victoria       : vmetrics/vlogs/vtraces clean, config & launch; vmalert_config, vmalert_launch
#   - alertmanager   : alertmanager_config, alertmanager_launch
#   - blackbox       : blackbox_config, blackbox_launch
#   - grafana        : grafana_clean, grafana_dir, grafana_config, grafana_launch, grafana_provision
#   - infra_register : add_metrics, add_logs, add_ds

infra-rm.yml

从配置文件 infra 分组定义的 Infra 节点 上移除 Pigsty 基础设施。

常用子任务包括：

./infra-rm.yml               # 执行全部阶段：注销、停服、删配置/环境/数据并卸载软件包
./infra-rm.yml -t deregister # 仅注销监控目标、Grafana 数据源与 Nginx 日志采集
./infra-rm.yml -t service    # 停止 INFRA 上的基础设施服务
./infra-rm.yml -t config     # 删除 INFRA 配置与 Systemd Unit
./infra-rm.yml -t env        # 删除管理用户环境文件
./infra-rm.yml -t data       # 移除 INFRA 数据
./infra-rm.yml -t package    # 卸载 INFRA 软件包

4 - 监控告警

本文介绍 Pigsty 中 INFRA 模块的监控面板与告警规则。

监控面板

Pigsty 针对 Infra 模块提供了以下监控面板：

告警规则

Pigsty 针对 INFRA 模块提供了以下两条告警规则：

可在 files/victoria/rules/infra.yml 中修改或添加新的基础设施告警规则。

告警规则配置

################################################################
#                Infrastructure Alert Rules                    #
################################################################
- name: infra-alert
  rules:

    #==============================================================#
    #                       Infra Aliveness                        #
    #==============================================================#
    # infra components (victoria,grafana) down for 1m triggers a P1 alert
    - alert: InfraDown
      expr: infra_up < 1
      for: 1m
      labels: { level: 0, severity: CRIT, category: infra }
      annotations:
        summary: "CRIT InfraDown {{ $labels.type }}@{{ $labels.instance }}"
        description: |
          infra_up[type={{ $labels.type }}, instance={{ $labels.instance }}] = {{ $value  | printf "%.2f" }} < 1

    #==============================================================#
    #                       Agent Aliveness                        #
    #==============================================================#

    # agent aliveness are determined directly by exporter aliveness
    # including: node_exporter, pg_exporter, pgbouncer_exporter, haproxy_exporter
    - alert: AgentDown
      expr: agent_up < 1
      for: 1m
      labels: { level: 0, severity: CRIT, category: infra }
      annotations:
        summary: 'CRIT AgentDown {{ $labels.ins }}@{{ $labels.instance }}'
        description: |
          agent_up[ins={{ $labels.ins }}, instance={{ $labels.instance }}] = {{ $value  | printf "%.2f" }} < 1

5 - 指标列表

注意：Pigsty v4.0 已将 Prometheus/Loki 替换为 VictoriaMetrics/Logs/Traces。以下指标清单仍基于 v3.x 生成，仅供排查旧版本问题参考。若需获取最新指标，请在 https://p.pigsty (VMUI) 或 Grafana 中直接查询，后续版本会重新生成与 Victoria 套件一致的指标速查表。

INFRA 指标

INFRA 模块包含有 964 类可用监控指标。