1. 迁移与升级工程总览
企业 GitLab 不是“装好就完事”的工具，而是一个会持续演进的生产系统。它承载代码托管、合并请求、CI/CD、制品库、安全扫描、审计与权限治理等关键能力，任何一次迁移或升级，本质上都是对一条正在运行的研发流水线做“心脏搭桥手术”。理解这一点，是做好迁移与升级工程的前提。
一、企业 GitLab 的生命周期
从工程视角看，企业 GitLab 的生命周期可以划分为五个阶段，每个阶段的核心诉求和风险点都不同：
- 规划与选型：确定部署形态（Omnibus 单机、多节点横向扩展、GitLab Helm Chart on Kubernetes、GitLab Dedicated 等），评估用户规模、仓库数量、CI 并发、存储增长与合规要求。
- 部署与初始化：完成基础环境、数据库、对象存储、Redis、Gitaly、Runner 的搭建，配置 SSO/LDAP、备份策略与监控。
- 稳定运行与扩容：随业务增长调整 Gitaly 分片、Runner 并发、Pages、Registry 存储，持续做容量与性能治理。
- 版本升级：跟随 GitLab 月度发布节奏，按升级路径逐跳升级，修补安全漏洞、获取新功能。
- 迁移与退役：因机房搬迁、云化、并购整合、版本过旧无法升级等原因，将数据与配置迁移到新实例，并完成旧实例下线。
这五个阶段并非线性独立，升级往往发生在稳定运行期，迁移又常常与升级绑定进行。工程团队需要把“生命周期”当作一个持续运营的对象，而不是一次性项目。
二、迁移与升级的典型场景
在实际企业环境中，迁移与升级通常由以下几类场景触发：
| 场景 | 典型触发原因 | 关键约束 |
|---|---|---|
| 同版本迁移 | 机房搬迁、服务器更换、云厂商切换 | 停机窗口、数据一致性 |
| 跨版本升级 | 安全补丁、功能需求、版本 EOL | 升级路径、数据库 schema 变更 |
| 迁移+升级 | 旧版本无法直接升级，需先迁移再升级 | 路径规划、回滚方案 |
| 架构重构 | 单机转集群、自建转 Helm/K8s | 组件拆分、存储迁移 |
| 合并整合 | 并购、多实例归一 | 命名空间冲突、权限映射 |
例如，一个典型场景是：企业当前运行 GitLab 14.10（Omnibus 单机），因安全合规要求需升级到 16.x，同时要把数据从自建 IDC 迁移到云上。此时不能直接“跳版本”，而要先规划升级路径：14.10 → 14.10.z 最新补丁 → 15.0 → 15.4 → 15.11 → 16.0 → 16.x。每一步都要验证数据库迁移、Gitaly 兼容性和 Runner 版本匹配。
三、核心挑战
迁移与升级的难点，往往不在“操作步骤”，而在以下几个层面：
- 数据一致性：Git 仓库、数据库、对象存储、Registry、Pages、CI 变量、Webhook、SSH Key 等分散在多个存储后端，任何一处遗漏都会导致功能异常。
- 版本兼容性：GitLab 主版本之间数据库 schema、API、Gitaly 协议、Runner 协议都可能不兼容，必须按官方升级路径逐跳进行。
- 停机窗口：企业研发不能长时间停摆，需要在有限窗口内完成备份、迁移、验证与切换。
- 权限与集成：LDAP/SSO、SCIM、审计日志、外部 CI 系统、Jira、Slack 等集成需要在迁移后重新验证。
- 回滚能力：一旦升级失败，能否在可接受时间内回退到旧版本，是工程成熟度的直接体现。
常见误区：把迁移当成“复制数据”。实际上，GitLab 的配置、密钥、CI Runner 注册信息、对象存储桶权限、数据库序列与索引状态，都是迁移对象的一部分。只迁移仓库数据，往往会在切换后出现 CI 无法运行、Webhook 失效、权限错乱等问题。
四、成功标准
判断一次迁移或升级是否成功，不能只看“服务能启动”。建议从以下维度定义可验证的成功标准：
- 功能完整性：登录、代码拉取、合并请求、CI 流水线、制品上传下载、Pages 访问、Webhook 触发均正常。
- 数据一致性：仓库数量、提交历史、分支标签、Issue/MR 数量、用户与权限、CI 变量与密钥与源实例一致。
- 性能达标：关键接口响应时间、CI 排队时间、Git 克隆速度在可接受范围内。
- 可观测性：监控、日志、告警、备份任务在新实例上正常工作。
- 回滚可行：保留旧实例或完整备份，且已验证回滚流程。
下面这张图把“生命周期—触发场景—核心挑战—成功标准”串成一条工程主线，帮助你在后续章节中始终带着全局视角看具体操作。
五、工程视角下的关键判断
在进入具体操作之前，建议先回答三个问题：
- 当前版本与目标版本之间隔了多少个主版本？如果超过一个主版本，必须按官方升级路径逐跳升级，不能跳版。
- 停机窗口有多长？窗口越短，越需要提前做全量备份、预迁移演练和增量同步方案。
- 回滚方案是否经过验证？没有验证过的回滚方案，等于没有回滚方案。
建议：在正式迁移或升级前，至少完成一次完整的预演。预演环境应尽量与生产环境一致，包括版本、数据量、存储后端和集成配置。预演中记录每一步耗时、报错和验证结果，形成可复用的操作清单。
本章后续内容将围绕这条主线展开：先建立全局认知，再逐步深入到备份、迁移、升级、验证与回滚的具体工程实践中。掌握生命周期、场景、挑战与成功标准，才能在面对真实生产环境时做出正确判断，而不是机械地执行命令。