排查直接传输迁移问题

在 rails console 会话 中， 你可以使用以下命令查找尝试导入组时出现的失败或错误信息：

# 获取相关的导入记录
import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import).last

# 通过用户进行替代查找
import = BulkImport.where(user_id: User.find(...)).last

# 获取导入实体列表。每个实体代表一个组或一个项目
entities = import.entities

# 获取实体失败列表
entities.map(&:failures).flatten

# 通过状态进行替代失败查找
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 内存限制： 如果你的实例有可用内存，增加 Sidekiq 进程的最大 RSS 限制。 例如，你可以将限制从 2 GB 增加到 3 GB 以防止频繁重启。

• 增加最大中断次数： 为了允许作业在失败前有更多中断次数，你可以增加 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"'

目标实例

在极少数情况下，目标实例可能无法成功迁移组或项目。 更多信息，请参见 issue 498720。

要解决此问题，请使用 import API 迁移失败的组或项目。 通过此 API，你可以单独迁移特定的组和项目。

错误：404 Group Not Found

如果你尝试导入一个路径仅包含数字的组（例如 5000），GitLab 会尝试 通过 ID 而不是路径来查找该组。这会在 GitLab 15.4 及更早版本中导致 404 Group Not Found 错误。

要解决此问题，你必须使用以下方法更改源组路径以包含非数字字符：

• 使用 GitLab UI：

  1. 在左侧边栏，选择 Search or go to 并找到你的组。
  2. 选择 Settings > General。
  3. 展开 Advanced。
  4. 在 Change group URL 下，更改组 URL 以包含非数字字符。

• 使用 Groups 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 会重试退出的命令。

错误：Batch export [batch_number] from source instance failed

在目标实例上，你可能会遇到以下错误：

Batch export [batch_number] from source instance failed: [source instance error]

当源实例无法导出某些记录时，会发生此错误。 最常见的原因是：

• 磁盘空间不足
• 由于内存不足导致 Sidekiq 作业多次中断
• 数据库语句超时

要解决此问题：

1. 识别并修复源实例上的问题。
2. 从目标实例中删除部分导入的项目或组，并启动新的导入。

有关未能导出的关系和批量的更多信息， 请使用源实例上的 项目 和 组 导出状态 API 端点。

错误：duplicate key value violates unique constraint

在导入记录时，你可能会收到以下错误：

PG::UniqueViolation: ERROR:  duplicate key value violates unique constraint

当处理导入的 Sidekiq 工作进程由于导入期间内存或 CPU 使用过高而重启时，可能会发生此错误。

要减少导入期间的 Sidekiq 内存或 CPU 问题：

• 优化导入的 Sidekiq 配置。
• 限制 bulk_import_concurrent_pipeline_batch_limit 应用程序设置 中的并发作业数量。

错误：BulkImports::FileDownloadService::ServiceError Invalid content type

在使用 GitLab 实例之间的直接传输时，你可能会遇到以下错误：

BulkImports::FileDownloadService::ServiceError Invalid content type

此错误与实例之间的网络流量路由方式有关。 如果返回的内容类型不是 application/gzip， 你的网络请求可能会绕过 GitLab Workhorse。

要解决此问题：

• 检查你的 Ingress 是否配置为通过端口 8181 上的 GitLab Workhorse 路由流量， 而不是直接路由到 Puma。
• 考虑为对象存储启用 proxy downloads。