Linux GitLab 升级实操指南
一 升级前准备
- 确认安装方式与版本
- 查看版本：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION
- 确认安装方式：Omnibus 包（RPM/DEB）、源码、Docker、Kubernetes（Helm），不同方式升级步骤不同。建议优先在测试环境演练，生产环境再执行。
- 规划升级路径
- 必须遵循官方的升级路线（upgrade paths），先升级到当前大版本的最新补丁版，再跨到下一大版本；不要跨多个大版本直接升级。示例（旧版路径）：11.4.3 → 11.11.8 → 12.0.12 → 12.1.17 → 12.10.14 → 13.0.14 → 13.1.11 → 13.8.8 → 13.12.15 → 14.0.12 → 14.3.6 → 14.9.5 → 14.10.5。实际以官方文档对应版本为准。
- 检查后台迁移是否完成（关键！）
- 对于 GitLab 14.0+，需同时确认后台迁移与批量后台迁移均已完成：
- 后台迁移剩余量：sudo gitlab-rails runner -e production ‘puts Gitlab::BackgroundMigration.remaining’
- 批量后台迁移状态：在管理员界面 Menu > Admin > Monitoring > Background Migrations 全部为 Finished；或 psql 查询：select job_class_name,table_name,column_name,job_arguments from batched_background_migrations where status<>3;
- 若未完成，升级会被拦截或导致数据不一致。
- 完整备份与回滚方案
- 备份命令：
- GitLab 12.2+：gitlab-backup create
- GitLab 12.1 及更早：gitlab-rake gitlab:backup:create
- 同时手工备份敏感文件：/etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json
- 备份目录：grep backup_path /etc/gitlab/gitlab.rb（默认 /var/opt/gitlab/backups）
- 回滚要点：恢复时必须使用与备份时完全相同的版本与发行类型（CE/EE）。
二 标准升级步骤 Omnibus 包（RPM/DEB）
- 小版本升级（同一大版本内，如 15.1.x → 15.1.y）
- 可选：停止写服务以减少冲突
- gitlab-ctl stop unicorn
- gitlab-ctl stop sidekiq
- 执行升级
- RPM：rpm -Uvh gitlab-ce-.rpm
- DEB：dpkg -i gitlab-ce_.deb
- 重载配置并重启
- gitlab-ctl reconfigure
- gitlab-ctl restart
- 访问页面与版本校验：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION
- 跨大版本升级（示例思路）
- 原则：先到当前大版本的最高补丁版，再到下一大版本的最低版，随后继续按“最高补丁版”前进。
- 示例（历史常见路径）：14.2.5 → 14.10.5 → 15.0.0 → 15.3.3（每一步执行“停止写服务 → 安装包 → reconfigure → restart → 校验”）。实际请以官方升级路线为准。
- 升级后数据库变更
- 如遇到数据结构变更或组件升级提示，按官方文档执行数据库迁移（例如对 PostgreSQL 的权限与迁移命令），完成后重启相关服务。
三 升级后验证与回滚
- 快速健康检查
- 配置与密钥：sudo gitlab-rake gitlab:check；sudo gitlab-rake gitlab:doctor:secrets
- 页面与功能：登录、项目列表、Issues/MR、git clone/push、Runner 取 jobs、Registry 镜像推送拉取等是否正常
- 如启用 Geo，在各节点执行：sudo gitlab-rake gitlab:geo:check
- 回滚步骤（仅在升级失败时执行）
- 停止服务：gitlab-ctl stop unicorn && gitlab-ctl stop sidekiq
- 恢复数据：gitlab-rake gitlab:backup:restore BACKUP=<时间戳_版本>（文件名去掉 “_gitlab_backup.tar” 后的部分）
- 还原配置与密钥：恢复 /etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json
- 启动与校验：gitlab-ctl reconfigure；gitlab-ctl restart；访问页面确认版本与数据。
四 常见问题与处理
- 页面 502 或 “Deploy in progress”
- 常见于升级期间或 Sidekiq/Unicorn 未完全就绪：
- systemctl restart gitlab-runsvdir
- gitlab-ctl restart sidekiq
- gitlab-ctl hup unicorn
- 等待数分钟再访问。
- 后台迁移未完成导致升级拦截
- 使用上文的 Rails Runner 与 psql 查询检查；必要时增加处理后台迁移的 Sidekiq worker 数量，或在 Rails 控制台对卡住任务进行重试/接管。
- 大版本间的组件升级耗时
- 例如 12.0 → 12.1 会升级 Prometheus，数据转换可能耗时较长，请预留维护窗口。
- 备份与恢复限制
- 备份不含对象存储数据（如使用 OSS/S3 需单独备份），且恢复时必须与备份时版本与发行类型完全一致。