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

为两个单节点站点设置 Geo（使用外部 PostgreSQL 服务）

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

以下指南提供了简洁的说明，介绍如何使用两个 Linux 包实例和外部 PostgreSQL 数据库（如 RDS、Azure Database 或 Google Cloud SQL）部署 GitLab Geo，以实现两个单节点站点的安装。

先决条件：

你至少有两个独立运行的 GitLab 站点。要创建这些站点，请参阅 GitLab 参考架构文档。
- 一个 GitLab 站点作为 Geo 主站点。你可以为每个 Geo 站点使用不同的参考架构大小。如果你已经有一个可用的 GitLab 实例，你可以将其用作主站点。
- 第二个 GitLab 站点作为 Geo 从站点。Geo 支持多个从站点。
Geo 主站点至少拥有 GitLab Premium 许可证。所有站点只需要一个许可证。
确认所有站点都满足运行 Geo 的要求。

为 Linux 包（Omnibus）设置 Geo

先决条件：

你使用 PostgreSQL 12 或更高版本，其中包含 pg_basebackup 工具。

配置主站点

SSH 连接到你的 GitLab 主站点并以 root 身份登录：
```
sudo -i
```

向 /etc/gitlab/gitlab.rb 添加一个唯一的 Geo 站点名称：

##
## Geo 站点的唯一标识符。请参阅
## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings
##
gitlab_rails['geo_node_name'] = '<site_name_here>'

应用更改，重新配置主站点：
```
gitlab-ctl reconfigure
```
将站点定义为主 Geo 站点：
```
gitlab-ctl set-geo-primary-node
```
此命令使用 /etc/gitlab/gitlab.rb 中定义的 external_url。

配置要复制的外部数据库

要设置外部数据库，你可以选择：

自己设置流复制（例如 Amazon RDS，或不由 Linux 包管理的裸机）。
按照以下说明手动配置你的 Linux 包安装。

利用云提供商的工具复制主数据库

假设你在 AWS EC2 上设置了一个使用 RDS 的主站点。现在你只需要在不同的区域创建一个只读副本，复制过程由 AWS 管理。请确保根据需要设置了网络 ACL（访问控制列表）、子网和安全组，以便从站点的 Rails 节点可以访问数据库。

以下说明详细介绍了如何为常见云提供商创建只读副本：

Amazon RDS - 创建只读副本
Azure Database for PostgreSQL - 在 Azure Database for PostgreSQL 中创建和管理只读副本
Google Cloud SQL - 创建只读副本

当你的只读副本设置完成后，你可以跳转到配置你的从站点使用外部只读副本。

配置从站点使用外部只读副本

对于 Linux 包安装， geo_secondary_role 有三个主要功能：

配置副本数据库。
配置跟踪数据库。
启用 Geo 日志游标。

要配置到外部只读副本数据库的连接：

SSH 连接到你从站点上的每个Rails、Sidekiq 和 Geo 日志游标节点，并以 root 身份登录：
```
sudo -i
```

编辑 /etc/gitlab/gitlab.rb 并添加以下内容：

##
## Geo 从站点角色
## - 自动配置相关标志以启用 Geo
##
roles ['geo_secondary_role']

# 注意这个密码在两个数据库之间是共享的，
# 确保你在两个数据库中定义相同的密码
gitlab_rails['db_password'] = '<your_db_password_here>'

gitlab_rails['db_username'] = 'gitlab'
gitlab_rails['db_host'] = '<database_read_replica_host>'

# 禁用捆绑的 Omnibus PostgreSQL，因为我们使用
# 外部 PostgreSQL
postgresql['enable'] = false

保存文件并重新配置 GitLab：
```
gitlab-ctl reconfigure
```

如果你在连接到副本数据库时遇到问题，可以使用以下命令从你的服务器检查 TCP 连接：

gitlab-rake gitlab:tcp_check[<replica FQDN>,5432]

如果此步骤失败，你可能使用了错误的 IP 地址，或者防火墙可能阻止了对站点的访问。检查 IP 地址，特别注意公共地址和私有地址之间的区别。如果存在防火墙，请确保从站点被允许连接到主站点的端口 5432。

手动复制 GitLab 密钥值

GitLab 在 /etc/gitlab/gitlab-secrets.json 中存储了许多密钥值。这个 JSON 文件在每个站点节点上必须相同。你必须手动复制这个密钥文件到所有从站点，尽管 issue 3789 提议改变这种行为。

SSH 连接到主站点上的一个 Rails 节点，并执行以下命令：
```
sudo cat /etc/gitlab/gitlab-secrets.json
```
这会显示你必须复制的密钥，以 JSON 格式。
SSH 连接到每个从 Geo 站点上的节点并以 root 身份登录：
```
sudo -i
```

备份任何现有的密钥：

mv /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.`date +%F`

将 /etc/gitlab/gitlab-secrets.json 从主站点 Rails 节点复制到每个从站点节点。你也可以在节点之间复制粘贴文件内容：
```
sudo editor /etc/gitlab/gitlab-secrets.json

# 粘贴你在主站点上运行 `cat` 命令的输出
# 保存并退出
```

确保文件权限正确：

chown root:root /etc/gitlab/gitlab-secrets.json
chmod 0600 /etc/gitlab/gitlab-secrets.json

应用更改，重新配置每个 Rails、Sidekiq 和 Gitaly 从站点节点：
```
gitlab-ctl reconfigure
gitlab-ctl restart
```

手动复制主站点 SSH 主机密钥

SSH 连接到每个从站点上的节点并以 root 身份登录：
```
sudo -i
```

备份任何现有的 SSH 主机密钥：

find /etc/ssh -iname 'ssh_host_*' -exec cp {} {}.backup.`date +%F` \;

从主站点复制 OpenSSH 主机密钥。

如果你能够以 root 身份访问其中一个处理 SSH 流量的主站点节点（通常是主要的 GitLab Rails 应用节点）：

# 从从站点运行此命令，将 `<primary_site_fqdn>` 更改为服务器的 IP 或 FQDN
scp root@<primary_node_fqdn>:/etc/ssh/ssh_host_*_key* /etc/ssh

如果你只有通过具有 sudo 权限的用户访问的权限：

# 在主站点节点上运行此命令：
sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz /etc/ssh/ssh_host_*_key*

# 在每个从站点节点上运行：
scp <user_with_sudo>@<primary_site_fqdn>:geo-host-key.tar.gz .
tar zxvf ~/geo-host-key.tar.gz -C /etc/ssh

对于每个从站点节点，确保文件权限正确：

chown root:root /etc/ssh/ssh_host_*_key*
chmod 0600 /etc/ssh/ssh_host_*_key

验证密钥指纹匹配，在每个站点的主节点和从节点上执行以下命令：

for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done

你应该得到类似于以下的输出：

SHA256:FEZX2jQa2bcsd/fn/uxBzxhKdx4Imc4raXrHwsbtP0M root@serverhostname (DSA)
SHA256:uw98R35Uf+fYEQ/UnJD9Br4NXUFPv7JAUln5uHlgSeY root@serverhostname (ECDSA)
SHA256:sqOUWcraZQKd89y/QQv/iynPTOGQxcOTIXU/LsoPmnM root@serverhostname (ED25519)
SHA256:qwa+rgir2Oy86QI+PZi/QVR+MSmrdrpsuH7YyKknC+s root@serverhostname (RSA)

输出在两个节点上应该完全相同。

验证你为现有私钥拥有正确的公钥：

# 这将打印私钥的指纹：
for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done

# 这将打印公钥的指纹：
for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done

公钥和私钥命令的输出应该生成相同的指纹。

对于每个从站点节点，重启 sshd：

# Debian 或 Ubuntu 安装
sudo service ssh reload

# CentOS 安装
sudo service sshd reload

验证 SSH 是否仍然正常工作，从新的终端 SSH 连接到你的 GitLab 从服务器。如果无法连接，请确保你拥有正确的权限。

快速查找授权 SSH 密钥

在初始复制过程完成后，按照步骤配置快速查找授权 SSH 密钥。

快速查找是 Geo 所需的。

身份验证由主站点处理。不要为从站点设置自定义身份验证。任何需要访问管理员区域的更改都应在主站点进行，因为从站点是只读副本。

添加从站点

SSH 连接到每个从站点上的 Rails 和 Sidekiq 节点并以 root 身份登录：
```
sudo -i
```

编辑 /etc/gitlab/gitlab.rb 并为你的站点添加一个唯一名称。

##
## Geo 站点的唯一标识符。请参阅
## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings
##
gitlab_rails['geo_node_name'] = '<secondary_site_name_here>'

保存此唯一名称以供后续步骤使用。

应用更改，重新配置每个从站点上的 Rails 和 Sidekiq 节点。
```
gitlab-ctl reconfigure
```
转到主节点 GitLab 实例：
1. 在左侧边栏底部，选择管理员。
2. 选择Geo > 站点。
3. 选择添加站点。
4. 在名称中，输入 /etc/gitlab/gitlab.rb 中 gitlab_rails['geo_node_name'] 的值。值必须完全匹配。
5. 在外部 URL中，输入 /etc/gitlab/gitlab.rb 中 external_url 的值。如果一个值以 / 结尾而另一个不结，这是可以的。否则，值必须完全匹配。
6. 可选。在**内部 URL（可选）**中，输入主站点的内部 URL。
7. 可选。选择应该由从站点复制的组或存储分片。要复制所有内容，请将字段留空。请参阅选择性同步。
8. 选择保存更改。
SSH 连接到每个从站点上的 Rails 和 Sidekiq 节点并重启服务：
```
sudo gitlab-ctl restart
```
通过运行以下命令检查你的 Geo 设置是否有常见问题：
```
sudo gitlab-rake gitlab:geo:check
```
如果任何检查失败，请参阅故障排除文档。
验证从站点是否可访问，SSH 连接到主站点上的 Rails 或 Sidekiq 服务器并运行：
```
sudo gitlab-rake gitlab:geo:check
```
如果任何检查失败，请检查故障排除文档。

将从站点添加到 Geo 管理页面并重启后，站点会自动开始从主站点复制缺失的数据，这个过程称为回填（backfill）。

同时，主站点开始通知每个从站点任何更改，以便从站点可以立即处理这些通知。

确保从站点正在运行且可访问。你可以使用与主站点相同的凭据登录从站点。

启用通过 HTTP/HTTPS 和 SSH 的 Git 访问

Geo 通过 HTTP/HTTPS 同步存储库（新安装默认启用），因此需要启用此克隆方法。如果你将现有站点转换为 Geo，你应该检查克隆方法是否已启用。

在主站点上：

在左侧边栏底部，选择管理员。
选择设置 > 常规。
展开可见性和访问控制。
如果你使用 Git over SSH：
1. 确保启用的 Git 访问协议设置为SSH 和 HTTP(S)。
2. 在主站点和从站点上启用数据库中授权 SSH 密钥的快速查找。
如果你不使用 Git over SSH，将启用的 Git 访问协议设置为仅 HTTP(S)。

验证从站点的正常运行

你可以使用与主站点相同的凭据登录从站点。

登录后：

在左侧边栏底部，选择管理员。
选择Geo > 站点。
验证站点是否正确标识为从 Geo 站点，并且 Geo 已启用。

初始复制可能需要一些时间。你可以在浏览器中从主站点的Geo 站点仪表板监控每个 Geo 站点的同步过程。

配置跟踪数据库

如果你还想在另一台服务器上外部设置跟踪数据库，此步骤是可选的。

从站点使用单独的 PostgreSQL 安装作为跟踪数据库，以跟踪复制状态并自动从潜在的复制问题中恢复。当设置 roles ['geo_secondary_role'] 时，Linux 包会自动配置跟踪数据库。如果你想将此数据库运行在 Linux 包安装之外，请使用以下说明。

云托管数据库服务

如果你使用云托管服务作为跟踪数据库，你可能需要为你的跟踪数据库用户（默认为 gitlab_geo）授予额外的角色：

Amazon RDS 需要 rds_superuser 角色。
Azure Database for PostgreSQL 需要 azure_pg_admin 角色。
Google Cloud SQL 需要 cloudsqlsuperuser 角色。

安装和升级期间需要额外的角色来安装扩展。作为替代方案，确保手动安装扩展，并了解在未来的 GitLab 升级中可能出现的问题。

如果你想使用 Amazon RDS 作为跟踪数据库，请确保它可以访问从数据库。不幸的是，仅分配相同的安全组是不够的，因为出站规则不适用于 RDS PostgreSQL 数据库。因此，你需要明确添加一个入站规则到只读副本的安全组，允许从跟踪数据库在端口 5432 上进行任何 TCP 流量。

创建跟踪数据库

在你的 PostgreSQL 实例中创建和配置跟踪数据库：

根据数据库要求文档设置 PostgreSQL。
设置一个 gitlab_geo 用户，选择密码，创建 gitlabhq_geo_production 数据库，并使该用户成为数据库的所有者。你可以在自编译安装文档中看到此设置的示例。
如果你不使用云托管的 PostgreSQL 数据库，确保你的从站点能够与你的跟踪数据库通信，通过手动更改与你的跟踪数据库关联的 pg_hba.conf。记得之后重启 PostgreSQL 以使更改生效：
```
##
## Geo 跟踪数据库角色
## - pg_hba.conf
##
host    all         all               <可信跟踪 IP>/32      md5
host    all         all               <可信从 IP>/32     md5
```

配置 GitLab

配置 GitLab 使用此数据库。这些步骤适用于 Linux 包和 Docker 部署。

SSH 连接到一个 GitLab 从服务器并以 root 身份登录：
```
sudo -i
```

编辑 /etc/gitlab/gitlab.rb，添加具有 PostgreSQL 实例的机器的连接参数和凭据：

geo_secondary['db_username'] = 'gitlab_geo'
geo_secondary['db_password'] = '<your_tracking_db_password_here>'

geo_secondary['db_host'] = '<tracking_database_host>'
geo_secondary['db_port'] = <tracking_database_port>      # 更改为正确的端口
geo_postgresql['enable'] = false     # 不使用内部管理的实例

保存文件并重新配置 GitLab：
```
gitlab-ctl reconfigure
```

手动设置数据库架构（可选）

前面列出的步骤中的重新配置命令会自动处理这些步骤。如果某些步骤出错，则提供这些步骤。

此任务创建数据库架构。它需要数据库用户是超级用户。
```
sudo gitlab-rake db:create:geo
```
应用 Rails 数据库迁移（架构和数据更新）也由重新配置执行。如果设置了 geo_secondary['auto_migrate'] = false，或者架构是手动创建的，则需要此步骤：
```
sudo gitlab-rake db:migrate:geo
```

故障排除

请参阅故障排除 Geo。