加速执行 GitLab 后台迁移任务及异常处理

在执行 GitLab 跨版本升级时，通常会有很多后台迁移任务需要运行，默认的调度策略会在后台进行穿行调度运行，消耗的时间会比较长。

同步运行所有后台迁移

从 17.x 版本开始，可以参考官网手册同步运行所有后台迁移任务。

## Start the rails console

databases = ActiveRecord::Tasks::DatabaseTasks.setup_initial_database_yaml

Gitlab::Database.database_base_models.each do |database_name, model|
  Gitlab::Database::SharedModel.using_connection(model.connection) do
    Gitlab::Database::BackgroundMigration::BatchedMigration.with_status([:paused, :active]).find_each(batch_size: 100) do |migration|
      puts "#{database_name}: Finalizing migration #{migration.job_class_name} (ID: #{migration.id})... "
      Gitlab::Database::BackgroundMigration::BatchedMigrationRunner.finalize(
        migration.job_class_name,
        migration.table_name,
        migration.column_name,
        Gitlab::Json.parse(migration.job_arguments),
        connection: model.connection
      )
      puts("done!\n")
    end
  end
end

小贴士：如果命令执行中出现中断也无所谓，可以重复执行，直到所有后台迁移任务完成。

如果出现某个后台迁移任务失败，优先参考 GitLab 变更日志，一般来说常见的问题都会在其中列举。

执行命令过程中会看到任务处于 Finalizing 状态

迁移加速

默认情况下，GitLab 会分配 sidekiq 执行后台迁移任务，老版本支持的 batched_migrations_parallel_execution 参数已经废弃。如果想加速后台迁移，可以修改配置增加执行器数量，修改 /etc/gitlab/gitlab.rb：

sidekiq['queue_groups'] = ['*'] * 4

默认情况下，只会使用一个 CPU 核心，一个进程内会有多个线程（默认 20 个），每个进程大约占用 1G 内存，增加执行器数量时应考虑到可用的内存，如果超量会导致 sidekiq 组件无法正常启动，循环报错。

异常处理

页面上所有的迁移任务完成后，为了防止网页异常，建议使用 SQL 命令复查一遍：

sudo gitlab-psql

执行命令：

SELECT
  job_class_name,
  table_name,
  column_name,
  job_arguments
FROM batched_background_migrations
WHERE status NOT IN(3, 6);

或者可以用非交互方式执行 SQL：

gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

可以筛选出来所有未成功完成的后台迁移任务，然后手动执行后台迁移：

sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>']

小贴士：其中的 <job_class_name>、<table_name> 等参数就是上述 SQL 查询出来的结果，需要注意的是最后一项的 <job_arguments> 任务参数，如果非空（[]）的情况下，需要用引号将其分隔，例如：
sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,ci_builds,id,'[["id"\, "stage_id"]\,["id_convert_to_bigint"\,"stage_id_convert_to_bigint"]]']

附录

参考链接

本文由柒创作，采用知识共享署名4.0 国际许可协议进行许可。
转载本站文章前请注明出处，文章作者保留所有权限。
最后编辑时间： 2025-06-04 16:55 PM