从GitLab 11.0.2到17.2.2：一个老版本CentOS7服务器的完整升级与避坑实录

从GitLab 11.0.2到17.2.2CentOS7环境下的超长跨度升级实战指南当一台运行CentOS 7的服务器上部署着GitLab 11.0.2时技术债务的阴影便开始显现。安全漏洞的威胁、功能缺失的困扰以及兼容性问题的频发都迫使我们必须面对这个看似艰巨的任务——将GitLab从11.0.2升级到17.2.2。本文将分享我在不升级操作系统大版本的前提下完成这一跨越6年26个中间版本的升级历程重点解析那些官方文档未曾详述的实战细节。1. 升级前的战略准备在按下升级按钮前充分的准备工作能避免80%的灾难性错误。对于这种超长跨度的升级我们需要建立完整的作战计划。环境检查清单操作系统CentOS 7.9最小化安装当前GitLab版本11.0.2通过RPM安装硬件配置4核CPU/8GB内存/100GB存储空间服务依赖Redis 3.2.12、PostgreSQL 9.6重要提示确保/var分区至少有20GB可用空间升级过程中的临时文件可能消耗大量存储。升级路径规划是成功的关键。通过GitLab官方提供的升级路径工具我们确定了以下必经之路11.0.2 → 11.0.6 → 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 → 15.0.5 → 15.4.6 → 15.11.13 → 16.0.8 → 16.1.6 → 16.3.7 → 16.7.7 → 16.10.1 → 16.11.8 → 17.2.22. 备份策略与系统加固真正的专业人士从不依赖运气。在开始升级前我们实施了多层防护措施。完整备份方案数据库快照使用PostgreSQL的pg_dumpall创建全量SQL备份GitLab原生备份gitlab-ctl stop unicorn gitlab-ctl stop sidekiq gitlab-rake gitlab:backup:create SKIPartifacts,registry配置文件归档cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab-secrets.json /backup/ tar czvf /backup/gitlab-$(date %s).tar.gz /var/opt/gitlab系统加固步骤执行yum update更新所有系统包临时关闭SELinuxsetenforce 0禁用防火墙systemctl stop firewalld创建快照如果是虚拟机环境3. 分阶段升级实战3.1 11.x到12.x的过渡期挑战从11.0.2起步我们需要特别注意Ruby版本的变化。GitLab 12.0开始要求Ruby 2.6而CentOS 7默认的Ruby仅为2.0。解决方案# 安装SCL仓库 yum install centos-release-scl-rh # 安装新版Ruby yum install rh-ruby30 rh-ruby30-ruby-devel # 配置环境变量 echo source /opt/rh/rh-ruby30/enable /etc/profile.d/ruby.sh升级命令示例rpm -Uvh gitlab-ce-11.11.8-ce.0.el7.x86_64.rpm gitlab-ctl reconfigure gitlab-ctl restart3.2 13.x到14.x的哈希存储迁移这是整个升级过程中最具技术挑战的部分。GitLab 14.0引入了哈希存储机制要求对现有仓库结构进行转换。关键操作流程升级到13.12.15后暂停服务执行存储迁移gitlab-rake gitlab:storage:migrate_to_hashed处理常见问题如果迁移后仍有遗留项目执行gitlab-rails runner -e production Project.where.not(project_namespace_id: nil).find_each(:refresh_project_authorizations)清理无效的runner令牌UPDATE projects SET runners_token null, runners_token_encrypted null;3.3 15.x的PostgreSQL升级GitLab 15.0要求PostgreSQL最低版本为12.x而我们的环境仍运行9.6版本。这是必须跨越的技术鸿沟。安全升级步骤在升级到15.0前执行gitlab-ctl pg-upgrade -V 13验证升级结果/opt/gitlab/embedded/bin/postgres --version处理可能的扩展问题ALTER EXTENSION pg_trgm UPDATE; ALTER EXTENSION btree_gist UPDATE;4. 关键问题排查手册在26个版本的升级过程中我遇到了数十个错误。以下是三个最具代表性的解决方案。4.1 Redis版本冲突当升级到14.3.6时系统提示需要Redis 5.0。CentOS 7默认仓库仅提供3.2版本。编译安装Redis 6.xyum install epel-release yum install gcc make tcl wget https://download.redis.io/releases/redis-6.2.13.tar.gz tar xzf redis-6.2.13.tar.gz cd redis-6.2.13 make make install配置GitLab使用外部Redis# /etc/gitlab/gitlab.rb redis[enable] false gitlab_rails[redis_host] 127.0.0.1 gitlab_rails[redis_port] 63794.2 文件权限问题在14.0.12升级阶段常见的错误是PostgreSQL目录权限不足。修复命令chmod 755 /var/opt/gitlab/postgresql chmod 755 /var/opt/gitlab/postgresql/data chown -R gitlab-psql:gitlab-psql /var/opt/gitlab/postgresql4.3 Sidekiq队列积压在多个升级节点出现Sidekiq处理延迟导致升级超时。应急处理方案gitlab-rake gitlab:background_migrations:finalize[CopyColumnWithBackgroundMigration] gitlab-rake gitlab:background_migrations:finalize[BackfillNamespaceIdForNamespaceRoute]5. 升级后的验证与优化完成17.2.2的安装只是成功的一半我们需要确保所有功能正常运作。完整性检查清单运行健康检查gitlab-rake gitlab:check SANITIZEtrue验证仓库完整性gitlab-rake gitlab:storage:verify测试CI/CD流水线执行检查监控仪表板的所有指标性能优化建议# /etc/gitlab/gitlab.rb puma[worker_processes] 4 sidekiq[concurrency] 10 postgresql[shared_buffers] 2GB整个升级过程耗时约8小时含验证时间其中最关键的经验是在每个大版本跨越前如11→1213→1414→15必须进行完整备份因为这些节点出现问题的概率最高。