故障排除

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

当更新到极狐GitLab 版本 14.2 或更高版本时，数据库迁移可能会失败，并显示如下消息：

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 '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 的特定版本升级说明进行操作。如果您已按照指示操作，您可以手动完成批处理后台迁移。如果没有，请选择以下方法之一：

  1. 回滚并升级到 14.2+ 之前的必需版本之一。
  2. 向前滚动，保持在当前版本，并手动确保批处理迁移成功完成。

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

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

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

对于有停机时间的部署

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

  1. 在数据库中检查批处理后台迁移的状态，并使用适当的参数手动运行它们，直到状态查询返回无行。
  2. 当所有状态标记为完成时，重新运行您安装的迁移。

  3. 从您的极狐 GitLab 升级中完成数据库迁移：

    sudo gitlab-rake db:migrate

  4. 运行重新配置：

    sudo gitlab-ctl reconfigure
  5. 完成您安装的升级。

对于无停机时间的部署

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

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

后台迁移仍在 Sidekiq 队列中

caution 以下操作可能会影响您的极狐 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+ 个待处理作业，这可能会溢出您的运行时内存。

::Tabs

:::TabTitle Linux 软件包（Omnibus）

# 启动 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) }

:::TabTitle 自行编译（source）

# 启动 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) }

::EndTabs

后台迁移卡在“待处理”状态

对于卡在待处理状态的后台迁移，运行以下检查。如果返回非零值且计数随时间不减少，请按照本节的其余步骤进行操作。

# 对于 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'

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

::Tabs

:::TabTitle Linux 软件包（Omnibus）

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

# 在 rails 控制台中执行以下命令
Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
  puts "Running pending job '#{job.class_name}' with arguments #{job.arguments}"
  result = Gitlab::BackgroundMigration.perform(job.class_name, job.arguments)
  puts "Result: #{result}"
end

:::TabTitle 自行编译（source）

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

# 在 rails 控制台中执行以下命令
Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
  puts "Running pending job '#{job.class_name}' with arguments #{job.arguments}"
  result = Gitlab::BackgroundMigration.perform(job.class_name, job.arguments)
  puts "Result: #{result}"
end

::EndTabs

如果高级搜索迁移卡住了怎么办？

在极狐GitLab 15.0 中，一个名为 DeleteOrphanedCommit 的高级搜索迁移可能会在升级过程中永久卡在待处理状态。此问题已在极狐GitLab 15.1 中得到修复。

如果您是使用极狐GitLab 15.0 进行高级搜索的私有化部署客户，您将遇到性能下降。要清理迁移，请升级到 15.1 或更高版本。

对于其他卡在待处理状态的高级搜索迁移，请参见如何重试中止的迁移。

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

遇到 Elasticsearch version not compatible 错误时该怎么办？

确认您的 Elasticsearch 或 OpenSearch 版本与您的极狐GitLab 版本兼容。