GitLab 备份恢复与配置迁移详尽教程（实战版）

🛠 GitLab 备份恢复与配置迁移详尽教程（实战版）

---

🧱 一、环境准备

1.1 检查版本一致性

恢复目标机 GitLab 版本必须与备份文件所用版本一致或兼容（推荐相同版本）

查看当前 GitLab 版本：

sudo gitlab-rake gitlab:env:info | grep "GitLab version"

或者更直接：

sudo cat /opt/gitlab/version-manifest.txt | grep "gitlab-ce"

1.2 停止关键服务

在执行恢复前，必须停止连接数据库的服务：

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq

也可以一口气停止所有：

sudo gitlab-ctl stop

---

📦 二、备份数据与配置

2.1 备份 GitLab 数据库

sudo gitlab-backup create

默认会生成在 /var/opt/gitlab/backups/ 目录下，文件名如：

1750765308_2025_06_24_16.7.6_gitlab_backup.tar

2.2 打包配置文件

sudo tar -cf gitlab_conf.tar /etc/gitlab

输出提示：

tar: Removing leading `/' from member names

✅ 正常提示。表示打包时去掉绝对路径前缀，防止覆盖系统路径。

---

🧳 三、迁移备份文件到目标主机（可选）

# 从源服务器复制到目标
scp /var/opt/gitlab/backups/1750765308_2025_06_24_16.7.6_gitlab_backup.tar root@target-host:/var/opt/gitlab/backups/# 同样迁移配置
scp gitlab_conf.tar root@target-host:~/

目标主机：

sudo tar -xf gitlab_conf.tar -C /

然后：

sudo gitlab-ctl reconfigure

---

🔄 四、执行 GitLab 数据恢复

sudo gitlab-backup restore BACKUP=1750765308_2025_06_24_16.7.6

会提示：

Be sure to stop Puma, Sidekiq... Do you want to continue (yes/no)?

输入：

yes

随后会尝试清空数据库并导入数据。

---

⚠️ 五、常见问题与解决方案

5.1 PostgreSQL 扩展权限错误

恢复时报错：

ERROR: must be owner of extension pg_trgm
ERROR: must be owner of extension btree_gist

解决方法一（推荐）：

使用超级用户 gitlab-psql 登录，并删除这两个扩展：

sudo gitlab-psql-- 删除可能存在的扩展
DROP EXTENSION IF EXISTS pg_trgm;
DROP EXTENSION IF EXISTS btree_gist;
\q

然后重新执行恢复命令。

解决方法二（若 PostgreSQL >= 9.3）：

ALTER EXTENSION pg_trgm OWNER TO gitlab;

但你遇到的报错说明 PostgreSQL 版本较低（如 9.1），不支持该语法。

---

5.2 logrotate 报错无法 reconfigure

恢复后执行：

sudo gitlab-ctl reconfigure

报错如下：

runit_service[logrotate] ...
timeout: down: /opt/gitlab/service/logrotate/log: 0s, normally up, want up

处理方式：

手动清理 logrotate 服务文件并重启：

sudo sv stop /opt/gitlab/service/logrotate
sudo rm -rf /opt/gitlab/service/logrotate
sudo gitlab-ctl reconfigure

如果还有问题，也可禁用 logrotate 服务（不推荐长期停用）或查看：

less /opt/gitlab/embedded/cookbooks/cache/cinc-stacktrace.out

---

✅ 六、恢复后验证步骤

6.1 启动 GitLab 服务

sudo gitlab-ctl start

6.2 检查服务状态

sudo gitlab-ctl status

确保关键服务如 postgresql, puma, sidekiq 均为 run 状态。

6.3 Web 页面访问验证

访问 http://<your-gitlab-host>，确认是否可正常登录、浏览项目。

---

🧩 七、恢复后可能还需要的命令

创建缺失扩展

sudo gitlab-psql -d gitlabhq_production -c "CREATE EXTENSION pg_trgm;"
sudo gitlab-psql -d gitlabhq_production -c "CREATE EXTENSION btree_gist;"

检查数据库角色

sudo gitlab-psql
\du

确保角色 gitlab 存在并非超级用户即可。

---

📘 八、参考资料

• GitLab 官方备份文档：https://blog.csdn.net/qq_44930876/article/details/129581849
• 镜像下载地址：https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/yum/el7/

---