公司内部前几天刚经历了一次“备份半小时、恢复两小时”的演练好在提前做了功课没出大乱子。趁热把 GitLab 备份和恢复这套东西完整梳理一遍尤其适合自己搭过 GitLab、但还没认真考虑过“数据没了怎么办”的团队。文章会覆盖备份命令、定时策略、异机保存、恢复流程以及一堆只有真正操作过才懂的坑。1. 备份恢复这件事到底在防什么自建 GitLab 和直接用云端代码托管平台最大的区别就是所有数据都攥在自己手里。代码仓库、Issue、Merge Request、CI/CD 流水记录、用户权限、Webhook 配置全都在服务器上。哪天磁盘坏了、机房断电、系统被误操作或者更常见的就是某次升级不小心把配置搞坏没有可用备份就真的只能对着屏幕发呆。很多人有个误解觉得“代码不是都 clone 到本地了吗”问题在于本地那份只是仓库快照GitLab 里的 Issue、评论、CI 变量、成员权限这些元数据本地完全没有。真出事之后重建一套 GitLab 再做手动迁移工时消耗非常大而且特别容易漏东西。GitLab 官方其实设计了一套相对完备的备份恢复机制。备份命令一条就能把所有核心数据打成一个压缩包恢复命令也能直接解包导入。但“命令简单”不代表“流程简单”。备份文件放哪、多久备一次、怎么验证备份可用、恢复时版本怎么匹配这些环环相扣任何一环考虑不周关键时刻都会掉链子。我见过好几个团队备份是做了cron 每天都跑结果到恢复那天发现备份文件只有几十 KB一看日志才知道早就报错了根本没人在意。备份这件事做了不等于有用能成功恢复的备份才是有效备份。这篇文章主要针对 Linux 服务器上以 Omnibus 方式安装的 GitLab也就是官方推荐的 all-in-one 安装包这也是社区里最常见的部署形态。源码安装和 Docker 部署在部分路径和命令上有差异但核心思路完全一致。2. GitLab 备份机制是怎么工作的在动手写备份命令之前先搞清楚备份到底做了什么否则出了问题很难排查。2.1 一条备份命令背后的完整流程GitLab 的备份命令是gitlab-backup create在比较老的版本12.2 之前里命令是gitlab-rake gitlab:backup:create新版本已经统一到gitlab-backup。执行后 GitLab 会按照固定顺序做以下几件事冻结数据库连接防止备份过程中有写入操作导致数据不一致备份 PostgreSQL 数据库这里存放了用户、权限、Issue、CI 记录等所有结构化数据备份 Git 仓库本身包括裸仓库、wiki 仓库、设计稿仓库等备份上传的文件附件比如 Issue 里上传的图片、设计文件备份 CI/CD 的构建产物和流水线日志打包所有内容生成一个 tar 归档文件默认情况下备份文件生成在/var/opt/gitlab/backups目录文件名格式类似1701234567_2023_12_01_16.7.0_gitlab_backup.tar前半段是时间戳后半段是 GitLab 版本号。2.2 关键问题一备份默认不包含配置文件这是新手最容易踩的坑。上面这条命令备份的是“数据”但 GitLab 的运行配置gitlab.rb不在其中。恢复一套全新的 GitLab 时如果没有原始配置文件数据库能导进去但服务很难启动到正常状态。因为配置里包含了各种路径、外部 URL、数据库密码、SSL 证书路径、统一资源入口等关键设置这些信息不匹配会导致 GitLab 根本起不来或者启动后大量组件报错。所以完整备份的原则必须是“数据 配置”双管齐下。配置文件本身就是一个小文件直接单独复制一份到安全位置即可cp /etc/gitlab/gitlab.rb /path/to/backup/gitlab.rb.$(date %Y%m%d)2.3 关键问题二密钥文件比配置文件还重要GitLab 有一套加密机制数据库里的某些密码字段、双因素认证密钥、CI/CD 变量都是加密存储的。解密用的主密钥在/etc/gitlab/gitlab-secrets.json里。如果只恢复数据、不恢复密钥文件结果就是能登录界面但所有 CI/CD 变量全部无法解密双因素认证全部失效各种服务之间互相调用的密码也解不开恢复过程会非常痛苦。这个文件同样需要单独备份。官方文档也反复强调备份必须包含 secrets 文件否则等于没备份。我的习惯是把gitlab.rb和gitlab-secrets.json打包到同一个目录和 tar 数据备份文件分开存放因为两者的恢复方式不同。2.4 备份包内部结构一览一个完整的 GitLab 备份 tar 包打开后主要包含这些内容内容说明db/PostgreSQL 数据库 dump 文件GitLab 系统里所有业务数据的核心repositories/所有 Git 仓库的裸仓库数据uploads/用户上传的各类附件文件builds/CI/CD 构建产物artifacts/流水线产生的归档文件pages/GitLab Pages 服务内容backup_information.yml备份元信息包含 GitLab 版本、备份时间等恢复时会校验这个结构在排查“备份文件为什么比想象中大很多/小很多”的场景下特别有用。比如某个仓库组异常膨胀可以直接看repositories/里哪个仓库体积异常。3. 备份前的准备工作与完整配置详解直接跑默认命令虽然简单但生产环境下的备份还是要做一些基础配置。很多实际问题其实在配置阶段就能规避。3.1 修改备份目录和保留策略默认备份目录在系统盘长期积累会把根分区打满。我建议把备份目录改到独立的数据盘# 编辑 /etc/gitlab/gitlab.rb gitlab_rails[backup_path] /data/gitlab/backups修改后执行gitlab-ctl reconfigure注意reconfigure会重新生成配置文件并重启部分服务尽量在业务低峰操作。同时建议配置备份保留天数GitLab 默认是无限制保留时间长了目录会非常膨胀。设置只保留 7 天内的备份gitlab_rails[backup_keep_time] 604800单位是秒604800 秒正好是 7 天。这个参数的作用是每次执行备份成功后系统会自动清理超过保留期限的旧备份文件。注意它只在备份命令执行后才触发清理不是定时清理。3.2 备份路径对权限的要求GitLab 的备份进程默认以git用户权限运行所以备份目录的所有者必须是git用户否则备份会直接失败或生成不完整的文件。配置新目录后手动纠正权限mkdir -p /data/gitlab/backups chown -R git:git /data/gitlab/backups chmod 0700 /data/gitlab/backups权限错误是备份失败的头号原因检查日志看到Permission denied时第一反应就该看这里。3.3 大仓库场景下的环境变量调优如果服务器上存在几个体积特别大的仓库备份过程中有可能出现内存不足或超时。GitLab 提供了两个环境变量来调节# 限制每次备份处理的仓库数量避免同时加载过多仓库导致内存暴涨 # 比如每次只处理 3 个仓库处理完再继续下一批 gitlab-backup create GITLAB_BACKUP_MAX_CONCURRENCY3这个参数从 GitLab 16.x 版本开始支持旧版本会自动忽略。仓库数量多、单仓库小的情况默认并发值完全没问题但如果单个仓库体积到了几十 GB 甚至上百 GB建议调低并发数。另一个变量是网盘类远程存储的并发gitlab-backup create GITLAB_BACKUP_MAX_STORAGE_CONCURRENCY3这两个变量通常不需要刻意设置但要记住存在这个调优手段万一备份过程内存告急知道去哪里找参数。3.4 备份策略规划建议经验之谈GitLab 的备份频率取决于提交活跃度。日均提交 20 次以内的内部团队每天一次全量备份足够外部客户也在使用的系统至少每天 2 次或者上每小时增量方案。GitLab 原生没有真正的增量备份gitlab-backup create每次都做全量。替代方案是全量备份每周做一次放到远程存储每天做一次全量备份到本地频繁的备份靠保留天数控制成本结合对象存储把备份直接传到远端实现异机容灾对于大多数自建团队每天一次全量 异地同步是成本与安全之间的平衡点。4. 实操从备份到定时任务到远程保存下面是一套可以“抄作业”的完整方案覆盖备份、执行、校验、远程同步四个环节。4.1 单次手动备份的正确姿势执行备份前先确认磁盘空间备份文件体积通常接近当前已用仓库存储的 60% 到 90%取决于附件和 CI 缓存的占比df -h /data/gitlab/backups空间确认没问题后直接执行gitlab-backup create整个过程会输出每个备份步骤的状态类似这种日志Dumping database ... Dumping repositories ... [DONE] [RUNNING] ...备份结束最后一行通常会提示类似Creating backup archive: 1701234567_2023_12_01_16.7.0_gitlab_backup.tar ...看到这个才说明完整结束。很多执行方式会输出一堆信息到 stdout用脚本调用时注意保留退出码判断。4.2 配置文件与密钥文件的同步备份自己写个小脚本把三样东西打包到一起比手敲命令更靠谱#!/bin/bash # /usr/local/bin/gitlab-backup-full.sh BACKUP_DIR/data/gitlab/backups STAMP$(date %Y%m%d_%H%M%S) CONFIG_BACKUP/data/gitlab/config-backup mkdir -p $CONFIG_BACKUP # 1. GitLab 数据备份 gitlab-backup create # 2. 配置文件与密钥归档 tar czf $CONFIG_BACKUP/gitlab-config_$STAMP.tar.gz \ -C /etc/gitlab gitlab.rb gitlab-secrets.json # 3. 清理超过 7 天的配置备份 find $CONFIG_BACKUP -type f -name *.tar.gz -mtime 7 -delete脚本里的gitlab-backup create如果失败后面的配置文件打包照样会执行所以严谨的做法是判断前一条命令的退出码gitlab-backup create if [ $? -eq 0 ]; then tar czf $CONFIG_BACKUP/gitlab-config_$STAMP.tar.gz ... else echo GitLab data backup failed, config backup skipped. exit 1 fi生产环境的备份脚本宁可直接失败退出也别留下“看起来成功其实缺一半”的结果。4.3 定时任务配置使用crontab配置每天凌晨 2 点整执行备份脚本crontab -e加入一行0 2 * * * /usr/local/bin/gitlab-backup-full.sh /var/log/gitlab-backup.log 21日志输出到独立文件方便后续排查。注意脚本本身要添加执行权限并提前用 bash 手动跑一遍验证chmod x /usr/local/bin/gitlab-backup-full.sh还有一点必须提醒cron 执行时的环境变量是极简的PATH往往不含/usr/bin脚本里所有命令建议写绝对路径或者在脚本开头手动声明export PATH/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin这个坑我踩过好几次写脚本时偷懒用相对路径cron 里跑得静悄悄一看日志全是 command not found。4.4 备份文件的远程同步本地备份扛不住磁盘整块损坏或者机房级故障所以远程副本是必备项。传输工具选择上$rsync增量同步性能最好适合局域网内备份服务器公网环境下用restic或rclone配合对象存储更合适。一个最小可用的 rsync 同步脚本#!/bin/bash # rsync 同步到备份服务器要求已经配置好 SSH 密钥免密登录 rsync -avz --delete \ /data/gitlab/backups/ \ backup-userbackup-server:/data/backups/gitlab/--delete参数表示源目录删除的文件在目标端也同步删除避免过期备份的残留占用远端空间。远程保存的保留期限建议至少 14 天比本地 7 天多一个缓冲周期。如果走公网传输强烈建议用rclone支持对象存储和加密传输中断还能断点续传。文件在传输前先做加密也很值得考虑备份包里是公司核心代码泄露出去影响很大。4.5 备份的“验证”环节很多团队从来不看备份日志导致备份连续失败了一个月都没发现。我的建议是每周第一个工作日做一次备份文件的完整性检查。检查内容分三层第一层确认备份文件存在且体积正常ls -lh /data/gitlab/backups/*.tar第二层检查 tar 包能否正常解压tar -tf /var/opt/gitlab/backups/1701234567_2023_12_01_16.7.0_gitlab_backup.tar | head -20第三层也是最有价值的一层在临时服务器上做一次完整的恢复演练确认恢复后服务可用。这个环节最耗时但最有价值至少每半年做一次。备份验证的优先级能列出仓库清单 能解压文件 能恢复出可用实例。理想情况是全部做到条件实在受限的团队也不要只看第一层就放心。5. 恢复流程从头搭建到数据还原恢复操作是备份价值的最终体现也是出错概率最高的环节。提前把流程捋顺畅真到要用的时候才能不慌。5.1 恢复的前置条件恢复 GitLab 需要先安装一套全新的、版本与备份文件一致的 GitLab 实例。这里说的版本一致包含两层含义大版本Major必须一致比如 16.x 的备份不能恢复到 15.x 实例上小版本Minor最好一致比如 16.7 的备份恢复到 16.9 实例上通常能成功但如果跨了多个小版本数据库结构迁移可能出现问题有一个通用规则备份数据的恢复上限是“备份时版本的后一个次要版本”超过这个范围不再保证兼容。举个例子16.7 的备份最多建议恢复到 16.8到 16.9 就有失败风险。实际操作里我的习惯是尽可能找到完全一致的版本省得在迁移问题上浪费时间。全新安装 GitLab 后先不要启动任何服务直接进入恢复流程。如果之前启动了恢复前要做一次停服务操作。5.2 恢复配置文件与密钥文件把备份好的gitlab.rb和gitlab-secrets.json复制回原路径cp /path/to/backup/gitlab.rb /etc/gitlab/gitlab.rb cp /path/to/backup/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json然后执行gitlab-ctl reconfigure这一步会按新的配置重新生成各服务配置并启动服务即使配置改动不大reconfigure 也会触发重启。如果跳过这一步直接恢复数据库得到的结果往往是连接数据库失败因为数据库密码不匹配。5.3 停止相关服务后恢复数据为了保证数据一致性恢复流程要求在停掉部分服务的状态下执行。GitLab 官方文档要求停掉所有与数据库交互相关的服务只保留必要的gitlab-ctl stop puma gitlab-ctl stop sidekiq # 如果有 geo 相关服务或其它依赖组件一并停止注意gitlab-ctl stop后面跟的是服务名不同版本略有差异先执行gitlab-ctl status查看当前服务状态再操作。然后执行恢复命令gitlab-backup restore BACKUP1701234567_2023_12_01_16.7.0BACKUP参数不需要带目录路径和.tar后缀只需传时间戳那一段前缀。执行过程中 GitLab 会提示两次是否继续输入yes确认。恢复过程会先解压 tar 包再逐项导入数据库、仓库、上传文件等。如果备份文件有损坏这个阶段就会报错。恢复完成后gitlab-ctl start随后执行gitlab-ctl reconfigure最后检查各服务状态gitlab-ctl status5.4 恢复后检查清单服务启动不等于恢复成功。我每次恢复完都会按下列清单逐项验证用管理员账号登录 Web 界面确认能正常跳转打开任意两个项目页面确认仓库文件列表和提交记录完整查看一个 Issue 的评论记录确认数据库中的非代码数据没有被破坏进入管理后台确认用户列表、权限组数量检查 CI/CD 设置页确认 Runner 注册情况和 CI 变量是否正常这一步直接检验 secrets 文件是否还原成功触发一次测试流水线确认 Runner 能正常拉取代码、执行任务CI 变量和 Runner 这步太重要了。有次演练时数据库和仓库都恢复了看起来一切正常直到跑流水线时发现里面引用的变量全部解不开才意识到迁移时根本没有复制gitlab-secrets.json。5.5 恢复期间的特殊情况处理如果恢复过程中断比如 SSH 断连、机器重启tar 包已经解压了一半该怎么办不要慌先确认当前实例还能否访问然后重新执行完整的恢复命令即可。GitLab 的 restore 会对目标目录做清空重建处理重复执行不会残留上一次的脏数据。但要注意重复执行前也必须确保相关服务处于停止状态否则数据库文件被占用会导致恢复失败。6. 升级场景下的备份策略GitLab 版本升级是备份恢复最常见的触发场景之一。很多人是在升级完成、数据丢失之后才想到要回滚。6.1 升级前必须做的事版本升级前必须执行一次完整备份并且要尽可能完整记录当前环境的配置信息。升级虽然大概率不会出问题但一旦出了没有备份基本只能从零开始。执行备份后确认备份文件的时间戳是升级前的而不是升级过程中生成的。升级后生成的备份文件往往已经带有数据库结构变更无法用于回滚。同时升级前建议执行gitlab-ctl status记录下健康状态升级完成后如果服务异常可以对照确认是升级导致的问题还是原本就存在的问题。6.2 升级失败后的回滚思路回滚的第一步是把 GitLab 降级到原来的版本。先停止服务然后卸载当前版本重新安装原版本安装包这里有一个关键点卸载时不要删除配置文件和数据目录否则等于从头开始。通常只需要卸载软件包/etc/gitlab/和/var/opt/gitlab/下的内容都会被保留。安装好原版本后按前面 5.2 和 5.3 的流程恢复配置和密钥再恢复升级前的备份数据即可。6.3 跨大版本升级的注意事项GitLab 官方明确规定跨大版本升级必须遵循“逐级升级”策略不能从 15.x 一步跳到 16.x必须经过 16.0 的中间版本。每条升级路径都需要一次完整备份。这种情况下备份文件的版本标识尤其有用——tar 包文件名里自带版本号恢复时能直接确认是不是当前阶段应该用的备份。7. 常见问题、排查方法与独家避坑经验整理几个实际运维中高频出现的问题附带排查方法和解决路径。7.1 备份时报 Permission denied日志里出现权限报错优先检查备份目录的属主ls -ld /data/gitlab/backups确认是git用户且权限为 0700如果不符就改回来。还有一种情况是备份目录所在的挂载点以noexec方式挂载导致备份脚本无法执行文件操作这种情况下换挂载位置。7.2 备份完成但文件体积异常小先对比 tar 包内backup_information.yml里记录的仓库数量如果备份包含的仓库数比当前实际仓库数少大概率是权限问题或仓库在备份过程中被锁定。查看备份日志中会不会有某个仓库报Repository has no content之类提示。还有一种可能某仓库在远端已经删除但备份配置里还指向旧路径导致自动跳过。这种情况在管理后台的仓库设置里清理即可。7.3 恢复后访问页面 502502 基本都是服务没起来或端口不通。分步排查gitlab-ctl status重点看puma和sidekiq是否正常。如果不正常查看对应日志gitlab-ctl tail puma gitlab-ctl tail postgresql最常见的原因是恢复前没有执行gitlab-ctl reconfigure导致服务配置还是默认值和数据库恢复后的数据不匹配。另外如果恢复了gitlab.rb但忘了恢复gitlab-secrets.json也会因为数据库密码不匹配导致服务无法启动。7.4 gitlab-backup create 不识别新版本统一命令是gitlab-backup旧版本用gitlab-rake gitlab:backup:create。如果你的 GitLab 版本还停留在 12.x 之前执行gitlab-backup会提示无此命令这不是错误而是版本差异。7.5 恢复时提示备份版本不匹配备份恢复前 GitLab 会校验 tar 包内的版本和当前实例版本不一致会直接中止。唯一的解法就是安装匹配版本。临时绕过校验不是一个好选择即使强制恢复了后续数据库迁移也可能失败。7.6 备份路径空间满备份目录空间满是最普遍的隐患。恢复期间需要的空间约为备份文件体积的 2 到 3 倍——解压出的数据 数据库重建空间。如果容量只够放置备份文件而不够解压恢复会失败。建议恢复前检查磁盘余量df -h /var/opt/gitlab如果空间不够优先清理旧的备份文件恢复完成后再补充备份。7.7 特殊仓库恢复失败某些使用了 Git LFS 的仓库恢复时如果下面几个条件不满足可能会丢部分文件备份时 LFS 对象是否完整入库恢复时目标实例是否配置了对应的 LFS 路径仓库是否启用了 LFS 支持LFS 文件不在 git 仓库的常规对象里是单独的存储文件。备份包里的lfs/目录专门负责这些对象。恢复完成后确认 LFS 文件完整性最简单的方式是直接 clone 大仓库查看文件能否全部拉取。8. 个人实践中的几点体会自己维护 GitLab 这几年的最大感受是备份恢复这件事80% 的工作量在前期规划和周期性演练真正纯粹的“执行命令”只占很小一部分。第一脚本里永远加日志。每次备份执行的输出务必追加到文件里没有日志的备份等同于没做。曾经遇到过一次备份互相竞争资源导致失败就是靠查看最近 7 天的备份日志定位到具体时间点的资源占用才快速解决问题。第二配置文件、密钥文件、数据备份三者缺一不可。很多恢复失败的真实原因都出在“只恢复了数据包没有恢复配置和密钥”上。把这三样东西的备份打包成一个整体恢复时才不会遗漏。第三备份的有效性只能靠恢复验证。我在内部做过一个约定每次大版本升级前先拿升级前的备份在测试环境完整恢复一次确认一切正常再动生产环境。这个习惯已经帮团队避免了至少两次潜在的严重事故。第四备份文件一定要能脱离当前环境独立存在。比如同一块磁盘上只存放备份文件却不做冗余一旦磁盘故障备份数据照样全丢。正确做法是至少保证有一份远端的副本。这个内容后续还可以继续扩展的方向是异地容灾的低成本方案怎么做、GitLab 数据量上来以后的备份窗口优化、以及基于对象存储的备份生命周期管理。目前这套方案对绝大多数中小团队已经非常够用关键是先把自己的备份闭环跑起来。