直接转移迁移故障排查

在 Rails 控制台会话中，您可以使用如下命令发现群组导入的失败或错误信息：

# Get relevant import records
import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import).last

# Alternative lookup by user
import = BulkImport.where(user_id: User.find(...)).last

# Get list of import entities. Each entity represents either a group or a project
entities = import.entities

# Get a list of entity failures
entities.map(&:failures).flatten

# Alternative failure lookup by status
entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :status)

您还可以通过使用 API 端点来查看具有失败信息的所有已迁移实体。

导入超时

迁移可能会因为源或目标实例上的一些问题而陷入停滞或以 timeout 状态结束。要解决这些问题，请检查源和目标实例的日志。

源实例

在源实例上，停滞导入通常是由过量内存使用导致的，这可能会重启 Sidekiq 进程并中断导出作业。目标实例可能等待导出文件，直到迁移最终超时。

要想检查群组 或 项目 关系是否被成功导出，可以运行如下命令：

curl --request GET --location "https://example.gitlab.com/api/v4/projects/:ID/export_relations/status" \
--header "PRIVATE-TOKEN: <your_access_token>"

如果关系的状态不是 1，则关系没有成功导出，问题可能在源实例上。

您还可以运行以下命令来查找中断的导出作业。请注意，Sidekiq 日志在重新启动后可能会轮换，因此请务必检查轮换后的日志。

grep `BulkImports::RelationBatchExportWorker` sidekiq.log | grep "interrupted_count"

如果是 Sidekiq 重启导致的问题：

  • 为导出作业单独配置一个 Sidekiq 进程。更多详情，可以查看 Sidekiq 配置。如果问题依旧，请将并发限制降低，以限制同时处理的作业数。
  • 增加 Sidekiq 内存限制：如果您的实例有足够的内存，为 Sidekiq 进程增加最大 RSS 限制。比如，您可以将内存从 2GB 增加到 3GB 以防止频繁重启。

  • 增加最大中断计数：为了在作业失败之前允许更多中断，您可以增加 BulkImports::RelationBatchExportWorker 的最大中断计数：

    1. 增加以下配置以将限制增加到 20（默认是 3）：

      sidekiq_options max_retries_after_interruption: 20

    2. 重启 Sidekiq 进程以使更改生效。

现在您可以触发一个新的迁移或使用关系导出 API 来手动触发导出。检查导出状态以查看关系是否被成功导出。

比如，要触发特定项目的导出，请运行以下命令：

curl --request POST --location "https://example.gitlab.com/api/v4/projects/:ID/export_relations" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--form 'batched="true"'

目标实例

在极少数情况下，目标实例可能会导致群组或项目的迁移失败。

要解决此问题，通过使用 导入 API来迁移失败的群组或项目。有了此 API，您可以单独迁移特定的群组和项目。

错误: 404 Group Not Found

如果您尝试导入一个路径只有数字的群组（比如 5000），则极狐GitLab 会尝试通过 ID 而不是路径来查找群组。这会导致极狐GitLab 15.4 及更早版本中的 404 Group Not Found 错误。

要解决此问题，您必须更改源群组路径以包含非数字字符，方法是：

  • 在极狐GitLab UI 上：

    1. 在左侧导航栏，选择 查找或前往 并找到您的群组。
    2. 选择 设置 > 通用。
    3. 展开 高级部分。
    4. 在 更改群组 URL 下，更改群组 URL 以包含非数字字符。

  • 群组 API。

其他 404 错误

当导入群组时，您可能还会接收到其他 404 错误，比如：

"exception_message": "Unsuccessful response 404 from [FILTERED] Bo...",
"exception_class": "BulkImports::NetworkError",

此错误预示着该错误是从 源 实例转移而来。要解决此问题，请检查您是否在源实例上满足先决条件。

群组或项目路径名称不匹配

如果源群组或项目路径名称不符合命名规则，则路径会被规范化以确保其有效。例如，Destination-Project-Path 会被规范化为 destination-project-path。

错误： command exited with error code 15 and Unable to save [FILTERED] into [FILTERED]

但使用直接转移进行迁移时候，您可以能会在日志中接收到错误 command exited with error code 15 and Unable to save [FILTERED] into [FILTERED]。如果您接收到了此错误，您可以安全的忽略它，因为极狐GitLab 会重试退出的命令。