StarRocks 版本命名规范与软件包命名规则全解-平芜编程栈

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 的版本号采用MAJOR.MINOR.PATCH[-PRERELEASE]三段式结构，软件发布包则遵循StarRocks-x.y.z[-rcxx]-os-arch.tar.gz的命名约定。本文以官方版本命名文档为核心，系统讲解主版本、次版本、补丁版本与预发布版本（Release Candidate）的语义划分，并结合仓库中的构建脚本、运行时版本查询实现与发布记录，说明版本号如何从构建环境注入到二进制产物、如何通过 SQL 与命令行查看，以及如何正确解读和选用发布包。

版本号三段式结构：`MAJOR.MINOR.PATCH[-PRERELEASE]`

StarRocks 对正式发布版本统一采用如下格式：

MAJOR.MINOR.PATCH[-PRERELEASE]

其中PRERELEASE用于标识预发布版本的类型与序号。各段位的具体含义如下：

MAJOR（主版本）

当发生不兼容的 API 变更，或产品的整体战略发生重大调整时，主版本号递增。升级主版本通常意味着需要关注破坏性变更，例如接口、协议或行为模式的重大改动，升级前应仔细阅读对应的发布说明。

MINOR（次版本）

当以向后兼容的方式新增功能时，次版本号递增。典型场景包括：增加新特性、能力增强，但不会破坏当前主版本下的 API 或软件的核心行为模式。例如 StarRocks 的3.3、3.4等版本线即属于此范畴。

PATCH（补丁版本）

当进行向后兼容的缺陷修复时，补丁版本号递增。这通常对应 Bug 修复或小幅改进，不影响软件的主要功能与 API。例如3.4.1、3.4.2都是针对3.4.0的补丁版本。

PRERELEASE（预发布标识）

在版本号后追加预发布标识，表示该构建面向早期采用者进行测试。预发布标识会标明预发布版本的序号，例如rc01、rc02。目前 StarRocks 唯一使用的预发布标签是rc后跟两位数字（如rc01）。

:::note 注意 Release Candidate（候选发布版）仅为初始次版本和主版本构建。例如3.4.0-rc01、4.0.0-rc01；也就是说，补丁版本（如3.4.1）通常不会再出-rc01预发布包。 :::

版本号实例解读

官方文档给出了三个典型样例，可直接对照理解：

版本号	含义
`3.4.0`	正式发布版本（GA 版本）
`3.4.0-rc01`	`3.4.0`的第一个预发布版本。例如`3.3`版本线也曾发布过第二个预发布版本`3.3.0-rc02`
`3.4.1`、`3.4.2`	Bug 修复版本（补丁版本）

从仓库的 release_notes 目录也可以验证这一规律：例如 release-3.4.md 中按3.4.0、3.4.1 (Yanked)、3.4.2、3.4.3……3.4.10的顺序罗列了各补丁版本的行为变更与修复项，其中3.4.1 (Yanked)还标注了“被撤回”的状态——这说明补丁版本虽小，但发布流程同样遵循严格的评审与回溯机制。

软件包命名规则

软件发布包的命名约定为：

StarRocks-x.y.z[-rcxx]{-os}{-arch}.tar.gz

即主形式为Product-version-os-arch，各组成部分说明如下：

x.y.z：遵循上述三位版本号规则；-rcxx为可选的预发布版本号，如-rc01、-rc02。
OS（操作系统）：目前包括ubuntu、centos，必填。
ARCH（CPU 架构）：目前为amd64，必填（截至本文档编写时，社区版暂未提供arm64构建包）。

软件包命名示例

StarRocks-3.4.0-rc01-ubuntu-amd64.tar.gz：3.4.0的预发布版本，面向 Ubuntu Linux 构建。
StarRocks-3.4.1-centos-amd64.tar.gz：面向 Red Hat Enterprise Linux / CentOS 构建的 PATCH 补丁版本。

命名细节提示：预发布标识位于版本号之后、操作系统标识之前；下载部署时请根据自身操作系统（Ubuntu 或 CentOS/RHEL）与 CPU 架构（amd64）精确匹配包名，避免误用。

从源码看版本号如何被注入与输出

版本号不仅是发布包的“标签”，它还会在构建阶段被写入二进制产物，并在运行时通过多种途径暴露给用户。以下链条均可在当前仓库中验证。

构建阶段：环境变量驱动的版本生成

在 gensrc/script/Makefile 中，gen_version目标会调用build-support/gen_build_version.py生成版本信息文件：

gen_version: ${PYTHON} ${CURDIR}/../../build-support/gen_build_version.py --cpp ${BUILD_DIR}/gen_cpp

而 gen_build_version.py 的核心逻辑是：通过get_version()读取环境变量STARROCKS_VERSION（未设置时回退为"UNKNOWN"），并采集 commit hash、构建类型、构建时间、构建用户、构建主机、发行版信息（解析/etc/os-release）与 CPU 架构（platform.uname().machine），分别生成：

C++ 侧：be/src/common/version.h（见 version.h）中声明的STARROCKS_VERSION、STARROCKS_COMMIT_HASH、STARROCKS_BUILD_TYPE、STARROCKS_BUILD_ARCH等常量对应的version.cpp；
Java 侧：com.starrocks.common.Version类（含STARROCKS_VERSION、STARROCKS_COMMIT_HASH等静态字段）。

因此，最终打进发布包的版本号本质上由构建时设置的STARROCKS_VERSION环境变量决定，这也保证了包名与二进制内部版本信息的一致性。

运行阶段：SQL 函数与命令行输出

版本号在运行时主要暴露在以下几个位置：

SQL 函数：在 gensrc/script/functions.py 中注册了version()与current_version()两个内置函数，底层实现在 be/src/exprs_ext/utility/utility_functions.cpp，返回STARROCKS_VERSION与STARROCKS_COMMIT_HASH拼接后的字符串。用户可直接执行SELECT version();或SELECT current_version();查看运行中的 BE 版本。
命令行/日志：be/src/common/util/debug_util.cpp 中的get_build_version()输出STARROCKS_VERSION-COMMIT_HASH，并附带BuildType、Build distributor id、Build arch、构建时间与构建用户/主机信息；get_short_version()则返回精简的版本-commit hash。
监控指标：be/src/service/service_metrics.cpp 将STARROCKS_VERSION作为build_info指标的version标签对外暴露，便于监控系统按版本聚合。
元数据：be/src/storage/cluster_id_mgr.cpp 在生成集群标识相关文件时也会拼接STARROCKS_VERSION，确保不同版本的存储侧标识可区分。

从源码结构推断的实践要点

版本语义上，3.4.x系列均为向后兼容的补丁版本，升级成本低、风险小，是日常维护推荐路径；跨MINOR（如3.x→4.x）或MAJOR升级时，应结合 release_notes 中各版本的行为变更说明评估兼容性。
生产环境建议优先选择无-rc后缀的正式版本包；需要提前验证新特性的团队，可选择对应MINOR初始版本的rc01/rc02预发布包进行测试，但不应直接用于生产。
发布包命名中 OS 与 ARCH 均为必填项，选包时务必同时核对操作系统与 CPU 架构两维信息。

结语

掌握 StarRocks 的版本命名规范，既能帮助你在升级时快速判断风险等级（主/次/补丁），也能让你在下载部署时准确匹配软件包。更进一步，通过 gen_build_version.py 与 version.h 等源码，你还可以理解版本号从构建注入到运行时输出的完整链路，从而更从容地构建、排查与运维 StarRocks 集群。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

StarRocks 版本命名规范与软件包命名规则全解