GitLab Linux项目备份与恢复方法

GitLab Linux项目备份与恢复方法

一 备份策略与准备

• 备份范围与工具：使用 GitLab 内置 Rake 任务执行全量备份，涵盖仓库、数据库、用户与权限、密钥、CI/CD 配置、问题/合并请求等。默认备份文件生成于**/var/opt/gitlab/backups/。为降低风险，建议同时保留一份异地/离线副本**（如对象存储或离线介质）。
• 版本要求：进行实例级恢复时，要求备份与恢复的 GitLab 版本一致（小版本也尽量一致），否则可能出现兼容性问题。
• 配置备份路径与保留策略：编辑 /etc/gitlab/gitlab.rb，设置备份目录、权限与保留天数，然后执行 gitlab-ctl reconfigure 使配置生效。
  • 示例：
    • gitlab_rails[‘manage_backup_path’] = true
    • gitlab_rails[‘backup_path’] = “/opt/gitlab_backup”
    • gitlab_rails[‘backup_archive_permissions’] = 0644
    • gitlab_rails[‘backup_keep_time’] = 604800 # 保留 7 天（秒）
• 目录与权限：若自定义备份目录，需确保目录存在且属主为 git:git，否则备份任务可能失败。

二 手动创建备份

• 执行全量备份（实例级）：
  • 命令：sudo gitlab-rake gitlab:backup:create
  • 备份文件命名规则：通常为时间戳_版本号_gitlab_backup.tar（如：1609396215_2020_12_31_12.3.5_gitlab_backup.tar），位于配置的 backup_path 下。
• 定时备份（推荐）：
  • 方式一：在 gitlab.rb 中设置 backup_keep_time 自动清理旧备份。
  • 方式二：使用脚本 + crontab 定时执行备份任务，示例脚本：
    • /opt/gitlab_backup/git_back.sh
      • #!/usr/bin/bash
      • /usr/bin/gitlab-rake gitlab:backup:create CRON=1
    • 赋权：chmod +x /opt/gitlab_backup/git_back.sh
    • 定时：0 0,6,12,18 * * * /bin/bash /opt/gitlab_backup/git_back.sh > /dev/null 2>&1
    • 说明：环境变量 CRON=1 用于抑制备份脚本在非错误情况下的进度输出，便于 cron 记录。

三 恢复步骤

• 场景一 实例级恢复（全量迁移/灾难恢复）
  • 准备：将备份文件放到目标实例的 backup_path（默认 /var/opt/gitlab/backups/），确认文件属主为 git:git，并确保GitLab 版本一致。
  • 停止写入服务：sudo gitlab-ctl stop unicorn && sudo gitlab-ctl stop sidekiq
  • 执行恢复（BACKUP 只需填写到“时间戳_版本号”前缀，工具会自动匹配 tar 包）：
    • sudo gitlab-rake gitlab:backup:restore BACKUP=1609396215_2020_12_31_12.3.5
    • 按提示输入 yes 确认两次完成恢复。
  • 启动服务：sudo gitlab-ctl start（或 gitlab-ctl restart）
  • 验证：登录 Web 界面检查项目、用户、权限、CI/CD、Issues/MR 等是否完整恢复。
• 场景二 仅误删项目的快速恢复（无需全量恢复）
  • 若项目删除时间较短，可在 GitLab 管理后台的已删除项目中直接恢复（管理员权限）。
  • 或使用 API（示例）：
    • curl --request POST --header “PRIVATE-TOKEN: <YOUR_TOKEN>” “https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/restore”
  • 如回收站已清空或无法使用后台恢复，再采用“实例级恢复”方式回滚到删除前的备份点。

四 迁移与升级注意事项

• 迁移流程要点：
  • 旧实例执行全量备份 → 新服务器安装相同版本 GitLab → 将备份文件拷贝到新实例的 backup_path → 在新实例执行恢复 → 校验数据 → 切换域名解析到新实例 → 观察一段时间后再下线旧实例。
  • 建议同时迁移 /etc/gitlab/gitlab.rb 中的关键配置（如 external_url、邮件、LDAP 等），确保恢复后业务可用。
• 升级策略：
  • 不支持跨大版本直接恢复/升级，需逐级小版本升级到目标版本后再进行恢复或继续升级（如 11 → 11.x 最新 → 12 → 12.x 最新 → 13…）。
  • 升级前务必完成全量备份与回滚预案。

五 常见问题与排错

• 权限问题：备份/恢复时提示权限不足，常见原因是备份目录或 tar 包属主非 git:git。修复：chown -R git:git /opt/gitlab_backup；个别环境为恢复临时放宽权限（如 777）仅用于测试，生产环境不建议。
• 找不到备份文件：确认备份文件位于配置的 backup_path，且 BACKUP 参数填写到“时间戳_版本号”前缀即可，工具会自动补全完整文件名。
• 恢复中断或失败：确保恢复前已停止 unicorn/sidekiq，恢复完成后再启动；必要时查看 /var/log/gitlab/gitlab-rails/production.log 定位问题。
• 版本不一致：恢复时报版本不匹配，需安装与备份时一致的 GitLab 版本后再恢复。