3. 版本升级路径规划

GitLab 的版本升级不是“下载最新版覆盖安装”这么简单。它同时涉及数据库结构变更、后台迁移任务、组件版本耦合（如 PostgreSQL、Redis、Gitaly、Runner）以及官方明确规定的升级停靠点。如果跳过停靠点直接跨大版本升级，最常见的后果是数据库迁移失败、服务无法启动，甚至需要从备份回滚。因此，升级路径规划的核心任务是：先读懂版本号，再确定必须经过的停靠点，最后用官方工具验证路径。

一、语义化版本规则：先分清“能升”和“必须升”

GitLab 采用语义化版本（SemVer）格式 MAJOR.MINOR.PATCH，例如 16.11.4。三个数字的含义直接决定升级策略：

• MAJOR（大版本）：如 15 → 16，通常包含破坏性变更、数据库结构重大调整、配置项废弃。跨大版本必须遵循官方升级路径，不能随意跳跃。
• MINOR（小版本）：如 16.10 → 16.11，每月发布一次，新增功能与常规数据库迁移。同一大版本内可逐个小版本升级，也可按停靠点跳升。
• PATCH（补丁版本）：如 16.11.3 → 16.11.4，仅修复缺陷与安全问题，可自由升级，不涉及停靠点限制。

需要特别注意的是，GitLab 的“升级停靠点”约束主要作用在 MINOR 和 MAJOR 层面。补丁版本之间没有停靠点要求，但生产环境仍建议升级到当前小版本的最新补丁，以规避已知缺陷。

二、升级停靠点：为什么不能从 15.4 直接升到 16.0

GitLab 在部分版本中引入了必须执行的数据库迁移或后台任务，这些版本被称为“升级停靠点”（required upgrade stops）。官方规定：升级路径中必须包含所有必需的停靠点，且每个停靠点至少要升级到该小版本的最新补丁版本。例如从 15.x 升级到 16.x，官方要求先停在 15.11.x，再升级到 16.0.x。如果当前是 15.4.2，正确路径是：

15.4.2 → 15.11.x（停靠点，升到最新补丁）→ 16.0.x → 16.11.x（下一停靠点）→ 17.0.x

停靠点的作用可以理解为“让数据库迁移和后台任务在可控版本内完成”。跳过停靠点，迁移脚本可能因为缺少前置表结构或数据状态而失败。判断某个版本是否为停靠点，最可靠的方式是查阅官方文档的升级路径说明，或使用下一节的官方工具。

三、跨大版本升级顺序：逐级停靠，不跳大版本

跨大版本升级的基本原则是：不能跳过任何大版本，且每个大版本内必须经过官方指定的停靠点。以 14.x 升级到 17.x 为例，合理路径如下：

14.10.x（14 的停靠点）→ 15.0.x → 15.11.x（15 的停靠点）
→ 16.0.x → 16.11.x（16 的停靠点）→ 17.0.x

这里有两个容易踩坑的地方。第一，停靠点版本必须升到该小版本的最新补丁，例如 15.11.13 而不是 15.11.0，否则可能缺少后续大版本依赖的迁移。第二，升级到新大版本的第一个小版本（如 16.0.x）后，不要立刻继续跳到 16.11.x，而应先确认服务健康、迁移任务完成，再继续。对于使用 Omnibus 包的环境，升级命令本身很简单，但路径顺序必须提前规划好。

四、官方升级路径工具：用 Upgrade Path 提前验证

GitLab 官方提供了升级路径工具（Upgrade Path Tool），地址为 https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/。使用时输入当前版本和目标版本，工具会输出一条完整的、包含所有停靠点的升级路径。例如输入当前 15.4.2、目标 16.11.4，工具会给出类似：

15.4.2 → 15.11.13 → 16.0.9 → 16.11.4

工具输出的路径可以直接作为升级计划的基础。建议在规划阶段就把每一步的目标版本、预计停机窗口、备份点记录下来，形成可执行的升级清单。下面这张图展示了从 15.4.2 到 16.11.4 的路径规划关系：当前版本经过 15.11 停靠点、16.0 入口版本，最终到达 16.11 停靠点，每一步都对应一次可验证的升级动作。

五、把路径规划落到升级清单

规划完成后，建议把路径整理成一份可执行的升级清单，至少包含每一步的当前版本、目标版本、是否停靠点、备份确认和验证结果。下面给出一个可直接参考的示例结构（版本号与时间仅为示例，实际以官方工具输出为准）：

执行时，每一步升级后都应检查 gitlab-ctl status、数据库迁移日志以及 Sidekiq 队列是否正常。如果某一步出现迁移失败，应停留在当前版本排查，而不是继续向下一版本推进。路径规划的价值就在于把“一次高风险跳跃”拆解为“多次可控的小步升级”，让每一步都有明确的验证点和回退依据。