配置清单

pigsty.yml 配置文件结构详解。

配置清单（Inventory）是 Pigsty 的核心配置文件，使用 YAML 格式描述整个基础设施的期望状态。

文件结构

默认配置文件为 pigsty.yml，位于 Pigsty 根目录：

---
# 全局配置
all:
  vars:
    # 全局变量...

  children:
    # 基础设施集群
    infra:
      hosts: { ... }
      vars: { ... }

    # ETCD 集群
    etcd:
      hosts: { ... }
      vars: { ... }

    # PostgreSQL 集群
    pg-meta:
      hosts: { ... }
      vars: { ... }

    pg-test:
      hosts: { ... }
      vars: { ... }
...

层次结构

全局级别（all.vars）

适用于所有主机和集群的默认配置：

all:
  vars:
    # 版本与区域
    version: v3.3.0
    region: default

    # 基础设施
    admin_ip: 10.10.10.10

    # PostgreSQL 默认配置
    pg_version: 17
    pg_conf: oltp.yml

集群级别（cluster.vars）

特定集群的配置，覆盖全局默认值：

pg-test:
  vars:
    pg_cluster: pg-test
    pg_version: 16              # 覆盖全局版本
    pg_conf: crit.yml           # 使用关键业务模板
    pg_databases:
      - name: testdb
    pg_users:
      - name: testuser

实例级别（host.vars）

特定实例的精细配置，最高优先级：

pg-test:
  hosts:
    10.10.10.11:
      pg_seq: 1
      pg_role: primary
    10.10.10.12:
      pg_seq: 2
      pg_role: replica
      pg_conf: tiny.yml         # 此实例使用 tiny 模板

集群定义

必需参数

每个集群必须定义以下参数：

参数 说明 示例
pg_cluster 集群名称 pg-meta
pg_seq 实例序号 1, 2, 3
pg_role 实例角色 primary, replica

完整示例

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
    10.10.10.13: { pg_seq: 3, pg_role: replica }
  vars:
    pg_cluster: pg-test
    pg_version: 17

    # 数据库定义
    pg_databases:
      - name: testdb
        owner: testuser
        extensions:
          - postgis
          - pg_stat_statements

    # 用户定义
    pg_users:
      - name: testuser
        password: DBUser.Test
        roles: [dbrole_readwrite]

    # 连接池
    pg_default_services:
      - { name: primary, port: 5433, dest: primary }
      - { name: replica, port: 5434, dest: replica }

变量覆盖规则

优先级从低到高：

1. 角色默认值（roles/xxx/defaults/main.yml）
       ↓
2. 全局变量（all.vars）
       ↓
3. 集群变量（cluster.vars）
       ↓
4. 实例变量（host.vars）
       ↓
5. 命令行变量（-e "key=value"）

示例

all:
  vars:
    pg_version: 17              # 全局默认 PG 17

  children:
    pg-legacy:
      vars:
        pg_version: 15          # 此集群使用 PG 15
      hosts:
        10.10.10.21:
          pg_seq: 1
          pg_role: primary
          pg_version: 14        # 此实例使用 PG 14（特殊需求）

多环境管理

环境分离

为不同环境创建独立配置文件：

pigsty/
├── pigsty.yml              # 当前环境（软链接）
├── conf/
│   ├── prod.yml            # 生产环境
│   ├── staging.yml         # 预发环境
│   ├── dev.yml             # 开发环境
│   └── demo.yml            # 演示环境

切换环境

# 方式一：使用软链接
ln -sf conf/prod.yml pigsty.yml

# 方式二：使用 -i 参数
./pgsql.yml -i conf/prod.yml -l pg-test

配置验证

语法检查

# YAML 语法检查
python3 -c "import yaml; yaml.safe_load(open('pigsty.yml'))"

# Ansible 语法检查
ansible-playbook pgsql.yml --syntax-check

查看变量

# 查看特定主机的变量
ansible -i pigsty.yml 10.10.10.11 -m debug -a "var=hostvars[inventory_hostname]"

# 查看集群变量
ansible -i pigsty.yml pg-test -m debug -a "var=group_vars"

干运行

# 检查模式（不实际执行）
./pgsql.yml -l pg-test --check

# 差异对比
./pgsql.yml -l pg-test --diff

最佳实践

配置组织

  1. 全局变量精简：只放真正全局的默认值
  2. 集群变量完整：包含集群特有的所有配置
  3. 实例变量最少：只放必需的身份标识

命名规范

# 集群名：模块-用途
pg-meta          # PostgreSQL 元数据库
pg-order         # 订单服务数据库
redis-cache      # Redis 缓存集群

# 实例名：集群名-序号
pg-meta-1        # 集群 pg-meta 的第 1 个实例
pg-order-2       # 集群 pg-order 的第 2 个实例

版本控制

# 初始化 Git
cd ~/pigsty
git init
git add pigsty.yml
git commit -m "Initial configuration"

# 每次变更都提交
git add pigsty.yml
git commit -m "Add pg-order cluster"