从 13 到 17：一次跨越四个大版本的 GitLab 升级实战

原创

已于 2026-08-13 14:21:16 修改 · 239 阅读

于 2026-08-13 12:04:09 首次发布

环境：CentOS 7 + GitLab CE（Omnibus 安装）
升级路径：13.12.15 → 17.7.7
总耗时：约 9 小时
涉及：15 次版本升级、2 次 PostgreSQL 大版本升级、4 个关键踩坑

前言

GitLab 的版本升级，尤其是跨多个大版本的升级，向来是 DevOps 工程师最头疼的事情之一。我们的 GitLab 实例长期运行在 13.12.15，由于 CentOS 7 的生命周期终结，加上新功能和安全补丁的需求，终于决定将其升级到 CentOS 7 支持的最高版本——17.7.7。

这不是一次简单的 yum update。从 13 到 17，跨越了 4 个大版本，涉及 15 次中间版本升级、2 次 PostgreSQL 大版本升级、若干次后台迁移手动收尾，以及 OpenSSL 3 带来的 TLS 兼容性变更。本文完整记录了整个升级过程、踩过的坑和最终的解决方案。

一、升级前：想清楚再动手

1.1 升级路径规划

GitLab 不支持跨大版本直接升级，必须严格按照官方的升级路径一步步来。我们使用 GitLab 官方的 Upgrade Path Tool 规划了完整的升级路径：

13.12.15 → 14.0.12 → 14.3.6 → 14.9.5 → 14.10.5
→ 15.0.5 → 15.4.6 → 15.11.13
→ 16.3.9 → 16.7.10 → 16.11.10
→ 17.1.8 → 17.3.7 → 17.5.5 → 17.7.7

⚠️ 关键里程碑节点：在 15.11.13 → 16.x 和 16.11.10 → 17.x 两个节点，强烈建议各创建一个云盘快照。一旦升级到新大版本后发现问题，可以用快照快速回滚，避免从头再来。

1.2 升级前必须考虑的事

升级前检查：

法律合规：确认与极狐 GitLab 是否存在法律风险（如果此前使用的是极狐版本）
OS 兼容性：CentOS 7 支持的最高 GitLab 版本是 17.7.7，更高版本需要先升级操作系统
RPM 包准备：提前下载所有中间版本的 RPM 包，放在服务器本地，避免升级过程中因网络问题中断
磁盘空间：确保 /opt 和数据盘有充足剩余空间（至少为数据库大小的 1.5 倍），PostgreSQL 大版本升级需要大量临时空间做数据迁移，空间不足会直接失败
停机公告：提前通知所有用户停机窗口（建议预留 10-12 小时），提醒用户提前保存工作，暂停所有 CI 流水线

RPM 包下载示例：

wget --content-disposition https://packages.gitlab.com/gitlab/gitlab-ce/packages/el/7/gitlab-ce-15.0.5-ce.0.el7.x86_64.rpm/download.rpm

💡 批量下载技巧：可以用 GitLab Package Registry 的 API 批量拉取所有中间版本的 RPM，省去一个个手动下载的麻烦。

升级后验证：

日志格式变化：新版本日志格式可能调整，接入数仓的解析规则需要同步修改
完整测试方案：必须覆盖 Runner 注册与执行、LDAP 认证、邮件通知、备份与恢复等核心功能
API 兼容性：新版本可能废弃旧 API，检查所有调用 GitLab API 的自动化脚本和工具

1.3 升级前检查清单

正式动手前，逐项过一遍这个 checklist，能避免 80% 的中途翻车：

# ============ 升级前检查清单 ============

# 1. 检查当前版本
gitlab-rake gitlab:env:info

# 2. 检查后台迁移状态（必须全部完成）
sudo gitlab-rake gitlab:background_migrations:status

# 3. 检查磁盘空间（重点关注 /opt 和数据盘）
df -h

# 4. 检查 PostgreSQL 版本
gitlab-psql -V

# 5. 仓库健康检查
gitlab-rake gitlab:git:fsck

# 6. 备份 /etc/gitlab 目录（不依赖快照的独立备份）
cp -a /etc/gitlab /etc/gitlab.bak.$(date +%Y%m%d)

# 7. 备份数据库（独立于快照的文件级备份）
gitlab-backup create

# 8. 确认所有 RPM 包已就位
ls -lh /root/gitlab-ce-*.rpm

⚠️ 第 2 项最容易翻车：后台迁移（Background Migration）是 GitLab 在大版本间做数据结构变更的方式，运行在 Sidekiq 中。如果升级前有未完成的迁移，db:migrate 会直接报错阻塞。这是本次升级踩到的第一个坑，详见后文。

1.3 备份：升级前的最后一道保险

在正式升级前，我们通过腾讯云控制台为实例创建了一个自定义镜像（底层是磁盘快照）。这一步耗时约 1.5 小时，且耗时不稳定——磁盘越大越慢。务必等镜像进度显示 100% 且状态正常后再进行下一步。

# 升级前的标准操作流程
gitlab-ctl stop
gitlab-ctl status
sync
gitlab-rake gitlab:git:fsck   # 仓库健康检查，提前发现问题

1.4 配置文件精简

升级前建议精简 gitlab.rb 配置文件，注释掉旧版本中自定义的日志目录配置，避免新版本 reconfigure 报错：

vim /etc/gitlab/gitlab.rb

# 保留 sidekiq 日志目录
sidekiq['log_directory'] = "/data/logs/sidekiq"

# 注释掉后续版本已废弃的配置
# sidekiq_cluster['log_directory'] = "/data/logs/sidekiq-cluster"
# repmgr['log_directory'] = '/data/logs/repmgrd'
# consul['log_directory'] = '/data/logs/consul'
# gitaly['log_directory']
# grafana['log_directory'] = '/data/logs/grafana'

💡 配置文件瘦身技巧：gitlab.rb 默认有上千行注释，排查配置问题时非常痛苦。可以用以下命令去掉所有注释行和空行，只保留实际生效的配置：
egrep -v "^#|^$" /etc/gitlab/gitlab.rb > /etc/gitlab/gitlab.rb.tmp
mv /etc/gitlab/gitlab.rb.tmp /etc/gitlab/gitlab.rb
建议在升级前执行，后续排查配置问题效率大幅提升。操作前务必备份原文件。

二、升级过程：15 步阶梯式爬升

整个升级过程的核心是一个高度重复的循环：reconfigure → 停服务 → rpm 安装 → db:migrate → reconfigure → restart。但每个版本都有可能踩到不同的坑。

2.1 标准升级流程

以 14.0.12 为例，每个版本的升级模板如下：

# 1. 应用配置
gitlab-ctl reconfigure

# 2. 停止核心服务（保留 postgresql 和 redis 运行）
gitlab-ctl stop sidekiq
gitlab-ctl stop nginx
gitlab-ctl stop puma

# 3. 安装新版本 RPM（安装完成后自动发飞书通知）
rpm -Uvh gitlab-ce-14.0.12-ce.0.el7.x86_64.rpm