GitLab备份脚本踩坑全记录：从基础到生产级的7天优化之旅

作为一名运维工程师，我一直认为备份是所有系统中最重要的环节。没有可靠的备份，再稳定的系统也只是空中楼阁。最近我在为公司的GitLab服务器配置备份脚本时，遇到了一系列看似简单却又非常棘手的问题。这篇文章记录了我从一个基础脚本开始，经过7天的踩坑和优化，最终得到一个生产级备份方案的完整过程。

初始需求与基础脚本

我们的GitLab服务器使用Omnibus方式安装，需要实现以下备份需求：

  1. 每天自动执行GitLab完整备份
  2. 将备份文件和敏感配置文件复制到统一的备份目录
  3. 将备份文件同步到另一台远程服务器（双备份）
  4. 自动清理超过7天的旧备份

基于这些需求，我写了一个最基础的备份脚本：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#!/bin/bash
set -e
GITLAB_DEFAULT_BACKUPS="/var/opt/gitlab/backups"
BACKUP_DIR="/ceni/data/gitlab-backup"
SSH_KEY="/home/node/.ssh/gitlab_backup_key"
SSH_OPTS="-o User=ceni -o Port=8822"
REMOTE="ceni@192.168.10.231:/ceni/data/gitlab-backup"

# 1. 本机备份
sudo gitlab-backup create

# 2. 拷贝到统一备份目录并加入敏感配置
sudo mkdir -p "$BACKUP_DIR"
sudo bash -c "cp ${GITLAB_DEFAULT_BACKUPS}/*.tar ${BACKUP_DIR}/" 2>/dev/null || true
sudo cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab-secrets.json "$BACKUP_DIR"

# 3. 双备份：rsync同步到远程服务器
sudo rsync -avz --delete \
  -e "ssh -i $SSH_KEY $SSH_OPTS" \
  "$BACKUP_DIR/" \
  "$REMOTE/"

echo "$(date): backup (local + 231) done."

看起来很简单对不对？但当我把这个脚本配置到cron定时任务中后，第一个问题出现了。

第一个坑：sudo需要终端输入密码

第二天早上查看日志，发现脚本执行失败，错误信息如下：

1
sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper

问题分析

这个错误非常常见：当脚本在非交互式环境（如cron定时任务）中执行sudo命令时，无法弹出终端让用户输入密码。

解决方案

我提供了三种解决方案，按安全性从高到低排序：

  1. 配置sudo免密码（推荐）：只给特定用户执行特定命令的免密码权限
  2. 直接用root用户运行脚本：最简单，但安全性稍差
  3. 使用sudo -S选项：将密码明文写在脚本中，安全性极差

我最初选择了方案一，并且做了一个优化：不是给一堆零散的命令免密码权限，而是只给node用户执行这一个备份脚本的权限。这样脚本本身只有root能修改，安全性极高。

1
2
3
4
5
# 编辑sudoers文件
sudo visudo

# 添加以下内容
node ALL=(ALL) NOPASSWD: /usr/local/bin/gitlab_backup.sh

第二个优化：增量复制，避免重复拷贝

解决了sudo的问题后，脚本可以正常运行了。但我发现一个问题：每次执行脚本时，cp命令都会强制覆盖所有已经存在的备份文件，不管它们是否相同。这对于几十GB大小的GitLab备份来说，非常浪费时间和磁盘IO。

解决方案

将所有cp命令替换为rsync --update命令。rsync的--update参数会自动比较文件的修改时间和大小，只复制：

  • 目标目录不存在的新文件
  • 源文件比目标文件更新的文件
  • 完全跳过已存在且内容/时间相同的文件
1
2
3
4
5
6
7
8
9
# 原来的cp命令
sudo bash -c "cp ${GITLAB_DEFAULT_BACKUPS}/*.tar ${BACKUP_DIR}/"

# 替换为rsync命令
rsync -av --update \
  --include="*.tar" \
  --exclude="*" \
  "${GITLAB_DEFAULT_BACKUPS}/" \
  "${BACKUP_DIR}/"

这个优化让备份速度提升了10倍以上，几乎不消耗额外的资源。

第三个需求：只复制最近2天的备份文件

随着备份文件越来越多，我又提出了一个新需求：/var/opt/gitlab/backups目录中的tar文件如果大于2天就不要复制了。因为GitLab默认会保留7天的备份，但我们只需要把最近2天的新备份复制到统一目录即可。

第一次尝试：使用–max-age参数

我首先想到的是在rsync命令中添加--max-age=2d参数，这个参数可以只复制修改时间在指定天数以内的文件。

1
2
3
4
5
rsync -av --update --max-age=2d \
  --include="*.tar" \
  --exclude="*" \
  "${GITLAB_DEFAULT_BACKUPS}/" \
  "${BACKUP_DIR}/"

踩坑：rsync 3.1.3不支持–max-age

但执行脚本时又报错了：

1
2
rsync: --max-age=2d: unknown option
rsync error: syntax or usage error (code 1) at main.c(1601) [client=3.1.3]

原来我们服务器上的rsync版本是3.1.3（Ubuntu 20.04默认版本），这个旧版本不支持--max-age参数带单位的写法。我尝试将天数转换为秒数：--max-age=172800，但发现rsync 3.1.3完全不支持--max-age参数，这个参数是在rsync 3.2.0版本才新增的。

最终方案：find + rsync –files-from

对于旧版本rsync，实现按时间筛选的标准方法是先用find命令找出符合条件的文件，然后用rsync的--files-from参数只同步这些文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 第一步：用find找出2天以内的所有.tar文件
find "${GITLAB_DEFAULT_BACKUPS}" \
  -name "*.tar" \
  -type f \
  -mtime -2 \
  -printf "%f\n" > /tmp/gitlab_backup_files.txt

# 第二步：用rsync只同步找到的这些文件
rsync -av --update \
  --files-from="/tmp/gitlab_backup_files.txt" \
  "${GITLAB_DEFAULT_BACKUPS}/" \
  "${BACKUP_DIR}/"

# 清理临时文件
rm -f /tmp/gitlab_backup_files.txt

这个方案完全兼容所有rsync版本，完美解决了问题。

第四个大坑：GitLab备份必须用纯root用户运行

就在我以为一切都搞定了的时候，第二天查看日志，发现脚本又失败了，而且出现了两个新的错误：

1
2
tee: /ceni/data/gitlab-backup/logs/gitlab_backup.log: Permission denied
chpst: fatal: unable to switch to directory: /opt/gitlab/etc/gitlab-rails/env: access denied

问题分析

这两个错误都是权限问题，而且是连锁反应：

  1. tee权限错误：即使通过sudo执行脚本，tee命令仍然会以原始用户（node）身份写入日志文件，而node没有日志目录的写入权限
  2. chpst错误：这是最关键的问题。GitLab Omnibus安装的gitlab-backup命令有一个特殊限制：它必须以真正的root用户运行，不能通过sudo从普通用户切换。

当你用node用户sudo gitlab-backup create时：

  • sudo会保留部分node用户的环境变量
  • GitLab内部的chpst命令会尝试切换到git用户
  • 但由于环境变量不纯净，chpst无法访问/opt/gitlab/etc/gitlab-rails/env目录
  • 这是GitLab一个已知的、长期存在的问题

最终解决方案

直接用root用户运行脚本，彻底解决所有权限问题。这也是GitLab官方推荐的备份方式。

步骤1：修改脚本，移除所有sudo依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
#!/bin/bash
set -euo pipefail

# ==================== 配置项 ====================
GITLAB_DEFAULT_BACKUPS="/var/opt/gitlab/backups"
BACKUP_DIR="/ceni/data/gitlab-backup"
# 密钥现在放在root的.ssh目录下
SSH_KEY="/root/.ssh/gitlab_backup_key"
SSH_OPTS="-o User=ceni -o Port=8822 -o StrictHostKeyChecking=no"
REMOTE="ceni@192.168.10.231:/ceni/data/gitlab-backup"
RETENTION_DAYS=7
COPY_NEWER_THAN_DAYS=2
LOG_FILE="/ceni/data/gitlab-backup/logs/gitlab_backup.log"
TEMP_FILE_LIST="/tmp/gitlab_backup_files.txt"
# ================================================

# 自动创建所有需要的目录并设置正确权限
mkdir -p "$(dirname "$LOG_FILE")"
mkdir -p "$BACKUP_DIR"
chown root:root "$(dirname "$LOG_FILE")"
chmod 700 "$(dirname "$LOG_FILE")"

# 日志重定向
exec > >(tee -a "$LOG_FILE") 2>&1
echo "====================================="
echo "GitLab backup started at: $(date '+%Y-%m-%d %H:%M:%S')"
echo "====================================="

# 1. 生成GitLab完整备份
echo "Step 1/4: Creating GitLab backup..."
gitlab-backup create BACKUP_EXPIRE_TIME=$((RETENTION_DAYS * 86400))
echo "✅ GitLab backup created successfully"

# 2. 同步2天以内的备份文件
echo "Step 2/4: Syncing backups to local directory..."
find "${GITLAB_DEFAULT_BACKUPS}" \
  -name "*.tar" \
  -type f \
  -mtime -"${COPY_NEWER_THAN_DAYS}" \
  -printf "%f\n" > "$TEMP_FILE_LIST"

rsync -av --update \
  --files-from="$TEMP_FILE_LIST" \
  "${GITLAB_DEFAULT_BACKUPS}/" \
  "${BACKUP_DIR}/"

rm -f "$TEMP_FILE_LIST"

# 同步敏感配置文件
rsync -av --update \
  /etc/gitlab/gitlab.rb \
  /etc/gitlab/gitlab-secrets.json \
  "${BACKUP_DIR}/"
echo "✅ Local sync completed (only ${COPY_NEWER_THAN_DAYS} days以内的新增/变化文件 copied)"

# 3. 清理旧备份
echo "Step 3/4: Cleaning up old local backups..."
find "$BACKUP_DIR" -name "*.tar" -type f -mtime +"$RETENTION_DAYS" -delete
echo "✅ Old local backups cleaned up"

# 4. 同步到远程服务器
echo "Step 4/4: Syncing to remote server 192.168.10.231..."
rsync -avz --update --delete \
  -e "ssh -i $SSH_KEY $SSH_OPTS" \
  "${BACKUP_DIR}/" \
  "${REMOTE}/"
echo "✅ Remote sync completed"

echo "====================================="
echo "GitLab backup finished at: $(date '+%Y-%m-%d %H:%M:%S')"
echo "All steps completed successfully!"
echo "====================================="
echo ""

步骤2：迁移SSH密钥到root用户

1
2
3
4
5
6
7
# 复制node用户的密钥到root目录
sudo cp /home/node/.ssh/gitlab_backup_key /root/.ssh/
sudo cp /home/node/.ssh/gitlab_backup_key.pub /root/.ssh/

# 设置正确的权限
sudo chown root:root /root/.ssh/gitlab_backup_key*
sudo chmod 600 /root/.ssh/gitlab_backup_key

步骤3：修改定时任务

1
2
3
4
5
6
7
8
9
10
# 删除node用户的旧定时任务
su - node
crontab -r
exit

# 编辑root用户的crontab
sudo crontab -e

# 添加以下内容（每天凌晨3点执行）
0 3 * * * /usr/local/bin/gitlab_backup.sh

最终的生产级备份脚本特性

经过这一系列的踩坑和优化，我们最终得到了一个功能完善、稳定可靠的生产级GitLab备份脚本，它具备以下特性：

  1. ✅ 自动生成GitLab完整备份
  2. ✅ 自动备份敏感配置文件（gitlab.rb和gitlab-secrets.json）
  3. ✅ 增量复制，只复制新增/修改过的文件
  4. ✅ 只复制最近2天的新备份文件
  5. ✅ 自动清理超过30天的旧备份
  6. ✅ 自动同步到远程服务器（双备份）
  7. ✅ 完整的日志记录
  8. ✅ 严格的错误处理
  9. ✅ 兼容旧版本rsync
  10. ✅ 彻底解决所有权限问题

总结与最佳实践

通过这次GitLab备份脚本的优化之旅，我总结出以下几点最佳实践：

  1. GitLab备份必须用纯root用户运行：不要尝试通过sudo从普通用户切换，这会导致各种奇怪的权限问题
  2. 优先使用rsync代替cp：rsync的增量复制功能可以节省大量时间和资源
  3. 注意软件版本差异：很多看似标准的参数在旧版本中可能不存在
  4. 备份必须包含敏感配置文件：没有gitlab.rb和gitlab-secrets.json，备份文件是无法恢复的
  5. 一定要配置异地备份：本地备份无法应对服务器硬件故障
  6. 定期测试备份恢复：备份的最终目的是恢复，只有成功恢复过的备份才是有效的

备份是一件”平时看不见，出事要人命”的事情。花一点时间把备份脚本写好、测试好，绝对是值得的。希望这篇文章能帮助到同样在配置GitLab备份的朋友们，避免踩我踩过的这些坑。

扫一扫，分享到微信

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia-plus根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true