GitLab升级踩坑实录：14.0.12到14.3.6，那个烦人的`gitlab-ctl reconfigure`错误我是这么解决的

GitLab升级实战：从14.0.12到14.3.6的深度排错指南

那次周五晚上9点的GitLab升级，至今让我记忆犹新。原本计划两小时完成的版本更新，最终演变成一场持续到凌晨的技术攻坚战。作为团队中负责DevOps基础设施的工程师，我亲历了从错误日志分析到最终解决的完整过程，也深刻体会到GitLab升级中那些官方文档未曾提及的"坑"。

1. 问题初现：当reconfigure命令突然崩溃

那是一个再普通不过的版本升级流程——从GitLab 14.0.12升级到14.3.6。按照官方升级路径，我执行了标准的sudo gitlab-ctl reconfigure命令，却遭遇了这样的错误输出：

Running handlers: There was an error running gitlab-ctl reconfigure: rails_migration[gitlab-rails] (gitlab::database_migrations line 51) had an error: Mixlib::ShellOut::ShellCommandFailed: bash[migrate gitlab-rails database] (/opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/resources/rails_migration.rb line 16) had an error: Mixlib::ShellOut::ShellCommandFailed: Expected process to exit with [0], but received '1'

更关键的错误信息隐藏在日志深处：

-- execute("ALTER TABLE \"vulnerability_finding_evidence_sources\"\nADD CONSTRAINT \"check_86b537ba1a\" CHECK (char_length(\"name\") <= 2048),\nADD CONSTRAINT \"check_0fe01298d6\" CHECK (char_length(\"url\") <= 2048)\n") rake aborted! StandardError: An error has occurred, all later migrations canceled: Expected batched background migration for the given configuration to be marked as 'finished', but it is 'paused': {:job_class_name=>"CopyColumnUsingBackgroundMigrationJob", :table_name=>"ci_builds_metadata", :column_name=>"id", :job_arguments=>[["id"], ["id_convert_to_bigint"]]}

关键诊断点：

• 错误明确指向后台迁移任务未完成
• 特定表ci_builds_metadata的列迁移被标记为"paused"而非"finished"
• 系统给出了具体的手动修复命令提示

2. 深入分析：GitLab后台迁移机制解析

GitLab采用了一种称为"Batched Background Migration"的机制来处理大规模数据迁移。这种设计主要出于两个考虑：

1. 避免单次迁移对生产系统造成过大负载
2. 允许管理员控制迁移节奏，避开业务高峰

在本次案例中，CopyColumnUsingBackgroundMigrationJob负责将ci_builds_metadata.id从integer类型迁移到bigint类型。GitLab将这个任务分解为多个小批次执行，但不知何故，该任务被标记为"paused"而非正常完成。

常见导致迁移暂停的原因：

提示：GitLab的后台迁移状态可以通过以下命令查看：

sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.statuses'

3. 解决方案：分步修复流程

3.1 初步检查与数据库恢复

首先确认数据库服务状态：

sudo gitlab-ctl status postgresql

发现PostgreSQL虽然显示运行中，但连接测试失败：

sudo gitlab-rake db:migrate:status # 返回连接错误

执行服务重启：

sudo gitlab-ctl restart postgresql

3.2 执行手动迁移命令

根据错误提示，运行指定的finalize命令：

sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,ci_builds_metadata,id,'[["id"], ["id_convert_to_bigint"]]']

然后重新配置：

sudo gitlab-ctl reconfigure

3.3 处理Redis连接异常

此时系统抛出新的错误：

Redis::CannotConnectError: Error connecting to Redis on /var/opt/gitlab/redis/redis.socket (Errno::ENOENT)

尽管sudo gitlab-ctl status redis显示服务正常，但实际连接存在问题。执行全服务重启：

sudo gitlab-ctl restart

3.4 处理额外的暂停迁移

重新运行reconfigure后，系统又提示另一个表的迁移被暂停：

sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,taggings,id,'[["id"\, "taggable_id"]\, ["id_convert_to_bigint"\, "taggable_id_convert_to_bigint"]]']

完成所有暂停的迁移后，最终执行：

sudo gitlab-ctl reconfigure sudo gitlab-rake db:migrate

4. 经验总结与预防措施

经过这次升级，我整理了一套GitLab升级最佳实践：

1. 预升级检查清单：

   • 确认磁盘空间至少是数据库大小的2倍
   • 检查sudo gitlab-rake db:migrate:status输出
   • 备份关键数据：sudo gitlab-rake gitlab:backup:create

2. 升级过程中的监控重点：

   • 后台迁移状态：sudo gitlab-rake gitlab:background_migrations:status
   • 资源使用情况：top、df -h、free -m
   • 错误日志实时跟踪：tail -f /var/log/gitlab/gitlab-rails/production.log

3. 常见问题快速参考：

那次深夜的升级经历让我明白，GitLab升级远不止是版本号的变更，更是对系统架构理解的考验。现在每次执行升级前，我都会先泡杯咖啡，打开三个终端分别监控日志、资源使用和迁移状态——这成了我的升级仪式感。