Help us learn about your current experience with the documentation. Take the survey.

灾难恢复 (Geo)

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

Geo 会复制您的数据库、Git 仓库以及其他资产。存在一些已知问题。

多从节点配置需要完全重新同步和重新配置所有未提升的从节点，并会导致服务中断。

在单从节点配置中提升从节点 Geo 站点

虽然您无法自动提升 Geo 副本并进行故障转移，但如果您拥有机器的 root 访问权限，则可以手动进行提升。

此过程会将 从节点 Geo 站点提升为 主节点 站点。为了尽快恢复地理冗余，您应在按照这些说明操作后立即添加一个新的 从节点 站点。

步骤 1. 如果可能，请等待复制完成

如果 从节点 站点仍在从 主节点 站点复制数据，请尽可能遵循计划内故障转移文档的步骤，以避免不必要的数据丢失。

步骤 2. 永久禁用主节点站点

如果 主节点 站点下线，主节点 站点上可能存在尚未复制到 从节点 站点的数据。如果您继续操作，这些数据将被视为已丢失。

如果 主节点 站点发生故障，您应尽一切可能避免“脑裂”情况（即两个不同的 GitLab 实例都可以进行写入操作），因为这会使恢复工作复杂化。因此，为准备故障转移，我们必须禁用 主节点 站点。

如果您有 SSH 访问权限：
1. 通过 SSH 登录到 主节点 站点以停止并禁用 GitLab：
```
sudo gitlab-ctl stop
```
2. 防止服务器意外重启后 GitLab 再次启动：
```
sudo systemctl disable gitlab-runsvdir
```
如果您没有 主节点 站点的 SSH 访问权限，请使该机器下线，并使用您可用的任何方式阻止其重启。您可能需要：
- 重新配置负载均衡器。
- 更改 DNS 记录（例如，将主 DNS 记录指向 从节点 站点，以停止对 主节点 站点的使用）。
- 停止虚拟服务器。
- 通过防火墙阻止流量。
- 撤销 主节点 站点的对象存储权限。
- 物理断开机器连接。
如果您计划更新主域的 DNS 记录，您可能希望保持较低的 TTL 值，以确保 DNS 更改能够快速传播。

在此过程中，主节点 站点的 /etc/gitlab/gitlab.rb 文件不会自动复制到从节点站点。请确保您已备份 主节点 的 /etc/gitlab/gitlab.rb 文件，以便日后在从节点站点上恢复任何需要的值。

步骤 3. 提升从节点站点

提升从节点时请注意以下几点：

如果从节点站点已暂停，提升操作将执行到最新已知状态的时间点恢复。从节点暂停期间在主节点上创建的数据将会丢失。
此时不应该添加新的 从节点。如果您想添加新的 从节点，请在完成将 从节点 提升为 主节点 的整个流程后再进行。
如果在此过程中遇到 ActiveRecord::RecordInvalid: Validation failed: Name has already been taken 错误消息，请参阅此故障排除建议获取更多信息。
如果您使用的是独立的 URL，您应该将主域 DNS 指向新提升的站点。否则，必须向新提升的站点重新注册 runners，并且所有 Git 远程仓库、书签和外部集成都必须更新。
如果您使用的是位置感知 DNS，在旧主节点从 DNS 条目中移除后，runners 应该会自动连接到新的主节点。
如果您不期望连接到先前主节点的 runners 再次出现，您应该将它们移除：
- 通过 UI：
  1. 在左侧边栏的底部，选择 管理员。
  2. 选择 CI/CD > Runners 并将其移除。
- 使用 Runners API。

提升在单个节点上运行的从节点站点

通过 SSH 登录到您的 从节点 站点并执行以下命令：
- 要将从节点站点提升为主节点：
```
sudo gitlab-ctl geo promote
```
- 要将从节点站点提升为主节点且无需任何进一步确认：
```
sudo gitlab-ctl geo promote --force
```
验证您是否可以使用先前用于 从节点 站点的 URL 连接到新提升的 主节点 站点。
如果成功，从节点 站点现在已提升为 主节点 站点。

提升具有多个节点的从节点站点

通过 SSH 登录到 从节点 站点中的每个 Sidekiq、PostgreSQL 和 Gitaly 节点，并运行以下命令之一：
- 要将从节点站点提升为主节点：
```
sudo gitlab-ctl geo promote
```
- 要将从节点站点提升为主节点且无需任何进一步确认：
```
sudo gitlab-ctl geo promote --force
```
通过 SSH 登录到 从节点 站点上的每个 Rails 节点，并运行以下命令之一：
- 要将从节点站点提升为主节点：
```
sudo gitlab-ctl geo promote
```
- 要将从节点站点提升为主节点且无需任何进一步确认：
```
sudo gitlab-ctl geo promote --force
```
验证您是否可以使用先前用于 从节点 站点的 URL 连接到新提升的 主节点 站点。
如果成功，从节点 站点现在已提升为 主节点 站点。

提升具有 Patroni 待机集群的从节点站点

通过 SSH 登录到 从节点 站点中的每个 Sidekiq、PostgreSQL 和 Gitaly 节点，并运行以下命令之一：
- 要将从节点站点提升为主节点：
```
sudo gitlab-ctl geo promote
```
- 要将从节点站点提升为主节点且无需任何进一步确认：
```
sudo gitlab-ctl geo promote --force
```
通过 SSH 登录到 从节点 站点上的每个 Rails 节点，并运行以下命令之一：
- 要将从节点站点提升为主节点：
```
sudo gitlab-ctl geo promote
```
- 要将从节点站点提升为主节点且无需任何进一步确认：
```
sudo gitlab-ctl geo promote --force
```
验证您是否可以使用先前用于 从节点 站点的 URL 连接到新提升的 主节点 站点。
如果成功，从节点 站点现在已提升为 主节点 站点。

提升具有外部 PostgreSQL 数据库的从节点站点

gitlab-ctl geo promote 命令可以与外部 PostgreSQL 数据库结合使用。在这种情况下，您必须首先手动提升与 从节点 站点关联的副本数据库：

提升与 从节点 站点关联的副本数据库。这会将数据库设置为读写模式。说明因您的数据库托管位置而异：

Amazon RDS
Azure PostgreSQL
Google Cloud SQL

对于其他外部 PostgreSQL 数据库，请在您的从节点站点中保存以下脚本，例如 /tmp/geo_promote.sh，并修改连接参数以匹配您的环境。然后，执行它以提升副本：

#!/bin/bash

PG_SUPERUSER=postgres

# 您的 pg_ctl 二进制文件的路径。您可能需要调整此路径以匹配
# 您的 PostgreSQL 安装
PG_CTL_BINARY=/usr/lib/postgresql/10/bin/pg_ctl

# 您的 PostgreSQL 数据目录的路径。您可能需要调整此
# 路径以匹配您的 PostgreSQL 安装。您也可以运行
# `SHOW data_directory;` 从 PostgreSQL 中查找您的数据目录
PG_DATA_DIRECTORY=/etc/postgresql/10/main

# 提升 PostgreSQL 数据库并允许读/写操作
sudo -u $PG_SUPERUSER $PG_CTL_BINARY -D $PG_DATA_DIRECTORY promote

通过 SSH 登录到 从节点 站点中的每个 Sidekiq、PostgreSQL 和 Gitaly 节点，并运行以下命令之一：
- 要将从节点站点提升为主节点：
```
sudo gitlab-ctl geo promote
```
- 要将从节点站点提升为主节点且无需任何进一步确认：
```
sudo gitlab-ctl geo promote --force
```
通过 SSH 登录到 从节点 站点上的每个 Rails 节点，并运行以下命令之一：
- 要将从节点站点提升为主节点：
```
sudo gitlab-ctl geo promote
```
- 要将从节点站点提升为主节点且无需任何进一步确认：
```
sudo gitlab-ctl geo promote --force
```
验证您是否可以使用先前用于 从节点 站点的 URL 连接到新提升的 主节点 站点。
如果成功，从节点 站点现在已提升为 主节点 站点。

步骤 4. (可选) 更新主域 DNS 记录

更新主域的 DNS 记录，使其指向 从节点 站点。这样就无需更新对主域的所有引用，例如更改 Git 远程仓库和 API URL。

通过 SSH 登录到 从节点 站点并以 root 身份登录：
```
sudo -i
```
更新主域的 DNS 记录。在将主域的 DNS 记录更新为指向 从节点 站点后，在 从节点 站点上编辑 /etc/gitlab/gitlab.rb 以反映新的 URL：
```
# 更改现有的 external_url 配置
external_url 'https://<new_external_url>'
```
更改 external_url 不会阻止通过旧的从节点 URL 进行访问，只要从节点的 DNS 记录仍然完好无损。
更新 从节点 的 SSL 证书：
- 如果您使用 Let’s Encrypt 集成，证书会自动更新。
- 如果您是手动设置的 从节点 证书，请将证书从 主节点 复制到 从节点。如果您无法访问 主节点，请签发一个新证书，并确保其主题备用名称中同时包含 主节点 和 从节点 的 URL。您可以通过以下命令检查：
```
/opt/gitlab/embedded/bin/openssl x509 -noout -dates -subject -issuer \
    -nameopt multiline -ext subjectAltName -in /etc/gitlab/ssl/new-gitlab.new-example.com.crt
```
重新配置 从节点 站点以使更改生效：
```
gitlab-ctl reconfigure
```
执行以下命令以更新新提升的 主节点 站点 URL：
```
gitlab-rake geo:update_primary_node_url
```
此命令使用在 /etc/gitlab/gitlab.rb 中定义的已更改的 external_url 配置。
验证您是否可以使用其 URL 连接到新提升的 主节点。如果您更新了主域的 DNS 记录，根据先前 DNS 记录的 TTL，这些更改可能尚未传播。

步骤 5. (可选) 将从节点 Geo 站点添加到已提升的主节点站点

使用上述过程将 从节点 站点提升为 主节点 站点，并不会在新 主节点 站点上启用 Geo。

要使新的 从节点 站点上线，请遵循 Geo 设置说明。

步骤 6. 移除前从节点的跟踪数据库

每个 从节点 都有一个特殊的跟踪数据库，用于保存从 主节点 同步的所有项目的状态。因为 从节点 已经被提升，跟踪数据库中的数据不再需要。

您可以使用以下命令删除该数据：

sudo rm -rf /var/opt/gitlab/geo-postgresql

如果您的 gitlab.rb 文件中启用了任何 geo_secondary[] 配置选项，请将它们注释掉或删除，然后重新配置 GitLab以使更改生效。

此时，您提升的站点是一个没有配置 Geo 的普通 GitLab 站点。您可以选择将旧站点作为从节点重新上线。

在多从节点配置中提升从节点 Geo 副本

如果您有多个 从节点 站点并且需要提升其中一个，我们建议您遵循在单从节点配置中提升 从节点 Geo 站点中的步骤，之后您还需要执行两个额外的步骤。

步骤 1. 准备新的主节点站点以服务一个或多个从节点站点

通过 SSH 登录到新的 主节点 站点并以 root 身份登录：
```
sudo -i
```

编辑 /etc/gitlab/gitlab.rb：

## 启用 Geo 主节点角色 (如果尚未启用)
roles ['geo_primary_role']

##
# 允许来自主节点和从节点 IP 的 PostgreSQL 客户端身份验证。这些 IP 可能是
# 公共地址或 VPC 地址，采用 CIDR 格式，例如 ['198.51.100.1/32', '198.51.100.2/32']
##
postgresql['md5_auth_cidr_addresses'] = ['<primary_site_ip>/32', '<secondary_site_ip>/32']

# 每个从节点站点都需要有自己的槽，因此请指定您将要拥有的从节点站点数量
# postgresql['max_replication_slots'] = 1 # 如果您有多个 Geo 从节点，请将其设置为 Geo 从节点的数量

##
## 临时禁用自动数据库迁移
## (直到 PostgreSQL 重启并在私有地址上监听)。
##
gitlab_rails['auto_migrate'] = false

(有关这些设置的更多详细信息，您可以阅读配置主服务器)

保存文件并重新配置 GitLab，以应用数据库监听更改和复制槽更改：
```
gitlab-ctl reconfigure
```
重启 PostgreSQL 以使其更改生效：
```
gitlab-ctl restart postgresql
```
现在重新启用迁移，因为 PostgreSQL 已重启并在私有地址上监听。

编辑 /etc/gitlab/gitlab.rb 并将配置更改为 true：
```
gitlab_rails['auto_migrate'] = true
```
保存文件并重新配置 GitLab：
```
gitlab-ctl reconfigure
```

步骤 2. 启动复制过程

现在我们需要让每个 从节点 站点监听新 主节点 站点上的更改。为此，您需要再次启动复制过程，但这次是针对另一个 主节点 站点。所有旧的复制设置都会被覆盖。

现有的从节点站点都将拥有已填充的数据库，因此您可能会看到如下消息：

Found data inside the gitlabhq_production database! If you are sure you are in the secondary server, override with --force

在确认您位于相应的从节点站点上后，使用 --force 启动复制。

使用 --force 会导致该从节点服务器上数据库中的所有现有数据被删除。

在 GitLab Helm chart 中提升从节点 Geo 集群

在更新云原生 Geo 部署时，更新从节点 Kubernetes 集群外部的任何节点的过程与非云原生方法没有区别。因此，您始终可以参考在单从节点配置中提升 从节点 Geo 站点获取更多信息。

以下部分假定您使用的是 gitlab 命名空间。如果您在设置集群时使用了不同的命名空间，则还应将 --namespace gitlab 替换为您的命名空间。

步骤 1. 永久禁用主节点集群

如果 主节点 站点下线，主节点 站点上可能存在尚未复制到 从节点 站点的数据。如果您继续操作，这些数据将被视为已丢失。

如果 主节点 站点发生故障，您应尽一切可能避免“脑裂”情况（即两个不同的 GitLab 实例都可以进行写入操作），因为这会使恢复工作复杂化。因此，为准备故障转移，您必须禁用 主节点 站点：

如果您有权访问 主节点 Kubernetes 集群，请连接到它并禁用 GitLab webservice 和 Sidekiq pod：

kubectl --namespace gitlab scale deploy gitlab-geo-webservice-default --replicas=0
kubectl --namespace gitlab scale deploy gitlab-geo-sidekiq-all-in-1-v1 --replicas=0

如果您没有访问 主节点 Kubernetes 集群的权限，请使该集群下线，并使用您可用的任何方式阻止其重新上线。您可能需要：
- 重新配置负载均衡器。
- 更改 DNS 记录（例如，将主 DNS 记录指向 从节点 站点，以停止对 主节点 站点的使用）。
- 停止虚拟服务器。
- 通过防火墙阻止流量。
- 撤销 主节点 站点的对象存储权限。
- 物理断开机器连接。

步骤 2. 提升集群外部的所有从节点站点节点

如果从节点站点已暂停，这将执行到最新已知状态的时间点恢复。从节点暂停期间在主节点上创建的数据将会丢失。

对于 从节点 Kubernetes 集群外部使用 Linux 软件包的每个节点（例如 PostgreSQL 或 Gitaly），通过 SSH 登录到该节点并运行以下命令之一：
- 要将 Kubernetes 集群外部的 从节点 站点节点提升为主节点：
```
sudo gitlab-ctl geo promote
```
- 要将 Kubernetes 集群外部的 从节点 站点节点提升为主节点且无需任何进一步确认：
```
sudo gitlab-ctl geo promote --force
```

查找 toolbox pod：

kubectl --namespace gitlab get pods -lapp=toolbox

提升从节点：

kubectl --namespace gitlab exec -ti gitlab-geo-toolbox-XXX -- gitlab-rake geo:set_secondary_as_primary

可以提供环境变量来修改任务的行为。可用的变量有：

名称	默认值	描述
`ENABLE_SILENT_MODE`	`false`	如果为 `true`，则在提升前启用静默模式（GitLab 16.4 及更高版本）

步骤 3. 提升从节点集群

更新现有集群配置。

您可以使用 Helm 检索现有配置：

helm --namespace gitlab get values gitlab-geo > gitlab.yaml

现有配置包含一个 Geo 部分，应类似于：

geo:
   enabled: true
   role: secondary
   nodeName: secondary.example.com
   psql:
      host: geo-2.db.example.com
      port: 5431
      password:
         secret: geo
         key: geo-postgresql-password

要将 从节点 集群提升为 主节点 集群，请将 role: secondary 更新为 role: primary。

如果集群保持为主节点站点，您可以删除整个 psql 部分；它指的是跟踪数据库，在集群充当主节点站点时会被忽略。

使用新配置更新集群：

helm upgrade --install --version <current Chart version> gitlab-geo gitlab/gitlab --namespace gitlab -f gitlab.yaml

验证您是否可以使用先前用于从节点的 URL 连接到新提升的主节点。
成功！从节点现在已提升为主节点。

故障排除

本节已移至其他位置。

灾难恢复 (Geo)

在单从节点配置中提升 从节点 Geo 站点

步骤 1. 如果可能，请等待复制完成

步骤 2. 永久禁用 主节点 站点

步骤 3. 提升 从节点 站点

提升在单个节点上运行的 从节点 站点

提升具有多个节点的 从节点 站点

提升具有 Patroni 待机集群的 从节点 站点

提升具有外部 PostgreSQL 数据库的 从节点 站点