如何在Linux上恢复GitLab数据

Linux上恢复GitLab数据的完整步骤

一 恢复前准备

• 确认备份文件存在且完整：默认位于 /var/opt/gitlab/backups/，文件名通常形如 <时间戳>_gitlab_backup.tar。如使用自定义备份路径，请先确认 /etc/gitlab/gitlab.rb 中的 gitlab_rails[‘backup_path’] 设置。必要时将备份文件拷贝到该目录。
• 安装同版本或更高版本的 GitLab：恢复时的 GitLab 版本需与备份时一致或更新，否则可能出现兼容性问题。
• 备份并妥善保存配置文件与密钥：内置备份不包含配置文件与密钥，至少备份 /etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json；如使用容器或自建环境，还需备份相应配置卷与密钥。
• 建议先停止写入服务：为减少一致性风险，恢复前执行：
  sudo gitlab-ctl stop unicorn
  sudo gitlab-ctl stop sidekiq
  恢复完成后再启动服务。

二 标准恢复步骤

1. 将备份文件放到备份目录（默认 /var/opt/gitlab/backups），确保文件可被 git 用户读取。
2. 执行恢复命令（BACKUP 取值为文件名的时间戳前缀，不含扩展名）：
   sudo gitlab-rake gitlab:backup:restore BACKUP=<时间戳>
   示例：sudo gitlab-rake gitlab:backup:restore BACKUP=1720000000
   按提示输入 yes 确认覆盖现有数据。
3. 启动服务：
   sudo gitlab-ctl start unicorn
   sudo gitlab-ctl start sidekiq
   或直接：sudo gitlab-ctl restart
4. 登录 Web 界面验证：检查项目、仓库、用户、CI/CD 工件、LFS、Pages、包、容器注册表镜像等是否完整。

三 常见场景与要点

• 自定义备份路径：若备份不在默认目录，先在 /etc/gitlab/gitlab.rb 中设置 gitlab_rails[‘backup_path’] = “/your/backup/path”，执行 sudo gitlab-ctl reconfigure 使配置生效，再将备份文件放入该路径后恢复。
• 备份保留策略：为避免磁盘占满，可设置保留时间（秒），如 gitlab_rails[‘backup_keep_time’] = 604800（7 天）。
• 文件权限：确保备份文件对 git 用户可读，必要时执行：
  sudo chown git:git /var/opt/gitlab/backups/<备份文件>
• 版本匹配与升级策略：恢复版本需与备份时一致或更新；若需跨小版本恢复，建议先升级到目标版本再恢复。
• 只恢复代码仓库：如仅需迁移/恢复代码，可直接备份与恢复 /var/opt/gitlab/git-data/repositories（注意这不会包含数据库、用户与权限等元数据）。

四 验证与回滚建议

• 验证清单：
  • 访问 Web 页面，随机检出多个仓库，验证 SSH/HTTP 访问与权限。
  • 检查 CI/CD 流水线、作业工件、Runner 注册状态。
  • 核对 LFS、Pages、包、容器注册表 内容是否完整。
  • 如启用 2FA，验证管理员与用户登录。
• 回滚方案：若恢复异常，可快速回滚至上一个稳定版本（如通过系统快照/虚拟机快照），或重新部署同版本 GitLab 后再次执行恢复。

五 故障排查要点

• 权限被拒或无法读取备份：检查备份文件属主为 git:git，权限至少为 600；必要时修正后再恢复。
• 版本不一致报错：恢复时 GitLab 版本需与备份时一致或更新，否则请先升级 GitLab 再恢复。
• 恢复命令找不到或 Rake 任务异常：确认使用的是 Omnibus 包的正确命令（如 gitlab-backup create 或 gitlab-rake gitlab:backup:restore），且 PATH 正确；必要时使用 /opt/gitlab/bin/ 下的绝对路径。
• 配置文件/密钥缺失导致功能异常：恢复后若 2FA、CI/CD 变量解密失败，说明未恢复 gitlab-secrets.json 等关键文件，请补齐并重启服务。