ubuntu gitlab项目迁移攻略

Ubuntu 下 GitLab 项目迁移攻略

一 迁移总览与前置检查

• 迁移方式选择
  • 标准方式：使用官方备份与恢复（推荐），迁移完整数据（仓库、议题、合并请求、用户与权限、CI/CD 等）。
  • 仅迁移代码：通过 API 遍历项目，使用 git clone --mirror 批量镜像到新实例，适合跨版本或跨平台迁移。
• 版本与一致性
  • 源与目标 GitLab 版本需保持一致（如 14.8.2），否则恢复易失败；如需升级，建议先迁移成功后再升级目标实例。
  • 备份时 GitLab 需处于运行状态；恢复操作会清空当前数据，务必先做好备份。
• 关键文件与路径
  • 备份归档：默认 /var/opt/gitlab/backups/1658368484_2022_07_21_14.8.2_gitlab_backup.tar。
  • 机密与配置：/etc/gitlab/gitlab-secrets.json（必须一致，涉及密码、密钥、2FA）、/etc/gitlab/gitlab.rb（域名、端口、存储路径等）。
  • 备份配置：可在 /etc/gitlab/gitlab.rb 中设置备份路径与保留时间（如 gitlab_rails[‘backup_path’]、gitlab_rails[‘backup_keep_time’]）。

二 标准迁移步骤 Omnibus 包安装

• 源服务器备份
  • 查看版本：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION
  • 创建备份：gitlab-rake gitlab:backup:create（归档生成于 /var/opt/gitlab/backups）
  • 拷贝关键文件：将备份归档与 /etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json 一并拷贝到目标服务器（建议同目录结构）。
• 目标服务器准备
  • 安装与源一致的 GitLab 版本（如 gitlab-ce_14.8.2-ce.0_amd64.deb），执行 dpkg -i 后 gitlab-ctl reconfigure。
  • 将备份归档放入目标备份目录（默认 /var/opt/gitlab/backups），必要时 chown git:git 并设置权限（如 0644）。
  • 用源服务器的 gitlab-secrets.json 覆盖目标的同名文件，保持 gitlab.rb 中的域名/端口等配置一致或按需调整。
• 目标服务器恢复
  • 停止连接服务：gitlab-ctl stop unicorn && gitlab-ctl stop sidekiq
  • 执行恢复（BACKUP=后填时间戳前缀，不含 .tar）：gitlab-rake gitlab:backup:restore BACKUP=1658368484_2022_07_21_14.8.2
  • 启动服务：gitlab-ctl start；如配置了自定义备份目录，先 gitlab-ctl reconfigure 使路径生效。

三 Docker 部署的迁移要点

• 备份
  • 进入容器执行：docker exec -t <容器名> gitlab-backup create
  • 备份归档位于容器内 /var/opt/gitlab/backups，宿主机挂载目录通常为 /srv/gitlab/data/backups；同时备份 /srv/gitlab/config/（内含 gitlab.rb 与 gitlab-secrets.json）。
• 恢复
  • 将归档与 config 目录拷贝到目标宿主机相同路径；必要时先停止容器：docker stop <容器名>
  • 启动容器（挂载 data、logs、config），进入容器执行恢复：gitlab-backup restore BACKUP=<时间戳前缀>
  • 重启容器：docker start <容器名>；如涉及域名或端口变更，更新 config/gitlab.rb 后重新创建/启动容器。

四 仅迁移代码库的替代方案

• 适用场景
  • 跨大版本迁移、只迁移仓库（不含议题/MR/权限）、外部托管或精简迁移。
• 快速做法
  • 在源 GitLab 生成 Personal Access Token（权限至少 api），使用脚本遍历项目并以 git clone --mirror 镜像到本地；随后推送到目标 GitLab（若不存在则先通过 API 创建项目）。
  • 示例脚本要点：curl 获取项目列表（ssh_url_to_repo、path_with_namespace），循环 git clone --mirror；推送前检查目标项目是否存在，不存在则 POST /api/v4/projects 创建，再 git push --mirror。

五 常见问题与排错清单

• 版本不一致导致恢复失败
  • 两端版本必须一致；如需升级，先迁后升，或先在源端升级到目标版本再备份。
• 403/402 或登录异常
  • 核对 /etc/gitlab/gitlab-secrets.json 是否从源端完整覆盖到目标端；该文件关系到加密密钥与会话安全。
• 备份归档无法恢复或权限错误
  • 确认归档位于正确目录（默认 /var/opt/gitlab/backups），属主为 git:git，权限建议 0644；恢复时 BACKUP= 只填时间戳前缀。
• 自定义备份目录未生效
  • 在 /etc/gitlab/gitlab.rb 设置 gitlab_rails[‘backup_path’] 后执行 gitlab-ctl reconfigure；恢复前确保目录存在且权限正确。
• 恢复后项目缺失或为空
  • 恢复会清空现有数据；确认使用了正确的备份归档，且恢复命令执行成功无报错；必要时检查 Nginx/SSH 访问与仓库存储路径配置。