GitLab在Linux中如何迁移项目

Linux下迁移GitLab项目的常用方式与步骤

一、方式总览与选择建议

方式	适用场景	是否保留完整历史	是否迁移用户/组/权限	主要优点	主要限制
官方备份恢复（gitlab-rake）	同版本迁移、整实例搬迁	是	是	简单可靠、官方支持	版本需一致，跨大版本需升级后再迁
手工镜像推送（git clone/fetch + push）	少量项目、跨实例/跨域名	是	否	不依赖实例整体迁移	需逐项目操作，元数据需另行处理
第三方工具 Congregate	大规模全量迁移（项目/组/用户）	是	是	批量编排、可回滚	需准备机器与Token，学习成本

二、官方备份恢复整实例迁移（推荐）

前提
- 新旧实例的 GitLab 版本保持一致（如 13.3.5-ee 对 13.3.5-ee），避免恢复时报版本不匹配。
- 备份文件默认位于 /var/opt/gitlab/backups，文件名形如 1626676976_2021_07_19_13.3.5-ee_gitlab_backup.tar。如自定义路径，以 /etc/gitlab/gitlab.rb 中 gitlab_rails[‘backup_path’] 为准。
- 迁移 EE（Enterprise Edition） 时，BACKUP 名称需包含 -ee 后缀，否则会报找不到文件。
步骤
1. 旧实例创建备份
  - 执行：sudo gitlab-rake gitlab:backup:create
  - 备份完成后将 /var/opt/gitlab/backups/xxx_gitlab_backup.tar 拷贝到新实例同目录（若自定义路径，请同步配置）。
2. 新实例安装同版本 GitLab
  - 使用 RPM/DEB 或 Docker 启动同版本实例（示例 Docker 启动命令见下文“Docker 场景”）。
3. 同步关键配置与密钥
  - 拷贝旧实例的 /etc/gitlab/gitlab.rb 与 /etc/gitlab/gitlab-secrets.json 到新实例对应路径，确保域名、SMTP、LDAP、密钥等一致。
4. 新实例恢复
  - 执行：sudo gitlab-rake gitlab:backup:restore BACKUP=1626676976_2021_07_19_13.3.5-ee
  - 如提示覆盖，输入 yes 继续。
5. 重新配置并启动
  - 执行：sudo gitlab-ctl reconfigure && sudo gitlab-ctl start
  - 登录 Web 检查项目、用户、权限与 Runner 是否正常。

三、手工镜像推送迁移（少量项目、跨实例）

四、使用 Docker 的场景

旧实例备份（宿主机执行）
- docker exec -it gitlab-ce-13.3.5-ee gitlab-rake gitlab:backup:create
- 备份文件位于容器内 /var/opt/gitlab/backups，从宿主机拷贝出来：docker cp gitlab-ce-13.3.5-ee:/var/opt/gitlab/backups/xxx.tar /host/backups/
新实例启动（与旧实例同版本）
- docker run -d --hostname gitlab -p 443:443 -p 80:80 -p 22:22 \ --name gitlab \ -v /opt/gitlab_docker/config:/etc/gitlab \ -v /opt/gitlab_docker/logs:/var/log/gitlab \ -v /opt/gitlab_docker/data:/var/opt/gitlab \ gitlab/gitlab-ee:13.3.5-ee.0
将备份拷入新容器并恢复
- docker cp /host/backups/xxx.tar gitlab:/var/opt/gitlab/backups/
- docker exec -it gitlab gitlab-rake gitlab:backup:restore BACKUP=1626676976_2021_07_19_13.3.5-ee
- 重启：docker exec -it gitlab gitlab-ctl reconfigure && gitlab-ctl restart

五、大规模全量迁移工具 Congregate（项目/组/用户）

适用：跨实例迁移大量项目、组与用户，保留提交历史与关联关系。
要点
- 准备一台 Linux 主机与 Docker，拉取 Congregate 镜像并启动容器（映射 /var/run/docker.sock 与配置文件）。
- 在容器内创建 data/congregate.conf，配置源/目标实例地址与管理员 Access Token，可设置并发、超时、是否迁移用户等参数。
- 通过 ./congregate.sh list 与 ./congregate.sh ui 选择需要迁移的对象（Projects/Groups/Users），生成 staged_*.json。
- 执行迁移：/congregate.sh migrate ...，先迁移用户，再迁移组与项目，支持重试与分批（wave）。

六、常见问题与注意事项

版本必须一致
- 恢复时报 GitLab version mismatch 时，需将新实例升级/降级到与备份一致的版本；EE 备份名需带 -ee。
备份与恢复路径
- 默认备份目录 /var/opt/gitlab/backups；如自定义，请同步 gitlab.rb 的 gitlab_rails[‘backup_path’]。
密钥与配置
- 迁移 gitlab-secrets.json 与 gitlab.rb 可保留 LDAP/SMTP/Runner 等配置与密钥一致性，减少恢复后故障。
分支保护
- 手工推送镜像时，目标项目默认分支可能受保护，需临时取消保护后再 git push --mirror，完成后恢复保护策略。
大规模迁移建议
- 使用 Congregate 分批（wave）迁移，先小范围演练，确认用户映射、权限与 CI 后再全量执行。

最新问答