如何在Linux上使用GitLab进行备份与恢复

Linux 上 GitLab 备份与恢复实操指南

一 前置准备与版本要求

• 确认 GitLab 版本一致：恢复目标机的 GitLab 版本需与备份时一致（推荐相同版本与发行版 CE/EE）。查看版本示例：
  • sudo gitlab-rake gitlab:env:info | grep “GitLab version”
  • 或 cat /opt/gitlab/version-manifest.txt | grep “gitlab-ce”
• 备份范围说明：gitlab-backup 默认包含仓库、数据库、上传文件、CI/CD 等；但以下敏感配置与密钥不包含，需单独备份：
  • 配置文件：/etc/gitlab/gitlab.rb
  • 密钥文件：/etc/gitlab/gitlab-secrets.json
  • 其他可选：Nginx 配置、Postfix 邮件配置等（按实际环境决定）
• 备份目录与权限：默认备份目录为 /var/opt/gitlab/backups，备份归档属主应为 git:git，权限建议 0644 或 0755（便于备份工具读取）。

二 手动备份步骤

• 修改备份目录（可选）：编辑 /etc/gitlab/gitlab.rb
  • gitlab_rails[‘backup_path’] = ‘/data/gitlab/backups’
  • gitlab_rails[‘backup_archive_permissions’] = 0644
  • gitlab_rails[‘backup_keep_time’] = 604800 # 保留 7 天（秒）
  • 使配置生效：sudo gitlab-ctl reconfigure
• 创建备份：
  • 新版本推荐：sudo gitlab-backup create
  • 旧版或兼容：sudo gitlab-rake gitlab:backup:create
• 备份文件命名：形如 <时间戳><日期><版本>_gitlab_backup.tar，例如：1750765308_2025_06_24_16.7.6_gitlab_backup.tar
• 单独备份配置与密钥（强烈建议）：
  • sudo tar -czf gitlab_conf_$(date +%F).tgz -C / etc/gitlab /etc/gitlab-secrets.json
  • 如需连同 Nginx/邮件等：tar czf gitlab_full_$(date +%F).tgz -C / etc/gitlab /var/opt/gitlab/nginx/conf /etc/postfix 等

三 自动备份与异地容灾

• 定时任务（crontab）示例：
  • 每天 02:00 本地备份：0 2 * * * /usr/bin/gitlab-backup create CRON=1
  • 脚本方式（便于加日志与错误处理）：
    • 0 2 * * * /bin/bash /opt/scripts/gitlab_backup.sh
    • 脚本内示例：/usr/bin/gitlab-backup create CRON=1 >> /var/log/gitlab/backup.log 2>&1
• 异地备份（SCP 免密示例）：
  • 在备份机生成密钥并分发公钥到远端存储服务器
  • 脚本片段：
    • scp -P 22 /var/opt/gitlab/backups/1750*.tar root@192.0.2.10:/data/gitlab/backup/
  • 远端可配合 find … -mtime +N -delete 做自动清理
• 保留策略：通过 gitlab_rails[‘backup_keep_time’] 控制本地保留周期，超期自动清理。

四 恢复步骤与注意事项

• 准备与前置检查：
  • 安装同版本 GitLab（CE/EE 一致），至少执行一次：sudo gitlab-ctl reconfigure
  • 将备份 tar 放到配置的备份目录（默认 /var/opt/gitlab/backups），并修正属主属组：
    • chown git:git /var/opt/gitlab/backups
    • chown git:git /var/opt/gitlab/backups/<备份文件>.tar
  • 停止写入组件（两种等效方式，择一）：
    • 仅停连接数据库的进程：sudo gitlab-ctl stop puma；sudo gitlab-ctl stop sidekiq
    • 或整机关停：sudo gitlab-ctl stop
• 执行恢复（BACKUP 取值为“时间戳_日期_版本”前缀，不含 “_gitlab_backup.tar”）：
  • 新版本：sudo gitlab-backup restore BACKUP=1750765308_2025_06_24_16.7.6
  • 旧版或兼容：sudo gitlab-rake gitlab:backup:restore BACKUP=1750765308_2025_06_24_16.7.6
  • 过程中会提示确认，输入 yes 继续
• 恢复后操作与验证：
  • 启动服务：sudo gitlab-ctl start；必要时 sudo gitlab-ctl reconfigure
  • 检查状态：sudo gitlab-ctl status（确保 postgresql、puma、sidekiq 为 run）
  • 访问 Web 验证项目、用户、密钥、CI/CD 等是否完整
• 常见报错与处理要点：
  • 扩展权限错误（如 pg_trgm/btree_gist）：用 gitlab-psql 登录后调整扩展属主或删除重建，再重试恢复
  • 版本不一致：恢复目标机版本需与备份时一致（或兼容），否则可能失败或数据不一致
  • 备份文件不在备份目录或属主错误：移动到正确目录并 chown git:git 后重试
  • 恢复后页面 502：重启 GitLab 并检查 socket 权限与目录可访问性。

五 实用补充

• 选择性备份（按需跳过对象）：
  • 示例：sudo gitlab-backup create SKIP=db,uploads,artifacts,lfs,registry
  • 适合仅需迁移代码或特定数据的场景
• 大数据量或高变更场景：
  • 使用 STRATEGY=copy 减少备份时锁竞争：sudo gitlab-backup create STRATEGY=copy
• 只备份代码仓库（不包含数据库与配置）：
  • 直接备份 /var/opt/gitlab/git-data/repositories 目录（迁移时仍建议配合数据库与配置一起恢复，避免元数据不一致）。