当前位置：首页 > news >正文

极狐GitLab 如何使用文件导出迁移项目和群组？

news 来源：原创 2025/5/20 4:25:42

极狐GitLab 是 GitLab 在中国的发行版，关于中文参考文档和资料有：

极狐GitLab 中文文档
极狐GitLab 中文论坛
极狐GitLab 官网

用文件导出迁移项目和群组 (FREE ALL)

推荐使用直接传输迁移群组和项目。然而，在某些情况下，您可能需要使用文件导出迁移群组和项目。

已知问题

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

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

任何极狐GitLab自管理实例或极狐saas上的现有项目都可以导出为文件，然后导入到另一个极狐GitLab实例中。

保留用户贡献

保留用户贡献的要求取决于您是迁移到极狐saas还是极狐GitLab自管理实例。

从极狐GitLab自管理迁移到极狐saas

通过文件导出迁移项目时，需要管理员的访问令牌才能正确映射用户贡献。
因此，在将极狐GitLab自管理实例的文件导出导入到极狐saas时，用户贡献无法正确映射。
相反，所有极狐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 文件来确保所有成员已导出。

兼容性

在极狐GitLab 15.11中移除了支持JSON格式的项目文件导出。项目文件导出采用NDJSON格式。

您可以导入从极狐GitLab版本导出的项目文件，这些版本最多可以比当前版本落后两个小版本。

例如:

Destination version	Compatible source versions
13.0	13.0, 12.10, 12.9
13.1	13.1, 13.0, 12.10

将文件导出配置为导入源 (BASIC SELF)

在私有化部署版实例上使用文件导出迁移项目之前，极狐GitLab 管理员必须：

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

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

1.在左侧边栏中，选择 搜索或转到。
2.选择 管理中心。
3.在左侧边栏中，选择 设置 > 通用。
4.展开 可见性和访问控制。
5.滚动到 导入来源。
6.选择 极狐GitLab 导出。

导出项目及其数据

在您可以导入项目之前，您必须将其导出。

先决条件：

查看导出的数据的列表，并非所有数据都导出。
您必须至少具有项目的维护者角色。

要导出项目及其数据，请执行以下步骤：

1.在左侧边栏，选择 搜索或前往 并找到您的项目。
2.选择 设置 > 常规。
3.展开高级。
4.选择 导出项目。
5.在导出生成后，您可以：

跟随您应该收到的电子邮件中的链接。
刷新项目设置页面，在 导出项目 区域，选择 下载导出。

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

导出的项目项

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

项目和 Wiki 仓库
项目上传的文件
项目配置，不包括集成
问题
- 问题评论
- 问题迭代（极狐GitLab 15.4引入）
- 问题资源状态事件（极狐GitLab 15.4引入）
- 问题资源里程碑事件（极狐GitLab 15.4引入）
- 问题资源迭代事件（极狐GitLab 15.4引入）
合并请求
- 合并请求差异
- 合并请求评论
- 合并请求资源状态事件（极狐GitLab 15.4引入）
- 合并请求多个指派人（极狐GitLab 15.3引入）
- 合并请求审阅者（（极狐GitLab 15.3引入）
- 合并请求审批人（极狐GitLab 15.3引入）
提交评论（（极狐GitLab 15.10引入）
标签
里程碑
片段
发布
时间追踪和其他项目实体
设计管理文件和数据
LFS 对象
问题板
CI/CD 流水线
流水线调度（不活跃并分配给发起导入的用户）
受保护的分支和标签
推送规则
表情符号反应
直接项目成员（如果您至少是导出项目组的维护者角色）
作为直接项目成员继承的项目成员（如果您是导出项目组的所有者角色或具有实例管理员权限）
一些合并请求审批规则：
- 受保护分支的审批
- 合格的审批者
漏洞报告（极狐GitLab 17.7 引入）

不导出的项目项

未导出的项目项包括：

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

通过文件导出迁移项目使用与创建模板项目相同的导入和导出机制，包括组和实例级别。因此，导出的项目项列表是相同的。

导入项目及其数据

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

在极狐GitLab自管理实例上，实例管理员可以设置最大导入文件大小。
在极狐saas上，值为5 GB。

警告：
仅从您信任的来源导入项目。如果您从不受信任的来源导入项目，攻击者可能窃取您的敏感数据。

先决条件

在极狐GitLab 16.0中引入了对维护者角色的要求，而不是开发者角色，并已回溯到极狐GitLab 15.11.1和极狐GitLab 15.10.5。

您必须导出项目及其数据。
比较极狐GitLab版本，确保您导入到的极狐GitLab版本与您导出的极狐GitLab版本相同或更高。
检查 兼容性 是否有问题。
在目标组中至少具有维护者角色。

导入项目

要导入项目：

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

您可以通过API查询导入的状态。
查询可能返回导入错误或异常。

导入项目的变更

导入的项目会有以下变更：

拥有 “Owner” 角色的项目成员将被导入为 “Maintainer” 角色。
如果导入的项目包含来自分支的合并请求，新的与这些合并请求相关的分支将在项目中创建。因此，目标项目中的分支数量可能会比源项目中的更多。
如果导入项目的 Internal 可见性级别被限制，所有导入的项目将设置为 Private 可见性。

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

导入大型项目 (FREE ALL)

如果你有较大的项目，建议考虑使用Rake 任务。

设置最大导入文件大小 (FREE ALL)

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

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

默认值为0（无限制）。

限制速率

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

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

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

在极狐GitLab 14.6中已弃用。

警告：
此功能在极狐GitLab 14.6中已弃用，并由直接迁移组取代。然而，该功能仍建议用于在离线系统之间迁移组。有关离线环境解决方案的最新进展，请参见相关 epic。

前提条件：

拥有迁移组的 Owner 角色。

使用文件导出，你可以：

将任何组导出到文件，并将该文件上传到另一个极狐GitLab实例或同一实例的其他位置。
使用极狐GitLab UI或API进行操作。
按顺序迁移组，一个组一个组地导出并导入每个项目。

当使用管理员访问令牌执行导入时，极狐GitLab会正确映射用户贡献。在从自管理实例导入到极狐saas时，极狐GitLab无法正确映射用户贡献。如果从自管理实例导入到极狐saas需要正确映射用户贡献，可以通过付费参与极狐GitLab专业服务团队来实现。

其他信息

导出文件存储在临时目录中，并由特定的工作程序在24小时后删除。
为了保持导入项目的组级关系，首先导出并导入组，以便项目可以导入到所需的组结构中。
导入的组将设置为private可见性，除非导入到父组中。
如果导入到父组中，子组将继承父组的可见性级别，除非另有限制。
可以将组从社区版导出到企业版，反之亦然。企业版保留一些社区版不包含的组数据。如果将企业版的组导出到社区版，可能会丢失这些数据。有关更多信息，请参见从 EE 降级到 CE。

最大导入文件大小取决于是导入到极狐GitLab自管理实例还是极狐 saas：

如果导入到极狐GitLab自管理实例，可以导入任意大小的文件。管理员可以通过以下方式更改此行为：
- 使用Application settings API中的max_import_size选项。
- 在管理员区域中进行设置。
在极狐saas上，导入的组文件最大为5 GB。

兼容性

在极狐GitLab 15.8版本移除了JSON 格式的项目文件导出。组文件导出为NDJSON格式。

你可以导入从最多两个次要版本之前的极狐GitLab版本导出的组文件。

例如：

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

导出的组项

导出的组项包括：

里程碑
组标签（__ 关联的标签优先级）
看板和看板列表
徽章
子组（包括所有上述数据）
史诗
- 史诗资源状态事件（在极狐GitLab 15.4中引入）
事件
Wiki
迭代节奏（在极狐GitLab 15.4中引入）

不导出的组项

不导出的项包括：

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

准备工作

为了在导入组时保留成员列表及其各自的权限，请审查这些组中的用户。确保在导入所需组之前，这些用户在目标实例中已存在。
用户必须在极狐GitLab实例中设置与其确认的主要电子邮件匹配的公开电子邮件地址。大多数用户会收到一封电子邮件，要求确认其电子邮件地址。

导出组

前提条件：

你必须拥有该组的Owner角色。

要导出组的内容：

1.在左侧边栏中，选择 搜索或转到 并找到你的组。
2.选择 设置 > 一般。
3.在高级部分，选择 导出组。
4.导出生成后，你可以：

点击你收到的电子邮件中的链接。
刷新组设置页面，在导出项目 区域选择 下载导出。

导入组

要导入组：

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

限制速率

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

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

用文件导出迁移项目和群组 (FREE ALL)

已知问题

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

保留用户贡献

从极狐GitLab自管理迁移到极狐saas

迁移到极狐GitLab自管理

编辑项目导出文件

兼容性

将文件导出配置为导入源 (BASIC SELF)

导出项目及其数据

导出的项目项

不导出的项目项

导入项目及其数据

设置最大导入文件大小 (FREE ALL)

限制速率

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

其他信息

兼容性

导出的组项

不导出的组项

导出组

导入组

限制速率

相关文章：