Gitaly Cluster

Gitaly Cluster
Gitaly Cluster

Gitaly Cluster

原文：https://docs.gitlab.com/ee/administration/gitaly/praefect.html

Requirements for configuring a Gitaly Cluster
Setup Instructions
Enabling TLS support
Distributed reads
Automatic failover and leader election
Primary Node Failure
Backend Node Recovery
Migrating existing repositories to Praefect
Debugging Praefect

Gitaly Cluster

Gitaly （为 Git 存储库提供存储的服务）可以在群集配置中运行，以提高容错能力. 在这种配置中，每个 Git 存储库都存储在集群中的每个 Gitaly 节点上. 可以配置多个集群（或分片）.

注意：可以使用GitLab Core和更高层来创建 Gitaly 群集. 但是，技术支持仅限于 GitLab Premium 和 Ultimate 客户. 在 GitLab.com 中不可用.

Praefect 是 Gitaly 的路由器和事务管理器，并且是运行 Gitaly 集群的必需组件.

使用 Gitaly 群集可通过以下方式提高容错能力：

复制写操作以预热备用 Gitaly 节点.
检测 Gitaly 节点故障.
自动将 Git 请求路由到可用的 Gitaly 节点.

Gitaly 群集的可用性目标是：

恢复点目标（RPO）：不到 1 分钟.

写入异步复制. 尚未复制到新提升的主数据库的所有写入都将丢失.

计划实现高度一致性，以将其改进为”无损失”.
恢复时间目标（RTO）：少于 10 秒.

每秒通过每个 Praefect 节点运行的运行状况检查来检测中断. 故障转移要求每个 Praefect 节点上连续十次失败的运行状况检查.

计划进行更快的中断检测，以将其缩短到不到 1 秒.

当前版本支持：

辅助副本的最终一致性.
Automatic failover from the primary to the secondary.
如果复制队列不为空，则报告可能的数据丢失.
仅当检测到可能的数据丢失时，才将新升级的主要读标记为标记.

遵循HA Gitaly 史诗进行的改进，包括横向分发读取 .

Requirements for configuring a Gitaly Cluster

建议的 Gitaly 群集最低配置要求：

1 个负载均衡器
1 个 PostgreSQL 服务器（PostgreSQL 11 或更高版本）
节点长官 3
3 个 Gitaly 节点（1 个主要节点，2 个辅助节点）

有关实现的详细信息，请参见设计文档 .

Setup Instructions

如果使用 Omnibus 软件包安装了 GitLab（强烈建议），请按照以下步骤操作：

Preparation
Configuring the Praefect database
Configuring the Praefect proxy/router
配置每个 Gitaly 节点（每个 Gitaly 节点一次）
Configure the load balancer
Updating the GitLab server configuration
Configure Grafana

Preparation

在开始之前，您应该已经有一个正常的 GitLab 实例. 了解如何安装 GitLab .

设置 PostgreSQL 服务器（PostgreSQL 11 或更高版本）. 尚不支持通过 Omnibus GitLab 发行版进行配置. 请关注此问题以进行更新.

通过安装 GitLab准备所有新节点.

1 个 Praefect 节点（需要最少的存储）
3 个 Gitaly 节点（高 CPU，高内存，快速存储）
1 个 GitLab 服务器

您将需要每个节点的 IP /主机地址.

LOAD_BALANCER_SERVER_ADDRESS ：负载均衡器的 IP /主机地址
POSTGRESQL_SERVER_ADDRESS ：PostgreSQL 服务器的 IP /主机地址
PRAEFECT_HOST ：Praefect 服务器的 IP /主机地址
GITALY_HOST ：每个 Gitaly 服务器的 IP /主机地址
GITLAB_HOST ：GitLab 服务器的 IP /主机地址

如果使用的是云提供商，则可以通过云提供商的管理控制台查找每个服务器的地址.

如果您使用的是 Google Cloud Platform，SoftLayer 或提供虚拟私有云（VPC）的任何其他供应商，则可以将每个云实例的私有地址（对应于 Google Cloud Platform 的”内部地址”）用于PRAEFECT_HOST ， GITALY_HOST ，和GITLAB_HOST .

Secrets

组件之间的通信由不同的秘密保护，下面将对此进行描述. 在开始之前，请为每个密钥生成一个唯一的秘密，并记录下来. 在完成设置过程时，这将很容易用安全令牌替换这些占位符令牌.

GITLAB_SHELL_SECRET_TOKEN ：当接受 Git 推送时，Git 挂钩将其用于向 GitLab 发出回调 HTTP API 请求. 出于遗留原因，此秘密已与 GitLab Shell 共享.
PRAEFECT_EXTERNAL_TOKEN ：承载此令牌的 Gitaly 客户端只能访问 Praefect 群集上托管的存储库.
PRAEFECT_INTERNAL_TOKEN ：此令牌用于 Praefect 群集内的复制流量. 这与PRAEFECT_EXTERNAL_TOKEN不同，因为 Gitaly 客户端必须不能直接访问 Praefect 群集的内部节点. 可能导致数据丢失.
PRAEFECT_SQL_PASSWORD ：Praefect 使用此密码连接到 PostgreSQL.

我们将在以下说明中指出需要这些秘密的地方.

PostgreSQL

注意：如果使用Geo，请勿将 GitLab 应用程序数据库和 Praefect 数据库存储在同一 PostgreSQL 服务器上. 复制状态是每个 GitLab 实例的内部状态，不应复制.

要完成本节，您将需要：

完美节点 1
1 个 PostgreSQL 服务器（PostgreSQL 11 或更高版本）
- 具有创建数据库权限的 SQL 用户

在本节中，我们将使用 Omnibus GitLab 安装的psql从 Praefect 节点配置 PostgreSQL 服务器.

SSH 进入Praefect节点并以 root 用户身份登录：
```
sudo -i
```
以管理员权限连接到 PostgreSQL 服务器. 这可能是postgres用户. 使用数据库template1是因为它默认在所有 PostgreSQL 服务器上创建.
```
/opt/gitlab/embedded/bin/psql -U postgres -d template1 -h POSTGRESQL_SERVER_ADDRESS
```
创建一个将由 Praefect 使用的新用户praefect . 将PRAEFECT_SQL_PASSWORD替换为您在准备步骤中生成的强密码.
```
CREATE ROLE praefect WITH LOGIN CREATEDB PASSWORD 'PRAEFECT_SQL_PASSWORD';
```
这次以praefect用户身份重新连接到 PostgreSQL 服务器：
```
/opt/gitlab/embedded/bin/psql -U praefect -d template1 -h POSTGRESQL_SERVER_ADDRESS
```
创建一个新的数据库praefect_production . 通过同时连接为创建数据库praefect的用户，我们有信心，他们有机会.
```
CREATE DATABASE praefect_production WITH ENCODING=UTF8;
```

现在已配置 Praefect 使用的数据库.

Praefect

要完成本节，您将需要：

配置的 PostgreSQL 服务器，包括：
- IP /主机地址（ POSTGRESQL_SERVER_ADDRESS ）
- 密码（ PRAEFECT_SQL_PASSWORD ）

Praefect 应该在专用节点上运行. 不要在应用程序服务器或 Gitaly 节点上运行 Praefect.

SSH 进入Praefect节点并以 root 用户身份登录：
```
sudo -i
```

通过编辑/etc/gitlab/gitlab.rb禁用所有其他服务：

# Disable all other services on the Praefect node
postgresql['enable'] = false
redis['enable'] = false
nginx['enable'] = false
prometheus['enable'] = false
grafana['enable'] = false
puma['enable'] = false
sidekiq['enable'] = false
gitlab_workhorse['enable'] = false
gitaly['enable'] = false
# Enable only the Praefect service
praefect['enable'] = true
# Prevent database connections during 'gitlab-ctl reconfigure'
gitlab_rails['rake_cache_clear'] = false
gitlab_rails['auto_migrate'] = false

通过编辑/etc/gitlab/gitlab.rb Praefect配置为侦听网络接口：

praefect['listen_addr'] = '0.0.0.0:2305'
# Enable Prometheus metrics access to Praefect. You must use firewalls
# to restrict access to this address/port.
praefect['prometheus_listen_addr'] = '0.0.0.0:9652'

配置强劲auth_token通过编辑提督 /etc/gitlab/gitlab.rb . 群集外部的客户端（如 GitLab Shell）将需要与 Praefect 群集进行通信：
```
praefect['auth_token'] = 'PRAEFECT_EXTERNAL_TOKEN'
```

通过编辑/etc/gitlab/gitlab.rb将Praefect配置为连接到 PostgreSQL 数据库.

您将需要用数据库的 IP /主机地址替换POSTGRESQL_SERVER_ADDRESS ，并用上面设置的强密码PRAEFECT_SQL_PASSWORD .

praefect['database_host'] = 'POSTGRESQL_SERVER_ADDRESS'
praefect['database_port'] = 5432
praefect['database_user'] = 'praefect'
praefect['database_password'] = 'PRAEFECT_SQL_PASSWORD'
praefect['database_dbname'] = 'praefect_production'

如果要使用 TLS 客户端证书，则可以使用以下选项：

# Connect to PostreSQL using a TLS client certificate
# praefect['database_sslcert'] = '/path/to/client-cert'
# praefect['database_sslkey'] = '/path/to/client-key'
# Trust a custom certificate authority
# praefect['database_sslrootcert'] = '/path/to/rootcert'

默认情况下，Praefect 将拒绝与 PostgreSQL 建立未加密的连接. 您可以通过取消注释以下行来覆盖它：

# praefect['database_sslmode'] = 'disable'

通过编辑/etc/gitlab/gitlab.rb将Praefect群集配置为连接到群集中的每个 Gitaly 节点.

虚拟存储的名称必须与 GitLab 配置中配置的存储名称匹配. 在随后的步骤中，我们将存储名称配置为default名称，因此我们也在此处使用default名称. 该集群具有三个 Gitaly 节点gitaly-1 ， gitaly-2和gitaly-3 ，它们将是彼此的副本.

注意：如果您已经在名为default现有存储上存储了数据，则应使用其他名称配置虚拟存储，然后将数据迁移到 Praefect 存储 .

将PRAEFECT_INTERNAL_TOKEN替换为一个强秘密，Praefect 将在与集群中的 Gitaly 节点通信时使用此秘密. 此令牌与PRAEFECT_EXTERNAL_TOKEN .

将GITALY_HOST替换为每个 Gitaly 节点的 IP /主机地址.

可以将更多 Gitaly 节点添加到群集以增加副本数. 还可以为大型 GitLab 实例添加更多集群.

注意： gitaly-1节点当前称为主要节点. 这可用于从一个节点到另一个节点的手动故障. 这将在被删除的未来 .
```
# Name of storage hash must match storage name in git_data_dirs on GitLab
# server ('praefect') and in git_data_dirs on Gitaly nodes ('gitaly-1')
praefect['virtual_storages'] = {
  'default' => {
    'gitaly-1' => {
      'address' => 'tcp://GITALY_HOST:8075',
      'token'   => 'PRAEFECT_INTERNAL_TOKEN',
      'primary' => true
    },
    'gitaly-2' => {
      'address' => 'tcp://GITALY_HOST:8075',
      'token'   => 'PRAEFECT_INTERNAL_TOKEN'
    },
    'gitaly-3' => {
      'address' => 'tcp://GITALY_HOST:8075',
      'token'   => 'PRAEFECT_INTERNAL_TOKEN'
    }
  }
}
```
在 GitLab 13.1 和更高版本中引入，启用了 read 的分发 .
将更改保存到/etc/gitlab/gitlab.rb并重新配置 Praefect ：
```
gitlab-ctl reconfigure
```
为了确保 Praefect 已更新其 Prometheus 监听地址，请重新启动 Gitaly ：
```
gitlab-ctl restart praefect
```
验证 Praefect 可以到达 PostgreSQL：
```
sudo -u git /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-ping
```
如果检查失败，请确保已正确执行了步骤. 如果您编辑/etc/gitlab/gitlab.rb ，请记住在尝试sql-ping命令之前再次运行sudo gitlab-ctl reconfigure .

必须为每个 Praefect 节点完成上述步骤！

Enabling TLS support

在 GitLab 13.2 中引入 .

Praefect 支持 TLS 加密. 要与侦听安全连接的 Praefect 实例进行通信，您必须：

在 GitLab 配置中相应存储条目的gitaly_address中使用tls:// URL 方案.
带上您自己的证书，因为这不会自动提供. 与每个 Praefect 服务器相对应的证书必须安装在该 Praefect 服务器上.

此外，必须按照GitLab 自定义证书配置中所述的过程（并在下面重复），将证书或其证书颁发机构安装在所有 Gitaly 服务器和与其通信的所有 Praefect 客户端上.

请注意以下几点：

证书必须指定用于访问 Praefect 服务器的地址. 如果通过以下方式寻址 Praefect 服务器：
- 主机名，您可以为此使用”公用名”字段，也可以将其添加为”使用者备用名”.
- IP 地址，您必须将其添加为证书的使用者备用名称.
您可以同时为 Praefect 服务器配置未加密的侦听地址listen_addr和已加密的侦听地址tls_listen_addr . 如果需要，这使您可以从未加密的流量逐渐过渡到加密的流量.

要使用 TLS 配置 Praefect：

对于所有 GitLab

Prefect 为服务器创建证书.

在 Praefect 服务器上，创建/etc/gitlab/ssl目录，然后在其中复制密钥和证书：

sudo mkdir -p /etc/gitlab/ssl
sudo chmod 755 /etc/gitlab/ssl
sudo cp key.pem cert.pem /etc/gitlab/ssl/
sudo chmod 644 key.pem cert.pem

编辑/etc/gitlab/gitlab.rb并添加：

praefect['tls_listen_addr'] = "0.0.0.0:3305"
praefect['certificate_path'] = "/etc/gitlab/ssl/cert.pem"
praefect['key_path'] = "/etc/gitlab/ssl/key.pem"

保存文件并重新配置 GitLab .
在 Praefect 客户端（包括每个 Gitaly 服务器）上，将证书或其证书颁发机构复制到/etc/gitlab/trusted-certs ：
```
sudo cp cert.pem /etc/gitlab/trusted-certs/
```

在 Praefect 客户端（Gitaly 服务器除外）上，在/etc/gitlab/gitlab.rb编辑git_data_dirs ，如下所示：

git_data_dirs({
  'default' => { 'gitaly_address' => 'tls://praefect1.internal:3305' },
  'storage1' => { 'gitaly_address' => 'tls://praefect2.internal:3305' },
})

保存文件并重新配置 GitLab .

对于源安装

Prefect 为服务器创建证书.

在 Praefect 服务器上，创建/etc/gitlab/ssl目录，然后在其中复制密钥和证书：

sudo mkdir -p /etc/gitlab/ssl
sudo chmod 755 /etc/gitlab/ssl
sudo cp key.pem cert.pem /etc/gitlab/ssl/
sudo chmod 644 key.pem cert.pem

在 Praefect 客户端（包括每个 Gitaly 服务器）上，将证书或其证书颁发机构复制到系统信任的证书中：
```
sudo cp cert.pem /usr/local/share/ca-certificates/praefect.crt
sudo update-ca-certificates
```

在 Praefect 客户端（Gitaly 服务器除外）上，按如下所示编辑/home/git/gitlab/config/gitlab.yml storages ：

gitlab:
  repositories:
    storages:
      default:
        gitaly_address: tls://praefect1.internal:3305
        path: /some/dummy/path
      storage1:
        gitaly_address: tls://praefect2.internal:3305
        path: /some/dummy/path

注意： /some/dummy/path应该设置为存在的本地文件夹，但是该文件夹中不会存储任何数据. 解决此问题后，将不再需要此操作 .

保存文件并重新启动 GitLab .
将所有 Praefect 服务器证书或其证书颁发机构复制到每台 Gitaly 服务器上的系统受信任证书，以便 Praefect 服务器在被 Gitaly 服务器调用时将信任该证书：
```
sudo cp cert.pem /usr/local/share/ca-certificates/praefect.crt
sudo update-ca-certificates
```

编辑/home/git/praefect/config.toml并添加：

tls_listen_addr = '0.0.0.0:3305'
[tls]
certificate_path = '/etc/gitlab/ssl/cert.pem'
key_path = '/etc/gitlab/ssl/key.pem'

保存文件并重新启动 GitLab .

Gitaly

注意：为每个 Gitaly 节点完成这些步骤.

要完成本节，您将需要：

Configured Praefect node
将 3 个（或更多）安装了 GitLab 的服务器配置为 Gitaly 节点. 这些应该是专用节点，不要在这些节点上运行其他服务.

分配给 Praefect 群集的每个 Gitaly 服务器都需要配置. 该配置与普通的独立 Gitaly 服务器相同，除了：

存储名称公开给 Praefect，而不是 GitLab
秘密令牌是与 Praefect 共享的，而不是与 GitLab 共享的

Praefect 群集中所有 Gitaly 节点的配置可以相同，因为我们依靠 Praefect 正确地路由操作.

应特别注意：

本节中配置的gitaly['auth_token']必须与 Praefect 节点上praefect['virtual_storages']下的token值匹配. 这是在上一节中设置的. 本文档始终使用占位符PRAEFECT_INTERNAL_TOKEN .
本节中配置的git_data_dirs中的存储名称必须与 Praefect 节点上praefect['virtual_storages']下的存储名称匹配. 这是在上一节中设置的. 本文档使用gitaly-1 ， gitaly-2和gitaly-3作为 Gitaly 存储名称.

有关 Gitaly 服务器配置的更多信息，请参阅我们的Gitaly 文档 .

SSH 进入Gitaly节点并以 root 用户身份登录：
```
sudo -i
```

Disable all other services by editing /etc/gitlab/gitlab.rb:

# Disable all other services on the Praefect node
postgresql['enable'] = false
redis['enable'] = false
nginx['enable'] = false
grafana['enable'] = false
puma['enable'] = false
sidekiq['enable'] = false
gitlab_workhorse['enable'] = false
prometheus_monitoring['enable'] = false
# Enable only the Gitaly service
gitaly['enable'] = true
# Enable Prometheus if needed
prometheus['enable'] = true
# Prevent database connections during 'gitlab-ctl reconfigure'
gitlab_rails['rake_cache_clear'] = false
gitlab_rails['auto_migrate'] = false

配置Gitaly通过编辑来听网络接口/etc/gitlab/gitlab.rb ：

# Make Gitaly accept connections on all network interfaces.
# Use firewalls to restrict access to this address/port.
gitaly['listen_addr'] = '0.0.0.0:8075'
# Enable Prometheus metrics access to Gitaly. You must use firewalls
# to restrict access to this address/port.
gitaly['prometheus_listen_addr'] = '0.0.0.0:9236'

配置强劲auth_token通过编辑Gitaly /etc/gitlab/gitlab.rb . 客户端将需要与该 Gitaly 节点进行通信. 通常，此令牌对于所有 Gitaly 节点都是相同的.
```
gitaly['auth_token'] = 'PRAEFECT_INTERNAL_TOKEN'
```

配置git push操作所需的 GitLab Shell secret_token和internal_api_url .

如果您已经在自己的服务器上配置了Gitaly

gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN'
# Configure the gitlab-shell API callback URL. Without this, `git push` will
# fail. This can be your front door GitLab URL or an internal load balancer.
# Examples: 'https://example.gitlab.com', 'http://1.2.3.4'
gitlab_rails['internal_api_url'] = 'http://GITLAB_HOST'

通过在/etc/gitlab/gitlab.rb设置git_data_dirs来配置 Git 数据的存储位置. 每个 Gitaly 节点应具有唯一的存储名称（例如gitaly-1 ）.

与其为每个 Gitaly 节点唯一地配置git_data_dirs将每个 Gitaly 节点上所有 Gitaly 节点的配置都包括在内通常会更容易. 由于 Praefect virtual_storages配置将每个存储名称（例如gitaly-1 ）映射到特定节点，并且相应地路由了请求，因此支持此操作. 这意味着舰队中的每个 Gitaly 节点都可以共享相同的配置.
```
# You can include the data dirs for all nodes in the same config, because
# Praefect will only route requests according to the addresses provided in the
# prior step.
git_data_dirs({
  "gitaly-1" => {
    "path" => "/var/opt/gitlab/git-data"
  },
  "gitaly-2" => {
    "path" => "/var/opt/gitlab/git-data"
  },
  "gitaly-3" => {
    "path" => "/var/opt/gitlab/git-data"
  }
})
```
将更改保存到/etc/gitlab/gitlab.rb并重新配置 Gitaly ：
```
gitlab-ctl reconfigure
```
为了确保 Gitaly 更新了其 Prometheus 监听地址，请重新启动 Gitaly ：
```
gitlab-ctl restart gitaly
```

必须对每个 Gitaly 节点完成上述步骤！

配置完所有 Gitaly 节点后，您可以运行 Praefect 连接检查器以验证 Praefect 可以连接到 Praefect 配置中的所有 Gitaly 服务器.

SSH into the Praefect node and run the Praefect connection checker:

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dial-nodes

Load Balancer

在高可用的 Gitaly 配置中，需要一个负载平衡器来将内部流量从 GitLab 应用程序路由到 Praefect 节点. 有关使用负载均衡器或进行确切配置的细节超出了 GitLab 文档的范围.

我们希望，如果您要管理像 GitLab 这样的 HA 系统，那么您已经选择了负载均衡器. 一些示例包括HAProxy （开源）， Google 内部负载均衡器， AWS Elastic 负载均衡器，F5 Big-IP LTM 和 Citrix Net Scaler. 本文档将概述您需要配置哪些端口和协议.

LB 端口	后端端口	Protocol
2305	2305	TCP

GitLab

要完成本节，您将需要：

Configured Praefect node
Configured Gitaly nodes

Praefect 集群需要作为存储位置公开给 GitLab 应用程序. 这是通过更新git_data_dirs完成的.

应特别注意：

本节中添加到git_data_dirs的存储名称必须与 Praefect 节点上praefect['virtual_storages']下的存储名称匹配. 这是在本指南的Praefect部分中设置的. 本文档使用storage-1作为 Praefect 存储名称.

SSH 进入GitLab节点并以 root 身份登录：
```
sudo -i
```
配置external_url以便可以通过编辑/etc/gitlab/gitlab.rb通过适当的端点访问/etc/gitlab/gitlab.rb GitLab 提供文件：

您需要将GITLAB_SERVER_URL替换为当前 GitLab 实例所服务的实际外部 URL：
```
external_url 'GITLAB_SERVER_URL'
```
禁用在 GitLab 主机上运行的默认 Gitaly 服务. 不需要它，因为 GitLab 将连接到配置的集群.

注意如果现有数据存储在默认的 Gitaly 存储中，则应首先迁移 Praefect 存储中的数据 .
```
gitaly['enable'] = false
```
通过编辑/etc/gitlab/gitlab.rb将 Praefect 集群添加为存储位置.

您将需要更换：
- 带有负载均衡器的 IP 地址或主机名的LOAD_BALANCER_SERVER_ADDRESS .
- PRAEFECT_EXTERNAL_TOKEN带有真正的秘密
```
git_data_dirs({
  "default" => {
    "gitaly_address" => "tcp://LOAD_BALANCER_SERVER_ADDRESS:2305",
    "gitaly_token" => 'PRAEFECT_EXTERNAL_TOKEN'
  }
})
```
配置gitlab_shell['secret_token']以便通过编辑/etc/gitlab/gitlab.rb正确验证git push期间来自 Gitaly 节点的回调：

您将需要用真实的机密替换GITLAB_SHELL_SECRET_TOKEN .
```
gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN'
```

通过编辑/etc/gitlab/gitlab.rb添加 Prometheus 监视设置.

您将需要更换：

PRAEFECT_HOST带有 Praefect 节点的 IP 地址或主机名
GITALY_HOST ，每个 Gitaly 节点的 IP 地址或主机名

prometheus['scrape_configs'] = [
  {
    'job_name' => 'praefect',
    'static_configs' => [
      'targets' => [
        'PRAEFECT_HOST:9652', # praefect-1
        'PRAEFECT_HOST:9652', # praefect-2
        'PRAEFECT_HOST:9652', # praefect-3
      ]
    ]
  },
  {
    'job_name' => 'praefect-gitaly',
    'static_configs' => [
      'targets' => [
        'GITALY_HOST:9236', # gitaly-1
        'GITALY_HOST:9236', # gitaly-2
        'GITALY_HOST:9236', # gitaly-3
      ]
    ]
  }
]

将更改保存到/etc/gitlab/gitlab.rb并重新配置 GitLab ：
```
gitlab-ctl reconfigure
```

验证每个gitlab-shell实例上的每个gitlab-shell都可以到达 GitLab. 在每个 Gitaly 实例上运行：

/opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml

验证 GitLab 是否可以达到 Praefect：
```
gitlab-rake gitlab:gitaly:check
```
在管理区域>设置>存储库>存储库中检查 Praefect 存储已配置为存储新存储库. 按照本指南， default存储应具有权重 100 以存储所有新存储库.
通过创建一个新项目来验证一切正常. 选中”使用自述文件初始化存储库”框，以使存储库中包含已查看的内容. 如果项目已创建，并且您可以看到 README 文件，那么它将起作用！

Grafana

Grafana 包含在 GitLab 中，可用于监视您的 Praefect 集群. 有关详细文档，请参见Grafana 仪表板服务 .

快速入门：

SSH into the GitLab node and login as root:
```
sudo -i
```
通过编辑/etc/gitlab/gitlab.rb启用 Grafana 登录表单.
```
grafana['disable_login_form'] = false
```
将更改保存到/etc/gitlab/gitlab.rb并重新配置 GitLab ：
```
gitlab-ctl reconfigure
```
设置 Grafana 管理员密码. 此命令将提示您输入新密码：
```
gitlab-ctl set-grafana-password
```
在您的 Web 浏览器中，在您的 GitLab 服务器上打开/-/grafana （例如https://gitlab.example.com/-/grafana ）.

使用您设置的密码和用户名admin登录.
转到浏览并查询gitlab_build_info以验证您是否正在从所有计算机中获取指标.

恭喜你！您已经配置了可观察的高可用性 Praefect 集群.

Distributed reads

在beta 版本的 GitLab 13.1 中引入，功能标志gitaly_distributed_reads设置为禁用.

Praefect supports distribution of read operations across Gitaly nodes that are configured for the virtual node.

为了进行性能测试，分布式读取当前处于beta 状态，默认情况下处于禁用状态. 要启用分布式读取，必须在 Ruby 控制台中启用gitaly_distributed_reads 功能标志：

Feature.enable(:gitaly_distributed_reads)

如果启用，则所有带有ACCESSOR选项（如GetBlob）的 RPC 都将重定向到最新且运行状况良好的 Gitaly 节点.

在这种情况下，最新意味着：

没有为此节点安排任何复制操作.
最后的复制操作处于完成状态.

如果没有这样的节点，或者在选择节点期间发生任何其他错误，那么将选择主节点来处理请求.

要跟踪读取操作的分布，可以使用gitaly_praefect_read_distribution Prometheus 计数器度量. 它有两个标签：

virtual_storage.
storage.

它们反映了为此 Praefect 实例定义的配置.

Automatic failover and leader election

Praefect 会定期检查每个后端 Gitaly 节点的运行状况. 如果发现当前主节点运行状况不佳，此信息可用于自动故障转移到新的主节点.

PostgreSQL（推荐）：默认启用，等效于： praefect['failover_election_strategy'] = sql . 此配置选项将允许多个 Praefect 节点通过 PostgreSQL 数据库进行协调，以选择一个主要的 Gitaly 节点. 如果大多数 Praefect 节点在 10 秒内仍无法访问当前主节点，此配置将导致 Praefect 节点选择一个新的主节点，监视其运行状况，并选择一个新的主节点.
手动：禁用自动故障转移. 可以在 Praefect 节点上的/etc/gitlab/gitlab.rb重新配置主节点. 通过将primary = true移至另一个 Gitaly 节点，将其修改为praefect['virtual_storages']字段. 在上述步骤中，将gitaly-1设置为主数据库. 在配置中需要praefect['failover_enabled'] = false .
内存：通过在 Praefect 节点上的/etc/gitlab/gitlab.rb设置praefect['failover_election_strategy'] = 'local' /etc/gitlab/gitlab.rb . 如果对于当前的主后端 Gitaly 节点，足够数量的运行状况检查失败，则将选择新的主节点. 不要与多个 Praefect 节点一起使用！ 与多个 Praefect 节点一起使用可能会导致大脑分裂.

将来我们可能会实施对 Consul 的支持以及云原生策略.

Primary Node Failure

Praefect 通过将健康的辅助节点升级为新的主节点来从发生故障的主 Gitaly 节点中恢复. 为了最大程度地减少数据丢失，Praefect 会选择从主节点进行最少重复写入的辅助节点. 仍然会有一些未复制的写入，从而导致数据丢失.

故障转移事件发生后，Praefect 会将虚拟存储切换为只读模式. 通过防止对新选举的主数据库进行新的可能冲突的写入，这可以简化数据恢复工作. 这使管理员可以尝试在允许新写入之前恢复丢失的数据.

如果您更喜欢写可用性而不是一致性，则可以通过在/etc/gitlab/gitlab.rb设置praefect['failover_read_only_after_failover'] = false并重新配置 Praefect来关闭此行为.

Checking for data loss

Praefect dataloss子命令可通过检查未完成的复制作业来帮助识别丢失的写操作. 这对于确定故障转移后可能的数据丢失情况很有用. 此命令必须在 Praefect 节点上执行.

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss [-virtual-storage <virtual-storage>]

如果未指定虚拟存储，则将检查每个已配置的虚拟存储的数据丢失.

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss

Virtual storage: default
  Current read-only primary: gitaly-2
  Previous write-enabled primary: gitaly-1
    Nodes with data loss from failing over from gitaly-1:
      @hashed/2c/62/2c624232cdd221771294dfbb310aca000a0df6ac8b66b696d90ef06fdefb64a3.git: gitaly-0
      @hashed/4b/22/4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a.git: gitaly-0, gitaly-2

当前，如果已直接从先前启用写操作的主数据库复制到该dataloss仅考虑该存储库为最新. 虽然从最新的辅助数据库进行协调可以恢复数据，但在数据丢失报告中不可见. 这是通过Gitaly＃2866进行的改进.

注意数据 dataloss仍处于 beta 状态，并且输出格式可能会更改.

Checking repository checksums

要在所有 Gitaly 节点上检查项目的存储库校验和，请在主 GitLab 节点上运行副本 Rake 任务 .

Recovering lost writes

Praefect reconcile子命令可用于恢复先前的主数据库恢复联机后丢失的写入. 仅当虚拟存储仍处于只读模式时才有可能.

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml reconcile -virtual <virtual-storage> -reference <previous-primary> -target <current-primary> -f

有关reconcile子命令的更多详细信息，请参阅” 后端节点恢复”部分.

Enabling Writes

在启用写入之前，应该进行任何数据恢复尝试，以消除冲突写入的任何可能性. 可以使用 Praefect enable-writes子命令为写入重新启用虚拟存储.

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml enable-writes -virtual-storage <virtual-storage>

Backend Node Recovery

当 Praefect 后端节点发生故障并且不再能够复制更改时，后端节点将开始从主节点开始漂移. 如果该节点最终恢复，则需要将其与当前主节点协调. 主节点被视为分片状态的唯一真实来源. Praefect reconcile子命令允许在后端节点和当前主节点之间进行手动协调.

Run the following command on the Praefect server after all placeholders (<virtual-storage> and <target-storage>) have been replaced:

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml reconcile -virtual <virtual-storage> -target <target-storage>

将占位符<virtual-storage>替换为包含要检查的后端节点存储的虚拟存储.
将占位符<target-storage>替换为后端存储名称.

该命令将返回与当前主数据库不一致的存储库列表. 这些不一致性中的每一个还将与随附的复制作业 ID 一起记录.

Migrating existing repositories to Praefect

如果您的 GitLab 实例已经有存储库，则不会自动迁移它们.

可以使用Repository API从一个存储位置移动存储库：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "repository_storage=praefect" https://example.gitlab.com/api/v4/projects/123

Debugging Praefect

如果收到错误，请检查/var/log/gitlab/gitlab-rails/production.log .

以下是常见的错误和潜在原因：

500 响应码
- ActionView :: Template :: Error（7：权限被拒绝）
  - praefect['auth_token']和gitlab_rails['gitaly_token']在 GitLab 服务器上不匹配.
- 无法保存项目. 错误：7：权限被拒绝
  - GitLab 服务器上的praefect['storage_nodes']秘密令牌与一台或多台 Gitaly 服务器上的gitaly['auth_token']中的值不匹配.
503 响应码
- GRPC ::不可用（14：无法连接到所有地址）
  - GitLab 无法到达 Praefect.
- GRPC ::不可用（14：所有 SubCon 都在 TransientFailure 中…）
  - Praefect 无法到达其一个或多个子 Gitaly 节点. 尝试运行 Praefect 连接检查器进行诊断.