Help us learn about your current experience with the documentation. Take the survey.

排查后台迁移问题

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

因批处理后台迁移未完成导致数据库迁移失败

当升级到 GitLab 14.2 或更高版本时，数据库迁移可能会失败，并显示类似以下的错误信息：

StandardError: 发生错误，所有后续迁移已取消：

期望给定配置的批处理后台迁移被标记为 'finished'，但实际是 'active'：
  {:job_class_name=>"CopyColumnUsingBackgroundMigrationJob",
   :table_name=>"push_event_payloads",
   :column_name=>"event_id",
   :job_arguments=>[["event_id"],
   ["event_id_convert_to_bigint"]]
  }

要解决此错误：

如果您遵循了 14.2 版本特定的升级说明，请手动完成批处理后台迁移。
如果您没有遵循这些说明，您必须：
- 在升级到 14.2+ 之前，回滚并升级到所需的某个版本。
- 向前滚动，保持在当前版本，并手动确保批处理迁移成功完成。

回滚并遵循所需的升级路径

要回滚并遵循所需的升级路径：

回滚并恢复之前安装的版本。
在升级到 14.2+ 之前，先升级到 14.0.5 或 14.1。
在尝试再次升级之前，检查批处理后台迁移的状态，并确保它们都被标记为完成。如果仍有标记为活动的，手动完成它们。

向前滚动并在升级版本上完成迁移

向前滚动的过程取决于是否需要停机。

对于有停机时间的部署

运行所有批处理后台迁移可能需要相当长的时间，具体取决于您的 GitLab 安装规模。

在数据库中检查批处理后台迁移的状态，并使用适当的参数手动运行它们，直到状态查询不返回任何行。
当所有迁移的状态都标记为完成时，为您的安装重新运行迁移。
从您的 GitLab 升级中完成数据库迁移：
```
sudo gitlab-rake db:migrate
```
运行重新配置：
```
sudo gitlab-ctl reconfigure
```
完成您的安装升级。

对于无停机时间的部署

由于失败的迁移是部署后迁移，您可以保持在升级版本的运行实例上，并等待批处理后台迁移完成。

从错误消息中检查批处理后台迁移的状态，并确保它被列为完成。如果迁移仍然处于活动状态，可以：
- 等待它完成。
- 手动完成它。
重新运行您的安装迁移，以便剩余的部署后迁移完成。

后台迁移保留在 Sidekiq 队列中

以下操作可能会影响您的 GitLab 性能。它们运行执行各种数据库或文件更新的 Sidekiq 作业。

运行以下检查。如果检查返回非零值且计数没有随时间减少，请遵循本节中的其余步骤。

# 对于 Linux 包安装：
sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'

# 对于自编译安装：
cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'

重新执行以下命令是安全的，特别是当您有 1000+ 个待处理作业时，这可能会溢出您的运行时内存。

# 启动 rails 控制台
sudo gitlab-rails c

# 在 rails 控制台中执行以下命令
scheduled_queue = Sidekiq::ScheduledSet.new
pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }

# 启动 rails 控制台
sudo -u git -H bundle exec rails RAILS_ENV=production

# 在 rails 控制台中执行以下命令
scheduled_queue = Sidekiq::ScheduledSet.new
pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }

后台迁移卡在 “pending” 状态

对于卡在 pending 状态的后台迁移，运行以下检查。如果它返回非零值且计数没有随时间减少，请遵循本节中的其余步骤。

# 对于 Linux 包安装：
sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigrationJob.pending.count'

# 对于自编译安装：
cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigrationJob.pending.count'

重新尝试这些迁移以清除它们的 pending 状态是安全的：

# 启动 rails 控制台
sudo gitlab-rails c

# 在 rails 控制台中执行以下命令
Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
  puts "运行待处理作业 '#{job.class_name}'，参数为 #{job.arguments}"
  result = Gitlab::BackgroundMigration.perform(job.class_name, job.arguments)
  puts "结果: #{result}"
end

# 启动 rails 控制台
sudo -u git -H bundle exec rails RAILS_ENV=production

# 在 rails 控制台中执行以下命令
Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
  puts "运行待处理作业 '#{job.class_name}'，参数为 #{job.arguments}"
  result = Gitlab::BackgroundMigration.perform(job.class_name, job.arguments)
  puts "结果: #{result}"
end

高级搜索迁移卡住

在 GitLab 15.0 中，名为 DeleteOrphanedCommit 的高级搜索迁移可能在升级过程中永久卡在 pending 状态。此问题已在 GitLab 15.1 中修复。

如果您是使用 GitLab 15.0 和高级搜索的 GitLab 自托管客户，您会遇到性能下降。要清理此迁移，请升级到 15.1 或更高版本。

对于其他卡在 pending 状态的高级搜索迁移问题，重试已停止的迁移。

如果在所有待处理的高级搜索迁移完成之前升级 GitLab，任何在新版本中已移除的待处理迁移都无法执行或重试。在这种情况下，您必须从头重新创建索引。

错误：`Elasticsearch version not compatible`

要解决此问题，请确认您的 Elasticsearch 或 OpenSearch 版本与您的 GitLab 版本兼容。