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

设置 Geo for Linux 软件包 (Omnibus)
配置跟踪数据库
故障排除

Tier: 专业版, 旗舰版
Offering: 私有化部署

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

先决条件：

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

设置 Geo for Linux 软件包 (Omnibus)

先决条件：

您使用 PostgreSQL 12 或更高版本，包括 pg_basebackup 工具。

配置主站

SSH 到您的极狐 GitLab 主站并以 root 身份登录：
```
sudo -i
```

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

##
## Geo 站点的唯一标识符。参见
## https://gitlab.cn/docs/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 中创建和管理只读副本

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

配置次站以使用外部只读副本

使用 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 文件必须在每个站点节点之间相同。您必须手动复制密钥文件到所有次站。

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://gitlab.cn/docs/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 管理页面并重启后，站点会自动开始从主站复制缺失数据，这个过程称为回填。

同时，主站开始通知每个次站任何变化，以便次站可以立即处理通知。

确保次站正在运行并可访问。您可以使用与主站相同的凭据登录到次站。

启用通过 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 角色。

安装和升级期间需要额外的角色来安装扩展。作为替代方案，确保扩展手动安装，并阅读在未来极狐 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               <trusted tracking IP>/32      md5
host    all         all               <trusted secondary 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。