前言

2018 年的时候，我写过一篇 gitlab 备份恢复的文章，详见：Gitlab备份以及恢复

上篇文章使用的 gitlab 版本是 10.x，如今 7 年过去，不少内容已不适用，今天再次来记录一下备份恢复的过程，以及遇到的问题。

备份恢复

通常 gitlab 如果是全新安装，则建议你安装最新版本，如果是旧版本，则使用原则也是非不要不升级。

现在我来记录一下从 12.x 之后适用的备份恢复流程。

流程

先来简要概述一下 gitlab 通过备份恢复的方式迁移的流程：

1. 首先准备一台新的机器，然后部署和原来环境同版本的 gitlab 服务。
2. 拷贝老的服务的 配置 和 秘钥，然后重载配置文件。
3. 在老的主机执行备份操作。
4. 将备份文件传到新的主机。
5. 在新的主机执行恢复操作。

准备

准备新的环境，部署新的服务，这个可参考：GitLab部署的最佳实践。

如果你是基于 docker 部署，则可使用如下 compose 文件拉起：

services:
  gitlab:
    image: 'gitlab/gitlab-ce:15.3.3-ce.0'
    container_name: gitlab
    restart: always
    environment:
      TZ: 'Asia/Shanghai'
    ports:
      - '22:22'
      - '8080:80'
    volumes:
      - '/data/project/gitlab/config:/etc/gitlab'
      - '/data/project/gitlab/logs:/var/log/gitlab'
      - '/data/project/gitlab/data:/var/opt/gitlab'

拉起之后，服务正常启动，所有重要内容都已挂载到本地。

此时去到老的服务器，把 gitlab.rb 和 gitlab-secrets.json 两个文件的内容覆盖掉新拉起环境的 config 目录下对应的两个文件。

警告

📢 注意：重中之重， gitlab-secrets.json 文件一定要一定要拷贝过来，gitlab 的许多重要功能都会依赖这个配置，如果老的配置没有拷贝，或者已经丢失，问题就会很难办。

这里也需要注意，新的环境通过 docker 部署时，配置文件中的一些自定义目录应该去掉，使其保持默认，以对应上挂载到宿主机的目录。

配置都放好之后，可以进入到容器，执行配置重载命令：

docker exec -it gitlab bash
gitlab-ctl reconfigure

重载完毕，新环境就准备好了，达到可恢复状态。

备份

通过如下命令可以对 gitlab 系统进行备份，此命令有别于上边 18 年那篇文章的命令。

gitlab-backup create

• 一般执行备份就要禁止写的操作了，因此这个阶段需提前通知维护窗口，先禁止访问，再执行备份，以保证数据完整性。
• 创建完毕之后，如果配置文件有指定，则备份文件在指定目录，如果没有指定，则默认目录为：/var/opt/gitlab/backups
• 关于备份耗时：备份执行的时间长短，取决于仓库文件大小，这里给一个参考数据。30G 左右的备份文件大约二十多分钟备份完成。
• 最后，再次提醒，务必注意上边提到的两个配置文件的备份，通常备份完成后，也会有如下提醒：

备份完成之后，将备份文件传到新的服务器的备份目录下，这个操作根据自己的习惯来传，不再赘述。

恢复

通过如下命令可对 gitlab 系统进行恢复，注意指定到文件的版本号处。

gitlab-backup restore BACKUP=1690008995_2025_09_07_15.3.3

• 恢复时看到错误提示 ERROR: _must be owner of extension pg_trgm_ 可忽略，不影响恢复动作。
• 如果提示文件不存在，看看是不是备份文件不在备份目录下，或者是文件名没写对。
• 恢复过程中，开始和最后会有两次输入 yes 用于确认的操作，请注意。
• 关于恢复耗时：恢复执行的时间长短，取决于备份文件的大小，如果文件较大，则需要较长的时间。这里还是以 30G 左右备份文件来举例，大约恢复时间需要三个小时左右，请耐心等待。

执行完毕之后，自己可通过绑定 hosts 验证是否有问题，没有问题就可以恢复访问了。

问题

gitlab 的备份恢复机制还是非常稳定好用的，可谓操作简单，数据稳定，值得信赖。

现在最大的问题，就是可能在执行这个备份恢复的过程中，漏掉了 gitlab-secrets.json 文件的迁移，并且老的配置也已丢失，可能会影响的问题如下：

• CI/CD variables
• Kubernetes / GCP integration
• Custom Pages domains
• Project error tracking
• Runner authentication
• Project mirroring
• Integrations
• Web hooks
• Deploy tokens

现象是使用这些功能的时候，会在页面遇到 500 的错误。

关于这个问题，网上有一些解决方案，但我参考之后，并没有找到完全根治此问题的方案，如果上边功能大部分你用不到，只是使用代码仓库的功能，那似乎也没什么影响，如果重度依赖如上功能，则仍需要探索解决方案。

gitlab 官方也提供了对应的文档：GitLab 备份故障排除 (opens new window)，我参考之后，只有 webhook 通过清空之后，重新配置解决了问题，其他的都没有效果。

web hooks

可通过如下命令进行清空，访问控制台：

sudo gitlab-rails dbconsole --database main

清空：

-- truncate web_hooks table
TRUNCATE integrations, chat_names, issue_tracker_data, jira_tracker_data, slack_integrations, web_hooks, zentao_tracker_data, web_hook_logs CASCADE;

清空完毕，再次进入到系统 hooks 页面，就不会报 500 的错误了，此时重新配置 hook 即可。

但是修改系统设置等功能出现的 500 错误，我至今未找到完美的解决方案，如果大家有可根治此问题的方案，请在评论区告诉我。