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

排查常见的 Geo 错误

  • Tier: Premium, Ultimate
  • Offering: GitLab Self-Managed

基础故障排除

在尝试更高级的故障排除前：

检查 Geo 站点的健康状况

在主站点上：

  1. 在左侧边栏底部，选择管理。
  2. 选择Geo > 站点。

我们对每个次级站点执行以下健康检查，以帮助识别是否存在问题：

  • 站点是否正在运行？
  • 次级站点的数据库是否配置了流式复制？
  • 次级站点的跟踪数据库是否已配置？
  • 次级站点的跟踪数据库是否连接成功？
  • 次级站点的跟踪数据库是否最新？
  • 次级站点的状态是否不超过 1 小时？

若站点状态超过 1 小时，则会显示为“不健康”。此时，尝试在受影响的次级站点的 Rails 控制台 中运行以下命令：

Geo::MetricsUpdateWorker.new.perform

若引发错误，则该错误可能也阻止了作业完成。若耗时超过 1 小时，即使状态偶尔更新，状态也可能波动或持续显示为“不健康”。这可能是由于使用量增长、数据随时间增长，或性能问题（例如缺少数据库索引）导致的。

您可使用 top 或 htop 等工具监控系统 CPU 负载。若 PostgreSQL 占用大量 CPU，可能表示存在问题，或系统资源不足。也应监控系统内存。

若增加内存，还需在 /etc/gitlab/gitlab.rb 配置中检查 PostgreSQL 的内存相关设置。

若状态更新成功，则 Sidekiq 可能存在问题：它是否正在运行？日志是否显示错误？此作业应每分钟入队一次，若未正确清除 job 去重幂等键，则可能无法运行。它在 Redis 中获取独占租约，以确保此类作业一次仅能运行一个。主站点直接在 PostgreSQL 数据库中更新状态；次级站点向主站点发送包含其状态数据的 HTTP Post 请求。

若某些健康检查失败，站点也会显示为“不健康”。您可通过在受影响的次级站点的 Rails 控制台 中运行以下命令查看失败原因：

Gitlab::Geo::HealthCheck.new.perform_checks

若返回 ""（空字符串）或 "Healthy"，则检查通过。若返回其他内容，则消息应解释失败原因，或显示异常消息。

有关如何解决用户界面报告的常见错误信息，请参阅 修复常见错误。

若用户界面无法工作，或您无法登录，可手动运行 Geo 健康检查以获取此信息及其他详细信息。

健康检查 Rake 任务

该Rake任务可在主或次级Geo节点的Rails节点上运行：

sudo gitlab-rake gitlab:geo:check

示例输出：

检查 Geo ...

GitLab Geo 可用性 ... 是
GitLab Geo 已启用 ... 是
此机器的 Geo 节点名称与数据库记录匹配 ... 是，找到一个名为 "Shanghai" 的次级节点
GitLab Geo 跟踪数据库配置正确 ... 是
数据库复制已启用？ ... 是
数据库复制正常工作？ ... 是
GitLab Geo HTTP(S) 连通性 ...
* 能连接到主节点 ... 是
HTTP/HTTPS 仓库克隆已启用 ... 是
机器时钟已同步 ... 是
Git 用户有默认 SSH 配置？ ... 是
OpenSSH 配置为使用 AuthorizedKeysCommand ... 是
GitLab 配置为禁止写入 authorized_keys 文件 ... 是
GitLab 配置为新项目存储在哈希存储中？ ... 是
所有项目都在哈希存储中？ ... 是

检查 Geo ... 完成

你也可以通过环境变量指定自定义NTP服务器。例如：

sudo gitlab-rake gitlab:geo:check NTP_HOST="ntp.ubuntu.com" NTP_TIMEOUT="30"

支持以下环境变量。

变量 描述 默认值
NTP_HOST NTP 主机 pool.ntp.org
NTP_PORT 主机监听的 NTP 端口 ntp
NTP_TIMEOUT NTP 超时时间（秒） net-ntp Ruby 库中定义的值（60 秒）。

如果 Rake 任务跳过了 OpenSSH configured to use AuthorizedKeysCommand 检查，会显示以下输出：

OpenSSH 配置为使用 AuthorizedKeysCommand ... 跳过
  原因：
  无法访问 OpenSSH 配置文件
  尝试修复方法：
  如果你正在使用 SELinux，这可能是预期的行为。你可能需要手动检查配置
  更多信息请参见：
  doc/administration/operations/fast_ssh_key_lookup.md

这种情况可能发生在：

  • 你使用了 SELinux。
  • 你没有使用 SELinux，且由于文件权限限制，git 用户无法访问 OpenSSH 配置文件。

在后一种情况下，以下输出显示只有 root 用户可以读取该文件：

sudo stat -c '%G:%U %A %a %n' /etc/ssh/sshd_config

root:root -rw------- 600 /etc/ssh/sshd_config

若要让 git 用户能够读取 OpenSSH 配置文件，而不更改文件所有者或权限，可使用 acl：

sudo setfacl -m u:git:r /etc/ssh/sshd_config

同步状态 Rake 任务

当前同步信息可以通过在 Geo 次要站点的任何运行 Rails（Puma、Sidekiq 或 Geo 日志游标）的节点上手动运行此 Rake 任务来找到。

GitLab 不会验证存储在对象存储中的对象。如果您使用对象存储，您会看到所有“已验证”检查显示 0 次成功。这是预期的，无需担心。

sudo gitlab-rake geo:status

输出包含：

  • 如果发生失败，则显示“失败”项目的数量
  • “成功”项目的百分比（相对于“总计”）

示例：

                        Geo 站点信息
--------------------------------------------
                                      名称: example-us-east-2
                                       URL: https://gitlab.example.com
                                  Geo 角色: 次要
                             健康状态: 健康
                此节点的 GitLab 版本: 17.7.0-ee

                     复制信息
--------------------------------------------
                             同步设置: 完整
                  数据库复制延迟: 0 秒
           从主节点看到的最新事件 ID: 12345（约 2 分钟前）
                   已处理的最新事件 ID: 12345（约 2 分钟前）
                    最新状态报告时间: 1 分钟前

                          复制状态
--------------------------------------------
                    LFS 对象已复制: 成功 111 / 总计 111 (100%)
            合并请求差异已复制: 成功 28 / 总计 28 (100%)
                  包文件已复制: 成功 90 / 总计 90 (100%)
       Terraform 状态版本已复制: 成功 65 / 总计 65 (100%)
             笔记仓库已复制: 成功 63 / 总计 63 (100%)
        组维基仓库已复制: 成功 14 / 总计 14 (100%)
             流水线制品已复制: 成功 112 / 总计 112 (100%)
              页面部署已复制: 成功 55 / 总计 55 (100%)
                        上传已复制: 成功 2 / 总计 2 (100%)
                  作业制品已复制: 成功 32 / 总计 32 (100%)
                CI 安全文件已复制: 成功 44 / 总计 44 (100%)
         依赖代理 Blob 已复制: 成功 15 / 总计 15 (100%)
       依赖代理清单已复制: 成功 2 / 总计 2 (100%)
        项目维基仓库已复制: 成功 2 / 总计 2 (100%)
 设计管理仓库已复制: 成功 1 / 总计 1 (100%)
           项目仓库已复制: 成功 2 / 总计 2 (100%)

                         验证状态
--------------------------------------------
                      LFS 对象已验证: 成功 111 / 总计 111 (100%)
              合并请求差异已验证: 成功 28 / 总计 28 (100%)
                    包文件已验证: 成功 90 / 总计 90 (100%)
         Terraform 状态版本已验证: 成功 65 / 总计 65 (100%)
             笔记仓库已验证: 成功 63 / 总计 63 (100%)
          组维基仓库已验证: 成功 14 / 总计 14 (100%)
               流水线制品已验证: 成功 112 / 总计 112 (100%)
                页面部署已验证: 成功 55 / 总计 55 (100%)
                          上传已验证: 成功 2 / 总计 2 (100%)
                    作业制品已验证: 成功 32 / 总计 32 (100%)
                  CI 安全文件已验证: 成功 44 / 总计 44 (100%)
         依赖代理 Blob 已验证: 成功 15 / 总计 15 (100%)
       依赖代理清单已验证: 成功 2 / 总计 2 (100%)
        项目维基仓库已验证: 成功 2 / 总计 2 (100%)
   设计管理仓库已验证: 成功 1 / 总计 1 (100%)
             项目仓库已验证: 成功 2 / 总计 2 (100%)

所有对象均已复制和验证，其定义可参考 Geo 术语表。有关我们用于复制和验证每种数据类型的方法的更多信息，请参阅 支持的 Geo 数据类型。

若需查找更多关于失败项目的详细信息，请查看 gitlab-rails/geo.log 文件

如果发现复制或验证失败，您可以尝试 解决这些问题。

修复运行 Geo 检查 Rake 任务时发现的错误

运行此 Rake 任务时，若节点未正确配置，可能会看到错误消息：

sudo gitlab-rake gitlab:geo:check

  • 连接数据库时，Rails 未提供密码。

    Checking Geo ...

GitLab Geo is available ... Exception: fe_sendauth: no password supplied
GitLab Geo is enabled ... Exception: fe_sendauth: no password supplied
...
Checking Geo ... Finished

    确保 gitlab_rails['db_password'] 已设置为创建 postgresql['sql_user_password'] 哈希时所用的明文密码。

  • Rails 无法连接到数据库。

    Checking Geo ...

GitLab Geo is available ... Exception: FATAL:  no pg_hba.conf entry for host "1.1.1.1",  user "gitlab", database "gitlabhq_production", SSL on
FATAL:  no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off
GitLab Geo is enabled ... Exception: FATAL:  no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL on
FATAL:  no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off
...
Checking Geo ... Finished

    确保 postgresql['md5_auth_cidr_addresses'] 中包含 Rails 节点的 IP 地址。同时，确保 IP 地址包含子网掩码：postgresql['md5_auth_cidr_addresses'] = ['1.1.1.1/32']。

  • Rails 提供了错误的密码。

    Checking Geo ...
GitLab Geo is available ... Exception: FATAL:  password authentication failed for user "gitlab"
FATAL:  password authentication failed for user "gitlab"
GitLab Geo is enabled ... Exception: FATAL:  password authentication failed for user "gitlab"
FATAL:  password authentication failed for user "gitlab"
...
Checking Geo ... Finished

    通过运行 gitlab-ctl pg-password-md5 gitlab 并输入密码，验证为 postgresql['sql_user_password'] 创建哈希时使用的 gitlab_rails['db_password'] 是否设置了正确密码。

  • 检查返回 not a secondary node。

    Checking Geo ...

GitLab Geo is available ... yes
GitLab Geo is enabled ... yes
GitLab Geo tracking database is correctly configured ... not a secondary node
Database replication enabled? ... not a secondary node
...
Checking Geo ... Finished

    确保已在主站点的 Web 界面中，于 管理（Admin） 区域下的 Geo > Sites 下添加了辅助站点。同时，确保在主站点的 管理（Admin） 区域中添加辅助站点时，输入了 gitlab_rails['geo_node_name']。

  • 检查返回 Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist。

    Checking Geo ...

GitLab Geo is available ... no
  Try fixing it:
  Add a new license that includes the GitLab Geo feature
  For more information see:
  https://about.gitlab.com/features/gitlab-geo/
GitLab Geo is enabled ... Exception: PG::UndefinedTable: ERROR:  relation "geo_nodes" does not exist
LINE 8:                WHERE a.attrelid = '"geo_nodes"'::regclass
                                           ^
:               SELECT a.attname, format_type(a.atttypid, a.atttypmod),
                     pg_get_expr(d.adbin, d.adrelid), a.attnotnull, a.atttypid, a.atttypmod,
                     c.collname, col_description(a.attrelid, a.attnum) AS comment
                FROM pg_attribute a
                LEFT JOIN pg_attrdef d ON a.attrelid = d.adrelid AND a.attnum = d.num
                LEFT JOIN pg_type t ON a.atttypid = t.oid
                LEFT JOIN pg_collation c ON a.attcollation = c.oid AND a.attcollation <> t.typcollation
               WHERE a.attrelid = '"geo_nodes"'::regclass
                 AND a.attnum > 0 AND NOT a.attisdropped
               ORDER BY a.attnum
...
Checking Geo ... Finished

    执行 PostgreSQL 主版本升级（9 → 10）时出现此情况属预期行为。请遵循 initiate-the-replication-process 操作。

  • Rails 似乎没有连接 Geo 跟踪数据库所需的配置。

    Checking Geo ...

GitLab Geo is available ... yes
GitLab Geo is enabled ... yes
GitLab Geo tracking database is correctly configured ... no
Try fixing it:
Rails does not appear to have the configuration necessary to connect to the Geo tracking database. If the tracking database is running on a node other than this one, then you may need to add configuration.
...
Checking Geo ... Finished

  • 如果您在独立节点上运行次要站点的跟踪数据库，请遵循多服务器 Geo 配置 Geo 次要站点的 Geo 跟踪数据库

消息：机器时钟已同步……异常

Rake 任务试图验证服务器时钟是否与 NTP 同步。Geo 正确运行需要同步的时钟。例如，出于安全考虑，当主站和副站的服务器时间相差约一分钟或更久时，跨 Geo 站点的请求会失败。如果此检查任务因非时间不匹配的原因而未能完成，并不一定意味着 Geo 无法正常工作。

执行检查的 Ruby gem 内部硬编码了 pool.ntp.org 作为其参考时间源。

  • 异常消息 Machine clock is synchronized ... Exception: Timeout::Error

    当您的服务器无法访问主机 pool.ntp.org 时会出现此问题。

  • 异常消息 Machine clock is synchronized ... Exception: No route to host - recvfrom(2)

    当域名 pool.ntp.org 解析到的服务器不提供时间服务时会出现此问题。

在这种情况下，在 GitLab 15.7 及更高版本中，使用环境变量指定自定义 NTP 服务器。

在 GitLab 15.6 及更早版本中，请使用以下解决方法之一：

  • 在 /etc/hosts 中添加 pool.ntp.org 条目，将请求定向到有效的本地时间服务器。这可修复长时间超时和超时错误。
  • 直接将检查定向到任何有效 IP 地址。这解决了超时问题，但检查会像之前所述那样以 No route to host 错误失败。

云原生 GitLab 部署 会生成错误，因为 Kubernetes 中的容器无法访问主机时钟：

Machine clock is synchronized ... Exception: getaddrinfo: Servname not supported for ai_socktype
消息：cannot execute INSERT in a read-only transaction

当在副站遇到此错误时，它可能会影响 GitLab Rails 的所有用法（如 gitlab-rails 或 gitlab-rake 命令），以及 Puma、Sidekiq 和 Geo 日志游标服务等。

ActiveRecord::StatementInvalid: PG::ReadOnlySqlTransaction: ERROR:  cannot execute INSERT in a read-only transaction
/opt/gitlab/embedded/service/gitlab-rails/app/models/application_record.rb:86:in `block in safe_find_or_create_by'
/opt/gitlab/embedded/service/gitlab-rails/app/models/concerns/cross_database_modification.rb:92:in `block in transaction'
/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/database.rb:332:in `block in transaction'
/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/database.rb:331:in `transaction'
/opt/gitlab/embedded/service/gitlab-rails/app/models/concerns/cross_database_modification.rb:83:in `transaction'
/opt/gitlab/embedded/service/gitlab-rails/app/models/application_record.rb:86:in `safe_find_or_create_by'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:21:in `by_name'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `block in populate!'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `map'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `populate!'
/opt/gitlab/embedded/service/gitlab-rails/config/initializers/fill_shards.rb:9:in `<top (required)>'
/opt/gitlab/embedded/service/gitlab-rails/config/environment.rb:7:in `<top (required)>'
/opt/gitlab/embedded/bin/bundle:23:in `load'
/opt/gitlab/embedded/bin/bundle:23:in `<main>'

PostgreSQL 只读副本数据库会产生这些错误：

2023-01-17_17:44:54.64268 ERROR:  cannot execute INSERT in a read-only transaction
2023-01-17_17:44:54.64271 STATEMENT:  /*application:web,db_config_name:main*/ INSERT INTO "shards" ("name") VALUES ('storage1') RETURNING "id"

这种情况可能发生在：

  • 初始配置期间，此时副站尚未意识到自身是副站。要解决此错误，请按照 第 3 步：添加副站 操作。

  • 升级 Geo 副站期间。可能是 gitlab_rails['auto_migrate'] 设置为 true 导致 GitLab 尝试在不需要的副本数据库上执行数据库迁移。要解决此错误：

    1. 以 root 身份通过 SSH 登录至副站的 GitLab Rails 节点。

    2. 编辑 /etc/gitlab/gitlab.rb，注释掉此设置或将其设为 false：

      gitlab_rails['auto_migrate'] = false

    3. 重新配置 GitLab：

      sudo gitlab-ctl reconfigure

检查 PostgreSQL 复制是否正常运行

要检查 PostgreSQL 复制是否正常运行，需确认：

如果您仍有问题，请参阅 高级复制故障排除。

站点是否指向正确的数据库节点？

您应确保您的主要（Primary） Geo 站点指向具有写权限的数据库节点。

任何次要（Secondary） 站点应仅指向只读数据库节点。

Geo能否正确检测当前站点？

Geo通过以下逻辑在 /etc/gitlab/gitlab.rb 中查找当前Puma或Sidekiq节点的Geo 站点名称：

  1. 获取“Geo节点名称”（存在将其重命名为“Geo站点名称”的问题）：
    • Linux包：获取 gitlab_rails['geo_node_name'] 设置。
    • GitLab Helm图表：获取 global.geo.nodeName 设置（参见带GitLab Geo的图表）。
  2. 如果未定义，则获取 external_url 设置。

此名称用于在Geo站点仪表板中查找具有相同名称的Geo站点。

若要检查当前机器的站点名称是否与数据库中的站点匹配，请运行检查任务：

sudo gitlab-rake gitlab:geo:check

它显示当前机器的站点名称以及匹配的数据库记录是主要（Primary） 还是次要（Secondary） 站点。

This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai"
This machine's Geo node name matches a database record ... no
  Try fixing it:
  您可以添加或更新一个Geo节点数据库记录，将名称设置为"https://example.com/"。
  或您可以将此机器的Geo节点名称调整为与现有数据库记录的名称一致："London"、"Shanghai"
  更多信息请参阅：
  doc/administration/geo/replication/troubleshooting/_index.md#can-geo-detect-the-current-node-correctly

有关名称字段描述中推荐站点名称的更多信息，请参阅Geo 管理（Admin） 区域通用设置。

检查操作系统locale数据兼容性

如果可能，所有站点的所有Geo节点应使用相同的方法和操作系统部署，如运行Geo的要求所述。

如果在Geo站点间部署了不同的操作系统或版本，则在设置Geo前必须执行locale数据兼容性检查。使用混合GitLab部署方法时，还须检查glibc。Linux包安装、GitLab Docker容器、Helm图表部署或外部数据库服务之间的locale可能不同。请参阅升级PostgreSQL操作系统的文档，包括如何检查glibc版本兼容性。

Geo使用PostgreSQL和流复制跨Geo站点复制数据。PostgreSQL使用操作系统C库提供的locale数据进行文本排序。如果各Geo站点的C库locale数据不兼容，会导致查询结果错误，进而引发次要站点的不当行为。

例如，Ubuntu 18.04（及更早版本）与RHEL/CentOS 7（及更早版本）与其后续版本不兼容。更多详情请参阅PostgreSQL Wiki。

修复常见错误

本节记录Web界面管理（Admin） 区域报告的常见错误消息及其解决方法。

现有跟踪数据库无法重复使用

Geo 无法重用现有的跟踪数据库。

最安全的做法是使用全新的二级节点，或按照 重置 Geo 二级站点复制 的指引重置整个二级节点。

如果在不重置二级节点的情况下重用它，会存在风险，因为该二级节点可能遗漏了一些 Geo 事件。例如，遗漏删除事件会导致二级节点永久保留本应被删除的数据；同样，丢失物理移动数据位置的事件会导致数据在一个位置永久孤立，而在另一个位置缺失，直到重新验证。这也是 GitLab 切换到哈希存储的原因——它让移动数据变得不再必要。由于事件丢失，还可能出现其他未知问题。

如果这些风险不适用（例如在测试环境中），或者你知道自添加 Geo 站点以来主 PostgreSQL 数据库仍包含所有 Geo 事件，则可以跳过此健康检查：

  1. 获取最后处理的事件时间。在 secondary 站点的 Rails 控制台中运行：

    Geo::EventLogState.last.created_at.utc

  2. 复制输出结果，例如 2024-02-21 23:50:50.676918 UTC。

  3. 更新二级站点的创建时间，使其看起来更早。在 primary 站点的 Rails 控制台中运行：

    GeoNode.secondary_nodes.last.update_column(:created_at, DateTime.parse('2024-02-21 23:50:50.676918 UTC') - 1.second)

    此命令假设受影响的二级节点是最近创建的那个。

  4. 在 Admin > Geo > Sites 中更新二级站点的状态。在 secondary 站点的 Rails 控制台中运行：

    Geo::MetricsUpdateWorker.new.perform

  5. 二级站点应显示为健康状态。如果不是，请在二级站点上运行 gitlab-rake gitlab:geo:check，或在重新添加二级站点后尚未重启 Rails 时尝试重启 Rails。

  6. 若要重新同步缺失或过时的数据，请前往 Admin > Geo > Sites。

  7. 在二级站点下选择 Replication Details。

  8. 为每种数据类型选择 Reverify all。

Geo 站点拥有可写入的数据库

此错误消息指向 secondary 站点的数据库副本存在问题——Geo 预期该副本应为只读。二级站点的数据库可写入，表明该数据库未针对与主站点的复制进行配置。通常意味着以下情况之一：

  • 使用了不受支持的复制方法（例如逻辑复制）。
  • 未正确遵循 Geo 数据库复制 的设置说明。
  • 数据库连接详情错误，即你在 /etc/gitlab/gitlab.rb 文件中指定了错误的用户。

Geo secondary 站点需要两个独立的 PostgreSQL 实例：

  • 主站点的只读副本。
  • 一个常规的可写入实例，用于存储复制元数据（即 Geo 跟踪数据库）。

此错误消息表明二级站点的副本数据库配置错误，复制已停止。

要恢复数据库并继续复制，你可以执行以下任一操作：

如果你从头开始搭建新的二级节点，还必须 从 Geo 集群中移除旧站点。

Geo 站点似乎没有从主站点复制数据库

阻止数据库正确复制的最常见问题包括：

  • secondary 站点无法访问 primary 站点。检查凭证和 防火墙规则。
  • SSL 证书问题。确保你已从 primary 站点复制了 /etc/gitlab/gitlab-secrets.json。
  • 数据库存储磁盘已满。
  • 数据库复制槽配置错误。
  • 数据库未使用复制槽或其他替代方案，且因 WAL 文件被清理而无法追上进度。

请务必遵循 Geo 数据库复制 指南以获得支持的配置。

Geo 数据库版本（…）与最新迁移（…）不匹配

如果你使用的是 Linux 包安装方式，升级过程中可能出现了故障。你可以：

  • 运行 sudo gitlab-ctl reconfigure。
  • 以 root 身份在 secondary 站点上手动触发数据库迁移：sudo gitlab-rake db:migrate:geo。

GitLab 显示超过 100% 的仓库已同步

这可能是项目注册表中存在孤儿记录导致的。注册表工作器会定期清理这些记录，因此给它一些时间自行修复即可。

主站点校验和不匹配

通过地理主节点验证信息屏幕识别出的校验和不匹配，可能由缺失文件或不匹配的校验和引起。你可以在 gitlab-rails/geo.log 文件中发现类似 "Repository cannot be checksummed because it does not exist" 或 "File is not checksummable" 的错误信息。

若需获取失败项的额外信息，运行完整性检查 Rake 任务：

sudo gitlab-rake gitlab:artifacts:check
sudo gitlab-rake gitlab:ci_secure_files:check
sudo gitlab-rake gitlab:lfs:check
sudo gitlab-rake gitlab:uploads:check

若需获取单个错误的详细信息，可使用 VERBOSE=1 变量。

次级站点在UI中显示“不健康”状态

如果你已更新主站点 /etc/gitlab/gitlab.rb 中 external_url 的值，或将从 http 切换为 https 协议，可能会看到次级站点显示为 Unhealthy。你也可能在 geo.log 中发现如下错误：

"class": "Geo::NodeStatusRequestService",
...
"message": "Failed to Net::HTTP::Post to primary url: http://primary-site.gitlab.tld/api/v4/geo/status",
  "error": "Failed to open TCP connection to <PRIMARY_IP_ADDRESS>:80 (Connection refused - connect(2) for \"<PRIMARY_ID_ADDRESS>\" port 80)"

此时，请确保在所有站点上更新变更后的URL：

  1. 在左侧边栏底部选择 管理。
  2. 选择 地理 > 站点。
  3. 更改URL并保存更改。

备份期间出现消息：ERROR: canceling statement due to conflict with recovery

在地理次级节点上执行备份不受支持。

在次级节点上运行备份时，可能会遇到以下错误信息：

Dumping PostgreSQL database gitlabhq_production ...
pg_dump: error: Dumping the contents of table "notes" failed: PQgetResult() failed.
pg_dump: error: Error message from server: ERROR:  canceling statement due to conflict with recovery
DETAIL:  User query might have needed to see row versions that must be removed.
pg_dump: error: The command was: COPY public.notes (id, note, [...], last_edited_at) TO stdout;

为防止在GitLab升级过程中自动对地理次级节点执行数据库备份，请创建以下空文件：

sudo touch /etc/gitlab/skip-auto-backup

对象验证期间主节点CPU使用率过高

从GitLab 16.11到GitLab 17.2，缺少PostgreSQL索引会导致CPU使用率升高且工件验证进度缓慢。此外，地理次级站点可能报告为不健康。问题471727详细描述了该行为。

若需确定是否受此问题影响，请按照确认是否受影响的步骤操作。

若受影响，请按照解决方法中的步骤手动创建索引。创建索引会使PostgreSQL消耗更多资源直至完成。之后，验证继续时CPU使用率可能仍较高，但查询应显著加快，且次级站点状态应正确更新。

验证失败，提示：Verification timed out after (...)

从 GitLab 16.11 开始，Geo 可能会为同一个 artifact_id 创建重复的 JobArtifactRegistry 条目，这可能导致主站和从站之间的同步失败。此问题也可能影响 UploadRegistry 和 PackageFileRegistry 条目。

若需判断是否受此问题影响并移除重复条目，请执行以下步骤：

  1. 在次级站点打开 Rails 控制台。

  2. 获取存在重复记录的模型记录 ID 数量：

    artifact_ids = Geo::JobArtifactRegistry.group(:artifact_id).having('COUNT(*) > 1').pluck(:artifact_id); artifact_ids.size
upload_ids = Geo::UploadRegistry.group(:file_id).having('COUNT(*) > 1').pluck(:file_id); upload_ids.size
package_file_ids = Geo::PackageFileRegistry.group(:package_file_id).having('COUNT(*) > 1').pluck(:package_file_id); package_file_ids.size

  3. 输出 ID：

    puts '开始 工件 ID', artifact_ids, '结束 工件 ID'
puts '开始 上传 ID', upload_ids, '结束 上传 ID'
puts '开始 包文件 ID', package_file_ids, '结束 包文件 ID'

    若输出为空，则未受影响。否则，将终端输出保存至文本文件，以防后续连接中断。

  4. 删除所有重复条目：

    Geo::JobArtifactRegistry.where(artifact_id: artifact_ids).delete_all
Geo::UploadRegistry.where(file_id: upload_ids).delete_all
Geo::PackageFileRegistry.where(package_file_id: package_file_ids).delete_all

  5. 等待后台作业重新创建注册表行并完成同步。

可通过 issue 479852 跟踪修复进展。

在次级站点运行 Geo Rake 检查任务时出现 end of file reached 错误

在次级站点运行 健康检查 Rake 任务 时，可能会遇到以下错误：

Can connect to the primary node ... no
Reason:
end of file reached

若主站点设置的 URL 不正确，可能出现此情况。排查方法如下：在 Rails 控制台 中运行以下命令：

primary = Gitlab::Geo.primary_node
primary.internal_uri
Gitlab::HTTP.get(primary.internal_uri, allow_local_requests: true, limit: 10)

检查前述输出中 internal_uri 的值是否正确。若主站点 URL 有误，请在 /etc/gitlab/gitlab.rb 及 Admin > Geo > Sites 中重新核对。

Geo 指标收集导致的数据库 IO 过高

若因频繁的 Geo 指标收集导致数据库负载过高，可降低 geo_metrics_update_worker 作业的执行频率，以缓解大型 GitLab 实例中指标收集对数据库性能的显著影响。

提高间隔意味着 Geo 指标更新频率降低，会导致指标过期时间延长，进而影响实时监控 Geo 复制的能力。若指标过期超过 10 分钟，站点会在管理区域被任意标记为“ unhealthy ”。

以下示例将作业设置为每 30 分钟运行一次，可根据需求调整 Cron 计划。

  1. 在 /etc/gitlab/gitlab.rb 中添加或修改以下设置：

    gitlab_rails['geo_metrics_update_worker_cron'] = "*/30 * * * *"

  2. 重新配置 GitLab：

    sudo gitlab-ctl reconfigure

  1. 编辑 /home/git/gitlab/config/gitlab.yml：

    production: &base
  ee_cron_jobs:
    geo_metrics_update_worker:
      cron: "*/30 * * * *"

  2. 保存文件并重启 GitLab：

    # 对于使用 systemd 的系统
sudo systemctl restart gitlab.target

# 对于使用 SysV init 的系统
sudo service gitlab restart