企业官网建设流程全解析

• 数据库
• 流处理
• 后端
• 数据工程

risingwave.toml是 RisingWave 集群的静态配置文件，通过命令行参数--config-path注入各节点（Meta、Frontend、Compute/Streaming、Compactor 等），并与源码内置默认值叠加生效。本文以src/config/README.md为骨架，结合src/config/example.toml、src/config/docs.md以及src/common/src/config/mod.rs中的真实定义，系统讲解配置文件的结构、加载与覆盖规则、RiseDev 集成方式，并逐分区解读核心配置项，帮助你为开发、测试与生产部署写出准确、可复用的risingwave.toml。

RisingWave 配置系统概述

RisingWave 的配置体系由两部分组成：

• 静态配置（本文主题）：risingwave.toml文件，由节点进程在启动时读取，贯穿其整个生命周期。
• 动态系统参数（System Parameters）：可通过 SQL（如ALTER SYSTEM SET）在线调整，定义见 src/common/src/session_config/。

risingwave.toml的加载遵循一个简单而重要的规则：

1. 如果没有指定配置文件，进程使用 src/common/src/config/mod.rs 中定义的源码默认值；
2. 如果通过--config-path指定了配置文件，则文件中出现的条目会覆盖源码中的默认值，未出现的条目仍取默认值。

也就是说，risingwave.toml是一个“增量覆盖”文件，你不需要写出全部配置项，只需写与你运行环境相关的部分。源码注释与docs.md中列出的“Default”列就是未覆盖时的取值。

配置文件的权威定义与生成

配置文件结构与每个分区的默认值，都定义在RwConfig及各个子配置结构体中，源码位于 src/common/src/config/，包括：

• mod.rs —RwConfig顶层结构，对应整个文件；
• server.rs —[server]分区；
• meta.rs —[meta]分区及[meta.compaction_config]、[meta.meta_store_config]等；
• batch.rs —[batch]分区；
• frontend.rs —[frontend]分区及hba_config；
• streaming.rs —[streaming]分区；
• storage.rs —[storage]分区及缓存、文件缓存、对象存储等子分区；
• system.rs —[system]分区；
• udf.rs —[udf]分区。

在源码中，RwConfig的每个字段都标注了#[serde(default)]，并对应一个带默认值的子结构体（见 mod.rs）。这正是“未配置则回落默认值”机制的实现基础：配置文件经 serde 反序列化后与默认结构合并。

提示：原文档中提到的src/common/src/config.rs，在仓库中实际以src/common/src/config/目录 +mod.rs的形式组织，即上述路径。

仓库维护者使用./risedev generate-example-config命令从源码结构自动生成两份文档：

• src/config/example.toml — 带默认值的完整配置示例；
• src/config/docs.md — 每个配置项的说明与默认值表格（自动生成，逐条注释来自源码#[config_doc]宏与字段 doc 注释）。

这两份文件与源码始终同步，是你查询“某个配置项是否可用、默认值是什么”的第一手资料。

通过 --config-path 加载配置文件

RisingWave 各节点（risingwave meta、risingwave compute、risingwave frontend、risingwave compactor、risingwave standalone等）都支持在启动时传入配置文件：

risingwave meta --config-path /path/to/risingwave.toml risingwave compute --config-path /path/to/risingwave.toml risingwave frontend --config-path /path/to/risingwave.toml

传入的配置文件会被对应节点加载，并覆盖 src/common/src/config/mod.rs 中的默认值。由于RwConfig是统一的结构定义，集群中各节点共享同一套配置 schema，实践中通常给所有节点传入同一份risingwave.toml，节点各自消费其中与自身相关的分区。

在 RiseDev 中指定配置

RiseDev（./risedev，配置见 risedev.yml）是 RisingWave 的本地开发工具。要在risedev dev <profile>启动的开发集群中应用自定义配置，只需在对应 profile 下配置config-path字段：

risedev: profile-name: config-path: src/config/ci.toml steps: - use: ...

RiseDev 会在启动时把该文件复制到工作目录（默认.risingwave/）并重命名为risingwave.toml，随后各节点自动通过--config-path加载它。

这一机制在仓库的 risedev.yml 中有大量真实用例。例如：

• CI 常规测试 profile 使用config-path: src/config/ci.toml；
• 恢复测试 profile 使用config-path: src/config/ci-recovery.toml；
• 会话初始化测试使用config-path: src/config/ci-session-init.toml；
• 时态旅行测试使用config-path: src/config/ci-time-travel.toml；
• 更长流式上传超时测试使用config-path: src/config/ci-longer-streaming-upload-timeout.toml。

正如 src/config/README.md 所说，config/目录下定义的配置文件主要用于测试与开发场景，你需要根据自己的开发环境（例如内存大小、是否开启某些实验特性）创建合适的副本。

risingwave.toml 顶层结构与完整示例

risingwave.toml是一个 TOML 文件，顶层包含 9 个分区（对应RwConfig的 9 个字段）：

其中meta、batch、streaming、storage还带有更深层的子分区（如[meta.compaction_config]、[storage.cache]、[storage.object_store]等）。完整带默认值的示例见 src/config/example.toml，下面是最常用的骨架：

[server] heartbeat_interval_ms = 1000 # 工作节点向 Meta 发送心跳的间隔 connection_pool_size = 16 # 连接 gRPC 服务器的默认连接数 metrics_level = "Info" # 指标级别，类似日志级别 telemetry_enabled = true # 是否启用遥测 [meta] backend = "Mem" # Meta 存储后端："Mem"/"Sql" 等 min_sst_retention_time_sec = 21600 # Hummock 全量 GC 保留 SST 的最小时间 full_gc_interval_sec = 3600 # Hummock 全量 GC 间隔 vacuum_interval_sec = 30 # 清理过期元数据的 vacuum 间隔 default_parallelism = "Full" # 流式作业的默认全局并行度 partition_vnode_count = 16 # 每个 split group 的 vnode 分区数 [batch] enable_spill = true # 批查询是否允许溢写到磁盘 statement_timeout_in_sec = 3600 # 批查询超时（秒） max_total_query_size_bytes = 1073741824 # 运行中查询的总内存约束 distributed_query_limit = "" # 每个 SQL 会话的最大查询数（"" 表示不限制） [frontend] stream_flush_threshold_bytes = 65536 # 流式 pgwire 响应的 flush 阈值字节数 unsafe_enable_local_fs_connector = false # 是否允许本地文件系统 connector [streaming] in_flight_barrier_nums = 10000 # 每个局部图的最大 pending barrier 数 snapshot_backfill_finish_max_lagged_barriers = 100 [storage] write_conflict_detection_enabled = true # 写冲突检测 block_cache_capacity_mb = "" # block cache 容量（MB，覆盖见下） meta_cache_capacity_mb = "" [system] barrier_interval_ms = 1000 # 周期 barrier 间隔 checkpoint_frequency = 1 # 每 N 个 barrier 做一次 checkpoint sstable_size_mb = 256 # SST 目标大小 state_store = "" # 状态存储 URL data_directory = "" # 数据对象存储目录 time_travel_retention_ms = 600000 # 时间旅行数据保留期 [udf] enable_embedded_python_udf = false enable_embedded_javascript_udf = true enable_embedded_wasm_udf = true [session_init] streaming_parallelism = "" # 会话初始化时的流式并行度

各分区核心配置项详解

以下配置项的完整说明与默认值均来自自动生成的 src/config/docs.md，可按需查阅原文。

[server]：节点通用设置

[meta]：Meta 节点调度与维护

[meta]是配置项最丰富的分区，覆盖压缩（compaction）、GC、恢复、并行度控制与 CDC 建表初始化等：

• 存储与 GC：min_sst_retention_time_sec（21600，GC 对悬挂 SST 的最低保留时间）、full_gc_interval_sec（3600，全量 GC 间隔）、full_gc_object_limit（100000，单轮 GC 拉取的对象上限）、gc_history_retention_time_sec（21600）、vacuum_interval_sec（30，清理过期元数据）、vacuum_spin_interval_ms（100，vacuum 内部自旋间隔，避免独占 Meta 资源）。
• 压缩调度：periodic_compaction_interval_sec（300，周期动态压缩）、periodic_space_reclaim_compaction_interval_sec（3600）、periodic_ttl_reclaim_compaction_interval_sec（1800）、periodic_tombstone_reclaim_compaction_interval_sec（600）。
• 压缩组分裂/合并：partition_vnode_count（16）、hybrid_partition_vnode_count（4）、split_group_size_limit（68719476736）、split_group_size_ratio（0.9）、table_high_write_throughput_threshold（16777216）、table_low_write_throughput_threshold（4194304）、table_write_throughput_retention_seconds（300）。注意table_stat_*系列与table_info_statistic_history_times已标记为 deprecated。
• 恢复与并行度控制：disable_recovery（false，仅 e2e 测试用）、disable_automatic_parallelism_control（false，自适应扩缩容开关）、parallelism_control_batch_size（10）、parallelism_control_trigger_period_sec（10）、parallelism_control_trigger_first_delay_sec（30）、default_parallelism（"Full"，作业未指定并行度时的全局默认值，也支持具体数字）、actor_cnt_per_worker_parallelism_soft_limit/hard_limit（100/400，位于[meta.developer]）。
• checkpoint 与时间旅行：hummock_version_checkpoint_interval_sec（30）、checkpoint_compression_algorithm（"zstd"）、checkpoint_read_chunk_size（134217728，大 checkpoint 并行分块读取的块大小）、checkpoint_read_max_in_flight_chunks（4，内存占用 = chunk_size × 并发数）、hummock_time_travel_snapshot_interval（100）、max_inflight_time_travel_query（1000）。
• CDC 建表初始化：cdc_table_split_init_insert_batch_size（100）、cdc_table_split_init_sleep_duration_millis（500）、cdc_table_split_init_sleep_interval_splits（1000），用于在写入元存储时分批、间歇，避免压垮上游系统。
• 其他：meta_leader_lease_secs（30）、max_heartbeat_interval_secs（60）、dangerous_max_idle_secs（""，空闲退出，主要用于 playground）、pause_on_next_bootstrap_offline（false，单机/standalone 场景离线暂停数据源）、enable_legacy_table_migration（true）、enable_compaction_deterministic（false，仅 e2e 测试用）。

[meta.compaction_config]子分区定义 LSM 压缩策略参数，例如max_bytes_for_level_base（536870912）、max_bytes_for_level_multiplier（10）、max_compaction_bytes（2147483648）、level0_tier_compact_file_number（12）、target_file_size_base（33554432）、max_sub_compaction（4）、max_level（6）、sstable_filter_type（默认["xor16", ...]）、sstable_filter_layout（默认["auto", "blocked", ...]）等。

[meta.meta_store_config]子分区配置 Meta 存储连接池：max_connections（10）、min_connections（1）、connection_timeout_sec（10）、idle_timeout_sec（30）、acquire_timeout_sec（30）。

[batch] 与 [batch.developer]：批处理查询

[batch.developer]下的chunk_size（1024）、output_channel_size（64）、receiver_channel_size（1000）、root_stage_channel_size（100）、local_execute_buffer_size（64）等控制批处理执行通道与 chunk 粒度；exchange_connection_pool_size未指定时回落到server.connection_pool_size。

[frontend]：前端查询与认证

• hba_config：Host-based 认证配置，支持connection_type（Local/Host）、databases、users、addresses、auth_method（如trust、password）。示例 src/config/example.toml 中默认一条 Local/trust 加一条 Host/password：

  [[frontend.hba_config.entries]] connection_type = "Local" databases = ["all"] users = ["all"] auth_method = "trust" [[frontend.hba_config.entries]] connection_type = "Host" databases = ["all"] users = ["all"] addresses = ["0.0.0.0/0"] auth_method = "password"

• stream_flush_threshold_bytes：65536，流式 pgwire 响应的 flush 阈值；0表示每行都 flush。单个 pgwire 消息是原子编码的，可能超过该阈值。
• unsafe_enable_local_fs_connector：默认 false。允许posix_fs、fs等本地文件系统 connector（可访问 Frontend 主机文件，生产构建默认关闭；debug 构建默认开启便于本地开发）。
• webhook_auth_max_clock_skew_ms：300000，WebSocket ingest 初始化认证允许的最大时钟偏差。

[streaming] 与 [streaming.developer]：流式执行

• in_flight_barrier_nums：10000，每个局部图最多 pending 的 barrier 数（含 in-flight、已收集未提交、正在完成的 barrier）。
• snapshot_backfill_finish_max_lagged_barriers：100，快照回填作业合并进主图时允许的最大滞后 barrier 数。
• snapshot_backfill_barrier_amplification_factor：1，快照回填局部图 barrier 限制的放大系数（0 视为 1）。
• actor_runtime_worker_threads_num：""，流式 actor 运行时线程数，默认由 tokio 决定。
• async_stack_trace："ReleaseVerbose"，为 risectl 启用的 async 栈跟踪。
• unique_user_stream_errors：10，每个 actor 允许的最大用户流错误数。

[streaming.developer]是另一个大型子分区，重点包括：

• 缓存与执行通道：chunk_size（256）、exchange_initial_permits（2048）、exchange_batched_permits（256）、exchange_concurrent_barriers（1）、dml_channel_initial_permits（32768）、exchange_connection_pool_size（1，未指定时回落server.connection_pool_size）。
• 内存控制器：memory_controller_threshold_aggressive/graceful/stable（0.9/0.81/0.72）、对应eviction_factor（2.0/1.5/1.0）、memory_controller_update_interval_ms（100）。
• backfill：enable_arrangement_backfill（true，已弃用但作为默认回退回填方式）、enable_snapshot_backfill（true，与会话变量streaming_use_snapshot_backfill联动）、snapshot_iter_rebuild_interval_secs（600）。
• Join 与聚合：hash_join_entry_state_max_rows（30000）、join_hash_map_evict_interval_rows（16）、join_encoding_type（"memory_optimized"）、hash_agg_max_dirty_groups_heap_size（67108864）、high_join_amplification_threshold（2048）、high_gap_fill_amplification_threshold（2048）。
• schema change 与共享源：enable_auto_schema_change（true）、enable_shared_source（true，与会话变量streaming_use_shared_source联动）、switch_jdbc_pg_to_native（false）。
• 状态表预加载：default_enable_mem_preload_state_table（false）、mem_preload_state_table_ids_whitelist/blacklist（[]）。
• cache 预填充策略：cache_refill_policy（"enabled"，可取值enabled/disabled/streaming/serving/both）。
• Iceberg 流式相关：iceberg_list_interval_sec（10）、iceberg_fetch_batch_size（1024）、iceberg_sink_positional_delete_cache_size（1024）、iceberg_sink_write_parquet_max_row_group_rows（100000）。

[storage] 及其子分区：Hummock 存储

[storage]控制 Hummock 存储引擎的缓存、文件缓存、压缩与对象存储访问，是生产调优的重点。

• 共享缓冲区：shared_buffer_capacity_mb（""，显式指定共享缓冲区容量；仅当block_cache_capacity_mb与meta_cache_capacity_mb也显式设置、且三者之和不超过非保留内存 30% 时生效）、shared_buffer_flush_ratio（0.8，容量使用率超过该比例开始向对象存储刷盘）、shared_buffer_min_batch_flush_size_mb（800，spill 的最小批量大小）、share_buffers_sync_parallelism（1，不能为 0）、share_buffer_compaction_worker_threads_number（4）、share_buffer_upload_concurrency（8）、imm_merge_threshold（0）。
• 缓存（[storage.cache]）：block_cache_capacity_mb、meta_cache_capacity_mb（顶层同名配置项已标记 deprecated，应使用此子分区），以及block_cache_shard_num、meta_cache_shard_num（默认根据容量自动决定）、vector_block_cache_capacity_mb（16）、vector_meta_cache_capacity_mb（16）与各缓存的 eviction 算法（默认Lru）。
• 本地文件缓存（[storage.data_file_cache]与[storage.meta_file_cache]）：dir（默认空，不启用磁盘缓存）、capacity_mb（1024）、file_capacity_mb（64）、flushers（4）、reclaimers（4）、recover_mode（"Quiet"，可取值None/Quiet/Strict）、blob_index_size_kb（16，修改会失效已有缓存数据）、direct_io（false）及[storage.data_file_cache.throttle]的 IO 限流（write_iops、read_iops、write_throughput、read_throughput）。
• 压缩器：disable_remote_compactor（false）、compactor_memory_limit_mb（""）、compactor_memory_available_proportion（0.8）、compactor_max_task_multiplier（3.0，max_pull_task_count = worker_num × multiplier）、max_concurrent_compaction_task_number（16）、compactor_max_sst_size（536870912）、compactor_max_sst_key_count（2097152）、enable_fast_compaction（true）、check_compaction_result（false）、compactor_fast_max_compact_task_size（2147483648）、compactor_max_overlap_sst_count（64）、compactor_max_preload_meta_file_count（32）。
• 对象存储（[storage.object_store]）：upload_part_size（16777216）、opendal_upload_concurrency（256）、req_concurrency_limit（0）以及[storage.object_store.retry]的完整重试/超时矩阵（如upload_attempt_timeout_ms=8000、upload_retry_attempts=3、read_attempt_timeout_ms=8000、list_attempt_timeout_ms=600000 等），还有 S3 专属的[storage.object_store.s3]（keepalive_ms=600000、nodelay=true 等）。
• Iceberg 压缩（[storage]下iceberg_compaction_*系列）：例如iceberg_compaction_memory_limit_mb（""）、iceberg_compaction_task_parallelism_ratio（4.0）、iceberg_compaction_pull_interval_ms（5000）、iceberg_compaction_max_pull_task_count（1）、iceberg_compaction_enable_prefetch（false，开启后每个输入文件用单次顺序读替代 N+1 次 range read，降低对象存储 API 调用但提高峰值内存）。
• 其他：write_conflict_detection_enabled（true）、mem_table_spill_threshold（4194304）、max_cached_recent_versions_number（60）、max_version_pinning_duration_sec（10800）、min_sst_size_for_streaming_upload（33554432）、min_sstable_size_mb（32）、sst_skip_bloom_filter_in_serde（false）、shorten_block_meta_key_threshold（""）。

[system]：系统级参数

[udf] 与 [session_init]

• [udf]：嵌入式 UDF 开关。enable_embedded_python_udf默认 false，enable_embedded_javascript_udf与enable_embedded_wasm_udf默认 true。
• [session_init]：会话初始化时的流式并行度，覆盖全局默认。streaming_parallelism默认""（等效default，保留传统自适应调度行为）；还有streaming_parallelism_for_backfill、_for_table、_for_sink、_for_index、_for_source、_for_materialized_view等细分项，未指定时分别回落全局STREAMING_PARALLELISM。

配置优先级与覆盖行为总结

综合 src/config/README.md 与源码实现，配置生效的优先级是：

1. risingwave.toml中显式指定的条目（通过--config-path或 RiseDev 注入）——最高；
2. 源码中的默认值（定义在 src/common/src/config/ 各结构体的default函数）——兜底；
3. 运行时可通过ALTER SYSTEM SET覆盖的动态系统参数（src/common/src/session_config/）——针对流式并行度等少量可在线调整的项。

由于RwConfig反序列化时对未出现的字段直接保留默认值（#[serde(default)]），一个空配置文件与完全不传配置文件等价。这也意味着：

• 配置文件中写错分区名或字段名不会生效（unrecognized字段被扁平化收集，见 mod.rs），因此建议基于 src/config/example.toml 修改，而不是手写；
• 同一份文件可同时用于多个节点，各节点只读取与自身相关的分区。

开发与测试场景的既有配置模板

src/config/目录本身就是一套现成的模板库，主要面向 CI 测试与本地开发（src/config/README.md 明确说明这一点）。常用模板包括：

调试时可以直接./risedev dev <profile>后修改.risingwave/risingwave.toml再重启节点，或者新建自己的 profile 并在 risedev.yml 中设置config-path。若要为一个新需求（如调整共享缓冲区容量、开启 cache 预填充、启用嵌入式 UDF）快速验证配置效果，建议先对比 src/config/example.toml 与 src/config/docs.md 中对应字段的默认值与约束说明（例如shared_buffer_capacity_mb的三条件生效规则），再写入配置。

小结

risingwave.toml是 RisingWave 静态配置的唯一入口，采用“显式条目覆盖源码默认值”的增量模型。理解RwConfig的 9 大分区结构（src/common/src/config/mod.rs）、掌握--config-path与 RiseDevconfig-path两种注入方式、并善用自动生成的 src/config/example.toml 与 src/config/docs.md 两份参考文档，就能针对开发、CI 测试与生产部署写出准确且可维护的配置。后续遇到任何“某个参数默认值是什么、是否已弃用、在何种条件下生效”的问题，都应优先以这三份源码/文档为准。

• 数据库
• 流处理
• 后端
• 数据工程