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

Geo

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

Geo 是为广泛分布的开发团队提供的解决方案，同时也是灾难恢复策略中的热备份方案。Geo 不是一个开箱即用的高可用性解决方案。

Geo 在每个版本发布时都会发生重大变化。升级是受支持的并且有文档说明，但您需要确保使用与您的安装版本对应的正确文档版本。

为确保您使用的是正确的文档版本，请访问 GitLab.com 上的 Geo 页面，并从 Switch branch/tag 下拉列表中选择相应的版本。例如，v15.7.6-ee。

对于距离单个 GitLab 实例较远的团队和 Runner 来说，获取大型仓库可能需要很长时间。

Geo 提供本地缓存，可以放置在靠近远程团队的位置，用于处理读取请求。这可以减少克隆和获取大型仓库所需的时间，加快开发速度，提高远程团队的工作效率。

Geo 从站透明地将写入请求代理到主站。所有 Geo 站点都可以配置为响应单个 GitLab URL，无论用户访问哪个站点，都能提供一致、无缝且全面的使用体验。

Geo 使用一组定义的术语，这些术语在 Geo 术语表 中有描述。请务必熟悉这些术语。

使用场景

实现 Geo 可以解决多种使用场景。本节提供了一些预期的使用场景及其优势。

区域灾难恢复

Geo 作为灾难恢复解决方案，为您在不同于主站的区域提供一个热备份从站。数据会持续同步到从站，确保数据始终是最新的。在发生灾难（如数据中心或网络中断或硬件故障）时，您可以故障转移到完全可用的从站。您可以使用计划性故障转移来测试灾难恢复流程和基础设施。

优势：

  • 在区域灾难发生时保持业务连续性。
  • 低恢复时间目标（RTO）和恢复点目标（RPO）。
  • 使用 GitLab Environment Toolkit (GET) 实现自动化（但非自动）故障转移。
  • 最少的运维工作量 - 无需干预的持续复制和验证确保您的从站保持最新状态，并且在传输和静态时复制的数据不会损坏。

远程团队加速

在地理位置上更靠近您的远程团队建立 Geo 从站，提供加速读取操作的本地缓存。您可以拥有多个 Geo 从站，每个从站都专门同步您的远程团队需要的项目。透明代理和统一 URL的地理路由确保了一致且无缝的开发者体验。

优势：

  • 改善地理分布团队的 GitLab 体验。Geo 在从站上提供完整的 GitLab 体验：维护一个主 GitLab 站点，同时为每个分布式团队启用具有读写访问权限和完整 UI 体验的从站。
  • 将分布式开发者克隆和获取大型仓库及项目的时间从分钟级减少到秒级。
  • 使所有开发者无论身在何处都能并行贡献想法和工作。
  • 在主站和从站之间平衡读取负载。
  • 克服远程办公室之间的慢速连接，通过提高分布式团队的速度来节省时间。
  • 减少自动化任务、自定义集成和内部工作流的加载时间。

CI/CD 流量卸载

您可以将 CI/CD Runner 配置为从 Geo 从站克隆。您可以根据 Runner 工作负载的需求定制从站，无需镜像主站。支持的读取请求由从站上的缓存数据提供服务，当从站上的数据过时或不可用时，请求会透明地转发到主站。

优势：

  • 在主站上，通过将流量转移到从站来减少 CI/CD 流量对用户体验的影响。
  • 减少跨区域流量，并将 CI/CD 计算时间定位到对组织最经济的地区。创建单一跨区域数据副本，使其可用于对从站的重复读取请求。

其他使用场景

基础设施迁移

您可以使用 Geo 迁移到新基础设施。如果您将 GitLab 实例移动到新服务器或数据中心，可以使用 Geo 在后台将 GitLab 数据迁移到新实例，同时旧实例继续为您的用户提供服务。活动 GitLab 数据的任何更改都会复制到新实例，因此在切换过程中不会丢失数据。

您不能使用 Geo 将 PostgreSQL 数据库从一个操作系统迁移到另一个操作系统。请参阅升级 PostgreSQL 操作系统。

优势：

  • 与备份和恢复迁移方法相比，显著减少迁移期间的停机时间。在切换停机时间窗口之前，无需停止活动的 GitLab 实例，即可在后台将数据复制到新实例。

迁移到 GitLab Dedicated

您也可以使用 Geo 将 GitLab Self-Managed 迁移到 GitLab Dedicated。迁移到 GitLab Dedicated 与基础设施迁移类似。

优势：

  • 显著降低停机时间，提供更顺畅的入职体验。在后台进行数据迁移时，您的团队可以继续使用 GitLab Self-Managed。

Geo 不适用的场景

Geo 并非为所有使用场景而设计。本节提供了一些 Geo 不适用作为解决方案的使用场景示例。

强制数据导出合规性

虽然 Geo 的选择性同步功能允许您限制同步到从站的项目，但其设计目的是减少跨区域流量和存储需求，而非强制执行导出合规性。您必须根据解决方案和文档，持续独立确定您在隐私、网络安全和适用贸易管制法律方面的法律义务。解决方案和文档都可能发生变化。

提供访问控制

Geo只读从站功能不是一流功能，将来可能不再支持。您不应依赖此功能进行访问控制。GitLab 提供了更适合此目的的认证和授权控制。

零停机升级的替代方案

Geo 不是零停机升级的解决方案。您必须先升级主 Geo 站点，然后才能升级从站。

防止恶意或意外损坏

Geo 会将主站上的损坏复制到所有从站。为了防止恶意或意外损坏，您应该将 Geo 与备份结合使用。

主动-主动、高可用性配置

Geo 设计为主动-被动、高可用性解决方案。它采用最终一致性同步模型，这意味着从站与主站不是紧密同步的。从站跟随主站但有轻微延迟，这可能导致灾难发生后少量数据丢失。灾难时故障转移到从站需要人工干预。但是，只要您使用 GitLab Environment Toolkit (GET) 部署所有站点，将从站提升为主站的大部分过程都是自动化的。

Gitaly Cluster (Praefect)

不应将 Geo 与 Gitaly Cluster (Praefect) 混淆。有关 Geo 和 Gitaly Cluster (Praefect) 之间差异的更多信息，请参阅与 Geo 的比较。

Geo 工作原理

这是 Geo 在您的 GitLab 环境中工作方式的简要概述。有关更多详细信息，请参阅 Geo 开发文档。

您的 Geo 实例除了读取任何数据外，还可用于克隆和获取项目。这使得在远距离处理大型仓库的工作速度大大加快。

Geo 概览

启用 Geo 时：

  • 原始实例称为主站。
  • 复制站点称为从站。

请记住：

  • 从站与主站通信以：
    • 获取登录用户数据（API）。
    • 复制仓库、LFS 对象和附件（HTTPS + JWT）。
  • 主站与从站通信以查看复制详情。主站对从站执行 GraphQL 查询以获取同步和验证数据（API）。
  • 您可以直接推送到从站（包括 HTTP 和 SSH，包括 Git LFS），它会将请求代理到主站。
  • 使用 Geo 时存在一些已知问题。

架构

下图说明了 Geo 的底层架构。

Geo 架构

在此图中：

  • 有主站和一个从站的详细信息。
  • 数据库写入只能在主站上执行。从站通过使用 PostgreSQL 流式复制接收数据库更新。
  • 如果存在，LDAP 服务器应配置为在灾难恢复场景下进行复制。
  • 从站对主站执行不同类型的同步，使用 JWT 保护的专用授权：
    • 仓库通过 Git over HTTPS 克隆/更新。
    • 附件、LFS 对象和其他文件通过 HTTPS 使用私有 API 端点下载。

从执行 Git 操作的用户角度来看：

  • 主站表现为完整的读写 GitLab 实例。
  • 从站表现为完整的读写 GitLab 实例。从站透明地将所有操作代理到主站，但有一些显著例外。特别是，当从站是最新的时，Git 获取请求由从站提供服务。

从浏览 GitLab UI 或使用 API 的用户角度来看：

  • 主站表现为完整的读写 GitLab 实例。
  • 从站表现为完整的读写 GitLab 实例。从站透明地将所有操作代理到主站，但有一些显著例外。特别是，Web UI 资源由从站提供服务。

为简化图表，省略了一些必要组件。

从站需要两个不同的 PostgreSQL 数据库：

从站还运行一个额外的守护进程：Geo 日志游标。

运行 Geo 的要求

运行 Geo 需要以下条件：

此外，请检查 GitLab最低要求，并使用最新版本的 GitLab以获得更好的体验。

防火墙规则

下表列出了 Geo 中主站和从站之间必须开放的基本端口。为简化故障转移，您应双向开放端口。

源站点 源端口 目标站点 目标端口 协议
主站 任意 从站 80 TCP (HTTP)
主站 任意 从站 443 TCP (HTTPS)
从站 任意 主站 80 TCP (HTTP)
从站 任意 主站 443 TCP (HTTPS)
从站 任意 主站 5432 TCP
从站 任意 主站 5000 TCP (HTTPS)

GitLab 使用的完整端口列表请参见包默认值

Web 终端支持需要您的负载均衡器正确处理 WebSocket 连接。 当使用 HTTP 或 HTTPS 代理时，您的负载均衡器必须配置为传递 Connection 和 Upgrade 逐跳头。更多详细信息请参阅Web 终端集成指南。

当使用 HTTPS 协议用于端口 443 时，您必须向负载均衡器添加 SSL 证书。 如果您希望在 GitLab 应用服务器上终止 SSL，请使用 TCP 协议。

如果您仅对外部/内部 URL 使用 HTTPS，则无需在防火墙中开放端口 80。

内部 URL

任何 Geo 从站到主 Geo 站的 HTTP 请求都使用主 Geo 站的内部 URL。如果这未在管理员区域的主 Geo 站设置中明确定义，则使用主站的公共 URL。

要更新主 Geo 站的内部 URL：

  1. 在左侧边栏底部，选择管理员。
  2. 选择Geo > 站点。
  3. 选择主站的编辑。
  4. 更改内部 URL，然后选择保存更改。

Geo 跟踪数据库

跟踪数据库实例用作元数据来控制本地实例需要更新什么。例如：

  • 下载新资源。
  • 获取新的 LFS 对象。
  • 获取最近更新的仓库的更改。

因为复制的数据库实例是只读的，我们需要为每个从站提供这个额外的数据库实例。

Geo 日志游标

此守护进程：

  • 读取主站复制到从站数据库实例的事件日志。
  • 使用必须执行的更改更新 Geo 跟踪数据库实例。

当跟踪数据库实例中的某些内容被标记为需要更新时，在从站上运行的后台作业会执行所需操作并更新状态。

这种新架构使 GitLab 能够抵御站点之间的连接问题。从站与主站断开连接多长时间并不重要，因为它能够按正确顺序重播所有事件并再次与主站同步。

已知问题

这些已知问题仅反映最新版本的 GitLab。如果您使用的是旧版本，可能存在其他问题。

  • 直接推送到从站会将请求重定向（HTTP）或代理（SSH）到主站，而不是直接处理。您不能使用带有嵌入 URI 凭证的 Git over HTTP，例如 https://user:[email protected]。更多信息，请参阅如何使用 Geo 站点。
  • 主站必须在线才能进行 OAuth 登录。现有会话和 Git 不受影响。支持从站使用独立于主站的 OAuth 提供商正在计划中。
  • 安装涉及多个手动步骤，根据情况可能需要约一个小时。考虑使用 GitLab Environment Toolkit Terraform 和 Ansible 脚本来部署和操作基于我们参考架构的生产 GitLab 实例，包括自动化常见日常任务。Epic 1465 提议进一步改进 Geo 安装。
  • 在禁用 HTTP 代理的从站上，问题/合并请求的实时更新（例如通过长轮询）不起作用。
  • 选择性同步仅限制复制哪些仓库和文件。整个 PostgreSQL 数据仍然会被复制。选择性同步并非为满足合规/出口管制用例而构建。
  • Pages 访问控制在从站上不起作用。更多详细信息请参阅问题 9336。
  • 对于具有多个从站的部署，灾难恢复会导致停机，因为需要在所有未提升的从站上重新初始化 PostgreSQL 流式复制以跟随新的主站。
  • 对于 Git over SSH，无论您浏览哪个站点，要使项目克隆 URL 显示正确，从站必须使用与主站相同的端口。更多信息请参阅问题 339262。
  • 通过 SSH 向从站推送超过 1.86 GB 的推送不起作用。问题 413109 跟踪此错误。
  • 备份不能在 Geo 从站上运行。
  • 通过 SSH 向从站推送带有选项的 Git 不起作用并终止连接。更多信息请参阅问题 417186。
  • 在大多数情况下，Geo 从站不会加速（服务）管道第一阶段的克隆请求。后续阶段也不保证由从站提供服务，例如如果 Git 更改很大、带宽很小或管道阶段很短。通常，它确实会为后续阶段提供克隆请求。问题 446176 讨论了此原因并提议增强功能以增加 Runner 克隆请求由从站服务的可能性。
  • 当单个 Git 仓库以足够高的速率接收推送时，从站的本地副本可能永远过时。这会导致该仓库的所有 Git 获取请求都转发到主站。更多信息请参阅问题 455870。
  • 代理仅在 Puma 服务或 Web 服务中的 GitLab 应用程序中实现，因此其他服务不会受益于此行为。您应使用单独的 URL来确保请求始终发送到主站。这些服务包括：
  • 使用统一 URL时，Let’s Encrypt 无法生成证书，除非它能够通过同一域访问两个 IP。要使用 TLS 证书与 Let’s Encrypt，您可以手动将域指向其中一个 Geo 站点，生成证书，然后将其复制到所有其他站点。
  • 当从站使用与主站不同的单独 URL时，在从站中使用 SAML 登录仅当 SAML 身份提供者 (IdP) 允许配置具有多个回调 URL 的应用程序时才受支持。
  • 通过 SSH 对从站进行带有选项 --depth 的 Git 克隆和获取请求不起作用，如果在请求发起时从站未更新，则会无限挂起。这是由于代理期间将 Git SSH 转换为 Git https 的问题。更多信息请参阅问题 391980。现在有一个新工作流可用于 Linux 包装的 GitLab Geo 从站，可通过功能标志启用。更多详细信息请参阅问题 454707 中的评论。Cloud Native GitLab Geo 从站的修复在问题 5641中跟踪。
  • 一些用户报告说，当从站过时时，通过 SSH 的 git fetch 会挂起和/或超时并失败。通过 SSH 的 git clone 请求不受影响。更多信息请参阅问题 454707。适用于 Linux 包装的 GitLab Geo 从站的修复可用，可通过功能标志启用。更多详细信息请参阅问题 454707 中的评论。Cloud Native GitLab Geo 从站的修复在问题 5641中跟踪。
  • 不要将相对 URL与 GitLab Geo 一起使用，因为它们会破坏站点之间的代理。更多信息请参阅问题 456427。

复制的数据类型

所有 GitLab 数据类型和复制的数据类型的完整列表。

安装后文档

在从站上安装 GitLab并执行初始配置后，请参阅以下文档获取安装后信息。

设置 Geo

有关配置 Geo 的信息，请参阅设置 Geo。

使用对象存储配置 Geo

有关使用对象存储配置 Geo 的信息，请参阅使用对象存储的 Geo。

复制容器注册表

有关如何复制容器注册表的更多信息，请参阅从站的容器注册表。

为 Geo 站点设置统一 URL

有关如何使用 AWS Route53 或 Google Cloud DNS 设置单个位置感知 URL 的示例，请参阅为 Geo 站点设置统一 URL。

单点登录 (SSO)

有关配置单点登录 (SSO) 的更多信息，请参阅使用单点登录 (SSO) 的 Geo。

LDAP

有关配置 LDAP 的更多信息，请参阅使用单点登录 (SSO) 的 Geo > LDAP。

调优 Geo

有关调优 Geo 的更多信息，请参阅调优 Geo。

暂停和恢复复制

有关更多信息，请参阅暂停和恢复复制。

回填

当设置从站时，它会通过称为回填的过程从主站复制缺失的数据。您可以在浏览器的主站的Geo 节点仪表板中监控每个 Geo 站点的同步过程。

回填期间发生的故障安排在回填结束时重试。

Runner

升级 Geo

有关如何将您的 Geo 站点更新到最新 GitLab 版本的信息，请参阅升级 Geo 站点。

安全审查

有关 Geo 安全的更多信息，请参阅Geo 安全审查。

删除 Geo 站点

有关删除 Geo 站点的更多信息，请参阅删除从站Geo 站点。

禁用 Geo

有关如何禁用 Geo 的信息，请参阅禁用 Geo。

日志文件

Geo 将结构化的日志消息存储在 geo.log 文件中。

有关如何访问和使用 Geo 日志的更多信息，请参阅日志系统文档中的 Geo 部分。

灾难恢复

有关在灾难恢复情况下使用 Geo 来减轻数据丢失和恢复服务的信息，请参阅灾难恢复。

常见问题

有关常见问题的答案，请参阅Geo FAQ。

故障排除