GitLab在CentOS上如何更新升级

CentOS 上 GitLab 升级指南

一 升级前准备

• 备份与配置
  • 完整备份：执行 sudo gitlab-rake gitlab:backup:create，备份默认位于 /var/opt/gitlab/backups/；如需修改备份目录，可在 /etc/gitlab/gitlab.rb 中设置 gitlab_rails['backup_path'] 后 gitlab-ctl reconfigure 生效。
  • 备份敏感文件与密钥：/etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json 必须单独备份。
• 版本与升级路径
  • 查看当前版本：sudo gitlab-rake gitlab:env:info 或 cat /opt/gitlab/version-manifest.txt。
  • 严禁跨大版本直接升级，需按官方升级路径逐级进行；可使用官方 Upgrade Path 工具生成路径。
• 系统与依赖
  • 执行 sudo yum update 更新系统及依赖，避免后续因依赖过低导致失败。
• 维护窗口与可用性
  • 单节点升级期间服务会短暂不可用（可能出现 Deploy in progress 或 502），请提前通知并选择低峰时段。

二 标准升级步骤 Omnibus RPM 包

• 方式 A Yum 在线升级
  1. 更新仓库元数据：sudo yum makecache
  2. 直接升级：sudo yum install gitlab-ce -y
  3. 如需指定版本：sudo yum install gitlab-ce-<version>.rpm
• 方式 B 离线 RPM 升级
  1. 下载目标版本 RPM（可从官方或镜像站获取）
  2. 升级安装：sudo rpm -Uvh gitlab-ce-<version>.rpm
• 公共步骤
  1. 重新配置并重启：sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart
  2. 状态与版本校验：sudo gitlab-ctl status；cat /opt/gitlab/version-manifest.txt 或管理界面查看版本
  3. 可选健康检查：sudo gitlab-rake gitlab:check
  4. 如遇 502/后台任务卡住，在“管理中心 > 监控 > 后台任务”清理卡住任务后重试。

三 大版本升级要点与常见坑

• 逐级升级与关键版本
  • 典型路径示例：11.0.2 => 11.11.8 => 12.10.14 => 13.12.15 => 14.10.5 => 15.11.13 => 16.11.8 => 17.2.2（示例仅示意，请以 Upgrade Path 工具结果为准）。
• 13 → 14 存储与只读
  • 升级前确保项目非只读；如有项目被置为只读，可在 Rails 控制台批量清除：Project.where(repository_read_only: true).each { |p| p.update!(repository_read_only: nil) }
  • 执行仓库哈希存储迁移：sudo gitlab-rake gitlab:storage:migrate_to_hashed，并校验 gitlab:storage:list_legacy_projects 为 0。
• 14 → 15/16 内置 PostgreSQL 升级
  • 升级到 GitLab 15.x 需内置 PostgreSQL 13：sudo gitlab-ctl pg-upgrade -V 13
  • 升级到 GitLab 16.x 需内置 PostgreSQL 14：sudo gitlab-ctl pg-upgrade -V 14
• 进程与端口
  • 13.10 之前停止 unicorn；13.10 及之后停止 puma：gitlab-ctl stop puma
  • 升级后短暂 502 属正常，等待后台迁移完成或通过控制台清理卡住任务。

四 回滚与验证

• 快速回滚
  • 使用最近一次备份恢复：先停止相关服务（gitlab-ctl stop unicorn、gitlab-ctl stop sidekiq），再执行 sudo gitlab-rake gitlab:backup:restore BACKUP=<timestamp>，最后 gitlab-ctl start。注意：备份只能恢复到与其创建时完全相同的版本与类型（CE/EE）。
• 升级后验证清单
  • 访问 Web 与管理员界面确认版本号与功能正常
  • 执行 sudo gitlab-ctl status 检查所有组件
  • 运行 sudo gitlab-rake gitlab:check 做健康检查
  • 查看日志定位问题：/var/log/gitlab/（如 nginx、gitlab-rails、sidekiq 等）。