ha/citus

13 节点 Citus 分布式 PostgreSQL 集群，1 协调组 + 5 工作组高可用配置，提供水平扩展与分片能力

ha/citus 配置模板部署一套完整的 Citus 分布式 PostgreSQL 集群，包含 1 个基础设施节点、1 组协调节点和 5 组工作节点（共 12 个 Citus 节点），提供透明的水平扩展与数据分片能力。

配置概览

配置名称： ha/citus
节点数量： 13 节点（1 基础设施 + 1 协调组 × 2 + 5 工作组 × 2）
配置说明：Citus 分布式 PostgreSQL 高可用集群
适用系统：el8, el9, el10, d12, d13, u22, u24
适用架构：x86_64
相关配置：meta，ha/trio

启用方式：

./configure -c ha/citus

备注：这是一个 13 节点模板，您需要在生成配置后修改各节点的 IP 地址

配置内容

源文件地址：pigsty/conf/ha/citus.yml

---
#==============================================================#
# File      :   citus.yml
# Desc      :   13-node Citus (6-group Distributive) Config Template
# Ctime     :   2020-05-22
# Mtime     :   2025-01-20
# Docs      :   https://pigsty.io/docs/conf/citus
# License   :   Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright :   2018-2026  Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#

# This is the config template for Citus Distributive Cluster
# tutorial: https://pigsty.io/docs/pgsql/kernel/citus
# we will use the local repo for cluster bootstrapping
#
# Topology:
#   - pg-citus0: coordinator (10.10.10.10)         VIP: 10.10.10.19
#   - pg-citus1: worker group 1 (10.10.10.21, 22)  VIP: 10.10.10.29
#   - pg-citus2: worker group 2 (10.10.10.31, 32)  VIP: 10.10.10.39
#   - pg-citus3: worker group 3 (10.10.10.41, 42)  VIP: 10.10.10.49
#   - pg-citus4: worker group 4 (10.10.10.51, 52)  VIP: 10.10.10.59
#   - pg-citus5: worker group 5 (10.10.10.61, 62)  VIP: 10.10.10.69
#   - pg-citus6: worker group 6 (10.10.10.71, 72)  VIP: 10.10.10.79
#
# Usage:
#   curl https://repo.pigsty.io/get | bash
#   ./configure -c citus
#   ./deploy.yml

all:
  children:
    infra: { hosts: { 10.10.10.10: { infra_seq: 1 }}}
    etcd:  { hosts: { 10.10.10.10: { etcd_seq: 1  }}, vars: { etcd_cluster: etcd }}
    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
        pg_databases: { name: meta ,baseline: cmdb.sql comment: "pigsty meta database" ,schemas: [pigsty] ,extensions: [ postgis, vector ]}
        pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every day 1am

    #----------------------------------------------------------#
    # pg-citus: 6 cluster groups, 12 nodes total
    #----------------------------------------------------------#
    pg-citus:
      hosts:

        # coordinator (group 0) on infra node
        10.10.10.21: { pg_group: 0, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.29/24 ,pg_seq: 1, pg_role: primary }
        10.10.10.22: { pg_group: 0, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.29/24 ,pg_seq: 2, pg_role: replica }

        # worker group 2
        10.10.10.31: { pg_group: 1, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.39/24 ,pg_seq: 1, pg_role: primary }
        10.10.10.32: { pg_group: 1, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.39/24 ,pg_seq: 2, pg_role: replica }

        # worker group 3
        10.10.10.41: { pg_group: 2, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.49/24 ,pg_seq: 1, pg_role: primary }
        10.10.10.42: { pg_group: 2, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.49/24 ,pg_seq: 2, pg_role: replica }

        # worker group 4
        10.10.10.51: { pg_group: 3, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.59/24 ,pg_seq: 1, pg_role: primary }
        10.10.10.52: { pg_group: 3, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.59/24 ,pg_seq: 2, pg_role: replica }

        # worker group 5
        10.10.10.61: { pg_group: 4, pg_cluster: pg-citus5 ,pg_vip_address: 10.10.10.69/24 ,pg_seq: 1, pg_role: primary }
        10.10.10.62: { pg_group: 4, pg_cluster: pg-citus5 ,pg_vip_address: 10.10.10.69/24 ,pg_seq: 2, pg_role: replica }

        # worker group 6
        10.10.10.71: { pg_group: 5, pg_cluster: pg-citus6 ,pg_vip_address: 10.10.10.79/24 ,pg_seq: 1, pg_role: primary }
        10.10.10.72: { pg_group: 5, pg_cluster: pg-citus6 ,pg_vip_address: 10.10.10.79/24 ,pg_seq: 2, pg_role: replica }

      vars:
        pg_mode: citus                            # pgsql cluster mode: citus
        pg_shard: pg-citus                        # citus shard name: pg-citus
        pg_primary_db: citus                      # primary database used by citus
        pg_dbsu_password: DBUser.Postgres         # enable dbsu password access for citus
        pg_extensions: [ citus, postgis, pgvector, topn, pg_cron, hll ]
        pg_libs: 'citus, pg_cron, pg_stat_statements'
        pg_users: [{ name: dbuser_citus ,password: DBUser.Citus ,pgbouncer: true ,roles: [ dbrole_admin ] }]
        pg_databases: [{ name: citus ,owner: dbuser_citus ,extensions: [ citus, vector, topn, pg_cron, hll ] }]
        pg_parameters:
          cron.database_name: citus
          citus.node_conninfo: 'sslrootcert=/pg/cert/ca.crt sslmode=verify-full'
        pg_hba_rules:
          - { user: 'all' ,db: all  ,addr: 127.0.0.1/32  ,auth: ssl ,title: 'all user ssl access from localhost' }
          - { user: 'all' ,db: all  ,addr: intra         ,auth: ssl ,title: 'all user ssl access from intranet'  }
        pg_vip_enabled: true
        pg_vip_interface: eth1
        pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every day 1am

  vars:
    #----------------------------------------------#
    # INFRA : https://pigsty.io/docs/infra/param
    #----------------------------------------------#
    version: v4.0.0
    admin_ip: 10.10.10.10
    region: default
    infra_portal:
      home : { domain: i.pigsty }

    #----------------------------------------------#
    # NODE : https://pigsty.io/docs/node/param
    #----------------------------------------------#
    nodename_overwrite: true
    node_repo_modules: node,infra,pgsql
    node_tune: oltp

    #----------------------------------------------#
    # PGSQL : https://pigsty.io/docs/pgsql/param
    #----------------------------------------------#
    pg_version: 18  # PostgreSQL 14-18
    pg_conf: oltp.yml
    pg_packages: [ pgsql-main, pgsql-common ]

    #----------------------------------------------#
    # PASSWORD : https://pigsty.io/docs/setup/security/
    #----------------------------------------------#
    grafana_admin_password: pigsty
    grafana_view_password: DBUser.Viewer
    pg_admin_password: DBUser.DBA
    pg_monitor_password: DBUser.Monitor
    pg_replication_password: DBUser.Replicator
    patroni_password: Patroni.API
    haproxy_admin_password: pigsty
    minio_secret_key: S3User.MinIO
    etcd_root_password: Etcd.Root
...

集群拓扑

此配置部署一套完整的 Citus 分布式集群，拓扑结构如下：

集群	节点	IP 地址	VIP	角色
pg-meta	1	10.10.10.10	-	基础设施 + CMDB
pg-citus1	2	10.10.10.21, 22	10.10.10.29	协调节点（group 0）
pg-citus2	2	10.10.10.31, 32	10.10.10.39	工作节点（group 1）
pg-citus3	2	10.10.10.41, 42	10.10.10.49	工作节点（group 2）
pg-citus4	2	10.10.10.51, 52	10.10.10.59	工作节点（group 3）
pg-citus5	2	10.10.10.61, 62	10.10.10.69	工作节点（group 4）
pg-citus6	2	10.10.10.71, 72	10.10.10.79	工作节点（group 5）

架构说明：

pg-meta：基础设施节点，运行 Grafana、Prometheus、etcd 等监控组件，同时部署一个独立的 CMDB 数据库
pg-citus1：Citus 协调节点（group 0），负责接收客户端查询并路由到工作节点，1 主 1 从高可用配置
pg-citus2~6：Citus 工作节点（group 1~5），存储分片数据，每组 1 主 1 从，通过 Patroni 实现自动故障转移
VIP：每个节点组配置 L2 VIP，由 vip-manager 管理，确保故障转移时客户端连接自动切换

配置解读

ha/citus 模板部署生产级 Citus 分布式集群，适合需要水平扩展的大规模数据场景。

关键特性：

水平扩展：5 个工作组可线性扩展存储和计算能力
高可用：每个工作组 1 主 1 从，支持自动故障转移
L2 VIP：每组配置虚拟 IP，故障切换对应用透明
SSL 加密：节点间通信使用 SSL 证书加密
透明分片：数据自动分布到多个工作节点

预装扩展：

pg_extensions: [ citus, postgis, pgvector, topn, pg_cron, hll ]
pg_libs: 'citus, pg_cron, pg_stat_statements'

安全配置：

启用 pg_dbsu_password，允许超级用户密码访问（Citus 节点间通信需要）
HBA 规则要求所有连接使用 SSL 认证
节点间使用证书验证：sslmode=verify-full

部署步骤

# 1. 下载 Pigsty
curl https://repo.pigsty.io/get | bash

# 2. 使用 ha/citus 配置模板
./configure -c ha/citus

# 3. 修改 IP 地址和密码
vi pigsty.yml

# 4. 部署完整集群
./deploy.yml

部署完成后，Citus 会自动注册所有工作节点。可通过以下命令验证：

-- 连接到任意协调节点
psql -h 10.10.10.29 -U dbuser_citus -d citus

-- 查看工作节点状态
SELECT * FROM citus_get_active_worker_nodes();

-- 查看分片分布
SELECT * FROM citus_shards;

使用示例

创建分布式表：

-- 创建表
CREATE TABLE events (
    tenant_id INT,
    event_id BIGSERIAL,
    event_time TIMESTAMPTZ DEFAULT now(),
    payload JSONB,
    PRIMARY KEY (tenant_id, event_id)
);

-- 按 tenant_id 分片
SELECT create_distributed_table('events', 'tenant_id');

-- 插入数据（自动路由到对应分片）
INSERT INTO events (tenant_id, payload)
VALUES (1, '{"type": "click"}');

-- 查询（自动并行执行）
SELECT tenant_id, count(*)
FROM events
GROUP BY tenant_id;

创建引用表（小表复制到所有节点）：

CREATE TABLE tenants (
    tenant_id INT PRIMARY KEY,
    name TEXT
);

SELECT create_reference_table('tenants');

适用场景

多租户 SaaS：按租户 ID 分片，实现租户数据隔离和并行查询
实时分析：大规模事件数据的实时聚合分析
时序数据：结合 TimescaleDB 处理海量时序数据
水平扩展：单表数据量超过单机容量时的扩展方案

注意事项

PostgreSQL 版本：Citus 支持 PostgreSQL 14~18，此模板默认使用 PG18
分布列选择：合理选择分布列（通常是租户 ID 或时间戳）对性能至关重要
跨分片限制：外键约束必须包含分布列，部分 DDL 操作有限制
网络要求：需要配置正确的 pg_vip_interface（默认 eth1）
架构限制：Citus 扩展不支持 ARM64 架构

意见反馈

这个页面对您有帮助吗？

感谢反馈！请告诉我们如何改进。

抱歉给您带来不便。请告诉我们如何改进。

最后修改 2026-01-25: batch doc update (9667d27)