• 单实例数据库复制
  • PostgreSQL 复制
    • 步骤 1. 配置主要站点
    • 步骤 2. 配置次要服务器
    • 步骤 3. 启动复制过程
  • PgBouncer 支持（可选）
  • 更改复制密码
• 多节点数据库复制
  • 将单个 PostgreSQL 节点迁移到 Patroni
  • Patroni 支持
    • 为 Geo 次要站点配置 Patroni 集群
      • 步骤 1. 在主要站点上配置 Patroni 永久复制槽
      • 步骤 2. 在主要站点上配置内部负载均衡器
      • 步骤 3. 在次要站点上配置 PgBouncer 节点
      • 步骤 4. 在次要站点上配置备用集群
  • 将单个跟踪数据库节点迁移到 Patroni
  • 配置跟踪 PostgreSQL 数据库的 Patroni 集群
• 故障排除

{{< details >}}

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

{{< /details >}}

本文档描述了将您的主极狐GitLab 数据库复制到次要站点数据库所需的最小步骤。您可能需要根据您的数据库的设置和大小等属性更改某些值。

{{< alert type=”note” >}}

如果您的极狐GitLab 安装使用外部 PostgreSQL 实例（不是通过 Linux 软件包安装管理），则角色无法执行所有必要的配置步骤。在这种情况下，请使用Geo with external PostgreSQL instances流程。

{{< /alert >}}

{{< alert type=”note” >}}

设置过程的各个阶段必须按文档顺序完成。如果没有，请在继续之前完成所有先前阶段。

{{< /alert >}}

确保次要站点运行的极狐GitLab 企业版与主要站点的版本相同。确认您已为您的主要站点添加了专业版或旗舰版订阅的许可证。

在测试或生产环境中执行这些步骤之前，请务必阅读并审查所有这些步骤。

单实例数据库复制

单实例数据库复制更易于设置，并且仍然提供与集群替代方案相同的 Geo 功能。它适用于在单机上运行或尝试评估未来集群安装的 Geo 的设置。

单实例可以使用 Patroni 扩展为集群版本，推荐用于高可用架构。

请按照以下说明设置 PostgreSQL 复制为单实例数据库。或者，您可以查看多节点数据库复制说明，以设置使用 Patroni 集群的复制。

PostgreSQL 复制

主要站点（进行写操作的地方）连接到主要数据库服务器。次要站点连接到他们自己的数据库服务器（它们是只读的）。

您应使用 PostgreSQL 的复制槽 来确保主要站点保留次要站点恢复所需的所有数据。请参见下面的详细信息。

以下指南假设：

• 您正在使用 Linux 软件包（因此正在使用 PostgreSQL 12 或更高版本），其中包括 pg_basebackup 工具。
• 您已经设置好一个主要站点（您正在复制的极狐GitLab 服务器），运行由您的 Linux 软件包安装管理的 PostgreSQL（或等效版本），并且您已经设置好一个新的次要站点，具有相同的PostgreSQL 版本、操作系统和所有站点上的极狐GitLab 。

{{< alert type=”warning” >}}

Geo 使用流复制。目前不支持逻辑复制。

{{< /alert >}}

步骤 1. 配置主要站点

1. SSH 进入您的极狐GitLab 主要站点，并以 root 身份登录：

   sudo -i
   

2. 编辑 /etc/gitlab/gitlab.rb 并为您的站点添加一个唯一名称：

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

3. 重新配置主要站点以使更改生效：

   gitlab-ctl reconfigure
   

4. 执行以下命令以将站点定义为主要站点：

   gitlab-ctl set-geo-primary-node
   

   此命令使用您在 /etc/gitlab/gitlab.rb 中定义的 external_url。

5. 为 gitlab 数据库用户定义密码：

   生成所需密码的 MD5 哈希：

   gitlab-ctl pg-password-md5 gitlab
   # 输入密码：<your_db_password_here>
   # 确认密码：<your_db_password_here>
   # fca0b89a972d69f00eb3ec98a5838484
   

   编辑 /etc/gitlab/gitlab.rb：

   # 填写 `gitlab-ctl pg-password-md5 gitlab` 生成的哈希
   postgresql['sql_user_password'] = '<md5_hash_of_your_db_password>'
   
   # 每个运行 Puma 或 Sidekiq 的节点都需要指定如下的数据库密码。如果您有高可用设置，这
   # 必须在所有应用节点中出现。
   gitlab_rails['db_password'] = '<your_db_password_here>'
   

6. 为数据库复制用户定义密码。

   使用在 /etc/gitlab/gitlab.rb 中定义的 postgresql['sql_replication_user'] 设置下的用户名。默认值是 gitlab_replicator。如果您将用户名更改为其他内容，请调整下面的说明。

   生成所需密码的 MD5 哈希：

   gitlab-ctl pg-password-md5 gitlab_replicator
   # 输入密码：<your_replication_password_here>
   # 确认密码：<your_replication_password_here>
   # 950233c0dfc2f39c64cf30457c3b7f1e
   

   编辑 /etc/gitlab/gitlab.rb：

   # 填写 `gitlab-ctl pg-password-md5 gitlab_replicator` 生成的哈希
   postgresql['sql_replication_password'] = '<md5_hash_of_your_replication_password>'
   

   如果您使用的是未由您的 Linux 软件包安装管理的外部数据库，您需要手动创建 gitlab_replicator 用户并为该用户定义密码：

   --- 创建新用户 'replicator'
   CREATE USER gitlab_replicator;
   
   --- 设置/更改密码并授予复制权限
   ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>';
   

7. 编辑 /etc/gitlab/gitlab.rb 并将角色设置为 geo_primary_role（有关详细信息，请参阅Geo 角色）：

   ## Geo 主要角色
   roles(['geo_primary_role'])
   

8. 配置 PostgreSQL 以监听网络接口：

   出于安全原因，默认情况下 PostgreSQL 不监听任何网络接口。然而，Geo 需要次要站点能够连接到主要站点的数据库。为此，您需要每个站点的 IP 地址。

   {{< alert type=”note” >}}

   对于外部 PostgreSQL 实例，请参阅附加说明。

   {{< /alert >}}

   如果您使用的是云提供商，您可以通过云提供商的管理控制台查找每个 Geo 站点的地址。

   要查找 Geo 站点的地址，请 SSH 进入 Geo 站点并执行：

   ##
   ## 私有地址
   ##
   ip route get 255.255.255.255 | awk '{print "Private address:", $NF; exit}'
   
   ##
   ## 公共地址
   ##
   echo "External address: $(curl --silent "ipinfo.io/ip")"
   

   在大多数情况下，以下地址用于配置极狐GitLab Geo：

   配置	地址
   postgresql['listen_address']	主要站点的公共或 VPC 私有地址。
   postgresql['md5_auth_cidr_addresses']	主要和次要站点的公共或 VPC 私有地址。

   如果您使用的是 Google Cloud Platform、SoftLayer 或任何其他提供虚拟私有云 (VPC) 的供应商，我们建议使用主要和次要站点的“私有”或“内部”地址用于 postgresql['md5_auth_cidr_addresses'] 和 postgresql['listen_address']。

   listen_address 选项打开 PostgreSQL 与给定地址相应的接口的网络连接。

   {{< alert type=”note” >}}

   如果您需要使用 0.0.0.0 或 * 作为 listen_address，您还必须将 127.0.0.1/32 添加到 postgresql['md5_auth_cidr_addresses'] 设置，以允许 Rails 通过 127.0.0.1 进行连接。

   {{< /alert >}}

   根据您的网络配置，建议的地址可能不正确。如果您的主要和次要站点通过局域网或连接可用区域的虚拟网络进行连接，您应该为 postgresql['md5_auth_cidr_addresses'] 使用次要站点的私有地址。

   编辑 /etc/gitlab/gitlab.rb 并添加以下内容，用适合您的网络配置的地址替换 IP 地址：

   ##
   ## 主要地址
   ## - 用您的 Geo 主要节点的公共或 VPC 地址替换 '<primary_node_ip>'
   ##
   postgresql['listen_address'] = '<primary_site_ip>'
   
   ##
   # 允许来自主要和次要 IP 的 PostgreSQL 客户端身份验证。这些 IP 可以是 CIDR 格式的公共或 VPC 地址，例如 ['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['max_wal_senders'] = 10
   # postgresql['wal_keep_segments'] = 10
   

9. 暂时禁用自动数据库迁移，直到 PostgreSQL 重新启动并监听私有地址。编辑 /etc/gitlab/gitlab.rb 并将配置更改为 false：

   ## 禁用自动数据库迁移
   gitlab_rails['auto_migrate'] = false
   

10. 可选：如果您想添加另一个次要站点，相关设置将如下所示：

    postgresql['md5_auth_cidr_addresses'] = ['<primary_site_ip>/32', '<secondary_site_ip>/32', '<another_secondary_site_ip>/32']
    

    您可能还想编辑 wal_keep_segments 和 max_wal_senders 以匹配您的数据库复制需求。

11. 保存文件并重新配置极狐GitLab 以应用数据库监听更改和复制槽更改：

    gitlab-ctl reconfigure
    

    重新启动 PostgreSQL 以使其更改生效：

    gitlab-ctl restart postgresql
    

12. 重新启用迁移，因为 PostgreSQL 已重新启动并监听私有地址。

    编辑 /etc/gitlab/gitlab.rb 并将配置更改为 true：

    gitlab_rails['auto_migrate'] = true
    

    保存文件并重新配置极狐GitLab：

    gitlab-ctl reconfigure
    

13. 现在 PostgreSQL 服务器已设置为接受远程连接，运行 netstat -plnt | grep 5432 以确保 PostgreSQL 正在监听主要站点的私有地址上的端口 5432。

14. 极狐GitLab 被重新配置时自动生成了一个证书。此证书用于自动保护您的 PostgreSQL 流量免受窃听。为了防止主动攻击（“中间人”攻击），次要站点需要一份签署证书的 CA 的副本。在这种自签名证书的情况下，通过运行此命令制作主要站点上 PostgreSQL server.crt 文件的副本：

    cat ~gitlab-psql/data/server.crt
    

    将输出复制到剪贴板或本地文件中。您在设置次要站点时需要它！证书不是敏感数据。

    然而，此证书是使用通用的 PostgreSQL 通用名称创建的。因此，您必须在复制数据库时使用 verify-ca 模式，否则，主机名不匹配会导致错误。

15. 可选。生成您自己的 SSL 证书并手动为 PostgreSQL 配置 SSL，而不是使用生成的证书。

    您至少需要 SSL 证书和密钥。将 postgresql['ssl_cert_file'] 和 postgresql['ssl_key_file'] 值设置为其完整路径，如数据库 SSL 文档所述。

    这允许您在复制数据库时使用 verify-full SSL 模式，并获得验证证书 CN 中完整主机名的额外好处。

    您可以在继续使用此证书（您也已在 postgresql['ssl_cert_file'] 中设置）而不是上述步骤中的证书。这样可以在 CN 匹配时使用 verify-full 而不会出现复制错误。

    在您的主要数据库上，打开 /etc/gitlab/gitlab.rb 并搜索 postgresql['ssl_ca_file']（CA 证书）。将其值复制到剪贴板，以便稍后将其粘贴到 server.crt 中。

步骤 2. 配置次要服务器

1. SSH 进入您的极狐GitLab 次要站点，并以 root 身份登录：

   sudo -i
   

2. 停止应用服务器和 Sidekiq：

   gitlab-ctl stop puma
   gitlab-ctl stop sidekiq
   

   {{< alert type=”note” >}}

   此步骤很重要，以便在站点完全配置之前不尝试执行任何操作。

   {{< /alert >}}

3. 检查 TCP 连接到主要站点的 PostgreSQL 服务器：

   gitlab-rake gitlab:tcp_check[<primary_site_ip>,5432]
   

   {{< alert type=”note” >}}

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

   {{< /alert >}}

4. 在次要站点创建一个文件 server.crt，内容为您在主要站点设置的最后一步中获得的内容：

   editor server.crt
   

5. 在次要站点上设置 PostgreSQL TLS 验证：

   安装 server.crt 文件：

   install \
      -D \
      -o gitlab-psql \
      -g gitlab-psql \
      -m 0400 \
      -T server.crt ~gitlab-psql/.postgresql/root.crt
   

   PostgreSQL 现在只能识别该确切的证书来验证 TLS 连接。证书只能由拥有私钥的人复制，而私钥仅存在于主要站点。

6. 测试 gitlab-psql 用户是否可以连接到主要站点的数据库（在 Linux 软件包安装中，默认数据库名称是 gitlabhq_production）：

   sudo \
      -u gitlab-psql /opt/gitlab/embedded/bin/psql \
      --list \
      -U gitlab_replicator \
      -d "dbname=gitlabhq_production sslmode=verify-ca" \
      -W \
      -h <primary_site_ip>
   

   {{< alert type=”note” >}}

   如果您使用手动生成的证书并希望使用 sslmode=verify-full 以便从完整主机名验证中获益，请在运行命令时将 verify-ca 替换为 verify-full。

   {{< /alert >}}

   当提示时，输入您为 gitlab_replicator 用户设置的明文密码。如果一切正常，您应该看到主要站点的数据库列表。

   如果连接失败，则表明 TLS 配置不正确。确保主要站点上的 ~gitlab-psql/data/server.crt 的内容与次要站点上的 ~gitlab-psql/.postgresql/root.crt 的内容匹配。

7. 编辑 /etc/gitlab/gitlab.rb 并将角色设置为 geo_secondary_role：

   ##
   ## Geo 次要角色
   ## - 自动配置相关标志以启用 Geo
   ##
   roles(['geo_secondary_role'])
   

8. 配置 PostgreSQL：

   此步骤与您配置主要实例的方式相似。即使使用单个节点，也必须启用此功能。

   编辑 /etc/gitlab/gitlab.rb 并添加以下内容，用适合您的网络配置的地址替换 IP 地址：

   ##
   ## 次要地址
   ## - 用您的 Geo 次要站点的公共或 VPC 地址替换 '<secondary_site_ip>'
   ##
   postgresql['listen_address'] = '<secondary_site_ip>'
   postgresql['md5_auth_cidr_addresses'] = ['<secondary_site_ip>/32']
   
   ##
   ## 数据库凭证密码（之前在主要站点中定义）
   ## - 在此处复制主要站点中定义的相同值
   ##
   postgresql['sql_replication_password'] = '<md5_hash_of_your_replication_password>'
   postgresql['sql_user_password'] = '<md5_hash_of_your_db_password>'
   gitlab_rails['db_password'] = '<your_db_password_here>'
   

   对于外部 PostgreSQL 实例，请参阅附加说明。如果您将以前的主要站点重新上线以充当次要站点，那么您还必须删除 roles(['geo_primary_role']) 或 geo_primary_role['enable'] = true。

9. 重新配置极狐GitLab 以使更改生效：

   gitlab-ctl reconfigure
   

10. 重新启动 PostgreSQL 以使 IP 更改生效：

    gitlab-ctl restart postgresql
    

步骤 3. 启动复制过程

下面是一个脚本，它连接次要站点上的数据库到主要站点上的数据库。此脚本复制数据库并创建流式复制所需的文件。

使用的目录是 Linux 软件包安装中设置的默认值。如果您更改了任何默认设置，请相应地配置脚本（替换任何目录和路径）。

{{< alert type=”warning” >}}

确保在次要站点上运行此操作，因为它在运行 pg_basebackup 之前删除 PostgreSQL 的所有数据。

{{< /alert >}}

1. SSH 进入您的极狐GitLab 次要站点，并以 root 身份登录：

   sudo -i
   

2. 选择一个数据库友好的名称，用于您的次要站点作为复制槽名称。例如，如果您的域是 secondary.geo.example.com，请使用 secondary_example 作为插槽名称，如下所示命令。

3. 执行以下命令以启动备份/恢复并开始复制

   {{< alert type=”warning” >}}

   每个 Geo 次要站点必须有自己的唯一复制槽名称。在两个次要站点之间使用相同的插槽名称会破坏 PostgreSQL 复制。

   {{< /alert >}}

   {{< alert type=”note” >}}

   复制槽名称只能包含小写字母、数字和下划线字符。

   {{< /alert >}}

   当提示时，输入您为 gitlab_replicator 用户设置的明文密码。

   gitlab-ctl replicate-geo-database \
      --slot-name=<secondary_site_name> \
      --host=<primary_site_ip> \
      --sslmode=verify-ca
   

   {{< alert type=”note” >}}

   如果您生成了自定义 PostgreSQL 证书，您需要使用 --sslmode=verify-full（或完全省略 sslmode 行），以便从证书 CN / SAN 中完整主机名验证中获益以提高安全性。否则，使用自动创建的证书与 verify-full 会失败，因为它具有一个通用的 PostgreSQL CN，与此命令中的 --host 值不匹配。

   {{< /alert >}}

   此命令还接受许多其他选项。您可以使用 --help 来列出所有选项，但这里有一些提示：

   • 如果您的主要站点有一个单节点，请使用主要节点主机作为 --host 参数。
   • 如果您的主要站点使用外部 PostgreSQL 数据库，您需要调整 --host 参数：
     • 对于 PgBouncer 设置，直接定位实际的 PostgreSQL 数据库主机，而不是 PgBouncer 地址。
     • 对于 Patroni 配置，定位当前 Patroni 领导者主机。
     • 使用负载均衡器（例如 HAProxy）时，如果负载均衡器配置为始终路由到 Patroni 领导者，您可以定位负载均衡器的 IP。如果没有，您必须定位实际的数据库主机。
     • 对于具有专用 PostgreSQL 节点的设置，直接定位专用数据库主机。
   • 将 --slot-name 更改为用于主要数据库的复制槽名称。脚本尝试自动创建复制槽，如果不存在。
   • 如果 PostgreSQL 在非标准端口上监听，请添加 --port=。
   • 如果您的数据库太大，无法在 30 分钟内传输，您需要增加超时时间。例如，如果您预计初始复制会在一小时内完成，请使用 --backup-timeout=3600。
   • 通过传递 --sslmode=disable 来完全跳过 PostgreSQL TLS 身份验证（例如，您知道网络路径是安全的，或者您正在使用站点到站点 VPN）。它在公共互联网中不安全！
   • 您可以在PostgreSQL 文档中阅读有关每个 sslmode 的更多详细信息。上述说明精心编写，以确保防止被动窃听者和主动“中间人”攻击者。
   • 如果您将旧站点改造为 Geo 次要站点，您必须在命令行中添加 --force。
   • 在非生产机器上，如果您确定这是您想要的，可以通过添加 --skip-backup 禁用备份步骤。

复制过程现在已完成。

{{< alert type=”note” >}}

复制过程只会将数据从主要站点的数据库复制到次要站点的数据库。要完成您的次要站点配置，请在您的主要站点上添加次要站点。

{{< /alert >}}

PgBouncer 支持（可选）

PgBouncer 可以与极狐GitLab Geo 一起使用来池化 PostgreSQL 连接，即使在单实例安装中使用时也可以提高性能。

如果您在支持 Geo 主要站点的节点集群和支持 Geo 次要站点的两个其他节点集群中以高可用配置使用极狐GitLab ，您应该使用 PgBouncer。您需要两个 PgBouncer 节点：一个用于主数据库，另一个用于跟踪数据库。有关更多信息，请参阅相关文档。

更改复制密码

要更改使用由 Linux 软件包安装管理的 PostgreSQL 实例时的复制用户密码：

在极狐GitLab Geo 主要站点上：

1. 复制用户的默认值是 gitlab_replicator，但如果您在 /etc/gitlab/gitlab.rb 中的 postgresql['sql_replication_user'] 设置中设置了自定义复制用户，请确保根据自己的用户调整以下说明。

   生成所需密码的 MD5 哈希：

   sudo gitlab-ctl pg-password-md5 gitlab_replicator
   # 输入密码：<your_replication_password_here>
   # 确认密码：<your_replication_password_here>
   # 950233c0dfc2f39c64cf30457c3b7f1e
   

   编辑 /etc/gitlab/gitlab.rb：

   # 填写 `gitlab-ctl pg-password-md5 gitlab_replicator` 生成的哈希
   postgresql['sql_replication_password'] = '<md5_hash_of_your_replication_password>'
   

2. 保存文件并重新配置极狐GitLab 以更改 PostgreSQL 中的复制用户的密码：

   sudo gitlab-ctl reconfigure
   

3. 重新启动 PostgreSQL 以使复制密码更改生效：

   sudo gitlab-ctl restart postgresql
   

在任何次要站点上更新密码之前，PostgreSQL 日志中的次要站点报告以下错误消息：

FATAL:  could not connect to the primary server: FATAL:  password authentication failed for user "gitlab_replicator"

在所有极狐GitLab Geo 次要站点上：

1. 从配置角度来看，第一步不是必需的，因为哈希 'sql_replication_password' 在极狐GitLab Geo 次要站点上不使用。然而，如果次要站点需要提升为极狐GitLab Geo 主要，请确保在次要站点配置中匹配 'sql_replication_password'。

   编辑 /etc/gitlab/gitlab.rb：

   # 填写在 Geo 主要站点上通过 `gitlab-ctl pg-password-md5 gitlab_replicator` 生成的哈希
   postgresql['sql_replication_password'] = '<md5_hash_of_your_replication_password>'
   

2. 在初始复制设置期间，gitlab-ctl replicate-geo-database 命令将复制用户帐户的明文密码写入两个位置：

   • gitlab-geo.conf：由 PostgreSQL 复制过程使用，写入 PostgreSQL 数据目录，默认情况下位于 /var/opt/gitlab/postgresql/data/gitlab-geo.conf。
   • .pgpass：由 gitlab-psql 用户使用，默认位于 /var/opt/gitlab/postgresql/.pgpass。

   在这两个文件中更新明文密码，并重新启动 PostgreSQL：

   sudo gitlab-ctl restart postgresql
   

多节点数据库复制

将单个 PostgreSQL 节点迁移到 Patroni

在引入 Patroni 之前，Geo 不支持在次要站点上的 HA 设置的 Linux 软件包安装。

使用 Patroni，现在可以支持此功能。要将现有的 PostgreSQL 迁移到 Patroni：

1. 确保您在次要站点上设置了一个 Consul 集群（类似于您在主要站点上设置的方式）。
2. 配置永久复制槽。
3. 配置内部负载均衡器。
4. 配置 PgBouncer 节点。
5. 在单节点机器上配置备用集群。

您最终会得到一个具有单个节点的 Standby Cluster。这允许您通过遵循上述相同说明添加其他 Patroni 节点。

Patroni 支持

Patroni 是 Geo 的官方复制管理解决方案。Patroni 可以用于在 Geo 主要和次要站点构建一个高可用集群。在次要站点上使用 Patroni 是可选的，您不必在每个 Geo 站点上使用相同数量的节点。

有关如何在主要站点上设置 Patroni 的说明，请参阅相关文档。

为 Geo 次要站点配置 Patroni 集群

在 Geo 次要站点，主 PostgreSQL 数据库是主要站点的 PostgreSQL 数据库的只读副本。

生产就绪和安全的设置至少需要：

• 3 个 Consul 节点 (主要和次要站点)
• 2 个 Patroni 节点 (主要和次要站点)
• 1 个 PgBouncer 节点 (主要和次要站点)
• 1 个内部负载均衡器 (仅主要站点)

内部负载均衡器为连接到 Patroni 集群的领导者提供单个端点，每当选举出新的领导者时。负载均衡器是启用次要站点级联复制所必需的。

务必使用密码凭证和其他数据库最佳实践。

步骤 1. 在主要站点上配置 Patroni 永久复制槽

在主要数据库上设置一个持久复制槽，以确保从主要数据库到次要节点上的 Patroni 集群的连续数据复制。

{{< tabs >}}

{{< tab title=”Primary with Patroni cluster” >}}

要在次要站点上使用 Patroni 配置数据库复制，您必须在主要站点的 Patroni 集群上配置一个_永久复制槽_，并确保使用密码认证。

在主要站点上运行 Patroni 实例的每个节点从 Patroni 领导者实例开始：

1. SSH 进入您的 Patroni 实例，并以 root 身份登录：

   sudo -i
   

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

   roles(['patroni_role'])
   
   consul['services'] = %w(postgresql)
   consul['configuration'] = {
     retry_join: %w[CONSUL_PRIMARY1_IP CONSUL_PRIMARY2_IP CONSUL_PRIMARY3_IP]
   }
   
   # 您需要为每个次要节点添加一个条目，使用一个唯一的名称，遵循 PostgreSQL slot_name 约束：
   #
   # 配置语法为：'unique_slotname' => { 'type' => 'physical' },
   # 我们不支持为逻辑复制类型设置永久复制槽
   patroni['replication_slots'] = {
     'geo_secondary' => { 'type' => 'physical' }
   }
   
   patroni['use_pg_rewind'] = true
   patroni['postgresql']['max_wal_senders'] = 8 # 使用双倍数量的 patroni/保留槽（3 个 patroni + 1 个保留槽用于 Geo 次要）。
   patroni['postgresql']['max_replication_slots'] = 8 # 使用双倍数量的 patroni/保留槽（3 个 patroni + 1 个保留槽用于 Geo 次要）。
   patroni['username'] = 'PATRONI_API_USERNAME'
   patroni['password'] = 'PATRONI_API_PASSWORD'
   patroni['replication_password'] = 'PLAIN_TEXT_POSTGRESQL_REPLICATION_PASSWORD'
   
   # 将所有 patroni 节点添加到允许列表
   patroni['allowlist'] = %w[
     127.0.0.1/32
     PATRONI_PRIMARY1_IP/32 PATRONI_PRIMARY2_IP/32 PATRONI_PRIMARY3_IP/32
     PATRONI_SECONDARY1_IP/32 PATRONI_SECONDARY2_IP/32 PATRONI_SECONDARY3_IP/32
   ]
   
   # 我们列出所有次要实例，因为它们都可以成为备用领导者
   postgresql['md5_auth_cidr_addresses'] = %w[
     PATRONI_PRIMARY1_IP/32 PATRONI_PRIMARY2_IP/32 PATRONI_PRIMARY3_IP/32 PATRONI_PRIMARY_PGBOUNCER/32
     PATRONI_SECONDARY1_IP/32 PATRONI_SECONDARY2_IP/32 PATRONI_SECONDARY3_IP/32 PATRONI_SECONDARY_PGBOUNCER/32
   ]
   
   postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH'
   postgresql['sql_replication_password'] = 'POSTGRESQL_REPLICATION_PASSWORD_HASH'
   postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH'
   postgresql['listen_address'] = '0.0.0.0' # 您可以在此处使用公共或 VPC 地址
   

3. 重新配置极狐GitLab 以使更改生效：

   gitlab-ctl reconfigure
   

{{< /tab >}}

{{< tab title=”Primary with single PostgreSQL instance” >}}

1. SSH 进入您的单节点实例，并以 root 身份登录：

   sudo -i
   

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

   postgresql['max_wal_senders'] = 2 # 每个次要站点使用 2（1 个临时槽用于初始 Patroni 复制 + 1 个保留槽用于 Geo 次要）
   postgresql['max_replication_slots'] = 2 # 每个次要站点使用 2（1 个临时槽用于初始 Patroni 复制 + 1 个保留槽用于 Geo 次要）
   

3. 重新配置极狐GitLab：

   gitlab-ctl reconfigure
   

4. 重新启动 PostgreSQL 服务以使新更改生效：

   gitlab-ctl restart postgresql
   

5. 启动数据库控制台

   gitlab-psql
   

6. 在主要站点上配置永久复制槽

   select pg_create_physical_replication_slot('geo_secondary')
   

7. 可选：如果主要没有 PgBouncer，但次要有：

   在主要站点上配置 pgbouncer 用户，并为 PgBouncer 包含的 Linux 软件包添加必要的 pg_shadow_lookup 函数。次要服务器上的 PgBouncer 仍然能够连接到次要站点上的 PostgreSQL 节点。

   --- 创建新用户 'pgbouncer'
   CREATE USER pgbouncer;
   
   --- 设置/更改密码并授予复制权限
   ALTER USER pgbouncer WITH REPLICATION ENCRYPTED PASSWORD '<pgbouncer_password_from_secondary>';
   
   CREATE OR REPLACE FUNCTION public.pg_shadow_lookup(in i_username text, out username text, out password text) RETURNS record AS $$
   BEGIN
       SELECT usename, passwd FROM pg_catalog.pg_shadow
       WHERE usename = i_username INTO username, password;
       RETURN;
   END;
   $$ LANGUAGE plpgsql SECURITY DEFINER;
   
   REVOKE ALL ON FUNCTION public.pg_shadow_lookup(text) FROM public, pgbouncer;
   GRANT EXECUTE ON FUNCTION public.pg_shadow_lookup(text) TO pgbouncer;
   

{{< /tab >}}

{{< /tabs >}}

步骤 2. 在主要站点上配置内部负载均衡器

为避免在主要站点选举新领导者时重新配置次要站点上的备用领导者，您应该设置一个 TCP 内部负载均衡器。此负载均衡器为连接到 Patroni 集群的领导者提供单个端点。

Linux 软件包不包括负载均衡器。以下是您可以使用 HAProxy 的方法。

以下 IP 和名称用作示例：

• 10.6.0.21：Patroni 1 (patroni1.internal)
• 10.6.0.22：Patroni 2 (patroni2.internal)
• 10.6.0.23：Patroni 3 (patroni3.internal)

global
    log /dev/log local0
    log localhost local1 notice
    log stdout format raw local0

defaults
    log global
    default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions

frontend internal-postgresql-tcp-in
    bind *:5432
    mode tcp
    option tcplog

    default_backend postgresql

backend postgresql
    mode tcp
    option httpchk
    http-check expect status 200

    server patroni1.internal 10.6.0.21:5432 maxconn 100 check port 8008
    server patroni2.internal 10.6.0.22:5432 maxconn 100 check port 8008
    server patroni3.internal 10.6.0.23:5432 maxconn 100 check port 8008

有关进一步的指导，请参阅您首选负载均衡器的文档。

步骤 3. 在次要站点上配置 PgBouncer 节点

生产就绪和高可用配置至少需要三个 Consul 节点和至少一个 PgBouncer 节点。然而，建议每个数据库节点都有一个 PgBouncer 节点。当有多个 PgBouncer 服务节点时，需要一个内部负载均衡器（TCP）。内部负载均衡器为连接到 PgBouncer 集群提供单个端点。

在次要站点上运行 PgBouncer 实例的每个节点：

1. SSH 进入您的 PgBouncer 节点，并以 root 身份登录：

   sudo -i
   

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

   # 禁用除 PgBouncer 和 Consul 代理之外的所有组件
   roles(['pgbouncer_role'])
   
   # PgBouncer 配置
   pgbouncer['admin_users'] = %w(pgbouncer gitlab-consul)
   pgbouncer['users'] = {
   'gitlab-consul': {
      # 使用：`gitlab-ctl pg-password-md5 gitlab-consul` 生成
      password: 'GITLAB_CONSUL_PASSWORD_HASH'
    },
     'pgbouncer': {
       # 使用：`gitlab-ctl pg-password-md5 pgbouncer` 生成
       password: 'PGBOUNCER_PASSWORD_HASH'
     }
   }
   
   # Consul 配置
   consul['watchers'] = %w(postgresql)
   consul['configuration'] = {
     retry_join: %w[CONSUL_SECONDARY1_IP CONSUL_SECONDARY2_IP CONSUL_SECONDARY3_IP]
   }
   consul['monitoring_service_discovery'] =  true
   

3. 重新配置极狐GitLab 以使更改生效：

   gitlab-ctl reconfigure
   

4. 创建一个 .pgpass 文件，以便 Consul 能够重新加载 PgBouncer。在提示时输入 PLAIN_TEXT_PGBOUNCER_PASSWORD 两次：

   gitlab-ctl write-pgpass --host 127.0.0.1 --database pgbouncer --user pgbouncer --hostuser gitlab-consul
   

5. 重新加载 PgBouncer 服务：

   gitlab-ctl hup pgbouncer
   

步骤 4. 在次要站点上配置备用集群

{{< alert type=”note” >}}

如果您将具有单个 PostgreSQL 实例的次要站点转换为 Patroni 集群，您必须从 PostgreSQL 实例开始。它成为 Patroni 备用领导者实例，然后您可以根据需要切换到其他副本。

{{< /alert >}}

对于次要站点上运行 Patroni 实例的每个节点：

1. SSH 进入您的 Patroni 节点，并以 root 身份登录：

   sudo -i
   

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

   roles(['consul_role', 'patroni_role'])
   
   consul['enable'] = true
   consul['configuration'] = {
     retry_join: %w[CONSUL_SECONDARY1_IP CONSUL_SECONDARY2_IP CONSUL_SECONDARY3_IP]
   }
   consul['services'] = %w(postgresql)
   
   postgresql['md5_auth_cidr_addresses'] = [
     'PATRONI_SECONDARY1_IP/32', 'PATRONI_SECONDARY2_IP/32', 'PATRONI_SECONDARY3_IP/32', 'PATRONI_SECONDARY_PGBOUNCER/32',
     # 根据文档需要访问数据库的任何其他实例
   ]
   
   
   # 将 patroni 节点添加到允许列表
   postgresql['md5_auth_cidr_addresses'] = [
     'PATRONI_SECONDARY1_IP/32', 'PATRONI_SECONDARY2_IP/32', 'PATRONI_SECONDARY3_IP/32', 'PATRONI_SECONDARY_PGBOUNCER/32',
     # Any other instance that needs access to the database as per documentation
   ]
   
   
   # Add patroni nodes to the allowlist
   patroni['allowlist'] = %w[
     127.0.0.1/32
     PATRONI_SECONDARY1_IP/32 PATRONI_SECONDARY2_IP/32 PATRONI_SECONDARY3_IP/32
   ]
   
   patroni['standby_cluster']['enable'] = true
   patroni['standby_cluster']['host'] = 'INTERNAL_LOAD_BALANCER_PRIMARY_IP'
   patroni['standby_cluster']['port'] = INTERNAL_LOAD_BALANCER_PRIMARY_PORT
   patroni['standby_cluster']['primary_slot_name'] = 'geo_secondary' # Or the unique replication slot name you setup before
   patroni['username'] = 'PATRONI_API_USERNAME'
   patroni['password'] = 'PATRONI_API_PASSWORD'
   patroni['replication_password'] = 'PLAIN_TEXT_POSTGRESQL_REPLICATION_PASSWORD'
   patroni['use_pg_rewind'] = true
   patroni['postgresql']['max_wal_senders'] = 5 # A minimum of three for one replica, plus two for each additional replica
   patroni['postgresql']['max_replication_slots'] = 5 # A minimum of three for one replica, plus two for each additional replica
   
   postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH'
   postgresql['sql_replication_password'] = 'POSTGRESQL_REPLICATION_PASSWORD_HASH'
   postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH'
   postgresql['listen_address'] = '0.0.0.0' # You can use a public or VPC address here instead
   
   # GitLab Rails configuration is required for `gitlab-ctl geo-replication-pause`
   gitlab_rails['db_password'] = 'POSTGRESQL_PASSWORD'
   gitlab_rails['enable'] = true
   gitlab_rails['auto_migrate'] = false
   

在配置 patroni['standby_cluster']['host'] 和 patroni['standby_cluster']['port'] 时： - INTERNAL_LOAD_BALANCER_PRIMARY_IP 必须指向主内部负载均衡器 IP。 - INTERNAL_LOAD_BALANCER_PRIMARY_PORT 必须指向 为主 Patroni 集群领导者配置的前端端口。不要使用 PgBouncer 前端端口。

1. 重新配置极狐GitLab 以使更改生效。此步骤是引导 PostgreSQL 用户和设置所必需的。

   • 如果这是 Patroni 的新安装：

     gitlab-ctl reconfigure
     

   • 如果你在之前有一个正常运行的 Patroni 集群的站点上配置 Patroni 备用集群：

     1. 停止由 Patroni 管理的所有节点上的 Patroni，包括级联副本：

        gitlab-ctl stop patroni
        

     2. 在领导者 Patroni 节点上运行以下命令以重新创建备用集群：

        rm -rf /var/opt/gitlab/postgresql/data
        /opt/gitlab/embedded/bin/patronictl -c /var/opt/gitlab/patroni/patroni.yaml remove postgresql-ha
        gitlab-ctl reconfigure
        

     3. 在领导者 Patroni 节点上启动 Patroni，以从主数据库开始复制过程：

        gitlab-ctl start patroni
        

     4. 检查 Patroni 集群的状态：

        gitlab-ctl patroni members
        

        验证：

        • 当前 Patroni 节点出现在输出中。
        • 角色是 Standby Leader。角色可能最初显示为 Replica。
        • 状态是 Running。状态可能最初显示为 Creating replica。

        等待节点的角色稳定为 Standby Leader 且状态为 Running。这可能需要几分钟。

     5. 当领导者 Patroni 节点是 Standby Leader 并且处于 Running 状态时，在备用集群中的其他 Patroni 节点上启动 Patroni：

        gitlab-ctl start patroni
        

        其他 Patroni 节点应自动作为副本加入新的备用集群，并从领导者 Patroni 节点开始复制。

2. 验证集群状态：

   gitlab-ctl patroni members
   

   确保所有 Patroni 节点都在 Running 状态中列出。应该有一个 Standby Leader 节点和多个 Replica 节点。

将单个跟踪数据库节点迁移到 Patroni

在引入 Patroni 之前，Geo 不支持在辅助站点上的基础版设置的 Linux 软件包安装。

通过 Patroni，现在可以支持基础版设置。然而，Patroni 中的一些限制阻止在同一机器上管理两个不同的集群。你应该按照上述相同的说明为跟踪数据库设置一个新的 Patroni 集群。

辅助节点会回填新的跟踪数据库，并且不需要数据同步。

配置跟踪 PostgreSQL 数据库的 Patroni 集群

辅助 Geo 站点使用单独的 PostgreSQL 安装作为跟踪数据库，以跟踪复制状态并自动从潜在的复制问题中恢复。

如果你想在单个节点上运行 Geo 跟踪数据库，请参阅在 Geo 辅助站点上配置 Geo 跟踪数据库。

Linux 软件包不支持在高可用配置中运行 Geo 跟踪数据库。特别是，故障转移无法正常工作。

如果你想在高可用配置中运行 Geo 跟踪数据库，可以将辅助站点连接到外部 PostgreSQL 数据库，例如云管理数据库或手动配置的 Patroni 集群（不由极狐GitLab Linux 软件包管理）。请遵循使用外部 PostgreSQL 实例的 Geo。

故障排除

阅读故障排除文档。