📚 课程目录第4章执行GitLab全量备份

4. 执行GitLab全量备份

GitLab 的全量备份由 gitlab-backup create 命令驱动，它会把数据库、仓库、上传文件、CI 构建产物、容器镜像仓库、Pages、LFS 等组件打包成一个归档文件。理解这条命令的参数、备份目录的落点以及如何跳过不需要的数据，是控制备份体积、缩短备份窗口、快速定位失败原因的关键。本节围绕命令执行、目录指定、跳过特定数据、日志分析与常见错误处理展开。

一、命令的基本形态与执行前提

GitLab 从 12.2 起把备份命令从 gitlab-rake 迁移到 gitlab-backup，Omnibus 安装方式下推荐使用后者。执行前需要确认两点：一是当前用户具备足够权限，通常用 root 或 sudo；二是 GitLab 组件处于运行状态，备份过程会读取数据库和仓库文件。

# 查看备份命令帮助
sudo gitlab-backup help create

# 执行一次默认全量备份
sudo gitlab-backup create

默认情况下，备份文件会写入 /var/opt/gitlab/backups，文件名形如 1700000000_2024_11_15_16.5.0_gitlab_backup.tar。文件名由时间戳、日期、GitLab 版本和固定后缀组成，时间戳用于排序和恢复时定位。备份完成后，命令会输出归档路径和耗时，这是判断是否成功的第一个信号。

二、指定备份目录

生产环境通常不会把备份留在系统盘，而是挂载独立磁盘或网络存储。GitLab 通过 gitlab_rails['backup_path'] 配置备份目录，修改后需要重新加载配置。

# /etc/gitlab/gitlab.rb
gitlab_rails['backup_path'] = "/data/gitlab-backups"

# 使配置生效
sudo gitlab-ctl reconfigure

也可以在单次执行时用环境变量覆盖，适合临时把备份写到其他位置：

sudo gitlab-backup create BACKUP_PATH=/mnt/backup/gitlab

需要注意，目标目录必须存在且对 git 用户可写，否则命令会在归档阶段报权限错误。若目录位于 NFS 上，还要确认挂载参数支持大文件写入和正确的属主映射。

三、跳过特定数据

全量备份并非每次都需要包含所有组件。例如数据库已由外部工具单独备份，或上传文件体积巨大且变化不频繁时，可以用 SKIP 参数排除指定组件，从而显著缩短备份时间、减小归档体积。

# 跳过数据库和上传文件
sudo gitlab-backup create SKIP=db,uploads

# 跳过多个组件
sudo gitlab-backup create SKIP=db,uploads,builds,artifacts

常用可跳过组件包括：db（PostgreSQL 数据库）、uploads（用户上传附件）、builds（CI 构建日志）、artifacts（构建产物）、lfs（大文件存储）、registry（容器镜像仓库）、pages（Pages 站点）。跳过某项后，恢复时必须单独补齐该部分数据，否则会出现数据缺失。因此跳过策略要与恢复方案配套设计，不能只图备份快。

跳过 db 后，归档中不再包含数据库转储。恢复时若没有独立的数据库备份，GitLab 将无法还原项目、用户、权限等核心元数据。跳过前务必确认已有对应的数据库备份。

四、备份日志分析与常见错误处理

备份命令的实时输出会打印各阶段进度，完整日志可通过 gitlab-ctl 或直接查看备份日志文件获取。分析日志时重点关注阶段名称、耗时和错误关键字。

# 查看备份相关日志
sudo gitlab-ctl tail gitlab-rails

# 或直接查看备份日志
sudo less /var/log/gitlab/gitlab-rails/backup_json.log

常见错误及处理方式如下：

权限拒绝（Permission denied）：备份目录属主不是 git，或磁盘挂载后权限被重置。处理方式是 chown git:git /data/gitlab-backups 并确认目录可写。
磁盘空间不足（No space left on device）：归档写入过程中空间耗尽。备份前用 df -h 检查目标分区，预留至少与当前数据量相当的余量。
数据库连接失败：PostgreSQL 未运行或连接数打满。用 gitlab-ctl status 确认 postgresql 状态，必要时重启相关组件。
备份进程被中断：归档文件不完整，恢复时会校验失败。应删除残留的 .tar 文件后重新执行，不要直接使用半成品。
版本不匹配警告：恢复时若 GitLab 版本与备份文件名中的版本差异过大，会提示兼容性风险。备份与恢复应尽量保持版本一致。

下面这张图把一次全量备份的输入、处理链、跳过分支和结果判断串在一起，便于对照日志定位问题。

五、一次可参考的执行与检查流程

把上述要点串成一次可复用的操作，建议按以下顺序执行，并在每一步留下可核对的输出。

确认备份目录存在且可写：ls -ld /data/gitlab-backups，属主应为 git。
检查磁盘余量：df -h /data，可用空间应大于当前 GitLab 数据总量。
执行带跳过策略的备份：sudo gitlab-backup create SKIP=builds,artifacts BACKUP_PATH=/data/gitlab-backups。
观察输出中的阶段名称与耗时，确认没有 error 或 failed 关键字。
核对归档文件：ls -lh /data/gitlab-backups/*.tar，确认文件大小合理且时间戳为本次执行时间。
如失败，按日志关键字对照上一节的处理方式逐项排查，清理残留文件后重试。

建议把备份命令、跳过组件、目标目录和预期归档大小记录成一份执行清单。每次备份后核对文件大小与上次的偏差，若明显偏小，往往意味着某个组件被意外跳过或写入中断。

掌握 gitlab-backup create 的参数组合、备份目录的配置方式以及日志中的错误信号，就能把全量备份从“能跑”推进到“可控、可查、可复现”。跳过策略要服务于恢复目标，日志分析要落到具体组件和权限上，这样备份才真正具备灾难恢复价值。