极狐GitLab容灾备份与恢复实操，备份策略与演练清单
极狐GitLab容灾备份与恢复实操，备份策略与演练清单
备份恢复：极狐GitLab通过
gitlab-backup工具将数据库、代码仓库、CI/CD产物等数据打包归档，并可在同版本实例上完整还原，是私有化部署容灾体系的最后一道防线。
数据丢了才发现备份没做全，是运维团队最常见的"事后诸葛"场景。代码仓库、CI/CD产物、用户凭据散落在不同位置，备份命令跑成功了不等于恢复能成功——备份的价值只能靠演练验证。这篇文章把极狐GitLab的备份与恢复拆成可执行的步骤：什么必须备份、怎么备、怎么恢复、怎么验证，最后给一份可以直接照着跑的演练清单。
一、先搞清楚：备份里有什么，缺什么
很多人以为跑一条 gitlab-backup create 就万事大吉，实际上备份归档有明确的覆盖边界。根据官方备份文档，默认备份生成单个压缩 tar 归档，包含以下内容：
类别 | 具体内容 |
|---|---|
数据与配置 | PostgreSQL 数据库数据、数据库配置 |
代码资产 | Git 代码仓库、LFS 对象、项目和群组 Wiki |
CI/CD | 产物（artifacts）、作业日志、Terraform 状态 |
内容与附件 | 上传文件、外部合并请求差异、项目级安全文件、Pages 内容、代码片段 |
生态数据 | 软件包仓库数据、容器镜像仓库镜像 |
账号 | 账号和群组设置 |
同样重要的是：这些内容不在备份里，必须单独处理。
不在备份中的数据 | 处理方式 |
|---|---|
配置文件 | 手动备份，建议纳入版本管理或加密存储 |
密钥文件 | 必须手动备份——含数据库加密密钥，丢了就无法解密任何加密值 |
对象存储中的数据（Omnibus/Docker/自编译安装） | 依赖对象存储自身的备份机制，如 S3 备份、版本化桶 |
Redis 数据、Sidekiq 作业 | 官方明确不备份，属可再生的临时数据 |
TLS 证书与 SSH 主机密钥 | 建议一并备份，避免整机恢复后出现中间人告警 |
密钥文件单独存是有意为之的设计：数据库里存着双重身份验证、CI/CD 安全变量等加密信息，密钥和密文放在一起等于没加密。这也是恢复时最容易翻车的地方——没恢复 gitlab-secrets.json，所有启用双因素认证的用户都会被锁在门外，Runner 也无法登录。
二、备份实操：一条命令与它的变体
Linux 软件包安装的基础备份命令：
sudo gitlab-backup create归档默认生成在 gitlab_rails['backup_path'] 配置的目录（默认 /var/opt/gitlab/backups），文件名形如 1393513186_2014_02_27_gitlab_backup.tar，属主为 git 用户、权限 0600。
生产环境常用的四个变体：
# 1. 数据高频变化时用 copy 策略，避免 "file changed as we read it" 报错
sudo gitlab-backup create STRATEGY=copy
# 2. 排除指定数据，比如仓库数据已由 Geo 站点承接时
sudo gitlab-backup create SKIP=db,uploads
# 3. 备份后自动上传远程存储（需先配置 backup_upload_connection）
sudo gitlab-backup create DIRECTORY=daily
# 4. cron 定时备份，每天凌晨 2 点
0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1两个配置项建议顺手改上：gitlab_rails['backup_keep_time'] = 604800 限制本地备份保留 7 天，防止磁盘被旧归档塞满；仓库量大时用 GITLAB_BACKUP_MAX_CONCURRENCY=4 并行打包可明显缩短窗口。
一个官方明示的边界：当数据库超过 100 GB 或 Git 数据达到 400 GB 量级时，备份命令很可能不再实用，此时应转向增量备份（INCREMENTAL=yes）、磁盘快照或 Geo 站点等替代策略。这不是备份工具的缺陷，而是 pg_dump 和 Git bundle 机制在超大规模下的固有约束。
三、恢复实操：五个前提，五步走
恢复比备份更容易出错，因为前提条件更苛刻。根据官方恢复文档，恢复前必须满足：
版本与类型完全一致：只能恢复到与备份创建时相同版本、相同类型（基础版/企业版）的实例，版本不匹配命令会直接中止；
目标实例已正常工作：
git用户无权创建 SQL 数据库，所以恢复前必须有一个装好的、能跑的极狐GitLab；目标实例无既有数据：PostgreSQL 会自动清除，但同名 Git 仓库会导致恢复失败，对象存储桶需手动清空；
密钥文件已恢复：从原服务器复制
gitlab-secrets.json并执行reconfigure；备份目录空间充足：可用空间至少为归档大小的三倍，不满足则恢复在解压前即停止。
满足前提后，恢复五步：
# 1. 将备份归档放入备份目录并修正属主
sudo cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/
sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar
# 2. 停止连接数据库的进程，其余服务保持运行
sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# 3. 执行恢复（文件名中 "_gitlab_backup.tar" 部分省略）
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
# 4. 在 PostgreSQL 节点上重载配置并启动
sudo gitlab-ctl reconfigure
sudo gitlab-ctl start
# 5. 检查与验证
sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-rake gitlab:doctor:secrets第 5 步里的 gitlab:doctor:secrets 值得单独强调：它会逐条验证数据库中的加密值能否用当前密钥解密。凡是涉及恢复 gitlab-secrets.json 或跨服务器恢复的场景，这条命令必须跑，否则问题会等到用户登录或 CI 变量读取时才集中爆发。
四、灾备演练清单：照着跑一遍
备份不做恢复演练，等于没备份。以下清单源自上述官方步骤，建议每季度在隔离环境完整执行一次：
# | 演练项 | 通过标准 |
|---|---|---|
1 | 在隔离环境准备同版本、同类型实例 |
|
2 | 拷贝备份归档与 | 文件完整、属主为 git |
3 | 执行完整恢复流程 |
|
4 | 运行 | 输出 "decrypted values are correct" |
5 | 运行 | 抽样文件校验通过 |
6 | 用真实账号登录，抽查双因素认证、CI/CD 变量、Runner 连接 | 用户可登录、流水线可触发 |
7 | 记录演练总耗时 | 满足业务 RTO（恢复时间目标） |
第 7 项最容易被忽略：演练的意义不只是验证流程通不通，更是拿到真实数据量下的恢复耗时，用它反推 RTO 承诺是否兑现。如果演练耗时已经超出业务容忍度，就该考虑增量备份缩短窗口，或用 Geo 建立温备站点把切换时间从"小时级"压到"分钟级"。
常见问题 FAQ
Q1：备份成功后恢复时提示 GitLab version mismatch，怎么办？
备份只能恢复到完全相同版本和类型的实例。按报错提示中给出的目标版本（如 16.4.3-ee）调整目标实例版本后重试。这也是演练清单要求"同版本实例"的原因——临时升级或降级会大幅拉长真实故障的恢复时间。
Q2：gitlab-secrets.json 丢了还能恢复吗？
密钥文件丢失意味着数据库加密值（双因素认证、CI/CD 安全变量等）无法解密。官方故障排除文档提供了处理路径，但代价是相关用户需重新配置双因素认证、相关变量需重新录入。最稳妥的做法是把密钥文件纳入离线加密备份，与归档分开存储。
Q3：对象存储上的数据备份命令管不到，怎么补齐？
备份命令不会备份存储在对象存储中的数据（Omnibus/Docker/自编译安装）。需依赖对象存储自身的机制补齐：如 S3 备份、版本化桶或跨区域复制，并注意极狐GitLab 不会自动清理第三方对象存储中的旧备份，保留策略需自行配置。
数据可备份、可恢复、演练过，才算真正的容灾。极狐GitLab 官方文档中心提供了从备份参数到 Geo 容灾的完整文档，如需结合贵司数据规模评估备份策略与恢复时间目标，欢迎预约演示或联系团队获取灾备方案建议。
