Apache Cloudberry 配置参数详解

目标：系统梳理 Apache Cloudberry 2.1.0 的配置参数体系——哪些参数在 postgresql.conf、哪些是 MPP 专属的 gp_* 参数、如何用 gpconfig 在 Coordinator 与 Segment 上统一查看与修改、gp_segment_configuration 系统表怎么读，并给出可直接套用的生产配置模板。本文参数值与回显均取自 Apache Cloudberry 2.1.0-incubating（PostgreSQL 14.4 内核）单机集群实测。

一、环境信息

说明：Cloudberry 基于 PostgreSQL，绝大多数 PG 原生 GUC 仍然有效；此外还有大量 gp_ 前缀的 MPP 专属参数（实测 pg_settings 中共 118 个 gp_* 参数）。配置分两层：PG 原生参数延续 PG 语义，gp_* 参数控制分发、互联、Mirror 副本、资源管理等分布式行为。

二、前置条件

阅读与操作本文需要一套已初始化的 Cloudberry 集群，并能以 gpadmin 用户登录 Coordinator。

sudo -iu gpadmin
source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
psql -d postgres -c "SELECT version();"

实测回显：

                                                                                             version
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 PostgreSQL 14.4 (Apache Cloudberry 2.1.0-incubating build bdf90c5518f) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.2) 11.4.0, 64-bit compiled on Apr 27 2026 11:21:44
(1 row)

解读：能查到版本说明集群可连；COORDINATOR_DATA_DIRECTORY 让 gpconfig/gpstate 等工具免去每次 -d 指定路径。

三、参数查看与修改方式

Cloudberry 的参数遍布 Coordinator 与所有 Segment 实例，逐台改 postgresql.conf 不现实，官方提供 gpconfig 一次性读写全集群。

3.1 用 gpconfig 查看参数

gpconfig -s max_connections
gpconfig -s shared_buffers

实测回显：

Values on all segments are consistent
GUC              : max_connections
Coordinator value: 250
Segment     value: 750
Values on all segments are consistent
GUC              : shared_buffers
Coordinator value: 125MB
Segment     value: 125MB

解读：gpconfig -s 分别打印 Coordinator 与 Segment 上的取值；max_connections 是典型的「两角色取值不同」参数，shared_buffers 则两角色一致。Values on all segments are consistent 表示各 Segment 取值统一。

3.2 用 gpconfig 修改参数

gpconfig -c gp_vmem_protect_limit -v 4096

解读：-c 指定参数名、-v 指定新值；若某参数需要在 Coordinator 上取不同值，追加 -m <Coordinator值>。修改后写入各实例的 postgresql.conf，需重启或重载生效。

3.3 生效方式

gpstop -u          # 重载配置（仅对 context 允许 reload 的参数有效）
gpstop -a && gpstart -a   # 完整重启（对 postgresql.conf 中需重启的参数生效）

解读：gpstop -u 执行 pg_ctl reload，只对「sighup」级参数生效；shared_buffers/max_connections 等标注 (change requires restart) 的参数必须完整重启。

3.4 用 SQL 查看参数

SHOW max_connections;
SELECT name, setting, unit FROM pg_settings WHERE name LIKE 'gp_%' ORDER BY name;

实测回显（SHOW max_connections）：

 max_connections
-----------------
 250
(1 row)

解读：SHOW 查当前会话所属实例的运行时取值；pg_settings 可一次性列出全部参数（本文第四、五章的数据即来自此系统表）。

四、参数总览

实测 pg_settings 中共有 118 个 gp_* 参数。下表列出最常用的分类与真实默认值。

解读：gp_* 参数按功能可分为「内存保护、互联、优化器、统计、资源管理、故障探测、存储」几大类。生产中最常调的是 gp_vmem_protect_limit、max_connections、shared_buffers、gp_interconnect_type 四类。

五、核心参数分类详解

本节按功能分组逐项说明每个核心参数的含义、默认值与调整影响。

5.1 连接与内存参数

这个子节聚焦「一个实例能吃多少内存、能接多少连接」。Cloudberry 每台主机上会跑多个 Segment 进程，因此单实例内存参数要按「主机内存 ÷ Segment 数」估算。

Coordinator 上的 postgresql.conf 关键行（实测）：

port=5432 ##port = 5432                              # sets the database listener port for
max_connections = 250                        # (change requires restart)
shared_buffers = 125MB                      # min 128kB
max_prepared_transactions = 250             # can be 0 or more
dynamic_shared_memory_type = posix  # the default is the first option

逐项解读：

• port=5432：Coordinator 监听端口；Segment 端口由 gpinitsystem 按 PORT_BASE 分配（6000/6001），逐实例不同。
• max_connections = 250：Coordinator 的最大并发连接数。每个客户端连接会在每个 Segment 上派生对应进程，Segment 侧默认 750，是 Coordinator 的 3 倍经验值。
• shared_buffers = 125MB：单实例共享缓冲区。建议为单实例可用内存的 1/4 左右；本机 2 个 Primary + 2 个 Mirror 共享物理内存，故取小值。
• max_prepared_transactions = 250：两阶段提交的事务上限，用于跨 Segment 的分布式事务；必须 ≥ max_connections。
• dynamic_shared_memory_type = posix：动态共享内存实现，取 posix（基于 /dev/shm），保证并行查询的算子内存可用。

查看运行时值：

SHOW shared_buffers;
SHOW work_mem;

实测回显：

 shared_buffers
----------------
 125MB
(1 row)

 work_mem
----------
 32MB
(1 row)

解读：work_mem=32MB 是每个排序/哈希等算子的内存上限，一条复杂查询可能同时开多个算子，故生产大查询场景要谨慎放大。

5.2 内存保护参数

MPP 最大的运行风险是「一条大查询把所有 Segment 内存打满」，Cloudberry 通过虚拟内存保护参数在超额时拒绝新算子而非 OOM。

# - Resource limits -
gp_vmem_protect_limit = 8192  #Virtual memory limit (in MB).
#gp_vmem_idle_resource_timeout = 18000 # idle-time before gang-release, in milliseconds (zero disables release).

逐项解读：

• gp_vmem_protect_limit = 8192：单个 Segment 实例可用的虚拟内存上限（单位 MB）。超过则查询报 out of memory 而不是让整机崩溃。经验公式：(主机内存 - 系统预留) / 单机 Segment 数，并留出安全余量。
• gp_vmem_idle_resource_timeout = 18000：空闲 gang 释放超时（毫秒），默认 18 秒。

查看：

gpconfig -s gp_vmem_protect_limit

实测回显：

Values on all segments are consistent
GUC              : gp_vmem_protect_limit
Coordinator value: 8192
Segment     value: 8192

5.3 互联（Interconnect）参数

Segment 之间的数据交换（Motion 算子）走 Interconnect，gp_interconnect_type 决定传输协议。

💡 技术拓展：Cloudberry 段间互联协议——

类型	传输	特点	适用场景
udpifc（默认）	UDP	有流控与 ACK，性能好，[实测默认]	一般生产环境
tcp	TCP	可靠但带宽利用率较低	UDP 被禁用的网络
udp	UDP	无流控，易丢包	极少使用

本文实测默认即 udpifc（UDP + 流控 + 可靠传输），是官方推荐值。

#gp_max_packet_size = 8192
gp_interconnect_type=udpifc
#gp_segment_connect_timeout = 180s

逐项解读：gp_interconnect_type=udpifc 为默认互联协议；gp_max_packet_size=8192（字节）为 Interconnect 数据包上限；gp_segment_connect_timeout=180s 为连接 Segment 的超时。

实测相关取值：

SHOW gp_interconnect_type;
SELECT name, setting, unit FROM pg_settings WHERE name IN ('gp_segment_connect_timeout','gp_interconnect_queue_depth','gp_max_packet_size');

实测回显（SHOW gp_interconnect_type）：

 gp_interconnect_type
----------------------
 udpifc
(1 row)

5.4 查询优化器参数

Cloudberry 内置 GPORCA 优化器（针对分布式环境）与传统 PG 规划器，optimizer 开关决定是否启用 ORCA。

SHOW optimizer;

实测回显：

 optimizer
-----------
 on
(1 row)

逐项解读：optimizer=on 表示启用 GPORCA，能对分布式 join/聚合生成更优计划；实测执行计划中显示 Optimizer: GPORCA（见《Apache Cloudberry 常用 CLI 命令与工具详解》的 EXPLAIN 示例）。相关参数（实测默认）：

5.5 资源管理参数

Cloudberry 支持「资源队列（resource queue）」与「资源组（resource group）」两套资源管理机制。

💡 技术拓展：Cloudberry 资源管理模式——

模式	参数值	机制	适用场景
资源队列	gp_resource_manager=queue（[实测默认]）	基于队列的并发/内存限额，按队列分配	传统 GP 迁移、简单限额
资源组	gp_resource_manager=group	基于 cgroup 的 CPU/内存隔离	需要强隔离的多租户

本文实测默认为 queue；若需按 cgroup 精细隔离 CPU/内存，可切换为 group（须先配置系统 cgroup）。

SHOW gp_resource_manager;
SELECT name, setting FROM pg_settings WHERE name LIKE 'gp_resqueue%';

实测回显（SHOW gp_resource_manager）：

 gp_resource_manager
---------------------
 queue
(1 row)

相关参数（实测默认）：gp_resqueue_memory_policy=eager_free、gp_resqueue_priority=on、gp_resqueue_priority_cpucores_per_segment=4。

5.6 故障探测（FTS）参数

FTS（Fault Tolerance Service）周期性探测 Segment 健康并在主段故障时触发 Mirror 提升。

解读：探测越频繁故障发现越快，但对系统开销也越大；默认 60s 间隔适合大多数场景，调小需评估负载。

5.7 存储与统计参数

SHOW gp_autostats_mode;
SELECT name, setting FROM pg_settings WHERE name IN ('gp_default_storage_options','gp_autostats_mode','gp_create_table_random_default_distribution');

实测回显（SHOW gp_autostats_mode）：

 gp_autostats_mode
-------------------
 none
(1 row)

逐项解读：

• gp_autostats_mode = none：关闭自动统计收集——Cloudberry 默认不自动 ANALYZE，需 DBA 手动或定期 ANALYZE，避免大表自动化统计带来的抖动。
• gp_default_storage_options = blocksize=32768,compresstype=none,checksum=true：建表默认块大小 32KB、无压缩、开启校验和。
• gp_create_table_random_default_distribution = off：建表未指定分布键时默认按第一个列 hash 分布（off），而非随机分布。

六、生产配置模板

以下模板按「单机 2 Primary + 2 Mirror、32 GiB 内存、SSD、分析型 OLAP」场景给出，参数值需结合机器规格调整。

解读：内存类参数按「单机内存 ÷ 实例数」分档最重要；本机 32 GiB 跑 2 Primary + 2 Mirror，单实例 shared_buffers 取 125MB、gp_vmem_protect_limit 取 8192MB。若主机内存升到 64 GiB 且只跑 1 个 Primary，可显著放大这两项。改完后用 gpstop -u 重载或 gpstop -a && gpstart -a 重启生效。

七、常见问题

Q1：gpconfig -s 与 psql 里的 SHOW 取到的值不一致，信哪个？

现象：gpconfig -s 显示某参数 Coordinator/Segment 不同，psql 里 SHOW 只有一个值。定位：gpconfig -s 读的是各实例 postgresql.conf 的配置文件值；SHOW 读的是当前会话所在实例的运行时值（含 SET 覆盖）。解法：确认目标——看持久配置用 gpconfig -s（--file 可看文件原文），看当前生效用 SHOW；两者不一致通常是某会话做过 SET 或参数改名后未重载。

Q2：改完参数执行 gpstop -u 后不生效，为什么？

现象：gpconfig -c 改了参数，gpstop -u 重载后值未变。定位：gpstop -u 等同 pg_ctl reload，只对 sighup 级参数生效；shared_buffers/max_connections 等标注 (change requires restart) 的参数必须完整重启。解法：

gpstop -a && gpstart -a

Q3：如何确认某个 gp_* 参数在某实例上的真实默认值？

现象：不确认参数默认值，怕改错。定位：pg_settings 系统表同时给出当前值与默认值。解法：

SELECT name, setting, boot_val, unit FROM pg_settings WHERE name = 'gp_vmem_protect_limit';

解读：setting 为当前生效值，boot_val 为编译默认值。

八、参考链接

• Apache Cloudberry 官网：https://cloudberry.apache.org/
• Apache Cloudberry 文档（系统配置）：https://cloudberry.apache.org/docs/sys-admin/configure-database-system
• Apache Cloudberry 文档（gpconfig）：https://cloudberry.apache.org/docs/next/sys-utilities/gpconfig
• Apache Cloudberry 文档（单机与系统参数）：https://cloudberry.apache.org/docs/deployment/single-node
• PostgreSQL 14 参数参考：https://www.postgresql.org/docs/14/runtime-config.html