CentOS 系统下 GitLab 的更新与升级指南
一 升级前准备
- 备份关键数据与配置：执行完整备份，包含数据库、仓库数据以及配置文件，防止升级失败导致数据丢失。命令示例：sudo gitlab-rake gitlab:backup:create；备份文件默认位于 /var/opt/gitlab/backups，可通过修改 /etc/gitlab/gitlab.rb 中的 gitlab_rails[‘backup_path’] 调整；同时手动备份 /etc/gitlab/gitlab.rb 与 /etc/gitlab/gitlab-secrets.json。完成后建议校验备份可用性。
- 确认当前与目标版本：查看当前版本（如：sudo gitlab-rake gitlab:env:info），并查阅官方升级路径与版本说明，明确目标版本及是否需要多步升级。
- 维护窗口与回滚预案：选择业务低峰期，准备回滚方案（保留旧包、保留可回滚的备份、记录当前配置）。
- 依赖与系统检查：确保系统时间、磁盘空间、邮件与网络连通性正常；必要时安装常见依赖（如 policycoreutils、openssh-server、openssh-clients、postfix）。
二 标准升级步骤（Omnibus 包，适用于 CentOS）
- 切换至维护模式（可选）：在升级期间减少写入，提升稳定性。
- 停止相关服务：建议先停止应用与任务队列，减少迁移冲突。命令示例：sudo gitlab-ctl stop unicorn；sudo gitlab-ctl stop sidekiq；如需，亦可停止 nginx：sudo gitlab-ctl stop nginx。
- 更新 GitLab 包：推荐使用仓库方式升级。命令示例：sudo yum update gitlab-ce；如需指定版本，可安装对应 RPM：sudo yum install gitlab-ce- 或下载后执行 sudo rpm -Uvh gitlab-ce-.rpm。
- 重新配置与启动：执行 sudo gitlab-ctl reconfigure 以应用新版本配置，随后 sudo gitlab-ctl restart 启动服务。
- 执行数据库迁移与后置任务：升级后运行 sudo gitlab-rake db:migrate 完成结构/数据迁移，并视需要执行 sudo gitlab-rake db:migrate:status 检查迁移状态。
- 验证升级结果：访问管理界面或执行 sudo gitlab-rake gitlab:check 确认版本与系统健康状态。
三 升级路径与多版本跨越
- 遵循官方升级路径：跨多个主版本时，通常需要按阶段逐步升级（例如先到中间版本，再到目标版本），每一步完成后均执行 reconfigure、迁移与验证，再进行下一步。
- 小版本可直接升级：同一主版本内的小版本通常可直接 yum update 完成；若遇到异常，优先检查日志与迁移状态。
- 升级后巡检：确认后台作业、仓库访问、CI/CD、邮件、LDAP/SSO、对象存储等集成正常。
四 常见问题与回滚
- 500 错误与迁移失败：检查 sudo gitlab-rake db:migrate:status；必要时重新执行 sudo gitlab-rake db:migrate；同时查看 /var/log/gitlab/ 下相关日志定位问题。
- 进程占用导致 reconfigure 失败：排查 Chef/sidekiq 等占用进程（如 ps aux | grep gitlab），必要时终止相关 PID 后重试。
- 权限问题：如遇仓库目录权限异常，可参考修正 /var/opt/gitlab/git-data/repositories 权限（如设置 2770）后重试。
- 回滚方案：优先使用备份恢复。流程要点：停止服务（gitlab-ctl stop unicorn/sidekiq）、执行恢复（gitlab-rake gitlab:backup:restore BACKUP=）、重新配置与启动（gitlab-ctl reconfigure；gitlab-ctl start）。如仅包升级出现问题，可降级 RPM 包并恢复配置与数据。
五 自动化备份与运维建议
- 配置定时备份：在 /etc/gitlab/gitlab.rb 中设置备份目录与保留策略，并通过 cron 定时执行，例如：0 2 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create（每天 02:00 执行）。
- 监控与告警：对备份结果、磁盘空间、服务状态设置监控告警，确保问题可被及时发现与处理。
- 测试环境验证：生产升级前在测试环境演练全流程（备份→升级→迁移→验证→回滚），降低风险。
