Geo

Geo 是为广泛分布的开发团队以及作为灾难恢复策略的一部分提供热备的解决方案。Geo 不是 开箱即用的高可用解决方案。

为确保您使用正确的文档版本，请前往 JihuLab.com 上的 Geo 页面 并从 切换分支/标签 下拉列表中选择合适的版本。例如，v15.7.6-ee。

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

Geo 提供可以在地理上靠近远程团队放置的本地缓存，这些缓存可以处理读取请求。这可以减少克隆和获取大型仓库所需的时间，加快开发速度并提高远程团队的生产力。

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

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

使用场景#

实施 Geo 可以解决多种使用场景。本节介绍了一些预期的使用场景并强调了它们的好处。

区域灾难恢复#

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

好处：

• 在发生区域性灾难时保持业务连续性。
• 较低的恢复时间目标 (RTO) 和恢复点目标 (RPO)。
• 使用极狐GitLab 环境工具包 (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 Dedicated 类似于基础设施迁移。

有关更多信息，请参阅使用 Geo 迁移到 GitLab Dedicated。

好处：

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

Geo 不适合解决的场景#

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

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

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

提供访问控制#

Geo 只读次要站点功能并非首要功能，未来可能不再支持。您不应依赖此功能进行访问控制。极狐GitLab 提供了身份验证和授权控制，可以更好地服务于这一目的。

零停机升级的替代方案#

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

防范恶意或意外损坏#

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

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

Geo 被设计为主动-被动、高可用性解决方案。它采用最终一致的同步模型，这意味着次要站点与主要站点并非紧密同步。次要站点跟随主要站点有少量延迟，这可能导致在灾难发生后丢失少量数据。发生灾难时故障转移到次要站点需要人工干预。但是，如果您使用 GET 部署所有站点，则提升次要站点成为主要站点的过程的大部分由极狐GitLab 环境工具包 (GET) 自动化。

Gitaly Cluster (Praefect)#

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

Geo 的工作原理#

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

您的 Geo 实例可用于克隆和获取项目，以及读取任何数据。这使得在远距离上处理大型仓库变得更快。

启用 Geo 后：

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

请记住：

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

架构#

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

在此图中：

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

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

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

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

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

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

• Git over SSH 需要 gitlab-shell。
• Git over HTTPS 需要 gitlab-workhorse。

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

• 一个只读数据库实例，从主极狐GitLab 数据库流式传输数据。
• 一个读写数据库实例（跟踪数据库），由 次要 站点内部使用，用于记录已复制的数据。

次要 站点还运行一个额外的守护进程：Geo Log Cursor。

运行 Geo 的要求#

运行 Geo 需要满足以下条件：

• 支持 OpenSSH 6.9 或更高版本的操作系统（需要用于在数据库中快速查找已授权的 SSH 密钥） 已知以下操作系统附带当前版本的 OpenSSH：
  • CentOS 7.4 或更高版本
  • Ubuntu 16.04 或更高版本
• 如果可能，您还应在所有 Geo 站点上使用相同的操作系统版本。如果在 Geo 站点之间使用不同的操作系统版本，您 必须 检查操作系统区域设置数据兼容性，以避免数据库索引的静默损坏。
• 适用于您的极狐GitLab 版本的受支持的 PostgreSQL 版本，并支持流复制。
  • 不支持 PostgreSQL 逻辑复制。
• 所有站点必须运行相同的 PostgreSQL 版本。
• Git 2.9 或更高版本
• 使用 LFS 时，用户端需要 Git-lfs 2.4.2 或更高版本
• 所有站点必须运行完全相同的极狐GitLab 版本。主版本、次版本和修订版本 都必须匹配。
• 所有站点必须定义相同的仓库存储。
• 在 Geo 中使用容器镜像仓库时，您必须在每个站点为容器镜像仓库元数据数据库配置独立的外部 PostgreSQL 实例。有关详细信息，请参阅次要站点的容器镜像仓库。

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

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

防火墙规则#

下表列出了 Geo 的 主要 和 次要 站点之间必须开放的基本端口。为简化故障转移，您应该在两个方向上开放端口。

请参阅软件包默认值 中极狐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 Log Cursor#

此守护进程：

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

当跟踪数据库实例中标记了要更新的内容时，在 次要 站点上运行的异步作业会执行所需的操作并更新状态。

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

已知问题#

- 通过辅助 Geo 站点进行 Git over SSH 不可靠。更多信息，请参见 issue #413109、issue #417186、issue #454707 和 issue 585913。 - 直接推送到**辅助**站点会（对于 HTTP）重定向或（对于 SSH）代理请求到**主**站点，而不是直接处理它。你不能使用在 URI 中嵌入了凭据的 Git over HTTP，例如 `https://user:personal-access-token@secondary.tld`。更多信息，请参见如何[使用 Geo 站点](replication/usage.md)。 - **主**站点必须在线才能进行 OAuth 登录。现有会话和 Git 不受影响。支持**辅助**站点使用独立于主站点的 OAuth 提供商的功能正在计划中。 - 安装过程包含多个手动步骤，根据不同情况，整个过程可能需要大约一个小时。考虑使用 [GitLab Environment Toolkit](https://jihulab.com/gitlab-cn/gitlab-environment-toolkit) 的 Terraform 和 Ansible 脚本，根据我们的[参考架构](../reference_architectures/_index.md)部署和运行生产环境极狐GitLab 实例，包括自动化日常任务。[史诗 1465](https://jihulab.com/groups/gitlab-cn/-/epics/1465) 提议进一步改进 Geo 的安装。 - 在禁用了 [HTTP 代理](secondary_proxy/_index.md#disable-secondary-site-http-proxying)的**辅助**站点上，议题/合并请求的实时更新（例如通过长轮询）不起作用。 - [选择性同步](replication/selective_synchronization.md)仅限制复制哪些仓库和文件。整个 PostgreSQL 数据仍会被复制。选择性同步不适用于合规/出口控制的用例。 - [Pages 访问控制](../../user/project/pages/pages_access_control.md)在辅助站点上不起作用。更多信息，请参见 issue 9336 了解详情。 - 对于拥有多个辅助站点的部署，[灾难恢复](disaster_recovery/_index.md)会导致停机，因为需要在所有未提升的辅助站点上重新初始化 PostgreSQL 流复制，以跟随新的主站点。 - 对于 Git over SSH，为了使项目克隆 URL 无论你浏览哪个站点都能正确显示，辅助站点必须使用与主站点相同的端口。更多信息，请参见 issue 339262。 - 备份[不能在 Geo 辅助站点上运行](replication/troubleshooting/postgresql_replication.md#message-error-canceling-statement-due-to-conflict-with-recovery)。 - 在大多数情况下，Geo 辅助站点不会加速（提供）流水线第一阶段的克隆请求。后续阶段也不能保证由辅助站点提供，例如如果 Git 变更很大、带宽很小或流水线阶段较短。通常，它会为后续阶段提供克隆请求。Issue 446176 讨论了其中的原因，并提出了一项增强功能，以提高 Runner 克隆请求由辅助站点提供的可能性。 - 当单个 Git 仓库以足够高的速率接收推送时，辅助站点的本地副本可能永远处于过时状态。这会导致该仓库的所有 Git 获取请求都被转发到主站点。更多信息，请参见 issue 455870。 - [代理](secondary_proxy/_index.md)仅在 Puma 服务或 Web 服务中的 GitLab 应用程序中实现，因此其他服务无法从中受益。你应该使用[单独的 URL](secondary_proxy/_index.md#set-up-a-separate-url-for-a-secondary-geo-site)来确保请求始终发送到主站点。这些服务包括： - 极狐GitLab 容器镜像仓库 - [可以配置为使用单独的域名](../packages/container_registry.md#configure-container-registry-under-its-own-domain)，例如 `registry.example.com`。辅助站点容器镜像仓库仅用于灾难恢复。不应将用户路由到这些仓库，尤其不应进行推送，因为数据不会传播到主站点。 - 极狐GitLab Pages - 应始终使用单独的域名，作为[运行极狐GitLab Pages 的先决条件](../pages/_index.md#prerequisites)的一部分。 - 使用[统一 URL](secondary_proxy/_index.md#set-up-a-unified-url-for-geo-sites)时，Let's Encrypt 无法生成证书，除非它可以通过同一域名访问两个 IP。要将 Let's Encrypt 用于 TLS 证书，你可以手动将域名指向其中一个 Geo 站点，生成证书，然后将其复制到所有其他站点。 - 当[辅助站点使用与主站点不同的 URL](secondary_proxy/_index.md#set-up-a-separate-url-for-a-secondary-geo-site)时，仅当 SAML 身份提供商（IdP）允许为应用程序配置多个回调 URL 时，才支持[使用 SAML 登录辅助站点](replication/single_sign_on.md#saml-with-separate-url-with-proxying-enabled)。 - 通过 SSH 对辅助站点使用 `--depth` 选项的 Git 克隆和获取请求不起作用，并且如果辅助站点在请求发起时未更新，则会无限期挂起。这是由于代理过程中将 Git SSH 转换为 Git HTTPS 的问题所致。更多信息，请参见 issue 391980。现在，Linux 软件包安装的极狐GitLab Geo 辅助站点提供了一种不涉及上述转换步骤的新工作流，可以通过功能标志启用。更多详细信息，请参见 issue 454707 中的评论。对于云原生极狐GitLab Geo 辅助站点的修复在 issue 5641 中进行跟踪。 - 不要对极狐GitLab Geo 使用[相对 URL](https://gitlab.cn/docs/omnibus/settings/configuration/#configure-a-relative-url-for-gitlab)，因为它们会破坏站点之间的代理。更多信息，请参见 issue 456427。

复制的数据类型#

有关所有极狐GitLab 数据类型和复制的数据类型的完整列表，请参阅。

安装后文档#

在辅助站点上安装极狐GitLab 并执行初始配置后，请参阅以下文档了解安装后信息。

设置 Geo#

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

配置 Geo 使用对象存储#

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

复制容器镜像仓库#

有关如何复制容器镜像仓库的更多信息，请参见辅助站点的容器镜像仓库。

为 Geo 站点设置统一 URL#

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

单点登录（SSO）#

有关配置单点登录（SSO）的更多信息，请参见Geo 与单点登录（SSO）。

LDAP#

有关配置 LDAP 的更多信息，请参见Geo 与单点登录（SSO）> LDAP。

调优 Geo#

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

暂停和恢复复制#

更多信息，请参见暂停和恢复复制。

回填#

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

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

Runner#

• 除了我们部署 runner 舰队 的标准最佳实践外，还可以将 runner 配置为连接到 Geo 辅助站点以分散作业负载。请参阅如何在辅助站点上注册 runner。
• 另请参阅如何处理故障转移期间的 Runner 连接。

升级 Geo#

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

安全审查#

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

移除 Geo 站点#

有关移除 Geo 站点的更多信息，请参见移除辅助 Geo 站点。

禁用 Geo#

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

日志文件#

Geo 将结构化日志信息存储在 geo.log 文件中。有关如何访问和使用 Geo 日志的更多信息，请参见日志系统文档中的 Geo 部分。

灾难恢复#

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

常见问题#

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

故障排查#

• 有关 Geo 故障排查步骤，请参见Geo 故障排查。
• 有关灾难恢复故障排查步骤，请参见Geo 故障转移故障排查。