• Elasticsearch 术语表
• 安装 Elasticsearch 或 AWS OpenSearch 集群
  • 版本要求
    • Elasticsearch
    • OpenSearch
  • 系统要求
  • 访问要求
    • Elasticsearch 的基于角色的访问控制
    • AWS OpenSearch 服务的访问控制
      • 网络
      • 域访问策略
      • 细粒度访问控制
  • 升级到新的 Elasticsearch 大版本
• Elasticsearch 存储库索引器
  • 安装索引器
    • 安装依赖项
      • Debian / Ubuntu
      • CentOS / RHEL
      • macOS
    • 构建并安装
  • 查看索引错误
• 启用高级搜索
  • 索引实例
    • 从用户界面
    • 使用 Rake 任务
  • 检查索引状态
  • 监控后台作业的状态
  • 高级搜索配置
  • 限制索引的群组和项目数据量
    • 索引的群组
• 启用自定义语言分析器
• 禁用高级搜索
• 恢复索引
• 零停机时间重新索引
  • 使用零停机时间重新索引
  • 触发重新索引
    • 触发零停机时间重新索引
      • 切片倍数
      • 最大运行切片数量
  • 将最新的重新索引作业标记为失败并恢复索引
• 索引完整性
• 高级搜索迁移
  • 迁移字典文件
  • 检查待处理的迁移
  • 重试暂停的迁移
  • 所有迁移必须在进行重大升级之前完成
  • 可跳过的迁移
• 极狐 GitLab 高级搜索 Rake 任务
  • 环境变量
  • 索引一系列项目或特定项目
• 高级搜索索引范围
• 调优
  • 关于选择最佳集群配置的指导
  • 高级搜索设置
    • Elasticsearch 分片数量
      • 包含数据库数据的索引
      • 包含仓库数据的索引
    • Elasticsearch 副本数量
  • 高效索引大型实例
  • 删除的文档
• 使用专用 Sidekiq 节点或进程索引大型实例
  • 单节点，两个进程
  • 两个节点，每个节点一个进程
• 恢复到基础搜索
• 灾难恢复

{{< details >}}

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

{{< /details >}}

本页面描述了如何启用高级搜索。启用后，高级搜索提供更快的搜索响应时间和改进的搜索功能。

要启用高级搜索，您必须：

1. 安装一个 Elasticsearch 或 AWS OpenSearch 集群。
2. 启用高级搜索。

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

高级搜索将所有项目存储在同一 Elasticsearch 索引中。然而，只有有访问权限的用户才能在搜索结果中看到私有项目。

{{< /alert >}}

Elasticsearch 术语表

该术语表提供与 Elasticsearch 相关的术语定义。

• Lucene：一个用 Java 编写的全文搜索库。
• 近实时 (NRT)：指从索引文档到文档可搜索之间的轻微延迟。
• 集群：一个或多个节点的集合，它们协同工作以保存所有数据，提供索引和搜索功能。
• 节点：作为集群一部分工作的单个服务器。
• 索引：具有某些相似特征的文档集合。
• 文档：可以被索引的基本信息单位。
• 分片：索引的全功能和独立子划分。每个分片实际上是一个 Lucene 索引。
• 副本：复制索引的故障转移机制。

安装 Elasticsearch 或 AWS OpenSearch 集群

Elasticsearch 和 AWS OpenSearch 不包含在 Linux 软件包中。您可以自己安装搜索集群或使用云托管服务，例如：

• Elasticsearch 服务（可在 Amazon Web Services、Google Cloud Platform 和 Microsoft Azure 上使用）
• Amazon OpenSearch 服务

您应该在单独的服务器上安装搜索集群。在与极狐GitLab 同一服务器上运行搜索集群可能会导致性能问题。

对于具有单个节点的搜索集群，由于主分片已分配，集群状态始终为黄色。集群无法将副本分片分配到与主分片相同的节点。

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

在生产环境中使用新的 Elasticsearch 集群之前，请参阅重要的 Elasticsearch 配置。

{{< /alert >}}

版本要求

Elasticsearch

{{< history >}}

• 在极狐GitLab 15.0 中移除对 Elasticsearch 6.8 的支持。

{{< /history >}}

高级搜索适用于以下版本的 Elasticsearch。

OpenSearch

如果您的 Elasticsearch 或 OpenSearch 版本不兼容，为了防止数据丢失，索引会暂停并在elasticsearch.log文件中记录一条消息。

如果您使用的是兼容版本，并且在连接到 OpenSearch 后收到消息 Elasticsearch version not compatible，请恢复索引。

系统要求

Elasticsearch 和 AWS OpenSearch 需要比极狐GitLab 安装要求更多的资源。

内存、CPU 和存储要求取决于您索引到集群中的数据量。使用频繁的 Elasticsearch 集群可能需要更多资源。estimate_cluster_size Rake 任务使用总存储库大小来估算高级搜索存储要求。

访问要求

极狐GitLab 支持根据您的需求和您使用的后端服务使用HTTP 和基于角色的身份验证方法。

Elasticsearch 的基于角色的访问控制

Elasticsearch 可以提供基于角色的访问控制，以进一步保护集群。要访问并在 Elasticsearch 集群中执行操作，管理员区域中配置的用户名必须具有授予以下权限的角色。用户名从极狐GitLab 向搜索集群发出请求。

{
  "cluster": ["monitor"],
  "indices": [
    {
      "names": ["gitlab-*"],
      "privileges": [
        "create_index",
        "delete_index",
        "view_index_metadata",
        "read",
        "manage",
        "write"
      ]
    }
  ]
}

AWS OpenSearch 服务的访问控制

先决条件：

• 在您的 AWS 账户中创建 OpenSearch 域时，您必须具有名为 AWSServiceRoleForAmazonOpenSearchService 的服务关联角色。
• AWS OpenSearch 的域访问策略必须允许 es:ESHttp* 操作。

AWSServiceRoleForAmazonOpenSearchService 被 所有 OpenSearch 域使用。在大多数情况下，当您使用 AWS 管理控制台创建第一个 OpenSearch 域时，会自动创建此角色。

AWS OpenSearch 服务有三个主要的安全层：

• 网络
• 域访问策略
• 细粒度访问控制

网络

通过此安全层，您可以在创建域时选择 公共访问，以便任何客户端的请求都可以到达域端点。如果选择 VPC 访问，客户端必须连接到 VPC 才能使请求到达端点。

域访问策略

极狐GitLab 支持以下 AWS OpenSearch 域的域访问控制方法：

• 基于资源的（域）访问策略：其中 AWS OpenSearch 域配置了 IAM 策略
• 基于身份的策略：其中客户端使用带有策略的 IAM 主体配置访问

基于资源的策略示例

以下是允许 es:ESHttp* 操作的基于资源的（域）访问策略示例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": [
        "es:ESHttp*"
      ],
      "Resource": "arn:aws:es:us-west-1:987654321098:domain/test-domain/*"
    }
  ]
}

以下是仅允许特定 IAM 主体执行 es:ESHttp* 操作的基于资源的（域）访问策略示例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::123456789012:user/test-user"
        ]
      },
      "Action": [
        "es:ESHttp*"
      ],
      "Resource": "arn:aws:es:us-west-1:987654321098:domain/test-domain/*"
    }
  ]
}

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

如果使用跨账户的 AWS AssumeRole，则必须提供 aws_role_arn。ARN 应为具有访问 OpenSearch 权限的角色。

{{< /alert >}}

基于身份的策略示例

以下是附加到 IAM 主体的基于身份的访问策略示例，其中允许 es:ESHttp* 操作：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "es:ESHttp*",
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

细粒度访问控制

启用细粒度访问控制时，必须通过以下方式之一设置主用户：

• 将 IAM ARN 设置为主用户。
• 创建主用户。

将 IAM ARN 设置为主用户

如果使用 IAM 主体作为主用户，则所有请求都必须使用 AWS 签名版本 4 签名发送到集群。您还可以指定 IAM ARN，这是您分配给 EC2 实例的 IAM 角色。

要将 IAM ARN 设置为主用户，您必须在您的极狐GitLab 实例上使用 AWS OpenSearch 服务和 IAM 凭证：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 展开 高级搜索。
4. 在 AWS OpenSearch IAM 凭证 部分：
   1. 选择 使用 AWS OpenSearch 服务和 IAM 凭证 复选框。
   2. 在 AWS 区域中，输入您的 OpenSearch 域所在的 AWS 区域（例如，us-east-1）。
   3. 在 AWS 访问密钥和 AWS 密钥中，输入您的访问密钥进行身份验证。

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

   直接在 EC2 实例上运行的极狐GitLab 部署（不在容器中）无需输入访问密钥。您的极狐GitLab 实例会自动从 AWS 实例元数据服务 (IMDS) 获取这些密钥。

   {{< /alert >}}

5. 选择 保存更改。

创建主用户

如果在内部用户数据库中创建主用户，您可以使用 HTTP 基本身份验证向集群发出请求。

要创建主用户，您必须在您的极狐GitLab 实例上配置 OpenSearch 域 URL 和主用户名及密码：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 展开 高级搜索。
4. 在 OpenSearch 域 URL中，输入 OpenSearch 域端点的 URL。
5. 在 用户名中，输入主用户名。
6. 在 密码中，输入主密码。
7. 选择 保存更改。

升级到新的 Elasticsearch 大版本

{{< history >}}

• 在极狐GitLab 15.0 中移除对 Elasticsearch 6.8 的支持。

{{< /history >}}

升级 Elasticsearch 时，您无需更改极狐GitLab 配置。

在 Elasticsearch 升级过程中，您必须：

• 暂停索引，以便仍可跟踪更改。
• 禁用高级搜索，以免搜索失败并出现 HTTP 500 错误。

当 Elasticsearch 集群完全升级并激活时，恢复索引并启用高级搜索。

当您升级到极狐GitLab 15.0 及更高版本时，您必须使用 Elasticsearch 7.x 及更高版本。

Elasticsearch 存储库索引器

为了索引 Git 存储库数据，极狐GitLab 使用 gitlab-elasticsearch-indexer。对于自编译安装，请参阅安装索引器。

安装索引器

首先安装一些依赖项，然后构建并安装索引器本身。

安装依赖项

该项目依赖于 Unicode 国际组件（ICU）进行文本编码，因此我们必须确保在运行 make 之前安装您平台的开发包。

Debian / Ubuntu

要在 Debian 或 Ubuntu 上安装，请运行：

sudo apt install libicu-dev

CentOS / RHEL

要在 CentOS 或 RHEL 上安装，请运行：

sudo yum install libicu-devel

macOS

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

您必须先安装 Homebrew。

{{< /alert >}}

要在 macOS 上安装，请运行：

brew install icu4c
export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig:$PKG_CONFIG_PATH"

构建并安装

要构建并安装索引器，请运行：

indexer_path=/home/git/gitlab-elasticsearch-indexer

# 运行 gitlab-elasticsearch-indexer 的安装任务：
sudo -u git -H bundle exec rake gitlab:indexer:install[$indexer_path] RAILS_ENV=production
cd $indexer_path && sudo make install

gitlab-elasticsearch-indexer 安装到 /usr/local/bin。

您可以使用 PREFIX 环境变量更改安装路径。如果这样做，请记住传递 -E 标志给 sudo。

示例：

PREFIX=/usr sudo -E make install

安装完成后，请确保启用 Elasticsearch。

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

如果您在索引时看到诸如 Permission denied - /home/git/gitlab-elasticsearch-indexer/ 的错误，您可能需要在您的 gitlab.yml 文件中将 production -> elasticsearch -> indexer_path 设置为 /usr/local/bin/gitlab-elasticsearch-indexer，这是二进制文件安装的位置。

{{< /alert >}}

查看索引错误

极狐GitLab Elasticsearch 索引器的错误会在 elasticsearch.log 文件和 sidekiq.log 文件中报告，json.exception.class 为 Gitlab::Elastic::Indexer::Error。这些错误可能会在索引 Git 存储库数据时发生。

启用高级搜索

先决条件：

• 您必须拥有实例的管理员访问权限。
• 配置每个索引的分片数量。
• 配置每个索引的副本数量。
• 可选。为索引大型实例做准备。

要启用高级搜索：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 配置您的 Elasticsearch 集群的高级搜索设置。暂时不要选择 启用 Elasticsearch 搜索 复选框。
4. 索引实例。
5. 可选。检查索引状态。
6. 索引完成后，选择 启用 Elasticsearch 搜索 复选框，然后选择 保存更改。

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

当您的 Elasticsearch 集群在启用 Elasticsearch 时宕机时，您可能会遇到更新文档（如议题）的问题，因为您的实例会将更改排队到索引的作业，但无法找到有效的 Elasticsearch 集群。

{{< /alert >}}

对于具有超过 50 GB 存储库数据的极狐GitLab 实例，请参阅有效地索引大型实例。

索引实例

从用户界面

{{< history >}}

• 在极狐GitLab 17.3 中引入。

{{< /history >}}

先决条件：

• 您必须拥有实例的管理员访问权限。

您可以从用户界面执行初始索引或重新创建索引。

要启用高级搜索并从用户界面索引实例：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 选择 Elasticsearch 索引 复选框，然后选择 保存更改。
4. 选择 索引实例。

使用 Rake 任务

先决条件：

• 您必须拥有实例的管理员访问权限。

要索引整个实例，请使用以下 Rake 任务：

# WARNING: 此任务会删除所有现有索引
# 对于使用 Linux 包安装的
sudo gitlab-rake gitlab:elastic:index

# WARNING: 此任务会删除所有现有索引
# 对于自编译安装
bundle exec rake gitlab:elastic:index RAILS_ENV=production

要索引特定数据，请使用以下 Rake 任务：

# 对于使用 Linux 包安装的
sudo gitlab-rake gitlab:elastic:index_epics
sudo gitlab-rake gitlab:elastic:index_work_items
sudo gitlab-rake gitlab:elastic:index_group_wikis
sudo gitlab-rake gitlab:elastic:index_namespaces
sudo gitlab-rake gitlab:elastic:index_projects
sudo gitlab-rake gitlab:elastic:index_snippets
sudo gitlab-rake gitlab:elastic:index_users

# 对于自编译安装
bundle exec rake gitlab:elastic:index_epics RAILS_ENV=production
bundle exec rake gitlab:elastic:index_work_items RAILS_ENV=production
bundle exec rake gitlab:elastic:index_group_wikis RAILS_ENV=production
bundle exec rake gitlab:elastic:index_namespaces RAILS_ENV=production
bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production
bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production
bundle exec rake gitlab:elastic:index_users RAILS_ENV=production

检查索引状态

先决条件：

• 您必须拥有实例的管理员访问权限。

要检查索引状态：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 展开 索引状态。

监控后台作业的状态

先决条件：

• 您必须拥有实例的管理员访问权限。

要监控后台作业的状态：

1. 在左侧边栏底部，选择 管理员。
2. 选择 监控 > 后台作业。
3. 在 Sidekiq 仪表板上，选择 队列，等待 elastic_commit_indexer 和 elastic_wiki_indexer 队列下降到 0。这些队列包含用于项目和群组的代码和 wiki 数据索引的作业。

高级搜索配置

以下是可用的 Elasticsearch 设置：

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

增加 最大批量请求大小（MiB） 和 批量请求并发性 的值可能会对 Sidekiq 性能产生负面影响。如果您在 Sidekiq 日志中看到 scheduling_latency_s 持续时间增加，请将它们恢复到默认值。

{{< /alert >}}

限制索引的群组和项目数据量

{{< history >}}

• 在极狐GitLab 16.7 中引入，使用名为 search_index_all_projects 的功能标志。默认禁用/
• 在极狐GitLab 16.11 中 GA。功能标志 search_index_all_projects 被移除。

{{< /history >}}

选择 限制索引的群组和项目数据量 复选框时，您可以指定要索引的群组和项目。如果群组是一个群组，则任何子群组及这些子群组中的项目也会被索引。

启用此设置时：

• 群组或项目必须指定为完全索引。
• 所有项目的项目记录（如项目名称和描述）始终被索引。
• 关联数据仅为您指定的群组和项目索引。

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

启用此设置后，如果未指定任何群组或项目，则仅索引项目记录，无法搜索任何关联数据。

{{< /alert >}}

索引的群组

{{< history >}}

• 在极狐GitLab 13.4 中引入，使用名为 search_index_all_projects 的功能标志。默认禁用。
• 在极狐GitLab 14.2 中为 JihuLab.com 启用。
• 在极狐GitLab 17.11 中 GA，作为一个 UI 选项，而不是 advanced_global_search_for_limited_indexing 标志。

{{< /history >}}

当您索引所有群组时，可以使用高级搜索进行全局代码和提交搜索。当您仅索引某些群组时：

• 全局搜索不包括代码或提交搜索范围。
• 代码和提交搜索仅在单个索引的群组中可用。
• 无法在多个索引的群组中进行单个代码或提交搜索。
• 在索引的群组中可以进行跨项目搜索。

例如，如果您索引两个单独的群组，则必须分别在每个群组上单独运行代码搜索。

要启用有限索引的全局搜索：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 展开 高级搜索。
4. 选择 启用有限索引的全局搜索。
5. 选择 保存更改。
6. 如果您已经索引了您的实例，则必须重新索引实例。这会删除现有的搜索数据，以使过滤正常工作。

启用自定义语言分析器

先决条件：

• 您必须拥有实例的管理员访问权限。

您可以使用 Elastic 的 smartcn 和 kuromoji 分析插件来改进中文和日文的语言支持。

要启用自定义语言分析器：

1. 安装所需的插件。插件必须安装在集群中的每个节点上，并且每个节点在安装后必须重新启动。有关插件列表，请参阅本节后面的表格。
2. 在左侧边栏底部，选择 管理员。
3. 选择 设置 > 搜索。
4. 找到 自定义分析器：语言支持。
5. 启用插件支持 索引。
6. 选择 保存更改以使更改生效。
7. 触发零停机时间重新索引或从头开始重新索引以使用更新的映射创建新索引。
8. 在完成上一步后启用插件支持 搜索。

有关安装指导，请参阅以下 Elasticsearch 语言插件选项：

禁用高级搜索

先决条件：

• 您必须拥有实例的管理员访问权限。

要在极狐GitLab 中禁用高级搜索：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 清除 Elasticsearch 索引和 启用 Elasticsearch 搜索 复选框。
4. 选择 保存更改。

5. 可选。对于仍在线的 Elasticsearch 实例，删除现有索引：

   # 对于使用 Linux 包安装的
   sudo gitlab-rake gitlab:elastic:delete_index
   
   # 对于自编译安装
   bundle exec rake gitlab:elastic:delete_index RAILS_ENV=production
   

恢复索引

先决条件：

• 您必须拥有实例的管理员访问权限。

要恢复索引：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 展开 高级搜索。
4. 清除 暂停 Elasticsearch 索引 复选框。

零停机时间重新索引

此重新索引方法的思想是利用 Elasticsearch 重新索引 API 和 Elasticsearch 索引别名功能来执行操作。我们设置一个连接到 primary 索引的索引别名，该别名用于极狐GitLab 的读写。当重新索引过程开始时，我们暂时暂停对 primary 索引的写入。然后，我们创建另一个索引并调用重新索引 API，将索引数据迁移到新索引中。重新索引作业完成后，我们通过连接索引别名到新索引来切换到新索引，该索引成为新的 primary 索引。最后，我们恢复写入，典型操作恢复。

使用零停机时间重新索引

您可以使用零停机时间重新索引来配置无法在不创建新索引和复制现有数据的情况下更改的索引设置或映射。您不应使用零停机时间重新索引来修复缺失数据。如果数据尚未索引，零停机时间重新索引不会向搜索集群中添加数据。在开始重新索引之前，您必须完成所有高级搜索迁移。

触发重新索引

先决条件：

• 您必须拥有实例的管理员访问权限。

要触发重新索引：

1. 以管理员身份登录到您的极狐GitLab 实例。
2. 在左侧边栏底部，选择 管理员。
3. 选择 设置 > 搜索。
4. 展开 Elasticsearch 零停机时间重新索引。
5. 选择 触发集群重新索引。

重新索引可能是一个漫长的过程，具体取决于您的 Elasticsearch 集群的大小。

此过程完成后，原始索引计划在 14 天后删除。您可以通过按下与您触发重新索引过程的同一页面上的 取消 按钮来取消此操作。

在重新索引运行时，您可以在同一部分下跟踪其进度。

触发零停机时间重新索引

先决条件：

• 您必须拥有实例的管理员访问权限。

要触发零停机时间重新索引：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。

3. 展开 Elasticsearch 零停机时间重新索引。可用的设置包括：

   • 切片倍数
   • 最大运行切片数量

切片倍数

切片倍数计算重新索引期间的切片数量。

极狐GitLab 使用手动切片来高效、安全地控制重新索引，使用户能够仅重试失败的切片。

倍数默认为 2，适用于每个索引的分片数量。例如，如果此值为 2，并且您的索引有 20 个分片，那么重新索引任务将被拆分为 40 个切片。

最大运行切片数量

最大运行切片数量参数默认为 60，对应于 Elasticsearch 重新索引期间允许同时运行的最大切片数量。

将此值设置得太高可能会对性能产生不利影响，因为您的集群可能会因搜索和写入而严重饱和。将此值设置得太低可能导致重新索引过程需要很长时间才能完成。

最佳值取决于您的集群大小，您是否愿意在重新索引期间接受一些性能下降，以及重新索引快速完成并恢复索引的重要性。

将最新的重新索引作业标记为失败并恢复索引

先决条件：

• 您必须拥有实例的管理员访问权限。

要放弃未完成的重新索引作业并恢复索引：

1. 将最新的重新索引作业标记为失败：

   # 对于使用 Linux 包安装的
   sudo gitlab-rake gitlab:elastic:mark_reindex_failed
   
   # 对于自编译安装
   bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production
   

2. 在左侧边栏底部，选择 管理员。
3. 选择 设置 > 搜索。
4. 展开 高级搜索。
5. 清除 暂停 Elasticsearch 索引 复选框。

索引完整性

{{< history >}}

• 在极狐GitLab 15.10 中引入，使用名为 search_index_integrity 的功能标志。默认启用。
• 在极狐GitLab 16.4 中 GA。功能标志 search_index_integrity 被移除。

{{< /history >}}

索引完整性检测并修复缺失的存储库数据。当范围为群组或项目的代码搜索返回无结果时，此功能会自动使用。

高级搜索迁移

在后台运行重新索引迁移，无需手动干预。这通常发生在高级搜索中添加新功能的情况下，这意味着添加或更改内容的索引方式。

迁移字典文件

{{< history >}}

• 在极狐GitLab 16.3 中引入。

{{< /history >}}

每个迁移在 ee/elastic/docs/ 文件夹中都有相应的字典文件，其中包含以下信息：

name:
version:
description:
group:
milestone:
introduced_by_url:
obsolete:
marked_obsolete_by_url:
marked_obsolete_in_milestone:

您可以使用此信息，例如，识别迁移何时引入或何时标记为过时。

检查待处理的迁移

要检查待处理的高级搜索迁移，请运行以下命令：

curl "$CLUSTER_URL/gitlab-production-migrations/_search?size=100&q=*" | jq .

这应该返回类似于以下内容：

{
  "took": 14,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "gitlab-production-migrations",
        "_type": "_doc",
        "_id": "20230209195404",
        "_score": 1,
        "_source": {
          "completed": true
        }
      }
    ]
  }
}

要调试迁移问题，请检查 elasticsearch.log文件。

重试暂停的迁移

某些迁移具有重试限制。如果迁移无法在重试限制内完成，则会暂停，并在高级搜索集成设置中显示通知。

建议检查 elasticsearch.log 文件以调试迁移暂停的原因，并在重试迁移之前进行任何更改。

当您认为已修复故障原因时：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 展开 高级搜索。
4. 在 Elasticsearch 迁移暂停 警报框中，选择 重试迁移。迁移将在后台安排重试。

如果您无法成功进行迁移，可以考虑从头重建索引的最后手段。这样可能允许您跳过问题，因为新创建的索引跳过了所有迁移，因为索引是使用正确的最新模式重新创建的。

所有迁移必须在进行重大升级之前完成

在升级到极狐 GitLab 的主要版本之前，您必须完成直到该主要版本之前的最新次要版本的所有迁移。在继续进行主要版本升级之前，您还必须解决并重试任何暂停的迁移。有关更多信息，请参阅升级的迁移。

已删除的迁移被标记为过时。如果您在所有待定的高级搜索迁移完成之前升级极狐 GitLab，则无法执行或重试新版本中已删除的任何待定迁移。在这种情况下，您必须从头重建索引。

可跳过的迁移

可跳过的迁移仅在满足特定条件时执行。例如，如果迁移依赖于特定版本的 Elasticsearch，则可以跳过直到达到该版本。

如果在迁移标记为过时时未执行可跳过的迁移，为了应用更改，您必须重建索引。

极狐 GitLab 高级搜索 Rake 任务

Rake 任务可用于：

• 构建和安装 索引器。
• 在禁用 Elasticsearch时删除索引。
• 将极狐 GitLab 数据添加到索引中。

以下是一些可用的 Rake 任务：

环境变量

除了 Rake 任务，还有一些环境变量可以用来修改进程：

索引一系列项目或特定项目

使用 ID_FROM 和 ID_TO 环境变量，您可以索引有限数量的项目。这对于阶段性索引可能很有用。

root@git:~# sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1 ID_TO=100

因为 ID_FROM 和 ID_TO 使用 或等于 比较，您可以通过将两者设置为相同的项目 ID 来索引仅一个项目：

root@git:~# sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=5 ID_TO=5
Indexing project repositories...I, [2019-03-04T21:27:03.083410 #3384]  INFO -- : Indexing GitLab User / test (ID=33)...
I, [2019-03-04T21:27:05.215266 #3384]  INFO -- : Indexing GitLab User / test (ID=33) is done!

高级搜索索引范围

执行搜索时，极狐 GitLab 索引使用以下范围：

调优

关于选择最佳集群配置的指导

• 通常，您希望使用至少 2 节点集群配置，并使用一个副本，这样可以提高弹性。如果您的存储使用量增长迅速，您可能希望提前计划水平扩展（增加更多节点）。
• 不建议在搜索集群中使用 HDD 存储，因为这会影响性能。最好使用 SSD 存储（例如 NVMe 或 SATA SSD 驱动器）。
• 不应与大型实例一起使用仅协调节点。仅协调节点比数据节点更小，这可能会影响性能和高级搜索迁移。
• 您可以使用极狐 GitLab 性能工具来基准测试不同搜索集群大小和配置下的搜索性能。
• Heap size 应设置为不超过物理 RAM 的 50%。此外，不应设置为超过零基压缩 oops 的阈值。确切的阈值有所不同，但在大多数系统上 26 GB 是安全的，但在某些系统上也可能高达 30 GB。
• refresh_interval 是一个每个索引的设置。如果不需要实时数据，您可能希望将其从默认的 1s 调整为更大的值。这会改变您看到新结果的速度。如果这对您很重要，您应尽量将其保持在接近默认值。
• 如果您有大量的重索引操作，您可能希望将 indices.memory.index_buffer_size 提高到 30% 或 40%。

高级搜索设置

Elasticsearch 分片数量

对于单节点集群，将每个索引的 Elasticsearch 分片数量设置为 Elasticsearch 数据节点上的 CPU 核心数。保持平均分片大小在几 GB 到 30 GB 之间。

对于多节点集群，将每个索引的 Elasticsearch 分片数量设置为至少 5。

要更新索引的分片大小，请更改设置并触发零停机时间重新索引。

包含数据库数据的索引

{{< history >}}

• 在极狐 GitLab 16.11 中引入了 gitlab:elastic:estimate_shard_sizes。

{{< /history >}}

对于包含数据库数据的索引：

• gitlab-production-projects
• gitlab-production-issues
• gitlab-production-epics
• gitlab-production-merge_requests
• gitlab-production-notes
• gitlab-production-users

运行 Rake 任务 gitlab:elastic:estimate_shard_sizes 以确定分片数量。任务返回近似文档计数和分片及副本大小的建议。

包含仓库数据的索引

对于包含仓库数据的索引：

• gitlab-production
• gitlab-production-wikis
• gitlab-production-commits

运行 Rake 任务 gitlab:elastic:estimate_cluster_size 以确定分片数量。任务返回代码（gitlab-production）和维基（gitlab-production-wikis）的近似索引大小。

保持平均分片大小在几 GB 到 30 GB 之间。如果平均分片大小增长超过 30 GB，则增加索引的分片大小并触发零停机时间重新索引。为了确保集群健康，每个节点的分片数量不得超过配置堆大小的 20 倍。例如，具有 30 GB 堆的节点必须最多有 600 个分片。

Elasticsearch 副本数量

对于单节点集群，将每个索引的 Elasticsearch 副本数量设置为 0。

对于多节点集群，将每个索引的 Elasticsearch 副本数量设置为 1（每个分片有一个副本）。数量不得为 0，因为失去一个节点会损坏索引。

高效索引大型实例

先决条件：

• 您必须拥有对实例的管理员访问权限。

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

索引大型实例会生成大量 Sidekiq 任务。通过拥有可扩展的设置 或创建额外的 Sidekiq 进程来准备此任务。

{{< /alert >}}

如果启用高级搜索由于大量数据被索引而导致问题：

1. 配置您的 Elasticsearch 主机和端口。

2. 创建空索引：

   # 对于使用 Linux 包的安装
   sudo gitlab-rake gitlab:elastic:create_empty_index
   
   # 对于自编译安装
   bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production
   

3. 如果这是您极狐 GitLab 实例的重新索引，请清除索引状态：

   # 对于使用 Linux 包的安装
   sudo gitlab-rake gitlab:elastic:clear_index_status
   
   # 对于自编译安装
   bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production
   

4. 选择 Elasticsearch 索引 复选框。

5. 索引大型 Git 仓库可能需要一段时间。为了加快进程，您可以为索引速度进行调优：

   • 您可以暂时增加 refresh_interval。
   • 您可以将副本数量设置为 0。此设置控制每个索引的主分片的副本数量。因此，将副本数量设置为 0 实际上禁用了分片在节点间的复制，这应该提高索引性能。这是关于可靠性和查询性能的重要权衡。重要的是在初始索引完成后记得将副本设置为一个考虑过的值。

   您可以预期索引时间减少 20%。索引完成后，您可以将 refresh_interval 和 number_of_replicas 设置回它们所需的值。

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

   这一步是可选的，但可能会显著加快大型索引操作。

   {{< /alert >}}

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "index" : {
              "refresh_interval" : "30s",
              "number_of_replicas" : 0
          } }'
   

6. 索引项目及其相关数据：

   # 对于使用 Linux 包的安装
   sudo gitlab-rake gitlab:elastic:index_projects
   
   # 对于自编译安装
   bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production
   

   这会为每个需要索引的项目排队一个 Sidekiq 任务。您可以在 管理员 区域的 监控 > 后台任务 > 队列选项卡 中查看任务，并选择 elastic_commit_indexer，或者您可以使用 Rake 任务查询索引状态：

   # 对于使用 Linux 包的安装
   sudo gitlab-rake gitlab:elastic:index_projects_status
   
   # 对于自编译安装
   bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production
   
   索引完成 65.55%（6555/10000 项目）
   

   如果您想限制索引到一系列项目，您可以提供 ID_FROM 和 ID_TO 参数：

   # 对于使用 Linux 包的安装
   sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000
   
   # 对于自编译安装
   bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production
   

   其中 ID_FROM 和 ID_TO 是项目 ID。两个参数都是可选的。上面的例子索引了 ID 从 1001 到（并包括）2000 的所有项目。

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

   有时 gitlab:elastic:index_projects 排队的项目索引任务可能会被中断。这可能由于多种原因发生，但再次运行索引任务始终是安全的。

   {{< /alert >}}

   您还可以使用 gitlab:elastic:clear_index_status Rake 任务强制索引器“忘记”所有进度，以便重新尝试索引过程。

7. 史诗、群组维基、个人代码段和用户与项目无关，必须单独索引：

   # 对于使用 Linux 包的安装
   sudo gitlab-rake gitlab:elastic:index_epics
   sudo gitlab-rake gitlab:elastic:index_group_wikis
   sudo gitlab-rake gitlab:elastic:index_snippets
   sudo gitlab-rake gitlab:elastic:index_users
   
   # 对于自编译安装
   bundle exec rake gitlab:elastic:index_epics RAILS_ENV=production
   bundle exec rake gitlab:elastic:index_group_wikis RAILS_ENV=production
   bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production
   bundle exec rake gitlab:elastic:index_users RAILS_ENV=production
   

8. 索引完成后，再次启用复制和刷新（仅在您之前增加了 refresh_interval 时）：

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "index" : {
              "number_of_replicas" : 1,
              "refresh_interval" : "1s"
          } }'
   

   在上面启用刷新后，应调用强制合并。

   对于 Elasticsearch 6.x 和更高版本，确保索引在进行强制合并之前处于只读模式：

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "settings": {
            "index.blocks.write": true
          } }'
   

   然后，启动强制合并：

   curl --request POST 'localhost:9200/gitlab-production/_forcemerge?max_num_segments=5'
   

   然后，将索引更改回读写模式：

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "settings": {
            "index.blocks.write": false
          } }'
   

9. 索引完成后，选择 启用与 Elasticsearch 搜索 复选框。

删除的文档

每当对已索引的极狐 GitLab 对象进行更改或删除（例如合并请求描述被更改，文件从仓库的默认分支中删除，项目被删除等），索引中的文档会被删除。然而，由于这些是“软”删除，索引中“删除的文档”的总数量，因此浪费的空间会增加。Elasticsearch 会智能地合并段以删除这些已删除的文档。然而，根据您极狐 GitLab 安装中的活动量和类型，索引中可能会浪费高达 50% 的空间。

一般来说，我们建议让 Elasticsearch 使用默认设置自动合并和回收空间。

然而，一些较大的安装可能希望调整合并策略设置：

• 考虑将 index.merge.policy.max_merged_segment 大小从默认的 5 GB 减少到可能的 2 GB 或 3 GB。合并仅在段至少有 50% 删除时发生。较小的段大小允许更频繁的合并。

  curl --request PUT localhost:9200/gitlab-production/_settings ---header 'Content-Type: application/json' \
       --data '{
         "index" : {
           "merge.policy.max_merged_segment": "2gb"
         }
       }'
  

• 您还可以调整 index.merge.policy.reclaim_deletes_weight，它控制删除的目标程度。但这可能导致昂贵的合并决策，因此我们建议除非您了解权衡，否则不要更改此设置。

  curl --request PUT localhost:9200/gitlab-production/_settings ---header 'Content-Type: application/json' \
       --data '{
         "index" : {
           "merge.policy.reclaim_deletes_weight": "3.0"
         }
       }'
  

• 不要进行 force merge 以删除已删除的文档。这可能导致非常大的段可能永远不会被回收，并且还可能导致显著的性能或可用性问题。

使用专用 Sidekiq 节点或进程索引大型实例

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

大多数实例不需要配置此设置。以下步骤使用 Sidekiq 的高级设置，称为路由规则。确保充分了解使用路由规则的影响，以避免完全丢失任务。

{{< /alert >}}

索引大型实例可能是一个冗长且资源密集的过程，可能会压倒 Sidekiq 节点和进程。这会对极狐 GitLab 的性能和可用性产生负面影响。

由于极狐 GitLab 允许您启动多个 Sidekiq 进程，您可以创建一个额外的进程专用于索引一组队列（或队列组）。通过这种方式，您可以确保索引队列始终有一个专用的工作者，而其余队列有另一个专用的工作者以避免争用。

为此，使用路由规则选项允许 Sidekiq 基于工作者匹配查询将任务路由到特定队列。

为了处理这个问题，我们通常推荐以下两种选择之一。您可以：

• 在单个节点上使用两个队列组。
• 使用两个队列组，每个节点上一个。

对于下面的步骤，考虑 sidekiq['routing_rules'] 的条目：

• ["feature_category=global_search", "global_search"] 因为所有索引任务都被路由到 global_search 队列。
• ["*", "default"] 因为所有其他非索引任务都被路由到 default 队列。

至少一个 sidekiq['queue_groups'] 中的进程必须包括 mailers 队列，否则邮件任务根本不会被处理。

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

路由规则（sidekiq['routing_rules']）必须在所有极狐 GitLab 节点（特别是极狐 GitLab Rails 和 Sidekiq 节点）中相同。

{{< /alert >}}

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

当启动多个进程时，进程数量不能超过您希望专用于 Sidekiq 的 CPU 核心数量。根据可用的工作负载和并发设置，每个 Sidekiq 进程只能使用一个 CPU 核心。有关更多详细信息，请参阅如何运行多个 Sidekiq 进程。

{{< /alert >}}

单节点，两个进程

在一个节点上创建一个索引和一个非索引 Sidekiq 进程：

1. 在您的 Sidekiq 节点上，更改 /etc/gitlab/gitlab.rb 文件为：

   sidekiq['enable'] = true
   
   sidekiq['routing_rules'] = [
      ["feature_category=global_search", "global_search"],
      ["*", "default"],
   ]
   
   sidekiq['queue_groups'] = [
      "global_search", # 监听 global_search 队列的进程
      "default,mailers" # 监听 default 和 mailers 队列的进程
   ]
   
   sidekiq['min_concurrency'] = 20
   sidekiq['max_concurrency'] = 20
   

   如果您使用的是极狐 GitLab 16.11 及更早版本，请显式禁用任何队列选择器：

   sidekiq['queue_selector'] = false
   

2. 保存文件并重新配置极狐 GitLab以使更改生效。
3. 在所有其他 Rails 和 Sidekiq 节点上，确保 sidekiq['routing_rules'] 与上述相同。
4. 运行 Rake 任务以迁移现有任务：

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

在重新配置极狐 GitLab 之后立即运行 Rake 任务非常重要。重新配置极狐 GitLab 后，现有任务不会被处理，直到 Rake 任务开始迁移任务。

{{< /alert >}}

两个节点，每个节点一个进程

在两个节点上处理这些队列组：

1. 要设置索引 Sidekiq 进程，请在您的索引 Sidekiq 节点上更改 /etc/gitlab/gitlab.rb 文件为：

   sidekiq['enable'] = true
   
   sidekiq['routing_rules'] = [
      ["feature_category=global_search", "global_search"],
      ["*", "default"],
   ]
   
   sidekiq['queue_groups'] = [
     "global_search", # 监听 global_search 队列的进程
   ]
   
   sidekiq['min_concurrency'] = 20
   sidekiq['max_concurrency'] = 20
   

   如果您使用的是极狐 GitLab 16.11 及更早版本，请显式禁用任何队列选择器：

   sidekiq['queue_selector'] = false
   

2. 保存文件并重新配置极狐 GitLab以使更改生效。

3. 要设置非索引 Sidekiq 进程，请在您的非索引 Sidekiq 节点上更改 /etc/gitlab/gitlab.rb 文件为：

   sidekiq['enable'] = true
   
   sidekiq['routing_rules'] = [
      ["feature_category=global_search", "global_search"],
      ["*", "default"],
   ]
   
   sidekiq['queue_groups'] = [
      "default,mailers" # 监听 default 和 mailers 队列的进程
   ]
   
   sidekiq['min_concurrency'] = 20
   sidekiq['max_concurrency'] = 20
   

   如果您使用的是极狐 GitLab 16.11 及更早版本，请显式禁用任何队列选择器：

   sidekiq['queue_selector'] = false
   

4. 在所有其他 Rails 和 Sidekiq 节点上，确保 sidekiq['routing_rules'] 与上述相同。
5. 保存文件并重新配置极狐 GitLab以使更改生效。

6. 运行 Rake 任务以迁移现有任务：

   sudo gitlab-rake gitlab:sidekiq:migrate_jobs:retry gitlab:sidekiq:migrate_jobs:schedule gitlab:sidekiq:migrate_jobs:queued
   

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

在重新配置极狐 GitLab 之后立即运行 Rake 任务非常重要。重新配置极狐 GitLab 后，现有任务不会被处理，直到 Rake 任务开始迁移任务。

{{< /alert >}}

恢复到基础搜索

有时，您的 Elasticsearch 索引数据可能会出现问题，因此极狐 GitLab 允许您在没有搜索结果时恢复到“基础搜索”，并假设该范围支持基础搜索。这种“基础搜索”表现得好像您根本没有为实例启用高级搜索，并使用其他数据源（如 PostgreSQL 数据和 Git 数据）进行搜索。

灾难恢复

Elasticsearch 是极狐 GitLab 的辅助数据存储。存储在 Elasticsearch 中的所有数据都可以从其他数据源重新生成，特别是 PostgreSQL 和 Gitaly。如果 Elasticsearch 数据存储损坏，您可以从头重新索引所有内容。

如果您的 Elasticsearch 索引太大，可能会导致重新索引所有内容的停机时间太长。您无法自动找到差异并重新同步 Elasticsearch 索引，但可以检查日志中是否有任何遗漏的更新。为了更快地恢复数据，您可以重播：

1. 通过在 elasticsearch.log 中搜索 track_items 来重播所有同步的非仓库更新。您必须再次通过 ::Elastic::ProcessBookkeepingService.track! 发送这些项目。
2. 通过在 elasticsearch.log 中搜索 indexing_commit_range 来重播所有仓库更新。您必须将 IndexStatus#last_commit/last_wiki_commit 设置为日志中最旧的 from_sha，然后使用 ElasticCommitIndexerWorker 和 ElasticWikiIndexerWorker 触发项目的另一次索引。
3. 通过在 sidekiq.log 中搜索 ElasticDeleteProjectWorker 来重播所有项目删除。您必须触发另一个 ElasticDeleteProjectWorker。

您还可以定期进行 Elasticsearch 快照，以减少从数据丢失中恢复而无需从头重新索引所需的时间。