GitLab在Linux环境下的备份与恢复方法

GitLab在Linux环境下的备份与恢复方法

一 备份与恢复总览

• 备份内容：使用内置工具可一次性备份仓库、数据库、用户与权限等关键数据；默认生成在**/var/opt/gitlab/backups**，文件名形如1750765308_2025_06_24_16.7.6_gitlab_backup.tar。建议同时单独备份**/etc/gitlab**配置目录，便于迁移与快速恢复。
• 恢复要点：恢复前需停止Puma/Sidekiq（或全停），恢复会清空现有数据再导入；版本需与备份时一致或兼容（推荐相同）。
• 常用命令对照：
  • 备份：sudo gitlab-backup create（或 sudo gitlab-rake gitlab:backup:create）
  • 恢复：sudo gitlab-backup restore BACKUP=时间戳（或 sudo gitlab-rake gitlab:backup:restore BACKUP=时间戳）
    以上流程与命令适用于常见 Omnibus 安装。

二 备份步骤

• 配置备份路径与保留策略：编辑**/etc/gitlab/gitlab.rb**
  • 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天（秒）
    执行：sudo gitlab-ctl reconfigure 使配置生效。
• 手动备份：sudo gitlab-backup create（或 sudo gitlab-rake gitlab:backup:create）。
• 定时备份（Cron）：例如每天02:00执行
  • 0 2 * * * /usr/bin/gitlab-rake gitlab:backup:create CRON=1
    说明：CRON=1 用于抑制非错误输出，便于日志整洁。
• 备份配置文件：sudo tar -cf gitlab_conf_$(date +%F).tar /etc/gitlab。
• 远程/离线归档：将备份目录（如**/opt/gitlab_backup**）通过 rsync/scp 同步到备份服务器，或定期清理过期备份。

三 恢复步骤

• 版本核对：在源与目标实例核对版本，推荐一致。
  • sudo cat /opt/gitlab/version-manifest.txt | grep “gitlab-ce”
• 准备备份文件：将备份 tar 放到gitlab_rails[‘backup_path’]指定目录（默认/var/opt/gitlab/backups）。注意：恢复时 BACKUP 参数填写时间戳前缀，不要包含“_gitlab_backup.tar”。
• 停止服务：
  • sudo gitlab-ctl stop puma
  • sudo gitlab-ctl stop sidekiq
    或：sudo gitlab-ctl stop（全停）。
• 执行恢复：
  • sudo gitlab-backup restore BACKUP=1750765308_2025_06_24_16.7.6
    出现确认提示时输入yes。
• 启动与初始化：
  • sudo gitlab-ctl start
  • 如迁移场景，先解压配置包：sudo tar -xf gitlab_conf.tar -C /，再 sudo gitlab-ctl reconfigure。
• 验证：
  • sudo gitlab-ctl status（确保 postgresql/puma/sidekiq 为 run）
  • 访问 Web 检查项目、用户、权限是否正常。

四 迁移与升级场景

• 同版本迁移：准备相同版本的 GitLab，先恢复数据，再恢复**/etc/gitlab**配置并 reconfigure，最后启动服务与验证。
• 跨版本恢复：一般要求版本一致；如必须跨版本，务必先在测试环境演练，确认兼容性与数据完整性。
• 容器化部署：在容器内执行备份并将产物拷出宿主机，例如
  • docker exec gitlab gitlab-rake gitlab:backup:create
  • docker cp gitlab:/var/opt/gitlab/backups/ /host/backup/
    恢复时先将备份放入容器内备份目录，再执行恢复命令。

五 常见问题与最佳实践

• 常见问题
  • 扩展权限错误（如 pg_trgm/btree_gist）：在恢复前以 gitlab 用户登录 psql，删除或更正扩展属主后重试；恢复后可按需重建扩展。
  • 服务未停导致恢复失败：恢复前确保Puma/Sidekiq已停止。
  • 找不到备份文件：确认 BACKUP 只填时间戳前缀，且文件位于配置的备份目录。
  • 恢复后页面 500：等待 Redis 等组件完全启动后再访问。
• 最佳实践
  • 3-2-1 策略：至少3份备份、2种介质、1份异地/离线。
  • 定期恢复演练：每月/每季度验证备份可用性与完整性。
  • 最小权限与审计：备份传输使用最小权限账号，保留操作日志。
  • 监控与告警：对备份任务与结果做监控/告警，及时发现失败与异常。