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

配置新的次要站点

层级：Premium, Ultimate
提供方式：GitLab 自托管

这是设置次要 Geo 站点的最后一步。必须按照文档顺序完成设置过程的各个阶段。如果没有，请在继续之前完成所有之前的阶段。

配置次要站点的的基本步骤如下：

在主要站点和次要站点之间复制所需的配置。
为每个次要站点配置跟踪数据库。
启动每个次要站点的 GitLab。

此文档聚焦于第一步。建议先通读所有步骤，再在测试/生产环境中执行。

主要站点和次要站点都需要满足的前提条件：

不要为次要站点设置任何自定义身份验证。这由主要站点处理。任何需要访问管理区域的更改都必须在主要站点中完成，因为次要站点是只读副本。

步骤 1. 手动复制 GitLab 的机密值

GitLab 将多个机密值存储在 /etc/gitlab/gitlab-secrets.json 文件中，这些值必须在站点的所有节点上相同。在找到自动在站点间复制这些值的方法之前（参见问题 #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`

将主要站点的 Rails 节点上的 /etc/gitlab/gitlab-secrets.json 复制到次要站点的每个节点，或在节点之间复制粘贴文件内容：
```
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
```

步骤 2. 手动复制主站点的 SSH 主机密钥

GitLab 集成了系统安装的 SSH 守护进程，指定一个用户（通常名为 git）来处理所有访问请求。

在灾难恢复场景中，GitLab 系统管理员会将次级站点提升为主站点。主域名的 DNS 记录也应更新以指向新的主站点（之前是次级站点）。这样做可以避免更新 Git 远程仓库和 API URL。

这会导致对新提升的主站点的所有 SSH 请求因 SSH 主机密钥不匹配而失败。为防止这种情况，必须手动将主 SSH 主机密钥复制到次级站点。

SSH 主机密钥的路径取决于所使用的软件：

如果使用 OpenSSH，路径是 /etc/ssh。
如果使用 gitlab-sshd，路径是 /var/opt/gitlab/gitlab-sshd。

在以下步骤中，将 <ssh_host_key_path> 替换为你正在使用的路径：

通过 SSH 连接到你次级站点的每个 Rails 节点，并以 root 用户登录：
```
sudo -i
```

备份现有的 SSH 主机密钥：

find <ssh_host_key_path> -iname 'ssh_host_*' -exec cp {} {}.backup.`date +%F` \;

从主站点复制 SSH 主机密钥：

如果你能够使用 root 用户访问主站点中某个提供 SSH 流量的节点（通常是主要的 GitLab Rails 应用程序节点）：

# 在次级站点运行此命令，将 `<primary_site_fqdn>` 替换为服务器的 IP 或 FQDN
scp root@<primary_node_fqdn>:<ssh_host_key_path>/ssh_host_*_key* <ssh_host_key_path>

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

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

# 在次级站点的每个节点上运行此命令：
scp <user_with_sudo>@<primary_site_fqdn>:geo-host-key.tar.gz .
tar zxvf ~/geo-host-key.tar.gz -C <ssh_host_key_path>

在次级站点的每个 Rails 节点上，确保文件权限正确：

chown root:root <ssh_host_key_path>/ssh_host_*_key*
chmod 0600 <ssh_host_key_path>/ssh_host_*_key

要验证密钥指纹是否匹配，在每个站点的所有主节点和次级节点上执行以下命令：

for file in <ssh_host_key_path>/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 <ssh_host_key_path>/ssh_host_*_key; do ssh-keygen -lf $file; done

# 此命令会打印公钥的指纹：
for file in <ssh_host_key_path>/ssh_host_*_key.pub; do ssh-keygen -lf $file; done

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

重启次级站点的每个 Rails 节上的 sshd（OpenSSH）或 gitlab-sshd 服务：

对于 OpenSSH：

# Debian 或 Ubuntu 安装
sudo service ssh reload

# CentOS 安装
sudo service sshd reload

对于 gitlab-sshd：
```
sudo gitlab-ctl restart gitlab-sshd
```

验证 SSH 仍可正常工作。

在新终端中通过 SSH 连接到你的 GitLab 次级服务器。如果无法连接，请根据之前的步骤检查权限是否正确。

步骤 3. 添加次要站点

通过 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'] = '<site_name_here>'

对次要站点的每个 Rails 和 Sidekiq 节点重新配置，使更改生效：
```
gitlab-ctl reconfigure
```
前往主节点的 GitLab 实例：
1. 在左侧边栏底部，选择 Admin。
2. 在左侧边栏中，选择 Geo > Sites。
3. 选择 Add site。
4. 在 Name 中，输入 /etc/gitlab/gitlab.rb 中 gitlab_rails['geo_node_name'] 的值。这些值必须始终完全一致，字符对字符。
5. 在 External URL 中，输入 /etc/gitlab/gitlab.rb 中 external_url 的值。这些值必须始终匹配，但如果其中一个以 / 结尾而另一个不以 / 结尾也没关系。
6. 可选。在 Internal URL (optional) 中，输入次要站点的内部 URL。
7. 可选。选择应由次要站点复制的组或存储分片。留空则以复制全部。更多信息请参阅选择性同步。
8. 选择 Save changes 以添加次要站点。
通过 SSH 登录到次要站点的每个 Rails 和 Sidekiq 节点，并重启服务：
```
gitlab-ctl restart
```
运行以下命令检查 Geo 设置是否存在常见问题：
```
gitlab-rake gitlab:geo:check
```
如果任何检查失败，请查看故障排除文档。
通过 SSH 登录到主站点的 Rails 或 Sidekiq 服务器，并以 root 身份登录，以验证次要站点是否可达或 Geo 设置是否存在常见问题：
```
gitlab-rake gitlab:geo:check
```
如果任何检查失败，请查看故障排除文档。

在次要站点被添加到 Geo 管理页面并重启后，该站点会自动开始通过一种称为回填的过程，从主要站点复制缺失的数据。同时，主要站点开始向每个次要站点通知任何变更，以便次要站点能立即对这些通知采取行动。

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

步骤 4. (可选) 使用自定义证书

如果满足以下条件，您可以安全地跳过此步骤：

您的主要站点使用了由公共 CA 颁发的 HTTPS 证书。
您的主要站点仅使用由 CA 颁发（而非自签名）的 HTTPS 证书连接外部服务。

入站连接的自定义或自签名证书

如果您的 GitLab Geo 主要站点使用自定义或自签名证书来保护入站 HTTPS 连接，这可以是单域或多域证书。

根据证书类型安装正确的证书：

包含主要和次要站点域名的多域证书：在次要站点的所有 Rails、Sidekiq 和 Gitaly 节点上，将证书安装在 /etc/gitlab/ssl。
证书特定于每个 Geo 站点域名的单域证书：为您的次要站点域名生成有效证书，并按照这些说明将其安装在次要站点的所有 Rails、Sidekiq 和 Gitaly 节点的 /etc/gitlab/ssl。

连接使用自定义证书的外部服务

外部服务的自签名证书副本需要添加到所有需要访问该服务的主站点节点的信任存储中。

为了让次级站点能访问相同的外部服务，这些证书必须添加到次级站点的信任存储中。

若您的主站点正在使用用于入站HTTPS连接的自定义或自签名证书，则主站点的证书需添加到次级站点的信任存储中：

通过SSH进入次级站点的每个Rails、Sidekiq和Gitaly节点，并以root身份登录：
```
sudo -i
```

从主站点复制受信任的证书：若您能用root用户访问主站点上提供SSH流量的某节点：

scp root@<primary_site_node_fqdn>:/etc/gitlab/trusted-certs/* /etc/gitlab/trusted-certs

若您只能通过有sudo权限的用户访问：

# 在主站点的节点上执行此命令：
sudo tar --transform 's/.*\///g' -zcvf ~/geo-trusted-certs.tar.gz /etc/gitlab/trusted-certs/*

# 在次级站点的每个节点上执行此命令：
scp <user_with_sudo>@<primary_site_node_fqdn>:geo-trusted-certs.tar.gz .
tar zxvf ~/geo-trusted-certs.tar.gz -C /etc/gitlab/trusted-certs

重新配置次级站点中每个已更新的Rails、Sidekiq和Gitaly节点：
```
sudo gitlab-ctl reconfigure
```

第5步：启用HTTP/HTTPS和SSH上的Git访问

Geo通过HTTP/HTTPS同步仓库，因此需启用此克隆方式。默认已开启，但若将现有站点转为Geo，需检查：

在主站点上：

左侧边栏底部选择Admin。
选择Settings > General。
展开可见性与访问控制。
若使用Git over SSH，则：
1. 确保将“Enabled Git access protocols”（启用的Git访问协议）设为“Both SSH and HTTP(S)”（同时启用SSH和HTTP(S)）。
2. 遵循步骤配置数据库中授权SSH密钥的快速查找于所有主站点和次级站点。
若未使用Git over SSH，则将“Enabled Git access protocols”设为“Only HTTP(S)”（仅HTTP(S)）。

第6步：验证次级站点的正常运行

可用与主站点相同的凭据登录次级站点。登录后：

左侧边栏底部选择Admin。
选择Geo > Sites。
验证其是否被正确识别为次级Geo站点且Geo已启用。

初始复制可能耗时较长。站点状态或“回填”（backfill）可能仍在进行。可在浏览器中通过主站点的Geo Sites仪表板监控各Geo站点的同步进程。

若安装无法正常工作，请查阅故障排除文档。

仪表板中最明显的问题通常是：

数据库复制未良好运行。
实例间通知失效。此时可能是以下原因：
- 使用了自定义证书或CA（见故障排除文档）。
- 实例被防火墙拦截（检查防火墙规则）。

禁用次级站点会停止同步进程。

若主站点对多仓库分片定制了存储配置，需在每个次级站点复刻相同配置。

引导用户参考使用Geo站点指南。

当前同步内容包括：

Git仓库
Wiki
LFS对象
问题、合并请求、片段及评论附件
用户、群组与项目头像

故障排除

请参阅故障排除文档。