极狐 GitLab

Geo

Tier: 专业版，旗舰版

Offering: 私有化部署

Geo 是面向广泛分布的开发团队的解决方案，也可作为灾难恢复策略的一部分提供温备。Geo 并非开箱即用的高可用解决方案。

Geo 在每个版本之间都会发生重大变化。支持升级并已记录在文档中，但您应确保使用的是与您的安装版本对应的正确文档版本。

为确保您使用的是正确的文档版本，请前往 GitLab.com 上的 Geo 页面，然后从 切换分支/标签 下拉列表中选择相应的版本。例如，v19.2.0-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 私有化部署迁移到 GitLab Dedicated。

优势：

  • 更顺畅的入门体验，停机时间显著降低。在后台进行数据迁移时，您的团队可以继续使用极狐GitLab 私有化部署。

Geo 不适用于解决的场景#

Geo 并非旨在解决所有使用场景。本节提供了一些 Geo 不是合适解决方案的使用场景示例。

强制执行数据导出合规性#

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

提供访问控制#

Geo 的只读从站点功能不是一等功能，将来可能不再支持。您不应依赖此功能来实现访问控制目的。极狐GitLab 提供了更适合此目的的身份验证和授权控制。

零停机升级的替代方案#

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

防范恶意或无意的损坏#

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

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

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

Gitaly 集群 (Praefect)#

不应将 Geo 与 Gitaly 集群 (Praefect) 混淆。有关 Geo 与 Gitaly 集群 (Praefect)之间区别的更多信息，请参阅与 Geo 的比较。

Geo 的工作原理#

以下简要概述了 Geo 在您的极狐GitLab 环境中的工作原理。有关更多详细信息，请参阅 Geo 开发文档。

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

Geo 概览

启用 Geo 后：

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

请记住：

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

架构#

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

Geo 架构图，显示主站点和从站点之间通过 PostgreSQL 流式复制进行数据库复制，以及通过 Git HTTP 和私有 API 进行文件复制。

在此图中：

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

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

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

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

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

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

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

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

运行 Geo 的要求#

运行 Geo 需要以下条件：

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

由于 Geo 在基础极狐GitLab 安装之上添加了跟踪数据库和复制元数据，对于没有代码仓库数据的最小 Geo 部署，请为每个站点规划至少 40 GB 的磁盘空间。有关更多详细信息，请参阅存储要求。

防火墙规则#

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

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

请参阅软件包默认值中极狐GitLab 使用的完整端口列表

对于 Geo 站点之间的 PostgreSQL 复制，您必须使用专用网络连接，例如内部 VPC 对等互连。 切勿将 PostgreSQL 端口暴露到互联网。将 PostgreSQL 端口暴露到互联网可能导致未经授权的访问，从而获得对极狐GitLab 数据库的完整写入权限，可能危及您的整个极狐GitLab 实例及所有相关数据。

此外：

  • Web 终端支持要求您的负载均衡器正确处理 WebSocket 连接。 使用 HTTP 或 HTTPS 代理时，您的负载均衡器必须配置为传递 Connection 和 Upgrade 逐跳请求头。有关更多详细信息，请参阅 Web 终端集成指南。
  • 对端口 443 使用 HTTPS 协议时，您必须向负载均衡器添加 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。如果您使用的是较旧版本，可能存在其他问题。

  • 通过 Geo 从站点进行 Git over SSH 无法可靠工作。有关更多信息，请参阅议题 #413109、议题 #417186、议题 #454707 和议题 585913。
  • 直接推送到从站点会将请求重定向（对于 HTTP）或代理（对于 SSH）到主站点，而不是直接处理它。您不能使用 URI 中嵌入凭据的 Git over HTTP，例如 https://user:personal-access-token@secondary.tld。有关更多信息，请参阅如何使用 Geo 站点。
  • 主站点必须在线才能进行 OAuth 登录。现有会话和 Git 不受影响。从站点使用独立于主站点的 OAuth 提供商的支持正在规划中。
  • 安装需要多个手动步骤，根据具体情况，这些步骤总共可能需要大约一个小时。考虑使用 GitLab Environment Toolkit Terraform 和 Ansible 脚本，基于我们的参考架构来部署和运维生产极狐GitLab 实例，包括自动化常见的日常任务。 史诗 1465 提议进一步改进 Geo 安装。
  • 议题/合并请求的实时更新（例如，通过长轮询）在禁用 HTTP 代理的从站点上无法工作。
  • 选择性同步仅限制复制哪些代码仓库和文件。整个 PostgreSQL 数据仍会被复制。选择性同步并非为满足合规/出口管制使用场景而构建。
  • Pages 访问控制在从站点上无法工作。有关更多信息，请参阅议题 9336了解详情。
  • 对于具有多个从站点的部署，灾难恢复会导致停机，因为需要在所有未提升的从站点上重新初始化 PostgreSQL 流式复制，以跟随新的主站点。
  • 对于 Git over SSH，为使项目克隆 URL 无论您浏览哪个站点都能正确显示，从站点必须使用与主站点相同的端口。 有关更多信息，请参阅议题 339262。
  • 备份无法在 Geo 从站点上运行。
  • 在大多数情况下，Geo 从站点不会加速（提供）流水线第一阶段的克隆请求。后续阶段也不保证由从站点提供服务，例如如果 Git 更改很大、带宽很小或流水线阶段很短。一般来说，它确实会为后续阶段提供克隆请求服务。议题 446176 讨论了此问题的原因，并提议进行增强，以提高 Runner 克隆请求由从站点提供服务的可能性。
  • 当单个 Git 代码仓库以足够高的速率接收推送时，从站点的本地副本可能会永远处于过期状态。这会导致该代码仓库的所有 Git 获取都被转发到主站点。有关更多信息，请参阅议题 455870。
  • 代理仅在 Puma 服务或 Web 服务中的极狐GitLab 应用程序中实现，因此其他服务无法从这种行为中受益。您应使用单独的 URL 来确保请求始终发送到主站点。这些服务包括：
    • 极狐GitLab 容器镜像仓库 - 可以配置为使用单独的域，例如 registry.example.com。从站点容器镜像仓库仅用于灾难恢复。不应将用户路由到它们，尤其是推送，因为数据不会传播到主站点。
    • GitLab Pages - 应始终使用单独的域，作为运行 GitLab Pages 的先决条件的一部分。
  • 使用统一 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中跟踪。
  • 不要将相对 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 后台作业。

回填#

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

回填期间发生的失败计划在回填结束时重试。

Runner#

升级 Geo#

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

安全审查#

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

移除 Geo 站点#

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

禁用 Geo#

要了解如何禁用 Geo，请参阅禁用 Geo。

日志文件#

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

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

灾难恢复#

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

常见问题解答#

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

故障排除#