Debian系统中如何迁移GitLab数据

Debian系统下迁移GitLab数据的完整步骤

一 迁移总览与前置检查

• 核对版本：在两台机器上查看 GitLab 版本，确保迁移前后版本一致（或按官方支持路径升级）。命令：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION。若版本不一致，先规划升级路径再迁移。
• 规划停机：备份与恢复期间建议短暂停机，避免写入导致不一致。
• 备份范围：Omnibus 包备份默认包含数据库、仓库、附件、CI 作业输出/工件、LFS、Pages、包、Terraform 状态等；不包含配置文件、TLS 证书、SSH 主机密钥、Redis 数据。迁移时必须单独迁移配置文件与密钥。
• 目标机器准备：安装与源机器相同版本的 GitLab（Omnibus 或 Docker），并预留足够磁盘空间。

二 源服务器备份

• Omnibus 包安装（Debian 常用）：
  • 创建备份（GitLab 12.2+）：sudo gitlab-backup create；老版本可用：sudo gitlab-rake gitlab:backup:create。备份默认位于 /var/opt/gitlab/backups/。
  • 备份配置文件与密钥（必须单独拷贝）：
    • /etc/gitlab/gitlab.rb
    • /etc/gitlab/gitlab-secrets.json
  • 如自定义了备份目录，请同时迁移该目录内容。
• Docker 部署：
  • 在容器内执行备份：docker exec -t <容器名> gitlab-backup create（老版本用 rake）。备份通常位于容器内 /var/opt/gitlab/backups，对应宿主机挂载目录（如 /srv/gitlab/data/backups 或自定义卷）。
  • 同时拷贝宿主机上挂载的配置卷（含 gitlab.rb、gitlab-secrets.json）与证书目录。

三 目标服务器恢复

• 安装与版本匹配：在目标 Debian 机器安装与源机器相同版本的 GitLab（Omnibus 或同标签的 gitlab/gitlab-ce 镜像）。
• 放置备份与配置：
  • Omnibus：将备份 tar 放入 /var/opt/gitlab/backups/；将 gitlab.rb 与 gitlab-secrets.json 覆盖到 /etc/gitlab/。
  • Docker：将备份放入宿主机挂载的备份目录（如 /srv/gitlab/data/backups），将配置与密钥放入挂载的 config 目录。
• 停止相关服务并恢复：
  • Omnibus：
    • 停止写入服务：sudo gitlab-ctl stop puma；sudo gitlab-ctl stop sidekiq。
    • 执行恢复（BACKUP 参数填写备份文件名的时间戳前缀，不含 “_gitlab_backup.tar”）：sudo gitlab-backup restore BACKUP=。
    • 如跨服务器恢复，恢复后执行：sudo gitlab-rake gitlab:doctor:secrets 检查密钥可用性。
  • Docker：
    • 进入容器：docker exec -it <容器名> /bin/bash
    • 停止服务：gitlab-ctl stop puma；gitlab-ctl stop sidekiq
    • 恢复：gitlab-backup restore BACKUP=
• 重新配置与启动：
  • Omnibus：sudo gitlab-ctl reconfigure；sudo gitlab-ctl start
  • Docker：exit 后 docker restart <容器名>
• 验证：登录 Web，检查项目、用户、权限、Runner、LFS、Pages、包、CI 工件等是否正常。

四 常见问题与排错

• 版本不一致导致恢复失败：请确保源与目标 GitLab 版本一致；如需升级，遵循官方升级路径，先在原机升级并验证，再备份迁移。
• 页面 500 或 Runner 注册异常：多与加密密钥不匹配有关。跨机恢复后执行：sudo gitlab-rake gitlab:doctor:secrets；必要时按官方指引清理相关加密 token（如 runners_token、ci_jwt_signing_key 等）后重试。
• 备份命令占用或并发问题：GitLab 15.5.0 之前备份任务不会检测是否已有备份在运行，建议确保旧备份完成后再发起新备份。
• 配置文件遗漏：Omnibus 备份不包含 gitlab.rb、gitlab-secrets.json 与证书，务必单独迁移，否则会出现 2FA、CI 变量、Runner 注册等异常。
• 备份目录自定义：如修改过 gitlab_rails[‘backup_path’]，需确保迁移前后目录一致或同步更新配置。

五 附加方案 仅迁移代码仓库

• 适用于只需迁移仓库、无需保留用户、权限、Issue、CI 等的场景。逐仓库执行：
  • git clone --mirror <旧地址>//.git
  • cd
  • git remote set-url origin <新地址>//.git
  • git push --mirror
• 注意：该方法不会迁移项目成员、权限、保护分支、Webhook、CI/CD 配置等平台级数据。