企业官网建设流程全解析

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

导读

RiseDev 是 RisingWave 仓库中内置的一体化开发工具：面向开发者，它是一个能自动构建并拉起全部组件的"游乐场"；面向部署场景，它是一个配置生成器；面向普通用户，它也能启动一个最小化的本地环境。本文将带你完整掌握./risedev的使用方法（如何一键启动集群、调试单个组件、自定义场景与配置），并深入到risedevtool的源码实现，讲清risedev.yml的模板展开、变量展开、通配符展开与组件注入四大阶段，让你既能熟练使用，也能无障碍地为 RiseDev 本身贡献代码。

RiseDev 是什么

根据仓库中的官方文档 src/risedevtool/README.md，RiseDev 在不同角色面前扮演不同身份：

• 开发时：它是一个"游乐场"（playground），自动完成所有组件的构建与引导（bootstrap）；
• 部署时：它是一个配置生成器（config generator），为每个服务生成命令行参数与配置文件；
• 对最终用户：它可以启动一个最小化的本地 playground 环境，快速体验 RisingWave。

整套工具由位于仓库根目录的 risedev 脚本（入口）与 src/risedevtool（核心实现）构成。risedev本身是一个 bash 包装脚本，负责安装cargo-binstall与cargo-make，并把所有命令透传给cargo make执行；risedevtool则是用 Rust 编写的配置解析、展开与各服务任务的具体实现。

使用级指南：如何用 RiseDev 启动与调试集群

一键启动集群与运行 e2e 测试

在仓库根目录下，最简单的用法是：

./risedev d # 默认开发模式 ./risedev <other modes> # 指定其他场景 ./risedev k # 杀掉整个集群

默认场景（default）会启动一个包含meta-node、compute-node、frontend的最小集群；如未配置额外对象存储，meta 元数据默认落在内存中。RiseDev 会自动下载并配置这些服务——第一次运行时，risedev脚本还会先执行cargo make configure-if-not-configured触发配置向导（见 risedev）。

除默认场景外，官方文档还列举了常用模式：

例如：

./risedev dev ci-3cn-1fe ./risedev dev ci-1cn-1fe

实际可用的场景远比上述更多。翻阅 risedev.yml 的profile段可以看到仓库内置了full（MinIO + Postgres 元数据 + 双 compactor + Prometheus/Grafana + Kafka + Lakekeeper）、for-ctl（配合 risectl 使用的最小配置）、full-benchmark、ci-backfill-3cn-1fe等数十个配置；元数据后端还支持memory/sqlite/postgres/mysql多种选择，分别对应meta-1cn-1fe-sqlite、meta-1cn-1fe-pg-backend、meta-1cn-1fe-mysql-backend等场景。

调试单个组件：user-managed 模式

日常开发中常遇到"只想调试一个组件，却需要拉起其他所有组件让它能跑起来"的场景，例如单独调试 compute-node。此时使用dev子命令：

./risedev dev dev-compute-node

你会看到类似输出：

✅ tmux: session risedev ✅ minio: api http://127.0.0.1:9301/, console http://127.0.0.1:9400/ .. compute-node-5688: waiting for user-managed service online... (you should start it!) .. dev cluster: starting 5 services for dev-compute-node...

关键点在于dev-compute-node场景中 compute-node 被标记为user-managed: true，RiseDev 会等待你自己启动这个组件——既可以用cargo run在命令行启动，也可以挂在 CLion 等调试器下断点调试，其余组件（meta-node、frontend、MinIO 等）则由 RiseDev 自动托管。

类似的调试场景还有dev-frontend（frontend 由用户管理）、dev-meta（meta-node 由用户管理）、dev-compactor（compactor 由用户管理），它们与默认场景的区别仅仅是目标组件被标记为user-managed，定义见 risedev.yml。

配置文件 risedev.yml：场景的本质是"组件步骤列表"

risedev.yml定义了所有可用场景。以ci-3cn-1fe为例（实际完整定义见 risedev.yml）：

profile: ci-3cn-1fe: - use: compute-node port: 5687 exporter-port: 1222 - use: compute-node port: 5688 exporter-port: 1223 - use: compute-node port: 5689 exporter-port: 1224 - use: meta-node - use: frontend

RiseDev 会按顺序启动这 5 个服务。use指定服务类型，port: 5687等字段则覆盖该类型的默认配置（默认值定义在template段，例如 compute-node 默认端口为 5688、exporter 端口为 1222，见 risedev.yml）。

如果不需要某个服务，或想调整启动顺序，直接增删或调整步骤即可。例如只要两个 compute-node：

profile: ci-3cn-1fe: - use: compute-node port: 5687 exporter-port: 1222 - use: compute-node port: 5688 exporter-port: 1223 - use: meta-node - use: frontend

如果某些组件（如 Prometheus、Grafana）不想下载，可以运行交互式配置工具：

./risedev configure

其余一切配置（各服务间如何互相连接、Prometheus 抓取哪些目标、meta 如何感知 compute-node 等）都由 RiseDev 自动生成，无需手工维护。

添加自定义场景：profile 与用户场景文件

在risedev.yml的profile段下新增一个键值即可新增内置场景。但更推荐的方式是利用risedev-profiles.user.yml——该文件在首次运行时自动生成，设计上不受版本控制，专门用于存放个人自定义场景。配置解析逻辑会在加载risedev.yml后合并该文件，若出现重名 profile 会直接报错（见 src/risedevtool/src/config.rs）。

此外，profile 还支持两个与steps平级的可选字段：

• config-path：为 RisingWave 组件指定额外的 TOML 配置文件（如src/config/ci.toml）；
• env：为整个场景注入环境变量（如RUST_LOG: "info,risingwave_storage::hummock=off"、ENABLE_PRETTY_LOG: "true"）。

官方文档同时提醒：config-path必须放在 profile 顶层、与steps平级，不能写进某个use步骤内部，否则会被配置展开器直接拒绝（见 src/risedevtool/src/config/use_expander.rs）。

日志与产物都在哪里

• RiseDev 的所有产物存放在仓库根目录的.risingwave文件夹；
• 日志目录中包含所有组件的运行日志；
• RiseDev 用tmux管理所有组件：执行tmux a即可附加到名为risedev的 tmux 会话，看到后台运行的所有组件；
• 每次启动执行的全部命令会记录在.risingwave/log/risedev.log中，便于排查启动问题。

开发级指南：RiseDev 内部机制

组件准备：cargo-make 任务编排

RiseDev 使用cargo-make完成组件下载与构建。首次启动时会弹出配置向导（config wizard），询问需要下载哪些组件；默认开发环境要求安装全部组件。向导把选择结果写入环境文件risedev-components.user.env，典型内容为：

RISEDEV_CONFIGURED=true ENABLE_MINIO=true ENABLE_BUILD_RUST=true

之后 cargo-make 读取这份环境文件，决定是否执行某个任务步骤。实际运行时的输出类似：

[cargo-make] INFO - Skipping Task: check-risedev-configured [cargo-make] INFO - Running Task: download-minio [cargo-make] INFO - Running Task: download-mcli [cargo-make] INFO - Skipping Task: download-grafana [cargo-make] INFO - Skipping Task: download-prometheus [cargo-make] INFO - Running Task: build-risingwave

由于环境文件中没有设置ENABLE_PROMETHEUS_GRAFANA，download-grafana、download-prometheus被跳过；而ENABLE_MINIO=true与ENABLE_BUILD_RUST=true则触发下载 MinIO / mcli 与构建 RisingWave。

所有"下载组件、拷贝配置、构建 RisingWave"的步骤都以 cargo-make 的 TOML 配置描述，分散在 src/risedevtool/*.toml（如 risedevtool/risedev-components.toml 定义了configure/configure-if-not-configured任务）与根目录 Makefile.toml 中。入口脚本 risedev 会在首次运行时通过cargo binstall cargo-make@~0.37自动安装 cargo-make，并把./risedev <args>原样转发为cargo make --allow-private <args>。

配置展开器（Config Expander）

risedev.yml简洁而强大，要修改配置格式或为 RiseDev 贡献代码，就必须理解它的展开机制。核心源码位于 src/risedevtool/src/config。

ConfigExpander::expand的完整流水线（见 src/risedevtool/src/config.rs）依次执行：

1. 加载根目录risedev.yml（全局配置），若存在则合并risedev-profiles.user.yml；
2. 取出目标 profile 的config-path、env、steps；
3. UseExpander（模板展开）→DollarExpander（变量展开）→IdExpander（通配符展开）→ProvideExpander（组件注入）；
4. 最后deserialize将展开后的 YAML 反序列化为ServiceConfig列表。

RiseDev 支持的use类型非常丰富，在反序列化时按字符串分发（见 config.rs），除 RisingWave 自身的meta-node、compute-node、frontend、compactor外，还包括minio、sqlite、postgres、mysql、kafka、pulsar、pubsub、redis、clickhouse、mongodb、elasticsearch、opensearch、nats、mqtt、schema-registry、lakekeeper、moto、moat等周边依赖组件，以及opendal、aws-s3等存储后端。

获取 VS Code 悬停提示：JSON Schema

RiseDev 配置文件的 JSON Schema 定义在 src/risedevtool/schemas（risedev.json、risedev-profiles.user.json、profile.json）。在.vscode/settings.json中加入以下配置，即可在编辑risedev.yml与risedev-profiles.user.yml时获得字段悬停提示与校验：

"yaml.schemas": { "src/risedevtool/schemas/risedev.json": "risedev.yml", "src/risedevtool/schemas/risedev-profiles.user.json": "risedev-profiles.user.yml" }

模板展开（Template Expanding）

risedev.yml有template与profile两个顶层段：template定义每个组件的默认配置，profile定义场景。以下面为例：

template: compute-node: address: "127.0.0.1" port: 5688 exporter-address: "127.0.0.1" exporter-port: 1222 id: compute-node-${port} provide-minio: "minio*" user-managed: false profile: ci-3cn-1fe: - use: compute-node port: 5687 exporter-port: 1222

UseExpander会把 profile 中的use: compute-node替换为模板中该类型的完整配置，再用用户提供的字段覆盖模板中的同名默认值（源码实现见 use_expander.rs）。展开结果为：

template: compute-node: address: "127.0.0.1" port: 5688 exporter-address: "127.0.0.1" exporter-port: 1222 id: compute-node-${port} provide-minio: "minio*" user-managed: false profile: ci-3cn-1fe: - use: compute-node address: "127.0.0.1" exporter-address: "127.0.0.1" id: compute-node-${port} provide-minio: "minio*" user-managed: false port: 5687 exporter-port: 1222

可以看到模板中的port（5688）与exporter-port（1222）被用户提供的 5687 / 1222 覆盖（本例恰好相同）；而模板未定义的键（如可选字段）也会被保留拼接，若最终无法反序列化为合法的ServiceConfig会被拒绝。

变量展开（Variable Expanding）

展开到 profile 层后，${port}这类变量由DollarExpander处理（实现见 dollar_expander.rs）。它用正则\$\{(.*?)\}匹配，变量的取值优先查找当前 YAML map 中的同名字段，找不到时再回退到extra_info（外部传入的附加变量）：

ci-3cn-1fe: - use: compute-node address: "127.0.0.1" exporter-address: "127.0.0.1" id: compute-node-${port} provide-minio: "minio*" user-managed: false port: 5687 exporter-port: 1222

展开后：

ci-3cn-1fe: - use: compute-node address: "127.0.0.1" exporter-address: "127.0.0.1" id: compute-node-5687 provide-minio: "minio*" user-managed: false port: 5687 exporter-port: 1222

id: compute-node-${port}中的${port}取当前 map 的port: 5687，得到compute-node-5687。这也是 template 中id: compute-node-${port}的默认写法能自动生成唯一实例 ID 的原因。

通配符展开（Wildcard Expanding）

*通配符由IdExpander基于场景内所有组件的 id 列表展开（实现见 id_expander.rs）。例如 frontend 配置：

frontend: address: "127.0.0.1" port: 4567 id: frontend provide-compute-node: "compute-node*" provide-meta-node: "meta-node*" user-managed: false

对ci-3cn-1fe（有 3 个 compute-node）展开为：

- use: frontend address: "127.0.0.1" port: 4567 id: frontend provide-compute-node: ["compute-node-5687", "compute-node-5688", "compute-node-5689"] provide-meta-node: ["meta-node-5690"] user-managed: false

实现上，IdExpander先把*前后部分拼成正则^前缀(.*)后缀$，再逐一匹配场景中所有 id，命中的 id 组成字符串数组。仓库自带单测覆盖了通配匹配与多实例匹配两种情形（见 id_expander.rs）。

组件注入（Component Provision）

最后，ProvideExpander把所有provide-*字段展开为对应组件的完整配置（实现见 provide_expander.rs）。上一步得到的 id 数组此时会被替换为按 id 找到的完整服务配置，同时从被注入的配置中剥离其自身的provide-*字段以避免无限嵌套：

- address: 127.0.0.1 port: 4567 id: frontend provide-compute-node: - address: 127.0.0.1 exporter-address: 127.0.0.1 id: compute-node-5687 user-managed: false use: compute-node port: 5687 exporter-port: 1222 - address: 127.0.0.1 exporter-address: 127.0.0.1 id: compute-node-5688 user-managed: false use: compute-node port: 5688 exporter-port: 1223 - address: 127.0.0.1 exporter-address: 127.0.0.1 id: compute-node-5689 user-managed: false use: compute-node port: 5689 exporter-port: 1224

至此，frontend 拿到了完整的 compute-node 列表（地址、端口、exporter 端口等），后续生成前端连接参数、Prometheus 抓取配置、meta-node 注册信息等就有了全部依据。

基于这份展开后的配置，RiseDev 会为每个服务生成启动所需的命令行参数或配置文件——这一层由 src/risedevtool/src/config_gen 实现，其中包含 prometheus_gen.rs、grafana_gen.rs、tempo_gen.rs 等针对监控组件的配置生成器。例如 Prometheus 的抓取目标、Grafana 的数据源、Tempo 的链路采集地址都由这些生成器基于展开后的ServiceConfig计算得出。

RiseDev Service：按顺序启动与存活检查

RiseDev 开发集群读取展开后的配置，按步骤顺序启动所有服务，任务运行在 tmux 会话中。启动过程的关键约束：

• 每个服务的启动任务实现位于 src/risedevtool/src/task，包括 compute-node、meta-node、frontend、compactor、minio、kafka、prometheus、grafana、mysql、postgres、redis、pulsar、mqtt 等几十个具体服务的启动逻辑；
• 启动每个服务后，RiseDev 都会执行**存活检查（liveness check）**并检查程序返回码，确保服务真正进入可用状态（如task_tcp_ready_check.rs、task_kafka_ready_check.rs、task_db_ready_check.rs、task_redis_ready_check.rs等 readiness 任务）；
• 所有由 RiseDev 执行过的命令都可以在.risingwave/log/risedev.log中找到；
• user-managed组件（如dev-compute-node场景中的 compute-node）不会被 RiseDev 启动，而是等待用户自行启动后通过存活检查确认上线。

从源码看 RiseDev 的整体结构

小结

RiseDev 的设计思路可以概括为一句话：一份声明式 YAML（场景 + 模板），经过"模板展开 → 变量展开 → 通配符展开 → 组件注入"四步标准化处理，反序列化为强类型服务配置，再生成各服务启动参数，最后由 tmux 托管、按序拉起并做存活检查。日常使用时，你只需记住三个命令——./risedev d启动、./risedev <profile>选场景、./risedev k停止；要调试单个组件时，把对应组件标记为user-managed并用./risedev dev <profile>启动其余部分即可。需要更深入地扩展场景时，将自定义配置写入risedev-profiles.user.yml，或者直接阅读 src/risedevtool 的源码与单测，理解四个展开器的行为后再动手修改配置格式。

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