• 先决条件
  • 网络和存储空间
  • 版本
  • 配置
• 用户贡献和成员映射
  • 在目标实例上配置用户
• 连接源极狐GitLab实例
• 选择要导入的群组和项目
• 查看导入结果
• 群组导入历史
• 取消正在运行的迁移
  • 使用 REST API 取消
  • 使用 Rails 控制台取消
• 重试失败或部分成功的迁移

{{< details >}}

• Tier: 基础版，专业版，旗舰版
• Offering: JihuLab.com, 私有化部署

{{< /details >}}

要通过直接传输来迁移极狐GitLab群组和项目，您需要：

1. 满足先决条件。
2. 查看用户贡献和成员映射，并在目标实例上配置用户。
3. 连接源极狐GitLab实例。
4. 选择要导入的群组和项目并开始迁移。
5. 查看导入结果。

如果出现任何问题，您可以：

1. 取消或重试迁移。
2. 检查故障排除信息。

先决条件

{{< history >}}

• 在极狐GitLab 16.0 中引入了对维护者角色的要求，并被回溯到极狐GitLab 15.11.1 和极狐GitLab 15.10.5。

{{< /history >}}

在使用直接传输进行迁移之前，请查看以下先决条件。

网络和存储空间

• 实例之间或 JihuLab.com 之间的网络连接必须支持 HTTPS。
• 防火墙不得阻止源和目标极狐GitLab实例之间的连接。
• 源和目标极狐GitLab实例必须在 /tmp 目录中有足够的空闲空间，以创建和提取已传输项目和群组的存档。

版本

为了最大限度地提高迁移的成功率和性能，您应该：

• 将源和目标实例都升级到极狐GitLab 16.8 或更高版本，以使用关系的批量导入和导出。
• 在尽可能新的版本之间进行迁移。更新源和目标实例到尽可能晚的版本，以利用随时间添加的错误修复和改进。
• 正确配置 Sidekiq。

我们已经成功测试了在运行极狐GitLab 16.2 的源实例和运行极狐GitLab 16.8 的目标实例之间的迁移。

配置

• 两个极狐GitLab实例必须由实例管理员在应用程序设置中启用通过直接传输进行群组迁移。
• 您必须拥有源极狐GitLab实例的个人访问令牌：
  • 对于极狐GitLab 15.1 及更高版本的源实例，个人访问令牌必须具有 api 范围。
  • 对于极狐GitLab 15.0 及更早版本的源实例，个人访问令牌必须同时具有 api 和 read_repository 范围。
• 您必须在源和目标实例上拥有所需的权限。对于：
  • 大多数用户，您需要：
    • 在要迁移的源群组上具有所有者角色。
    • 在允许您在该命名空间中创建子群组的目标命名空间中拥有角色。
  • 两个实例的管理员没有所需的角色时，您可以使用API启动导入。
• 要导入项目代码片段，请确保代码片段在源项目中启用。
• 要导入存储在对象存储中的项目，您必须：
  • 配置 proxy_download。
  • 确保目标极狐GitLab实例可以访问源极狐GitLab实例的对象存储。
• 当源实例或群组的创建项目所需的默认最低角色设置为无时，您无法导入带有项目的群组。如有必要，可以更改此设置：
  • 对于整个实例。
  • 对于特定群组。

用户贡献和成员映射

{{< details >}}

• Offering: 私有化部署

{{< /details >}}

{{< history >}}

• 在极狐GitLab 16.3 中引入了作为直接成员的共享和继承共享成员的映射。
• 在极狐GitLab 16.11 中引入，作为导入的群组或项目的共享或继承共享成员的共享和继承共享成员不再映射为直接成员。
• 在极狐GitLab 17.1 中引入了对继承成员映射的完整支持。
• 在极狐GitLab 17.5 中从 JihuLab.com 的直接传输中移除，转而使用替代方案。
• 在极狐GitLab 17.7 中从极狐GitLab私有化部署和极狐GitLab Dedicated 中移除作为默认直接传输方法，转而使用替代方案。

{{< /history >}}

这种用户贡献和成员映射的方法适用于当 importer_user_mapping 和 bulk_import_importer_user_mapping 被禁用时的极狐GitLab私有化部署。默认情况下，这些功能标志是启用的。有关适用于极狐GitLab私有化部署和 JihuLab.com 的默认方法的信息，请参阅用户贡献和成员映射。

在迁移过程中永远不会创建用户。相反，源实例上的用户贡献和成员资格映射到目标实例上的用户。用户成员资格的映射类型取决于源实例上的成员资格类型：

• 直接成员资格映射为目标实例上的直接成员资格。
• 继承成员资格映射为目标实例上的继承成员资格。
• 共享成员资格映射为目标实例上的直接成员资格，除非用户已有共享成员资格。

在映射继承和共享成员资格时，如果用户在目标命名空间中已有一个更高角色的成员资格，则成员资格将映射为直接成员资格。这确保成员不会获得提升的权限。

{{< alert type=”note” >}}

有一个已知问题影响共享成员资格的映射。

{{< /alert >}}

在目标实例上配置用户

为了确保极狐GitLab在源和目标实例之间正确映射用户及其贡献：

1. 在目标极狐GitLab实例上创建所需的用户。您只能在极狐GitLab私有化部署实例上通过 API 创建用户，因为这需要管理员访问权限。当迁移到 JihuLab.com 或极狐GitLab私有化部署时，您可以：
   • 手动创建用户。
   • 设置或使用现有的SAML SSO 提供商，并利用通过SCIM支持的 SAML SSO 群组的用户同步。您可以使用已验证的电子邮件域绕过极狐GitLab用户账户验证。
2. 确保用户在源极狐GitLab实例上有一个公开电子邮件，该电子邮件与目标极狐GitLab实例上的任何已确认电子邮件地址匹配。大多数用户会收到一封电子邮件，要求他们确认他们的电子邮件地址。
3. 如果用户已经存在于目标实例上，并且您使用极狐GitLab.com 群组的 SAML SSO，所有用户必须将他们的 SAML 身份链接到他们的 JihuLab.com 账户。

在极狐GitLab UI 或 API 中没有自动为用户设置公开电子邮件地址的方法。

连接源极狐GitLab实例

在目标极狐GitLab实例上，创建您要导入的群组并连接源极狐GitLab实例：

1. 创建以下之一：
   • 一个新群组。在左侧边栏顶部，选择创建新 ({{< icon name=”plus” >}}) 和新群组。然后选择导入群组。
   • 一个新子群组。在现有群组的页面上，选择新子群组。或在左侧边栏顶部，选择创建新 ({{< icon name=”plus” >}}) 和新子群组。然后选择导入现有群组链接。
2. 输入极狐GitLab实例的基本 URL。
3. 输入您的源极狐GitLab实例的个人访问令牌。
4. 选择连接实例。

选择要导入的群组和项目

{{< history >}}

• 在极狐GitLab 15.8 中引入了带或不带项目导入群组的选项。
• 在极狐GitLab 17.6 中引入了导入用户成员资格复选框。

{{< /history >}}

在您授权访问源极狐GitLab实例后，您将被重定向到极狐GitLab群组导入页面。在这里，您可以看到连接的源实例上您拥有所有者角色的顶级群组列表。

如果您不想从源实例导入所有用户成员资格，请确保清除导入用户成员资格复选框。例如，源实例可能有 200 名成员，但您可能只想导入 50 名成员。导入完成后，您可以向群组和项目添加更多成员。

1. 默认情况下，建议的群组命名空间与它们在源实例中的名称相匹配，但根据您的权限，您可以在继续导入其中任何一个之前选择编辑这些名称。群组和项目路径必须符合命名规则，如果需要，会进行规范化以避免导入失败。
2. 在您要导入的群组旁边，选择以下之一：
   • 带项目导入。如果不可用，请参阅先决条件。
   • 不带项目导入。
3. 状态列显示每个群组的导入状态。如果您将页面保持打开状态，它会实时更新。
4. 群组导入后，选择其极狐GitLab路径以打开其极狐GitLab URL。

{{< alert type=”warning” >}}

带项目导入群组处于测试版。此功能尚未准备好用于生产环境。

{{< /alert >}}

查看导入结果

{{< history >}}

• 在极狐GitLab 16.6 中引入，使用名为 bulk_import_details_page 的功能标志。默认启用。
• 极狐GitLab 16.8 中移除了 bulk_import_details_page 功能标志。
• 在极狐GitLab 16.9 中增加了部分完成和完成导入的详细信息。
• 在极狐GitLab 17.0 中引入了一个已导入徽章，以指示设计、史诗、议题、合并请求、备注（系统备注和评论）、代码片段以及用户档案活动已导入。

{{< /history >}}

要查看导入结果：

1. 转到群组导入历史页面。
2. 要查看失败导入的详细信息，请选择任何状态为失败或部分完成的导入上的显示错误链接。
3. 如果导入状态为部分完成或完成，要查看哪些项目已导入和未导入，请选择查看详细信息。

您还可以通过在极狐GitLab UI 中某些项目上看到一个已导入徽章来看到某个项目已导入。

群组导入历史

{{< history >}}

• 在极狐GitLab 16.7 中引入了部分完成状态。

{{< /history >}}

您可以查看所有通过直接传输迁移的群组在群组导入历史页面上的列表。此列表包括：

• 源群组的路径。
• 目标群组的路径。
• 每次导入的开始日期。
• 每次导入的状态。
• 如果发生任何错误，则为错误详细信息。

要查看群组导入历史：

1. 登录极狐GitLab。
2. 在左侧边栏顶部，选择创建新 ({{< icon name=”plus” >}}) 和新群组。
3. 选择导入群组。
4. 在右上角，选择历史记录。
5. 如果某个导入出现任何错误，请选择显示错误以查看其详细信息。

取消正在运行的迁移

如有需要，您可以通过 REST API 或 Rails 控制台取消正在运行的迁移。

使用 REST API 取消

有关使用 REST API 取消正在运行的迁移的信息，请参阅取消迁移。

使用 Rails 控制台取消

要使用 Rails 控制台取消正在运行的迁移：

1. 在目标极狐GitLab实例上启动一个Rails 控制台会话。

2. 通过运行以下命令找到最后一次导入。将 USER_ID 替换为启动导入的用户 ID：

   bulk_import = BulkImport.where(user_id: USER_ID).last
   

3. 通过运行以下命令使导入及其所有相关项目失败：

   bulk_import.entities.each do |entity|
     entity.trackers.each do |tracker|
       tracker.batches.each(&:fail_op!)
     end
     entity.trackers.each(&:fail_op!)
     entity.fail_op!
   end
   bulk_import.fail_op!
   

取消 bulk_import 不会阻止正在源实例上导出项目的工作者，但会阻止目标实例：

• 请求源实例导出更多项目。
• 为各种检查和信息向源实例发出其他 API 调用。

重试失败或部分成功的迁移

如果您的迁移失败，或部分成功但缺少项目，您可以重试迁移。要重试迁移：

• 顶级群组及其所有子群组和项目，请使用极狐GitLab UI 或极狐GitLab REST API。
• 特定子群组或项目，请使用极狐GitLab REST API。