当前位置：首页 > news >正文

如何恢复极狐GitLab？

news 来源：原创 2025/8/18 18:24:41

极狐GitLab 是 GitLab 在中国的发行版，关于中文参考文档和资料有：

极狐GitLab 中文文档
极狐GitLab 中文论坛
极狐GitLab 官网

恢复极狐GitLab (BASIC SELF)

极狐GitLab 提供了一个命令行界面来恢复整个安装，足够灵活以满足您的需求。

恢复先决条件部分包含关键信息。在尝试在生产环境中执行之前，请务必至少阅读和测试完整的恢复过程一次。

恢复先决条件

目标极狐GitLab 实例必须已经在工作

您需要有一个正在运行的极狐GitLab 安装才能进行恢复。这是因为执行恢复操作的系统用户（git）通常不被允许创建或删除导入数据所需的 SQL 数据库（gitlabhq_production）。所有现有数据要么被删除（SQL），要么被移动到单独的目录（例如存储库和上传）。恢复 SQL 数据跳过 PostgreSQL 扩展拥有的视图。

目标极狐GitLab 实例必须具有完全相同的版本

您只能将备份恢复到创建它的极狐GitLab 的完全相同版本和类型（基础版或企业版）。例如，基础版 15.1.4。
如果您的备份版本与当前安装版本不同，则必须在恢复备份之前降级或升级您的极狐GitLab 安装。

极狐GitLab 密钥必须恢复

要恢复备份，您还必须恢复极狐GitLab 密钥。这些包括数据库加密密钥，CI/CD 变量，以及用于双因素认证的变量。如果没有这些密钥，会发生多个问题，包括启用双因素认证的用户无法访问，以及极狐GitLab Runner 无法登录。
恢复：

/etc/gitlab/gitlab-secrets.json（Linux 软件包安装）
/home/git/gitlab/.secret（自编译安装）
恢复密钥（云原生极狐GitLab）
- 如果需要，极狐GitLab Helm chart 密钥可以转换为 Linux 软件包格式。

某些极狐GitLab 配置必须与原始备份环境匹配

您可能还希望恢复之前的 /etc/gitlab/gitlab.rb（对于 Linux 软件包安装）或 /home/git/gitlab/config/gitlab.yml（对于自编译安装）以及任何 TLS 密钥、证书（/etc/gitlab/ssl，/etc/gitlab/trusted-certs），或 SSH 主机密钥。

某些配置与 PostgreSQL 中的数据相关。例如：

如果原始环境有三个存储库存储（例如，default、my-storage-1 和 my-storage-2），那么目标环境也必须至少在配置中定义这些存储名称。
从使用本地存储的环境恢复备份，即使目标环境使用对象存储，仍会恢复到本地存储。迁移到对象存储必须在恢复之前或之后完成。

恢复作为挂载点的目录

如果您要恢复到作为挂载点的目录中，则必须确保这些目录在尝试恢复之前是空的。否则，极狐GitLab 会在恢复新数据之前尝试移动这些目录，从而导致错误。

关于配置 NFS 挂载的信息。

Linux 软件包安装的恢复

该过程假设：

您已安装了极狐GitLab 的完全相同版本和类型（基础版/企业版），备份就是使用该版本创建的。
您至少运行过一次 sudo gitlab-ctl reconfigure。
极狐GitLab 正在运行。如果没有，请使用 sudo gitlab-ctl start 启动它。

首先确保您的备份 tar 文件位于 gitlab.rb 配置中描述的备份目录中 gitlab_rails[‘backup_path’]。默认路径是 /var/opt/gitlab/backups。备份文件需要由 git 用户拥有。

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

停止连接到数据库的进程。让极狐GitLab 的其他部分继续运行：

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# 验证
sudo gitlab-ctl status

接下来，确保您已完成恢复先决条件步骤，并在从原始安装复制极狐GitLab 密钥文件后运行 gitlab-ctl reconfigure。
接下来，恢复备份，指定您要恢复的备份的 ID：
WARNING:
以下命令会覆盖您的极狐GitLab 数据库的内容！

# NOTE: "_gitlab_backup.tar" 是省略的名称
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

如果您的备份 tar 文件和安装的极狐GitLab 版本之间存在版本不匹配，恢复命令会以错误消息中止：

极狐GitLab 版本不匹配：您当前的极狐GitLab 版本（16.5.0-ee）与备份中的极狐GitLab 版本不同！请切换到以下版本并重试：version: 16.4.3-ee

安装正确的极狐GitLab 版本，然后重试。
WARNING:
恢复命令需要附加参数，当您的安装使用 PgBouncer 时，出于性能原因或与 Patroni 集群一起使用时。
接下来，重启并检查极狐GitLab：

sudo gitlab-ctl restart
sudo gitlab-rake gitlab:check SANITIZE=true

验证数据库值是否可以解密，特别是如果 /etc/gitlab/gitlab-secrets.json 已恢复，或如果不同的服务器是恢复目标。

sudo gitlab-rake gitlab:doctor:secrets

为增加保证，您可以对上传文件执行完整性检查：

sudo gitlab-rake gitlab:artifacts:check
sudo gitlab-rake gitlab:lfs:check
sudo gitlab-rake gitlab:uploads:check

恢复完成后，建议生成数据库统计数据以提高数据库性能并避免 UI 中的不一致：

1.进入数据库控制台。

2.运行以下命令：

SET STATEMENT_TIMEOUT=0 ; ANALYZE VERBOSE;

Docker 镜像和极狐GitLab Helm chart 安装的恢复

对于在 Kubernetes 集群上使用 Docker 镜像或极狐GitLab Helm chart 的极狐GitLab 安装，恢复任务期望恢复目录是空的。然而，使用 Docker 和 Kubernetes 卷挂载时，可能会在卷根目录创建一些系统级目录，例如在 Linux 操作系统中发现的 lost+found 目录。这些目录通常由 root 拥有，这可能导致访问权限错误，因为恢复 Rake 任务以 git 用户身份运行。要恢复极狐GitLab 安装，用户必须确认恢复目标目录是空的。

对于这两种安装类型，备份 tarball 必须可用于备份位置（默认位置是 /var/opt/gitlab/backups）。

Helm chart 安装的恢复

极狐GitLab Helm chart 使用恢复极狐GitLab Helm chart 安装中记录的过程。

Docker 镜像安装的恢复

如果您使用 Docker Swarm，容器可能会在恢复过程中重启，因为 Puma 被关闭，导致容器健康检查失败。为了解决这个问题，暂时禁用健康检查机制。

1.编辑 docker-compose.yml：

healthcheck:
disable: true

2.部署堆栈：

docker stack deploy --compose-file docker-compose.yml mystack可以从主机运行恢复任务：# 停止连接到数据库的进程
docker exec -it <name of container> gitlab-ctl stop puma
docker exec -it <name of container> gitlab-ctl stop sidekiq# 在继续之前验证所有进程都已关闭
docker exec -it <name of container> gitlab-ctl status# 运行恢复。NOTE: "_gitlab_backup.tar" 是省略的名称
docker exec -it <name of container> gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce# 重启极狐GitLab 容器
docker restart <name of container># 检查极狐GitLab
docker exec -it <name of container> gitlab-rake gitlab:check SANITIZE=true

自编译安装的恢复

首先，确保您的备份 tar 文件位于 gitlab.yml 配置中描述的备份目录中：

## 备份设置
backup:path: "tmp/backups"   # 相对路径相对于 Rails.root（默认：tmp/backups/）

默认路径是 /home/git/gitlab/tmp/backups，并且需要由 git 用户拥有。现在，您可以开始备份过程：

# 停止连接到数据库的进程
sudo service gitlab stopsudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production

示例输出：

解压备份... [完成]
恢复数据库表：
-- create_table("events", {:force=>true})-> 0.2231s
[...]
- 加载固定事件...[完成]
- 加载固定议题...[完成]
- 加载固定密钥...[跳过]
- 加载固定合并请求...[完成]
- 加载固定里程碑...[完成]
- 加载固定命名空间...[完成]
- 加载固定备注...[完成]
- 加载固定项目...[完成]
- 加载固定受保护分支...[跳过]
- 加载固定 schema_migrations...[完成]
- 加载固定服务...[跳过]
- 加载固定代码片段...[跳过]
- 加载固定标记...[跳过]
- 加载固定标签...[跳过]
- 加载固定用户...[完成]
- 加载固定用户项目...[完成]
- 加载固定 web_hooks...[跳过]
- 加载固定 wiki...[跳过]
恢复存储库：
- 恢复存储库 abcd... [完成]
- 对象池 1 ...
删除临时目录...[完成]

接下来，如果需要恢复 /home/git/gitlab/.secret，如前所述。
重启极狐GitLab：

sudo service gitlab restart

从备份中仅恢复一个或几个项目或组

虽然用于恢复极狐GitLab 实例的 Rake 任务不支持恢复单个项目或组，但您可以通过将备份恢复到单独的临时极狐GitLab 实例，然后从那里导出项目或组来使用一种解决方法：

1.安装一个新的极狐GitLab 实例，版本与您要恢复的备份实例相同。
2.将备份恢复到这个新实例，然后导出您的项目或组。有关导出的内容和未导出的内容的更多信息，请参阅导出功能的文档。
3.导出完成后，转到旧实例，然后导入它。
4.完成您想要的项目或组导入后，您可以删除新的临时极狐GitLab 实例。

恢复增量存储库备份

每个备份档案都包含一个完整的自包含备份，包括通过增量存储库备份过程创建的备份。要恢复增量存储库备份，请使用与恢复任何其他常规备份档案相同的说明。

恢复选项

极狐GitLab 提供的命令行工具可以接受更多选项来从备份中恢复。

在存在多个备份时指定恢复的备份

备份文件使用以备份 ID 开头的命名方案 starting with a backup ID。当存在多个备份时，您必须通过设置环境变量 BACKUP= 来指定要恢复的 _gitlab_backup.tar 文件。

在恢复期间禁用提示

在从备份恢复期间，恢复脚本会提示确认：

如果启用了 Write to authorized_keys 设置，则在恢复脚本删除并重建 authorized_keys 文件之前。
在恢复数据库时，在恢复脚本删除所有现有表之前。
在恢复数据库后，如果恢复架构时出现错误，则在继续之前，因为可能会出现进一步的问题。

要禁用这些提示，请将 GITLAB_ASSUME_YES 环境变量设置为 1。

Linux 软件包安装：

sudo GITLAB_ASSUME_YES=1 gitlab-backup restore

自编译安装：

sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ENV=production

force=yes 环境变量也会禁用这些提示。

在恢复时排除任务

您可以通过添加环境变量 SKIP 来排除恢复时的特定任务，其值是以下选项的逗号分隔列表：

db（数据库）
uploads（附件）
builds（CI 作业输出日志）
artifacts（CI 作业制品）
lfs（LFS 对象）
terraform_state（Terraform 状态）
registry（容器注册表镜像）
pages（Pages 内容）
repositories（Git 存储库数据）
packages（软件包）

要排除特定任务：

Linux 软件包安装：

sudo gitlab-backup restore BACKUP=<backup-id> SKIP=db,uploads

自编译安装：

sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> SKIP=db,uploads RAILS_ENV=production

恢复特定存储库存储

引入于极狐GitLab 15.0。

WARNING:
极狐GitLab 17.1 及更早版本受竞争条件影响，可能导致数据丢失。该问题影响了已被 fork 并使用极狐GitLab 对象池的存储库。为了避免数据丢失，仅使用极狐GitLab 17.2 或更高版本恢复备份。

当使用多个存储库存储时，可以使用 REPOSITORIES_STORAGES 选项单独恢复特定存储库存储的存储库。该选项接受逗号分隔的存储名称列表。

例如：

Linux 软件包安装：

sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2

自编译安装：

sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2

恢复特定存储库

引入于极狐GitLab 15.1。

您可以使用 REPOSITORIES_PATHS 和 SKIP_REPOSITORIES_PATHS 选项恢复特定存储库。这两个选项都接受项目和组路径的逗号分隔列表。如果您指定了组路径，则所有项目中的所有存储库以及子组中的存储库都被包括在内或跳过，具体取决于您使用的选项。这些组和项目必须存在于指定的备份或目标实例中。

NOTE:
REPOSITORIES_PATHS 和 SKIP_REPOSITORIES_PATHS 选项仅适用于 Git 存储库。它们不适用于项目或组数据库条目。如果您使用 SKIP=db 创建了存储库备份，单独它不能用于将特定存储库恢复到新实例。

例如，要恢复群组 A（group-a）中所有项目的所有存储库，群组 B 中项目 C（group-b/project-c）的存储库，并跳过群组 A 中的项目 D（group-a/project-d）：

Linux 软件包安装：

sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d

自编译安装：

sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d

恢复未打包的备份

如果发现未打包的备份（使用 SKIP=tar 创建），并且没有使用 BACKUP= 选择备份，则使用未打包的备份。
例如：

Linux 软件包安装：

sudo gitlab-backup restore

自编译安装：

sudo -u git -H bundle exec rake gitlab:backup:restore

故障排除

以下是您可能遇到的问题以及潜在的解决方案。

使用 Linux 软件包安装时输出警告恢复数据库备份

如果您使用备份恢复程序，可能会遇到以下警告消息：

ERROR: 必须是扩展 pg_trgm 的所有者
ERROR: 必须是扩展 btree_gist 的所有者
ERROR: 必须是扩展 plpgsql 的所有者
WARNING: "public" 没有权限可以撤销（出现两次）
WARNING: "public" 没有权限被授予（出现两次）

请注意，备份已成功恢复，尽管有这些警告消息。
Rake 任务以 gitlab 用户身份运行，该用户没有数据库的超级用户访问权限。当恢复启动时，它也以 gitlab 用户身份运行，但它也尝试改变它没有访问权限的对象。这些对象对数据库备份或恢复没有影响，但显示警告消息。

有关更多信息，请参阅：

PostgreSQL 问题跟踪：
- 不是超级用户。
- 具有不同所有者。

由于 Git 服务器钩子导致恢复失败

在备份恢复期间，如果以下条件为真，您可能会遇到错误：

使用极狐GitLab 版本 15.10 及更早版本的方法配置了 Git 服务器钩子（custom_hook）
您的极狐GitLab 版本是版本 15.11 及更高版本
您创建了指向极狐GitLab 管理位置之外的目录的符号链接

错误看起来像：

{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupID>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"}

要解决此问题，可以更新极狐GitLab 版本 15.11 及更高版本的 Git 服务器钩子，并创建新的备份。

使用 fapolicyd 时恢复成功但存储库显示为空

使用 fapolicyd 增强安全性时，极狐GitLab 可以报告恢复成功，但存储库显示为空。有关更多故障排除帮助，请参阅Gitaly 故障排除文档。