Linux下GitLab如何迁移

Linux下GitLab迁移实操指南

一 迁移总览与前置准备

• 迁移思路：在源服务器创建全量备份（包含数据库与仓库等），将备份与关键配置文件拷贝到目标服务器，在目标服务器恢复并校验。为降低风险，建议先在测试环境演练。
• 版本策略：优先保持源与目标GitLab版本一致；若需升级，遵循官方支持的逐级升级路径，不要跨大版本直接升级。
• 备份范围：使用官方备份工具会包含附件、Git仓库、CI/CD作业输出与工件、LFS对象、Pages、包、Terraform状态、容器镜像、群组Wiki、项目级安全文件等；但不包含配置文件、TLS证书/密钥、SSH主机密钥、Redis/Sidekiq作业等，这些需单独备份。

二 源服务器备份

• Omnibus安装（常见方式）创建备份：
  • 查看版本：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION
  • 创建备份：gitlab-rake gitlab:backup:create（或新版本用 gitlab-backup create）
  • 备份文件默认位于：/var/opt/gitlab/backups/，文件名通常包含时间戳与版本，如：1656107713_2022_06_25_15.0.0_gitlab_backup.tar
• 备份配置文件与密钥（必须单独拷贝）：
  • /etc/gitlab/gitlab.rb
  • /etc/gitlab/gitlab-secrets.json
  • 如使用容器或自托管，还需备份相应卷/目录中的配置与证书
• 权限与目录检查：
  • 确保备份目录属主为git:git，必要时执行：chown -R git:git /var/opt/gitlab/backups
• 传输到目标服务器（示例）：
  • scp /var/opt/gitlab/backups/1656107713_2022_06_25_15.0.0_gitlab_backup.tar root@新服务器IP:/var/opt/gitlab/backups/

三 目标服务器恢复

• 安装同版本GitLab：在新服务器安装与源服务器完全一致的GitLab版本（若计划升级，先同版本恢复成功后再按官方路径逐级升级）。
• 恢复配置文件与密钥：将源服务器的gitlab.rb与gitlab-secrets.json复制到新服务器的**/etc/gitlab/**，保持文件权限与属主正确。
• 放置备份文件：将备份tar包放到新服务器的**/var/opt/gitlab/backups/，属主为git:git**。
• 停止写入服务并恢复：
  • gitlab-ctl stop unicorn
  • gitlab-ctl stop sidekiq
  • 执行恢复（BACKUP取值为文件名中时间戳_版本部分，不含.tar）：
    • gitlab-rake gitlab:backup:restore BACKUP=1656107713_2022_06_25_15.0.0
  • 启动服务：gitlab-ctl start
• 首次访问与自检：
  • 访问新实例URL，登录后检查项目、用户、CI/CD、LFS、Pages、容器镜像等是否完整；必要时查看日志：gitlab-ctl tail。

四 常见场景与注意事项

• 跨版本迁移：先同版本恢复，再按官方升级路径逐级升级（如 13.12.Z → 14.0.Z → 14.1.Z → 14.Y.Z），每一步验证无误再继续，避免直接跨大版本。
• 自定义备份目录：若修改过gitlab.rb中的 gitlab_rails[‘backup_path’]，需确保目标服务器配置一致，目录存在且属主为git:git，然后执行 gitlab-ctl reconfigure 使配置生效。
• 仅迁移部分数据：
  • 只迁移代码仓库：可直接rsync源服务器的**/var/opt/gitlab/git-data/repositories**到目标服务器相同路径，然后 gitlab-ctl reconfigure；注意这不会迁移数据库与配置，适合特殊场景。
  • 迁移附件/LFS/制品：这些已包含在官方备份中，优先使用完整备份恢复。
• 故障排查要点：
  • 502/权限问题：检查备份与数据目录权限（如 chmod/chown -R git:git），必要时查看日志定位组件异常。
  • 备份占用/锁冲突：GitLab 15.5.0之前备份任务不会校验是否已有备份在运行，确保无并发备份后再执行。