openGemini.conf 配置项详细解释文档

openGemini.conf 是 openGemini 分布式时序数据库的主配置文件，采用 TOML 格式，分为多个配置段（section），每个段下有若干参数用于控制集群、存储、网络、日志、安全、性能等行为。本文档基于最新源码和样例配置文件，系统梳理各配置项的作用、类型、默认值、可选值及适用场景，便于开发者查阅和理解。

[common] 通用配置#

• meta-join
  类型：字符串数组
  说明：指定 Meta 节点的地址列表，集群启动时用于发现和连接元数据服务。
  示例：meta-join = ["127.0.0.1:8092", "127.0.0.2:8092"]
  必填项，至少配置一个有效地址。

• ha-policy
  类型：字符串
  说明：高可用策略。可选值包括 write-available-first（优先写可用分片）、shared-storage（共享存储）、replication（主从复制）。
  默认值：write-available-first
  适用场景：根据实际部署架构选择。

• cpu-num
  类型：整数
  说明：指定进程可用的 CPU 核数。为 0 时自动检测。
  默认值：0

• memory-size
  类型：字符串（如 "8G"）
  说明：进程可用的最大内存。为 0 时自动检测。
  默认值：0

• ignore-empty-tag
  类型：布尔
  说明：是否忽略空标签。
  默认值：false

• report-enable
  类型：布尔
  说明：是否开启集群状态上报。
  默认值：true

• node-role
  类型：字符串
  说明：节点角色，可选 reader、writer 或空（自动分配）。
  默认值：空

• product-type
  类型：字符串
  说明：产品类型，通常为空或设置为 logkeeper。
  默认值：空

• pre-agg-enabled
  类型：布尔
  说明：是否记录预聚合信息到元数据。
  默认值：true

• pprof-enabled
  类型：布尔
  说明：是否开启性能分析（pprof）接口。
  默认值：true

• global-dict-files
  类型：字符串数组
  说明：全局字典文件列表，主要用于优化标签压缩。

[meta] 元数据服务配置#

• bind-address
  类型：字符串
  说明：Meta 服务监听地址。
  默认值："127.0.0.1:8088"

• http-bind-address
  类型：字符串
  说明：Meta HTTP 服务监听地址。
  默认值："127.0.0.1:8091"

• rpc-bind-address
  类型：字符串
  说明：Meta RPC 服务监听地址。
  默认值："127.0.0.1:8092"

• dir
  类型：字符串
  说明：Meta 数据存储目录。
  默认值：/tmp/openGemini/data/meta/{id}

• expand-shards-enable
  类型：布尔
  说明：是否开启分片扩容。
  默认值：false

• retention-autocreate
  类型：布尔
  说明：是否自动创建保留策略。
  默认值：true

• election-timeout、heartbeat-timeout、leader-lease-timeout、commit-timeout
  类型：字符串（时间间隔）
  说明：Raft 选举、心跳、租约、提交等超时时间。
  默认值：分别为 "1s"、"1s"、"500ms"、"50ms"

• cluster-tracing
  类型：布尔
  说明：是否开启集群追踪。
  默认值：true

• logging-enabled
  类型：布尔
  说明：是否开启日志。
  默认值：true

• lease-duration
  类型：字符串（时间间隔）
  说明：租约持续时间。
  默认值："1m0s"

• meta-version
  类型：整数
  说明：Meta 数据版本号。
  默认值：0

• split-row-threshold
  类型：整数
  说明：分片行数阈值，超过则自动分裂。
  默认值：10000

• imbalance-factor
  类型：浮点数
  说明：分片负载不均衡因子。
  默认值：0.3

• auth-enabled
  类型：布尔
  说明：是否开启 Meta 层认证。
  默认值：false

• https-enabled、https-certificate、https-private-key
  类型：布尔 / 字符串
  说明：是否开启 HTTPS 及证书路径配置。

• ptnum-pernode
  类型：整数
  说明：每节点分片数。
  默认值：1

• balance-algorithm-version
  类型：字符串
  说明：分片均衡算法版本。可选 "v1.0"（串行）、"v1.1"（并行，默认）。
  默认值："v1.1"

[http] HTTP 服务配置#

• bind-address
  类型：字符串
  说明：HTTP 服务监听地址。
  默认值："127.0.0.1:8086"

• flight-address
  类型：字符串
  说明：Flight 服务监听地址（用于高性能数据传输）。
  默认值："127.0.0.1:8087"

• flight-enabled
  类型：布尔
  说明：是否开启 Flight 服务。
  默认值：false

• auth-enabled
  类型：布尔
  说明：是否开启 HTTP 层认证。
  默认值：false

• max-connection-limit
  类型：整数
  说明：最大连接数限制。
  默认值：0（不限制）

• max-concurrent-write-limit、max-concurrent-query-limit
  类型：整数
  说明：最大并发写入 / 查询数。
  默认值：0

• max-body-size
  类型：整数
  说明：HTTP 请求体最大字节数。
  默认值：0

• https-enabled、https-certificate、https-private-key
  类型：布尔 / 字符串
  说明：是否开启 HTTPS 及证书路径配置。

• max-row-size-limit
  类型：整数
  说明：单行最大字节数限制。
  默认值：0

• max-line-size
  类型：整数
  说明：单行最大长度。
  默认值：65536

• [http.result-cache]
  说明：结果缓存相关配置，包括是否启用、缓存新鲜度、类型、分片间隔、缓存大小等。

[data] 存储引擎配置#

• store-ingest-addr、store-select-addr
  类型：字符串
  说明：数据写入 / 查询服务监听地址。
  默认值："127.0.0.1:8400"、"127.0.0.1:8401"

• store-data-dir、store-wal-dir、store-meta-dir
  类型：字符串
  说明：数据、WAL、Meta 存储目录。
  默认值：/tmp/openGemini/data 等

• enable-mmap-read
  类型：布尔
  说明：是否启用 mmap 方式读取数据文件。
  默认值：false

• write-concurrent-limit
  类型：整数
  说明：最大并发写入数。
  默认值：0

• open-shard-limit
  类型：整数
  说明：最大并发打开分片数。
  默认值：0

• readonly
  类型：布尔
  说明：是否只读模式。
  默认值：false

• downsample-write-drop
  类型：布尔
  说明：写入降采样数据时是否丢弃。
  默认值：true

• max-series-per-database
  类型：整数
  说明：每数据库最大时序数。0 表示不限制。

• enable_query_file_handle_cache
  类型：布尔
  说明：是否启用查询文件句柄缓存。
  默认值：true

• max_query_cached_file_handles
  类型：整数
  说明：最大缓存文件句柄数。
  默认值：0（自动计算）

• lazy-load-shard-enable
  类型：布尔
  说明：是否启用分片懒加载。
  默认值：true

• thermal-shard-start-duration、thermal-shard-end-duration
  类型：字符串（时间间隔）
  说明：热分片时间范围。
  默认值："0s"

• interrupt-query
  类型：布尔
  说明：是否自动中断占用资源过高的查询。
  默认值：true

• interrupt-sql-mem-pct
  类型：整数
  说明：SQL 查询内存占用阈值（百分比）。
  默认值：85

• proactive-manager-interval
  类型：字符串（时间间隔）
  说明：主动管理内存检查间隔。
  默认值："100ms"

• temporary-index-compress-mode
  类型：整数
  说明：临时索引文件压缩算法。0：不压缩，1：snappy。
  默认值：0

• chunk-meta-compress-mode
  类型：整数
  说明：TSSP 文件 ChunkMeta 压缩算法。0：不压缩，1：snappy，2：lz4，3：自编码。
  默认值：0

• index-read-cache-persistent
  类型：布尔
  说明：索引读缓存关闭时是否持久化到磁盘。
  默认值：false

• string-compress-algo
  类型：字符串
  说明：字符串类型数据压缩算法。可选 snappy、lz4、zstd。
  默认值："snappy"

• unordered-only
  类型：布尔
  说明：是否全部按无序数据处理。
  默认值：false

• enable-write-history-ordered-data
  类型：布尔
  说明：是否允许有序历史数据写入。
  默认值：false

• availability-zone
  类型：字符串
  说明：可用区标识。
  默认值："az1"

• clear-entryLog-tolerate-time
  类型：字符串（时间间隔）
  说明：节点故障时清理 entry log 的容忍时间。
  默认值："10h"

• clear-entryLog-tolerate-size
  类型：字符串（如 "10G"）
  说明：强制清理 entry log 的最大容忍大小。
  默认值："10G"

• float-compress-algorithm
  类型：字符串
  说明：浮点数压缩算法。空为默认，mlf 为乘法无损压缩。

子段配置（如 [data.wal]、[data.memtable]、[data.compact]、[data.readcache] 等）#

详见样例配置文件注释，涵盖 WAL、内存表、压缩、读缓存等高级参数。

[data.merge] 数据合并配置#

• merge-self-only
  类型：布尔
  说明：是否仅合并无序数据自身。
  默认值：false

• max-unordered-file-number
  类型：整数
  说明：每次合并的最大无序文件数。
  默认值：64

• max-unordered-file-size
  类型：字符串（如 "8g"）
  说明：每次合并的最大无序文件总大小。
  默认值："8g"

• min-interval
  类型：字符串（时间间隔）
  说明：强制合并的最小间隔。
  默认值："300s"

• max-merge-self-level
  类型：整数
  说明：低层级文件优先自合并的最大层级。
  默认值：0

• stream-merge-mode-level
  类型：整数
  说明：高层级文件自合并采用流式合并的层级。
  默认值：2

[data.hot-mode] 热数据缓存配置#

• enabled
  类型：布尔
  说明：是否开启热数据缓存。
  默认值：false

• memory-allowed-percent
  类型：整数
  说明：热数据缓存允许占用的系统内存百分比。
  默认值：5

• duration
  类型：字符串（时间间隔）
  说明：热数据时间窗口。
  默认值："1h"

• time-window
  类型：字符串（时间间隔）
  说明：批量转换热数据为温数据的时间窗口。
  默认值："60s"

• max-file-size
  类型：字符串（如 "2g"）
  说明：缓存的最大文件大小。
  默认值："2g"

• pool-object-cnt
  类型：整数
  说明：内存池最大对象数。
  默认值：2

• max-cache-size
  类型：字符串（如 "1g"）
  说明：本地最大缓存大小。
  默认值："1g"

[logging] 日志配置#

• format
  类型：字符串
  说明：日志格式。可选 auto、json、console。
  默认值："auto"

• level
  类型：字符串
  说明：日志级别。可选 info、debug、warn、error。
  默认值："info"

• path
  类型：字符串
  说明：日志文件存储路径。
  默认值：/tmp/openGemini/logs/{id}

• max-size
  类型：字符串（如 "64m"）
  说明：单个日志文件最大大小。
  默认值："64m"

• max-num
  类型：整数
  说明：日志文件最大数量。
  默认值：16

• max-age
  类型：整数
  说明：日志文件最大保存天数。
  默认值：7

• compress-enabled
  类型：布尔
  说明：是否启用日志压缩。
  默认值：true

[gossip] Gossip 协议配置#

• enabled
  类型：布尔
  说明：是否启用 Gossip 协议。
  默认值：true

• log-enabled
  类型：布尔
  说明：是否记录 Gossip 日志。
  默认值：true

• bind-address
  类型：字符串
  说明：Gossip 服务监听地址。
  默认值："127.0.0.1"

• store-bind-port、meta-bind-port、sql-bind-port
  类型：整数
  说明：Store、Meta、SQL 服务端口。
  默认值：8011、8010、8012

• prob-interval
  类型：字符串（时间间隔）
  说明：探测间隔。
  默认值："400ms"

• suspicion-mult
  类型：整数
  说明：怀疑倍数。
  默认值：4

• members
  类型：字符串数组
  说明：Gossip 集群成员地址列表。

[continuous_queries] 连续查询配置#

• enabled
  类型：布尔
  说明：是否启用连续查询服务。
  默认值：true

• run-interval
  类型：字符串（时间间隔）
  说明：检查连续查询是否需要运行的间隔。
  默认值："1s"

• max-process-CQ-number
  类型：整数
  说明：并发执行连续查询的最大 goroutine 数。
  默认值：0（自动计算）

[hierarchical_storage] 分层存储配置#

• enabled
  类型：布尔
  说明：是否启用分层存储服务。
  默认值：false

• run-interval
  类型：字符串（时间间隔）
  说明：分层存储检查间隔。
  默认值："1m"

• max-process-HS-number
  类型：整数
  说明：分片迁移最大并发数。
  默认值：1

[runtime-config] 动态配置加载#

• enabled
  类型：布尔
  说明：是否启用运行时配置加载。
  默认值：false

• load-path
  类型：字符串
  说明：动态配置文件路径。
  默认值：/opt/dbs/runtimeconfig/overrides.yml

• reload-period
  类型：字符串（时间间隔）
  说明：动态配置自动重载周期。
  默认值："10s"

[limits] 限流与约束配置#

• prom-limit-enabled
  类型：布尔
  说明：是否启用 Prometheus 写入限流。
  默认值：false

• max-label-name-length
  类型：整数
  说明：标签名最大长度。
  默认值：1024

• max-label-value-length
  类型：整数
  说明：标签值最大长度（包括 metric 名）。
  默认值：2048

• max-label-names-per-series
  类型：整数
  说明：单条时序最大标签数。
  默认值：30

• max-metadata-length
  类型：整数
  说明：元数据最大长度（Metric Name、HELP、UNIT）。
  默认值：1024

• reject-old-samples
  类型：布尔
  说明：是否拒绝过旧样本。
  默认值：false

• reject-old-samples-max-age
  类型：字符串（时间间隔）
  说明：最大允许样本年龄。
  默认值："14d"

• creation-grace-period
  类型：字符串（时间间隔）
  说明：表创建 / 删除的宽限期，超期样本不被接受。
  默认值："10m"

• enforce-metadata-metric-name
  类型：布尔
  说明：是否强制每个样本必须有 metric name。
  默认值：true

• enforce-metric-name
  类型：布尔
  说明：是否强制每个元数据必须有 metric name。
  默认值：true

• max-query-length
  类型：字符串（时间间隔）
  说明：查询最大允许时长。
  默认值："0"（不限制）

[record-write] 批量写入服务配置#

• enabled
  类型：布尔
  说明：是否启用 record.Record 批量写入服务。
  默认值：true

• auth-enabled
  类型：布尔
  说明：是否启用用户名 / 密码认证。
  默认值：false

• shelf-mode
  类型：布尔
  说明：是否启用 shelf 写入模式。
  默认值：false

• rpc-address
  类型：字符串
  说明：批量写入服务 RPC 监听地址。
  默认值："127.0.0.1:8305"

• max-message-size
  类型：整数（字节）
  说明：最大消息大小（默认 4MB）。
  默认值：4194304

[record-write.TLS] 批量写入 TLS 配置#

• enabled
  类型：布尔
  说明：是否启用 TLS。
  默认值：false

• mTLS-enabled
  类型：布尔
  说明：是否启用双向 TLS。
  默认值：false

• key-file、cert-file、CA-root
  类型：字符串
  说明：TLS 密钥、证书、CA 根证书路径。

其他配置段#

openGemini.conf 还包含如 [monitor]（监控）、[spdy]（高性能网络）、[castor]（算法）、[sherlock]（诊断）、[clv_config]（分词）、[io-detector]（IO 检测）、[spec-limit]（查询约束）、[subscriber]（订阅）等高级或扩展配置，详见样例配置文件注释及源码结构体定义。

配置项使用建议#

• 推荐根据实际部署规模和业务场景调整如存储路径、端口、并发数、内存 / CPU 限制等参数。
• 安全相关参数（如认证、TLS）建议在生产环境开启并正确配置证书。
• 日志、监控、限流等参数有助于提升运维可观测性和系统稳定性。
• 高级参数如分层存储、热数据缓存、批量写入等可根据业务需求灵活启用。

如需了解各参数的详细默认值、类型约束和最新变更，建议参考 openGemini.conf 样例文件 及源码 lib/config 目录。