GitLab Linux项目备份与恢复方法
小樊
38
2025-12-06 16:00:50
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 版本后再恢复。
