GBase 8a 参数配置全景图：gbase.cnf 核心参数分类详解

GBase 8a 的配置参数分散在 gcluster 和 gnode 两套 gbase.cnf 文件中，参数总数超过数百个，不同参数之间还存在联动关系。本文把核心参数按功能模块分类梳理，解释每个参数的作用机制、典型取值和调整时机，帮助 DBA 建立完整的参数调优知识体系，而不是在遇到问题时靠碰运气改参数。

一、参数文件的组织结构

GBase 8a 的配置文件统一命名为 gbase.cnf，但 gcluster 和 gnode 各自有独立的配置文件，分别控制协调节点和数据节点的行为。两套配置文件的格式相同，但参数的作用范围不同——有些参数只在 gcluster 上生效，有些只在 gnode 上生效，有些两边都需要配置。

区分参数归属的最简单方法是按职能判断：凡是与 SQL 解析、执行计划生成、分布式任务调度、用户连接管理相关的参数，通常在 gcluster 侧配置；凡是与数据存储、列存引擎、内存分配、数据加载相关的参数，通常在 gnode 侧配置。部分参数两边都需要配置，比如字符集、超时时间、审计日志。

gbase.cnf 的配置文件路径通常是 $GCLUSTER_BASE/config/gbase.cnf 和 $GNODE_BASE/config/gbase.cnf。修改配置文件后，需要重启对应的进程才能生效。部分参数支持通过 SET 命令在会话或全局级别动态修改，不需要重启，这类参数会在下文中特别说明。

在生产环境修改配置参数时，强烈建议遵循以下原则：每次只改一个参数；改之前记录原始值；先在测试环境验证效果；生产环境的修改要有审批和回滚方案。参数配置错误导致 gnode 无法启动、或者内存配置错误导致集群 OOM，是完全可以通过规范操作流程来避免的事故。

二、连接与网络参数

连接管理参数控制客户端如何建立和维持与集群的连接，是应用接入时最容易踩坑的一类参数。

max_connections 是单个 gcluster 节点允许的最大并发连接数。这个值直接决定了集群能同时服务多少个客户端。设置时需要考虑应用服务器数量、每台服务器的连接池大小，以及监控、DBA 操作等额外的连接需求。设得太低会导致业务高峰期连接被拒绝；设得太高在连接数真的很多时会占用大量内存（每个连接维护一定的内存状态）。生产环境通常设置在 200 到 1000 之间，根据实际业务并发量调整。

Wait_timeout 和 interactive_timeout 控制空闲连接的超时时间。GBase 8a 和大多数数据库一样，空闲太久的连接会被服务端主动断开，但客户端（尤其是连接池）可能不知道连接已被断开，下次使用时才发现。调低这个值可以更快回收空闲连接资源；但如果应用的连接池没有配置心跳保活，过低的超时值会导致频繁出现"连接已被服务器关闭"的错误。一般设置为 1800 到 3600 秒，同时要求应用连接池开启空闲连接检测。

节点间内部通信的超时参数（gcluster_async_connect_timeout、gcluster_reconn_times）控制 gcluster 与 gnode 之间的连接行为。在网络质量较差的环境中，适当调大超时时间和重连次数可以避免因短暂的网络抖动导致查询失败，但也会让网络真正故障时的检测时间变长。

# gcluster 的 gbase.cnf

# 最大客户端连接数
max_connections                    = 500

# 空闲连接超时（秒）
Wait_timeout                       = 3600
interactive_timeout                = 3600

# 连接超时（TCP 握手）
connect_timeout                    = 10

# 客户端读写超时
gcluster_connect_net_read_timeout  = 3600
gcluster_connect_net_write_timeout = 3600

# 节点间内部连接
gcluster_async_connect_timeout     = 5000   # 毫秒
gcluster_reconn_times              = 3

三、内存参数

内存配置是 GBase 8a 调优中最关键、也最复杂的部分。配置不足会导致大查询 OOM 报错；配置过大会挤占操作系统和其他进程的内存，导致系统层面的 OOM Killer 介入。找到合适的内存配置需要结合机器物理内存大小和实际查询负载来反复调整。

gbase_memory_pct_target 是 gnode 进程占系统物理内存的目标比例，通常设为 0.70 到 0.80（留 20%~30% 给操作系统和 gcluster 进程）。这是内存配置的"总预算"，后续所有内存参数的值加起来不应超过这个总预算。

在总预算内，内存进一步划分为两个大池：gbase_heap_data（普通操作的内存池）和 gbase_heap_large（大操作——排序、Hash Join、大 GROUP BY——的内存池）。这两个参数的单位是 MB，设置时需要根据典型查询的数据量来估算。对于以聚合分析为主的数据仓库，gbase_heap_large 应该设得更大；对于以导入和简单查询为主的场景，gbase_heap_data 和 gbase_heap_large 可以均衡分配。

各操作级缓冲区（gbase_buffer_hj、gbase_buffer_sort、gbase_buffer_hgrby 等）是从大池中进一步分配给特定操作类型的内存配额。这些参数决定了单个 Hash Join 或单个 Sort 操作最多能使用多少内存，超过限制的操作会溢出到磁盘，性能会急剧下降。如果频繁看到 gnode 日志中出现溢出告警，说明对应的缓冲区配置不足，需要适当调大。

# gnode 的 gbase.cnf（以 64GB 物理内存节点为例）

# gnode 使用物理内存的比例（64GB × 0.75 = 48GB）
gbase_memory_pct_target     = 0.75

# 两个内存大池（单位 MB）
gbase_heap_data             = 16384    # 16GB
gbase_heap_large            = 16384    # 16GB

# 操作级缓冲区（单位 MB，从 heap_large 中划拨）
gbase_buffer_hj             = 2048     # Hash Join
gbase_buffer_hgrby          = 1024     # Hash Group By
gbase_buffer_distgrby       = 1024     # 分布式 Group By
gbase_buffer_sort           = 1024     # 排序
gbase_buffer_result         = 512      # 结果集
gbase_buffer_insert         = 512      # 批量插入

# 内存监控（开启后可查 gclusterdb.session_memory_stat）
_gbase_session_memory_stat  = 1

四、并行度参数

并行度参数控制查询执行和数据加载的并发级别，直接影响 CPU 的利用率和多个并发请求之间的资源分配方式。

gbase_parallel_degree 是 gnode 上单个查询片段（Fragment）的内部并行线程数。增大这个值可以让单条查询更充分地利用多核 CPU，但同时也意味着多个并发查询之间的 CPU 竞争加剧。对于以单用户大查询为主的场景（如夜间批处理），可以调高；对于多用户并发场景，应该适当调低，给每个查询留出更均匀的 CPU 配额。

加载相关的并行度参数（gcluster_loader_max_data_processors、gbase_loader_parallel_degree）控制数据导入时的并发级别，在前文的加载优化章节已有详述。这里需要补充的是，加载并行度和查询并行度会共享 CPU 资源，在加载高峰期如果同时有大量查询，可能需要临时降低其中一方的并行度，以避免 CPU 过载。

# gnode 的 gbase.cnf

# 单 Fragment 的并行线程数
gbase_parallel_degree        = 4     # 默认值，按核数调整

# 加载相关并行度
gbase_loader_parallel_degree = 4
gbase_loader_buffer_count    = 4
gbase_loader_read_timeout    = 300

# gcluster 侧的加载并发
gcluster_loader_max_data_processors = 4    # 在 gcluster 的 gbase.cnf 中配置
gcluster_loader_min_chunk_size      = 67108864  # 64MB

五、查询优化器参数

优化器参数控制执行计划的生成策略，是性能调优中最精细、也最需要谨慎对待的一类参数。大部分优化器参数以下划线开头（如 _t_gcluster_...），这表示它们是内部调优参数，在官方文档中可能没有完整说明，需要结合实测结果来判断是否启用。

数据重分布相关的优化器参数控制优化器在何种情况下选择 Hash Redistribute vs Broadcast：gcluster_hash_redist_threshold_row 设定了触发 Broadcast 的行数上限（低于此阈值的表自动广播）；gcluster_hash_redistribute_join_optimize 和 gcluster_hash_redistribute_groupby_optimize 控制是否对 JOIN 和 GROUP BY 启用重分布优化。

COUNT(DISTINCT) 相关的参数（_gbase_optimizer_aggr_distinct、_t_gcluster_agg_distinct_redist_optimize）控制大基数去重聚合时是否启用两阶段处理，在第 17 篇慢 SQL 案例集中已有详细分析。

# gcluster 的 gbase.cnf

# 触发 Broadcast 的行数阈值（低于此值的表自动广播，不做 Redistribute）
gcluster_hash_redist_threshold_row      = 1000000

# JOIN 重分布优化
gcluster_hash_redistribute_join_optimize    = 1
gcluster_hash_redistribute_groupby_optimize = 1

# 慢查询记录阈值（毫秒）
gcluster_dql_statistic_threshold = 3000

# CTE 支持（需 gcluster 和 gnode 同时开启）
_t_gcluster_support_cte = 1

# COUNT DISTINCT 两阶段优化
_gbase_optimizer_aggr_distinct                            = 1
_t_gcluster_agg_distinct_redist_optimize                  = 1
_t_gcluster_agg_distinct_redist_optimize_with_groupby     = 1

六、日志与审计参数

日志参数决定了系统产生什么日志、存在哪里、记录多少。前文"日志体系全解析"已从日志文件的角度详细介绍，这里从参数配置的角度做补充。

日志参数的配置需要在"记录足够的信息供排障使用"和"不产生过多的 I/O 开销拖慢查询"之间找平衡。最常见的错误配置是把 log_level 设为 DEBUG 后忘记改回来，导致日志文件以极快速度增长，最终磁盘写满。建议把 DEBUG 级别的参数修改纳入变更管理，在变更单上注明"排查完成后需恢复 INFO"并设置提醒。

慢查询阈值（long_query_time）的设置需要结合业务的 SLA 要求。如果业务要求所有查询在 5 秒内完成，阈值应该设为 5 秒以下，这样超标的查询都会被记录，方便持续优化。如果阈值设得太高（比如 60 秒），很多影响用户体验的慢查询可能被漏掉。

# gcluster 和 gnode 均需配置的日志参数

log_level          = INFO      # 生产环境标准级别
log_output         = FILE      # FILE 或 TABLE
long_query_time    = 5         # 慢查询阈值（秒）
audit_log          = ON        # 开启审计

# gcluster 侧：节点执行时间统计阈值（毫秒）
gcluster_dql_statistic_threshold = 3000

七、参数调整的正确流程

参数调整不是一次性的工作，而是一个持续迭代的过程。每次调整都应该遵循以下步骤，而不是凭经验一次性把所有参数调到"理论最优值"：

第一步，明确问题和目标。 是查询太慢、还是加载太慢、还是集群经常出现 OOM？不同的问题对应不同的参数组合，没有一套"万能配置"。

第二步，建立基准。 在修改任何参数之前，记录当前的性能数字（查询耗时、加载速度、内存使用率等）作为对比基准。没有基准数据，就无法判断修改是否真的带来了改善。

第三步，每次只改一个参数。 同时修改多个参数后，如果性能变化，无法判断是哪个参数起了作用，也无法判断哪个参数起了负作用。单参数变更是参数调优的基本原则。

第四步，在非生产环境验证。 关键参数（尤其是内存配置）的修改应该先在配置相近的测试环境验证，确认节点能正常启动、查询能正常执行，再推到生产。

第五步，监控变更后的效果。 参数修改上线后，至少观察 24 小时（覆盖一个完整的业务周期），确认在业务高峰期和加载期间都表现正常，再确认变更结束。

以下是最常见的参数调整场景和对应的参数组：