Ubuntu 上 GitLab 备份与恢复实操指南
一 备份
-
准备与配置
- 备份默认目录为：/var/opt/gitlab/backups。可在 /etc/gitlab/gitlab.rb 中自定义：
- 启用并设定路径：gitlab_rails[‘manage_backup_path’] = true、gitlab_rails[‘backup_path’] = “/new/backup/path”
- 保留时长（秒）：gitlab_rails[‘backup_keep_time’] = 7776000（示例为3个月）
- 修改后执行：sudo gitlab-ctl reconfigure 使配置生效。备份命令建议使用新接口：/opt/gitlab/bin/gitlab-backup create；旧版可用：gitlab-rake gitlab:backup:create。为减少写入冲突，可使用拷贝策略：STRATEGY=copy。定时任务示例（每天02:00）：0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1（CRON=1 用于抑制无错误时的输出）。
-
执行与校验
- 手动创建备份：
- 标准：sudo /opt/gitlab/bin/gitlab-backup create
- 高变更环境：sudo /opt/gitlab/bin/gitlab-backup create STRATEGY=copy
- 查看生成的归档（示例）：ls -l /var/opt/gitlab/backups，文件名通常包含时间戳_版本号_gitlab_backup.tar。建议定期将备份拷贝到异地存储（如对象存储、挂载盘）。
二 恢复
-
前提与准备
- 恢复要求：GitLab 版本需与备份时一致；在新环境先完成安装并执行一次 sudo gitlab-ctl reconfigure，备份归档需位于配置的 backup_path（默认 /var/opt/gitlab/backups），并确保文件属主为 git:git（如：sudo chown git:git /var/opt/gitlab/backups/<归档>）。
-
标准恢复步骤
- 停止写入服务：
- 新版本多使用 Puma：sudo gitlab-ctl stop puma
- 兼容旧版 Unicorn：sudo gitlab-ctl stop unicorn
- 停止任务队列：sudo gitlab-ctl stop sidekiq
- 执行恢复（BACKUP 值为时间戳，不含 “_gitlab_backup.tar” 后缀）：
- sudo /opt/gitlab/bin/gitlab-backup restore BACKUP=
- 按提示输入 yes 确认
- 启动与校验：
- 启动：sudo gitlab-ctl start
- 自检：sudo gitlab-rake gitlab:check SANITIZE=true
- 如为迁移，恢复后按需调整 /etc/gitlab/gitlab.rb 中的 external_url 等配置，再 gitlab-ctl reconfigure。
三 增量备份与远程存储
- 增量备份
- 需先有一个基础全量备份。自 GitLab 15.0 起使用：sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=<base_timestamp>；14.9–14.10 使用 BACKUP=<base_timestamp> 指定基准备份。可按需跳过打包：SKIP=tar。示例：
- 全量：sudo gitlab-backup create
- 增量：sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=1728000000_2025_01_01_15.11.0
- 远程/挂载存储
- 可将备份自动复制到本地挂载的共享（如 NFS/CIFS/SMB）。在 /etc/gitlab/gitlab.rb 配置：
- gitlab_rails[‘backup_upload_connection’] = { :provider => ‘Local’, :local_root => ‘/mnt/backups’ }
- gitlab_rails[‘backup_upload_remote_directory’] = ‘gitlab_backups’
- 修改后 gitlab-ctl reconfigure 生效。
四 常见问题与最佳实践
- 版本匹配：恢复时若版本不一致会报错，务必保持同一主版本（如 15.x → 15.x）。必要时先升级目标实例到与备份一致版本再恢复。
- 配置文件与密钥：备份归档默认不包含 /etc/gitlab/gitlab.rb 与 gitlab-secrets.json。跨环境迁移时，建议同时妥善备份与恢复这两个文件（或在新环境手动对齐密钥与必要配置），以避免 LDAP/SMTP/OAuth 等集成异常。
- 备份保留与清理：通过 gitlab_rails[‘backup_keep_time’] 设置自动清理周期，或定期用 find 删除过期归档，避免磁盘被占满。
- 高变更数据：在写入密集场景创建备份时使用 STRATEGY=copy，降低备份期间的数据一致性风险。