企业官网建设流程全解析

StarRocks 集群升级完全指南：从版本路径规划到滚动升级实战

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

本篇技术指南以 StarRocks 官方部署文档《Upgrade StarRocks》为骨架，系统讲解 StarRocks 集群的版本体系与升级路径、升级顺序与兼容性配置、以及 BE / CN / FE 三类节点的滚动升级完整实操步骤。结合本仓库中的 FE 配置源码（Config.java）与官方 SQL 参考文档，帮助读者在掌握可复制的升级命令之外，理解升级背后"BE/CN 向后兼容 FE"的设计原理与各个配置项的真实作用。

升级前必读：版本、路径与核心原则

理解 StarRocks 版本号

StarRocks 版本号采用Major.Minor.Patch（主版本.次版本.补丁版本）三段式表示，例如2.5.4：

• 第一个数字代表主版本（Major）；
• 第二个数字代表次版本（Minor）；
• 第三个数字代表补丁版本（Patch）。

CAUTION

无法将已有的 shared-nothing（存算一体）集群升级为 shared-data（存算分离）集群，反之亦然。两者架构差异巨大，必须重新部署一套新的 shared-data 集群。

三条升级路径规则

• 补丁版本升级：允许跨补丁版本直接升级，例如从 v2.2.6 直接升级到 v2.2.11。
• 次版本升级：从 StarRocks v2.0 起，允许跨次版本升级（例如从 v2.2.x 直接升级到 v2.5.x），但出于兼容性与安全性考虑，官方强烈建议逐次版本连续升级：v2.2.x → v2.3.x → v2.4.x → v2.5.x。
• 主版本升级：要升级到 v3.0，必须先将集群升级到 v2.5。

连续升级与失败回退场景的元数据保护

CAUTION

如果需要进行连续的次版本升级（如 2.4 → 2.5 → 3.0 → 3.1 → 3.2），或者升级失败后降级、随后再次尝试升级（如 2.5 → 3.0 → 2.5 → 3.0），为防止部分 Follower FE 发生元数据升级失败，必须在两次连续升级之间、或降级后再次升级之前，执行以下两步：

1. 执行 ALTER SYSTEM CREATE IMAGE 创建新的 image（元数据镜像）；
2. 等待新 image 同步到所有 Follower FE。

可以通过查看 Leader FE 的fe.log日志确认 image 是否同步完成。出现类似如下记录即表示同步成功：

push image.* from subdir [] to other nodes. totally xx nodes, push successful xx nodes

关于降级后的再次升级场景，可一并参阅本仓库中的 downgrade.md（降级操作本身是升级的逆序：先降 FE，再降 BE 与 CN）。

升级顺序：先 BE/CN，后 FE

StarRocks 支持滚动升级（rolling upgrade），即升级过程中无需停止服务。其设计原则是BEs 和 CNs 向后兼容 FEs，因此升级顺序必须是：

1. 先升级BE与CN；
2. 再升级FE。

如果颠倒顺序，新 FE 与旧 BE/CN 之间可能产生不兼容，进而导致服务崩溃。对于 FE 节点，还必须先升级所有 Follower FE，最后升级 Leader FE。

升级前准备：兼容性配置与可用性测试

正式开始升级前，需要完成两类准备：兼容性配置（次版本/主版本升级必须执行）与升级可用性测试（先在单个 FE 和 BE 上验证）。

通用兼容性配置：暂停 tablet 调度与均衡

升级前必须禁用 tablet 克隆（clone）。如果你已经禁用了 balancer，可以跳过此步骤。执行以下 SQL：

ADMIN SET FRONTEND CONFIG ("tablet_sched_max_scheduling_tablets" = "0"); ADMIN SET FRONTEND CONFIG ("tablet_sched_max_balancing_tablets" = "0"); ADMIN SET FRONTEND CONFIG ("disable_balance"="true"); ADMIN SET FRONTEND CONFIG ("disable_colocate_balance"="true");

升级完成、且所有 BE 节点状态均为Alive后，重新启用 tablet 克隆：

ADMIN SET FRONTEND CONFIG ("tablet_sched_max_scheduling_tablets" = "10000"); ADMIN SET FRONTEND CONFIG ("tablet_sched_max_balancing_tablets" = "500"); ADMIN SET FRONTEND CONFIG ("disable_balance"="false"); ADMIN SET FRONTEND CONFIG ("disable_colocate_balance"="false");

这些配置项在源码中的定义：以上四个动态配置均可通过ADMIN SET FRONTEND CONFIG在线修改，其默认值与含义定义于 FE 的 Config.java：

• tablet_sched_max_scheduling_tablets = 10000：TabletScheduler 中排队的调度 tablet 数量超过该阈值时跳过检查；
• tablet_sched_max_balancing_tablets = 500：TabletScheduler 中排队的均衡 tablet 数量上限；
• tablet_sched_disable_balance（别名为disable_balance，默认false）：置为true时 TabletScheduler 不再执行均衡操作；
• tablet_sched_disable_colocate_balance（别名为disable_colocate_balance，默认false）：置为true时 ColocateTableBalancer 不再对 Colocate 表执行迁移与均衡。

升级期间将这些调度阈值归零并关闭两类均衡，是为了避免版本切换过程中 tablet 调度/克隆任务与 FE 元数据变更相互干扰，保证升级期间集群状态的稳定。

从 v2.0 升级到更高版本的专属配置

如果你是从 StarRocks v2.0 升级，还必须额外设置以下 BE 配置与系统变量：

1. 如果你修改过 BE 配置项vector_chunk_size，必须在升级前将其恢复为4096。由于它是静态参数，需要修改 BE 配置文件be.conf并重启节点才能生效。
2. 将系统变量batch_size全局设置为小于等于4096：

SET GLOBAL batch_size = 4096;

vector_chunk_size在 BE 侧对应config::vector_chunk_size，它决定向量化执行引擎每次处理的 chunk 行数，与查询层batch_size变量相互配合；保持两者一致可避免新旧版本间执行协议与数据块大小的不匹配（BE 侧源码可见于 be/src/bench 系列基准测试对config::vector_chunk_size的引用）。

其他前置检查

• 阅读目标版本发布说明（release notes）：升级前必须阅读目标版本、以及当前版本到目标版本之间所有版本的发布说明，重点记录：行为变更（behavior changes）、以及 StarRocks 与外部系统（导入、导出、可视化等）集成方式的变化。
• 核对目标版本的部署前置条件：参见 deployment_prerequisites.md。例如 StarRocks 3.5.x 要求 JDK 17，StarRocks 3.4.x 在 Ubuntu 上要求 JDK 11（当前仓库文档中 v3.3/v3.4 使用 JDK 11 或更高，v3.5 及以后使用 JDK 17 或更高，且不支持 JRE）。

升级 BE 节点

通过可用性测试后，即可开始升级集群中的 BE 节点。

1. 进入 BE 工作目录并停止节点

# 将 <be_dir> 替换为 BE 节点的部署目录 cd <be_dir>/be ./bin/stop_be.sh

2. 用新版本文件替换 bin 与 lib 目录

mv lib lib.bak mv bin bin.bak cp -r /tmp/StarRocks-x.x.x/be/lib . cp -r /tmp/StarRocks-x.x.x/be/bin . # 如果旧版本中使用了自定义函数（UDF），需要将旧版本的 UDF 目录复制到新的 lib 目录 cp -r lib.bak/udf lib/

3. 启动 BE 节点

./bin/start_be.sh --daemon

4. 检查 BE 是否启动成功

ps aux | grep starrocks_be

5. 重复以上步骤升级其余 BE 节点。

提示：本仓库对应的启动脚本位于 bin/start_be.sh，--daemon参数表示以守护进程方式后台启动。mv保留旧目录为.bak而非删除，是为了在升级异常时能够快速回退到旧版本文件。

升级 CN 节点

计算节点（CN）的升级流程与 BE 基本一致，区别在于使用独立的启停脚本，并建议优雅停止。

1. 进入 CN 工作目录并优雅停止节点

# 将 <cn_dir> 替换为 CN 节点的部署目录 cd <cn_dir>/be ./bin/stop_cn.sh --graceful

2. 用新版本文件替换 bin 与 lib 目录

mv lib lib.bak mv bin bin.bak cp -r /tmp/StarRocks-x.x.x/be/lib . cp -r /tmp/StarRocks-x.x.x/be/bin . # 如果旧版本中使用了自定义函数（UDF），需要将旧版本的 UDF 目录复制到新的 lib 目录 cp -r lib.bak/udf lib/

3. 启动 CN 节点

./bin/start_cn.sh --daemon

4. 检查 CN 是否启动成功

ps aux | grep starrocks_be

5. 重复以上步骤升级其余 CN 节点。

升级 FE 节点

当所有 BE 与 CN 节点升级完成后，再升级 FE 节点。注意顺序：先升级所有 Follower FE，最后升级 Leader FE。

1. 进入 FE 工作目录并停止节点

# 将 <fe_dir> 替换为 FE 节点的部署目录 cd <fe_dir>/fe ./bin/stop_fe.sh

2. 用新版本文件替换 bin、lib 与 spark-dpp 目录

FE 相比 BE/CN 多了一个spark-dpp目录，同样需要替换为对应新版本。

mv lib lib.bak mv bin bin.bak mv spark-dpp spark-dpp.bak cp -r /tmp/StarRocks-x.x.x/fe/lib . cp -r /tmp/StarRocks-x.x.x/fe/bin . cp -r /tmp/StarRocks-x.x.x/fe/spark-dpp .

3. 启动 FE 节点

./bin/start_fe.sh --daemon

4. 检查 FE 是否启动成功

ps aux | grep StarRocksFE

5. 重复以上步骤升级其他 Follower FE 节点，最后升级 Leader FE 节点。

升级完成后的收尾

• 确认集群中所有 BE 节点状态均为Alive（可在 FE 的 Web UI 或通过SHOW BACKENDS查看）；
• 重新执行"通用兼容性配置"中的恢复语句，将tablet_sched_max_scheduling_tablets恢复为10000、tablet_sched_max_balancing_tablets恢复为500，并将disable_balance、disable_colocate_balance置回false，恢复 tablet 克隆与均衡能力；
• 如果升级过程中执行过ALTER SYSTEM CREATE IMAGE创建元数据镜像，可在确认升级稳定后继续观察 fe.log 确认 Follower FE 同步正常；
• 若升级后出现异常，可参考 downgrade.md 按逆序（先 FE 后 BE/CN）降级回原版本以快速恢复服务。

核心要点速查

按照本文的顺序完成兼容性配置、可用性测试、BE/CN 先行升级与 FE 的 Follower 优先升级，即可在不中断业务的前提下，安全地将 StarRocks 集群滚动升级到目标版本。

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks