GitLab 10.x → 19.5.x 升级路线图

从 GitLab 10.x 跨越至最新的 19.5.x，升级的关键在于遵循官方定义的 "必需升级停靠点"（Required Upgrade Stops） 。由于版本跨度极大，绝对不能跳版本升级，必须像沿着阶梯一样，在每一个停靠点完成升级并等待后台迁移结束，才能继续前进。

下表汇总了从 10.x 到当前最新 19.5.x 路径上所有已知的关键停靠点。表中的版本号是"最低要求" ，实际操作时，应尽量升级到该 major.minor 系列下的最新补丁版本 （例如，计划停靠 14.3.6，若有 14.3.9 则应升级到 14.3.9）。

大版本	必需的升级停靠点（Required Upgrade Stops）	关键说明与官方依据
10.x	10.8.z	从 10.8 开始，GitLab 默认强制执行升级路径，阻止跳过主要版本的直接升级。
11.x	官方文档未列出独立的强制停靠点。	通常建议遵循路径，升级至 11.8 或 11.x 的最终补丁版，为下一个大版本做准备。
12.x	12.0.z	必须先升级到 12.0 系列，才能继续升级到 12.y 的更高版本。
13.x	13.5.z	升级到 13.5 后，建议等待至少一周，再升级到 14.0。
14.x	14.3.6 → 14.9.5 → 14.10.5	这是官方文档明确列出的一个完整升级链示例，必须依次通过这些版本。
15.x	15.0.5 → 15.1.6 → 15.4.6 → 15.11.13	这是 GitLab 15 的官方停靠点列表。其中 15.1.6 对拥有多个 Web 节点的实例尤为重要。
16.x	16.3.z	大多数安装可以跳过 16.0 至 16.2，16.3 是升级路径上的第一个强制停靠点。
17.x	17.1.8 → 17.8.7 → 17.11.7	官方明确要求的停靠点。从 17.5 开始 ，停靠点规则固定为 x.2, x.5, x.8, x.11。
18.x	18.2.z → 18.5.z → 18.8.z → 18.11.z	停靠点严格遵循 x.2, x.5, x.8, x.11 的规律。
19.x (最新)	19.2.z → 19.5.z → 19.8.z → 19.11.z	当前最新大版本，停靠点同样遵循固定规律。你的目标版本 19.5.3 是其中的一个停靠点，而 19.8 和 19.11 可能是未来的停靠点。

注意 ：上表中的停靠点信息，特别是早期版本（10-16），部分来源于官方文档的示例或社区整理，旨在提供路径指引。在实际操作前，务必查阅对应版本的官方升级说明（Upgrade Notes），以确认是否有临时的、未在此表中列出的特定停靠要求。

🐳 Docker 环境下的操作要点

无论使用 docker run 还是 docker-compose，每一次停靠升级的核心流程都遵循官方文档的指引：

1. 备份优先 ：在每一次停靠升级前，必须 创建备份。至少需要备份数据库 和 gitlab-secrets.json 文件。
2. 停止并移除旧容器 ：sudo docker stop <容器名> 然后 sudo docker rm <容器名>。
3. 拉取目标镜像 ：sudo docker pull gitlab/gitlab-ce:<目标停靠版本>-ce.0。
4. 使用原配置重建容器 ：使用与之前完全相同 的 docker run 命令（卷映射、端口映射等），仅将镜像标签替换为目标版本。
5. 等待后台迁移完成 ：容器启动后，GitLab 会自动执行升级和数据库迁移。必须等待所有后台迁移（Background Migrations）完成 ，才能进行下一次停靠升级。可以通过 gitlab-rake gitlab:check 等命令进行验证。

🔗 引用的官方文档关键信息与链接

以下是支撑上述路线图的核心官方文档来源：

• 核心概念：必需升级停靠点 (Required Upgrade Stops)

  • 关键信息 ：升级路径包含必需的停靠点，你必须先升级到这些版本，才能升级到更高版本。从 GitLab 17.5 开始，停靠点固定出现在 x.2.z, x.5.z, x.8.z, x.11.z 版本。
  • 官方链接 ：Plan your upgrade path (docs.gitlab.com)，这是最权威的总览页面。

• 各版本的停靠点详情（均可在上述总览页面中找到）：

  • GitLab 19 停靠点 ：19.2, 19.5, 19.8, 19.11。
  • GitLab 18 停靠点 ：18.2, 18.5, 18.8, 18.11。
  • GitLab 17 停靠点 ：明确列出了 17.1.8, 17.8.7, 17.11.7。
  • GitLab 16 停靠点 ：16.3 是第一个强制停靠点。
  • GitLab 15 停靠点 ：完整列表为 15.0.5, 15.1.6, 15.4.6, 15.11.13。
  • 14.x 停靠链示例 ：官方以 14.3.6 → 14.9.5 → 14.10.5 为例，展示了完整的停靠序列。

• Docker 部署的升级方法：

  • 关键信息：详细说明了在 Docker 和 Docker Compose 环境中执行升级的标准步骤，包括备份、拉取镜像和重建容器。
  • 官方链接 ：升级 Docker 实例 (docs.gitlab.cn)

从 10.x 到 19.5.x 的升级是一项需要耐心和细致规划的系统工程。核心就是严格对照路线图，在每一个停靠点完成"备份 → 升级 → 等待迁移完成"的闭环，再迈向下一站。