使用文件导出迁移项目和组

文件导出为您提供一个可移植的 GitLab 数据包，可在离线环境中使用。 这种迁移方法会保留大部分项目数据，包括 仓库、问题、合并请求和评论。

使用文件导出可以：

• 在离线环境之间迁移。
• 移动特定项目而不移动其整个组结构。

直接传输 仍然是大多数情况下的推荐迁移方法。

已知问题

• 由于已知问题，您可能会遇到 PG::QueryCanceled: ERROR: canceling statement due to statement timeout 错误。 更多信息，请参阅 故障排除文档。
• 在 GitLab 17.0、17.1 和 17.2 版本中，导入的史诗和工作项会被映射到 导入用户而不是原始作者。
• 对于合并请求，仅在导入或导出过程中保留最新的 diff。 导入或导出项目后，仅显示合并请求中的最新 diff 版本和最新流水线。

通过上传导出文件迁移项目

现有项目可以导出到文件，然后导入到另一个 GitLab 实例中。

保留用户贡献

保留用户贡献的要求取决于您是迁移到 GitLab.com 还是迁移到 GitLab 自托管实例。

从 GitLab 自托管迁移到 GitLab.com

当使用文件导出迁移项目时，需要管理员访问令牌才能正确映射用户贡献。

因此，当从 GitLab 自托管实例导入文件导出到 GitLab.com 时，用户贡献永远不会正确映射。 相反，所有 GitLab 用户关联（如评论作者）都会更改为导入项目的用户。要保留 贡献历史，请执行以下操作之一：

• 使用直接传输进行迁移。
• 考虑使用专业服务。更多信息，请参阅 专业服务完整目录。

迁移到 GitLab 自托管

为确保 GitLab 正确映射用户及其贡献：

• 项目的顶级组所有者应导出项目，以便可以包含所有成员（直接 和继承）的访问信息。项目维护者和所有者可以 启动项目导出。但是，仅导出项目的直接成员。
• 必须由管理员执行导入。
• 目标 GitLab 实例上必须存在所需用户。管理员可以批量在 Rails 控制台中创建已确认用户，或在 UI 中逐个创建。
• 用户必须在源 GitLab 实例上在个人资料中设置公开邮箱，该邮箱必须与目标 GitLab 实例上的主要邮箱地址匹配。您也可以通过编辑项目导出文件手动添加用户的公开邮箱。

当现有用户的邮箱与导入用户的邮箱匹配时，该用户将被添加为 导入项目的直接成员。

如果未满足上述任何条件，用户贡献将不会正确映射。相反，所有 GitLab 用户 关联都会更改为执行导入的用户。该用户将成为其他用户创建的合并请求的作者。提及原始作者的补充评论：

• 会为评论、合并请求审批、关联任务和项目添加。
• 不会为合并请求或问题创建者、添加或删除的标签以及合并信息添加。

编辑项目导出文件

您可以添加或删除导出文件中的数据。例如，您可以：

• 手动向 project_members.ndjson 文件添加用户公开邮箱。
• 通过从 ci_pipelines.ndjson 文件中删除行来修剪 CI 流水线。

要编辑项目导出文件：

1. 解压导出的 .tar.gz 文件。
2. 编辑相应的文件。例如，tree/project/project_members.ndjson。
3. 将文件重新压缩为 .tar.gz 文件。

您还可以通过检查 project_members.ndjson 文件来确保所有成员都已导出。

兼容性

项目文件导出采用 NDJSON 格式。

您可以导入从 GitLab 导出文件，这些文件是从比目标版本最多两个 次要版本的 GitLab 版本导出的。

例如：

目标版本	兼容的源版本
13.0	13.0, 12.10, 12.9
13.1	13.1, 13.0, 12.10

将文件导出配置为导入源

在使用文件导出迁移 GitLab 自托管上的项目之前，GitLab 管理员必须：

1. 在源实例上启用文件导出。
2. 为目标实例启用文件导出作为导入源。在 GitLab.com 上，文件导出已启用 作为导入源。

为目标实例启用文件导出作为导入源：

1. 在左侧边栏底部，选择管理员。
2. 选择设置 > 常规。
3. 展开导入和导出设置。
4. 滚动到导入源。
5. 选择GitLab 导出复选框。

在 CE 和 EE 之间迁移

您可以将项目从社区版导出到企业版， 反之亦然，前提是满足兼容性要求。

如果您将项目从企业版导出到社区版，可能会丢失 仅在企业版中保留的数据。更多信息，请参阅 从 EE 降级到 CE。

导出项目及其数据

在导入项目之前，必须先导出它。

先决条件：

• 查看导出的项目项列表。并非所有项目都会被导出。
• 您必须至少拥有项目的维护者角色。
• 对于具有大量 Git 引用的仓库，要获得显著提升的性能，请使用 GitLab 18.0 或更高版本。更多信息，请参阅我们的 关于减少 GitLab 仓库备份时间的博客文章。

要导出项目及其数据，请按照以下步骤操作：

1. 在左侧边栏，选择搜索或转到并找到您的项目。
2. 选择设置 > 常规。
3. 展开高级。
4. 选择导出项目。
5. 导出生成后，您可以：
   • 遵收到的邮件中包含的链接。
   • 刷新项目设置页面，在导出项目区域选择下载导出。

导出文件会在您配置的 shared_path（临时共享目录）中生成，然后 移动到您配置的 uploads_directory。每 24 小时，一个工作进程会删除这些导出文件。

导出的项目项

导出的项目项取决于您使用的 GitLab 版本。要确定特定 项目项是否被导出：

1. 检查 exporters 数组。
2. 检查您的 GitLab 版本项目的 project/import_export.yml 文件。例如，GitLab 16.8 的 https://gitlab.com/gitlab-org/gitlab/-/blob/16-8-stable-ee/lib/gitlab/import_export/project/import_export.yml。

快速概览，导出的项目项包括：

• 项目和 wiki 仓库
• 项目上传
• 项目配置（不包括集成）
• 问题
  • 问题评论
  • 问题迭代（在 GitLab 15.4 中引入）
  • 问题资源状态事件（在 GitLab 15.4 中引入）
  • 问题资源里程碑事件（在 GitLab 15.4 中引入）
  • 问题资源迭代事件（在 GitLab 15.4 中引入）
• 合并请求
  • 合并请求 diff
  • 合并请求评论
  • 合并请求资源状态事件（在 GitLab 15.4 中引入）
  • 合并请求多个被分配者（在 GitLab 15.3 中引入）
  • 合并请求审查者（在 GitLab 15.3 中引入）
  • 合并请求审批者（在 GitLab 15.3 中引入）
• 提交评论（在 GitLab 15.10 中引入）
• 标签
• 里程碑
• 代码片段
• 发布
• 时间跟踪和其他项目实体
• 设计管理文件和数据
• LFS 对象
• 问题看板
• CI/CD 流水线
• 流水线计划（不活跃的并分配给发起导入的用户）
• 受保护的分支和标签
• 推送规则
• Emoji 反应
• 直接项目成员 （如果您至少拥有导出项目的组的维护者角色）
• 作为直接项目成员继承的项目成员 （如果您拥有导出项目的组的所有者角色或对实例的管理员访问权限）
• 一些合并请求审批规则：
  • 受保护分支的审批
  • 符合条件的审批者
• 漏洞报告（在 GitLab 17.7 中引入）

未导出的项目项

未导出的项目项包括：

• 子流水线历史
• 流水器触发器
• 构建跟踪和产物
• 包和容器注册表镜像
• CI/CD 变量
• CI/CD 作业令牌允许列表
• Webhook
• 任何加密令牌
• 所需审批数量
• 仓库大小限制
• 允许推送到受保护分支的部署密钥
• 安全文件
• 与 Git 相关事件的活动日志（例如推送和创建标签）
• 与您的项目关联的安全策略
• 问题与关联项目之间的链接
• 与相关合并请求的链接
• 流水线计划变量

导入项目及其数据

您可以导入项目及其数据。可以导入的数据量取决于最大导入文件大小：

• 在 GitLab 自托管上，管理员可以 设置最大导入文件大小。
• 在 GitLab.com 上，该值设置为 5 GB。

先决条件

• 您必须已导出项目及其数据。
• 比较 GitLab 版本，确保您导入到的 GitLab 版本与您导出的 GitLab 版本相同或更高。
• 查看兼容性中的任何问题。
• 目标组的至少维护者角色。

导入项目

要导入项目：

1. 在左侧边栏顶部，选择新建（ ）和新项目/仓库。
2. 选择导入项目。
3. 在从以下位置导入项目中，选择GitLab 导出。
4. 输入您的项目名称和 URL。然后选择您之前导出的文件。
5. 选择导入项目。

您可以使用 API 查询导入状态。 查询可能会返回导入错误或异常。

导入项的变更

导出的项在导入时会发生以下变更：

• 拥有所有者角色的项目成员在导入时会被赋予维护者角色。
• 如果导入的项目包含来自派生仓库的合并请求，则会为这些合并请求创建新分支。 因此，新项目中的分支数量可能多于源项目。
• 如果 Internal 可见性级别受到限制， 所有导入的项目都会被赋予 Private 可见性。

部署密钥不会被导入。要使用部署密钥，您必须在导入的项目中启用它们并更新受保护的分支。

导入大型项目

如果您有较大的项目，请考虑使用 Rake 任务。

设置最大导入文件大小

管理员可以通过以下两种方式之一设置最大导入文件大小：

• 使用 Application settings API 中的 max_import_size 选项。
• 在管理员区域 UI中。

默认值为 0（无限制）。

速率限制

为避免滥用，默认情况下，用户受到以下速率限制：

请求类型	限制
导出	每分钟 6 个项目
下载导出	每个项目每分钟 1 次下载
导入	每分钟 6 个项目

通过上传导出文件迁移组（已弃用）

先决条件：

• 要迁移组的所有者角色。

使用文件导出，您可以：

• 将任何组导出到文件，然后将该文件上传到另一个 GitLab 实例或同一实例上的其他位置。
• 使用 GitLab UI 或 API。
• 逐个迁移组，然后逐个导出和导入每个组的项目。

当使用管理员访问令牌执行导入时，GitLab 会正确映射用户贡献。当您从 GitLab 自托管实例导入到 GitLab.com 时，GitLab 不会正确映射用户贡献。 通过专业服务团队的付费参与，可以在从 GitLab 自托管实例导入到 GitLab.com 时保留用户贡献的正确映射。

其他信息

• 导出文件存储在临时目录中，每 24 小时由特定工作进程删除。
• 要保留导入项目的组级关系，请先导出和导入组，以便项目可以 导入到所需的组结构中。
• 导入的组会被赋予 private 可见性级别，除非导入到父组中。
• 如果导入到父组，子组会继承相同的可见性级别，除非另有限制。
• 您可以将组从社区版导出到企业版， 反之亦然。企业版保留一些不属于社区版的组数据。如果您将组从 企业版导出到社区版，可能会丢失这些数据。更多信息，请参阅 从 EE 降级到 CE。

最大导入文件大小取决于您是导入到 GitLab 自托管还是 GitLab.com：

• 如果导入到 GitLab 自托管实例，您可以导入任意大小的导入文件。管理员可以使用以下任一方式更改此行为：
  • Application settings API 中的 max_import_size 选项。
  • 管理员区域。
• 在 GitLab.com 上，您可以使用不超过 5 GB 大小的导入文件导入组。

兼容性

组文件导出采用 NDJSON 格式。

您可以导入从 GitLab 导出文件，这些文件是从比目标版本最多两个 次要版本的 GitLab 版本导出的。

例如：

目标版本	兼容的源版本
13.0	13.0, 12.10, 12.9
13.1	13.1, 13.0, 12.10

导出的组项

组的 import_export.yml 文件列出了使用文件导出迁移组时导出和导入的项目。在您的 GitLab 版本的分支中查看此文件， 以检查哪些项目可以导入到目标 GitLab 实例中。例如， 16-8-stable-ee 分支上的 import_export.yml。

导出的组项包括：

• 里程碑
• 组标签（不带关联的标签优先级）
• 看板和看板列表
• 徽章
• 子组（包括上述所有数据）
• 史诗
  • 史诗资源状态事件。在 GitLab 15.4 中引入。
• 事件
• Wiki
• 迭代周期。在 GitLab 15.4 中引入。

未导出的组项

未导出的组项包括：

• 项目
• Runner 令牌
• SAML 发现令牌
• 上传

准备工作

• 要保留导入组的成员列表及其相应权限，请查看这些组中的用户。 确保在导入所需组之前这些用户存在。
• 用户必须在源 GitLab 实例上设置公开邮箱，该邮箱必须与目标 GitLab 实例上的已确认主要邮箱匹配。大多数用户会收到要求他们确认邮箱地址的邮件。

导出组

先决条件：

• 您必须拥有该组的所有者角色。

要导出组的内容：

1. 在左侧边栏，选择搜索或转到并找到您的组。
2. 选择设置 > 常规。
3. 在高级部分，选择导出组。
4. 导出生成后，您可以：
   • 遵收到的邮件中包含的链接。
   • 刷新组设置页面，在导出项目区域选择下载导出。

导入组

要导入组：

1. 在左侧边栏顶部，选择新建（ ）和新组。
2. 选择导入组。
3. 在从文件导入组部分，输入组名称并接受或修改关联的组 URL。
4. 选择选择文件。
5. 选择您要导入的 GitLab 导出文件。
6. 开始导入，选择导入。

速率限制

为避免滥用，默认情况下，用户受到以下速率限制：

请求类型	限制
导出	每分钟 6 个组
下载导出	每个组每分钟 1 次下载
导入	每分钟 6 个组

相关主题

• 项目导入和导出 API
• 项目导入和导出管理 Rake 任务
• 迁移 GitLab 组
• 组导入和导出 API
• 通过直接传输迁移组。