• 安装 Elasticsearch 或使用 AWS OpenSearch 集群
  • Elasticsearch 版本要求
  • OpenSearch 版本要求
  • 系统要求
  • 访问要求
    • Elasticsearch 基于角色的访问控制（RBAC）
    • AWS OpenSearch 服务的访问控制
      • 网络
      • 域名访问策略
      • 细粒度的访问控制
• 升级到新的 Elasticsearch 主要版本
• Elasticsearch 仓库索引器
  • 安装索引器
    • 安装依赖
      • Debian / Ubuntu
      • CentOS / RHEL
      • macOS
    • 构建和安装
  • 查看索引错误
• 启用高级搜索
  • 索引实例
    • 从用户界面索引
    • 使用 Rake 任务
  • 检查索引状态
  • 监控后台作业的状态
  • 高级搜索配置
  • 限制索引的命名空间和项目数据数量
    • 所有的项目记录都被索引
• 启用自定义语言分析器
• 禁用高级搜索
• 取消暂停索引
• 零停机时间重新索引
  • 使用零停机时间重新索引
  • 触发重新索引
    • 触发零停机重新索引
      • Slice multiplier
      • 最大运行分片
  • 将最近的重新索引作业标记为失败并恢复索引
• 索引完整性
• 高级搜索迁移
  • 迁移目录文件
  • 检查等待的迁移
• 极狐GitLab 高级搜索 Rake 任务
  • 环境变量
  • 索引一系列项目或特定项目
• 高级搜索索引范围
• 微调
  • 选择优化集群配置指南
  • 高级搜索设置
    • Elasticsearch 分片数量
      • Indices with database data
      • Indices with repository data
    • Elasticsearch 副本数量
  • 高效地索引大实例
  • 删除文档（documents)
• 用专用的 Sidekiq 节点或进行索引大型实例
  • 单个节点，两个进程
  • 两个节点，每一个节点一个进程
• 切回基础搜索
• 灾难恢复

Elasticsearch

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

要启用高级搜索，您必须： 1. 安装一个 Elasticsearch 或使用 AWS OpenSearch 集群。 1. 启用高级搜索。

安装 Elasticsearch 或使用 AWS OpenSearch 集群

Elasticsearch 和 AWS OpenSearch 没有 包含在 Linux 软件包中。您可以安装一个 Elasticsearch 实例或使用云厂商提供的集群。

您应该在单独的服务器上安装查找集群。将查询集群安装在极狐GitLab 服务器上可能会导致性能问题。

对于使用单个节点的查找集群，集群的状态总是黄色的，因为主 shard 已经被分配了。集群不能将副本分片分配到与主分片相同的节点上。

Elasticsearch 版本要求

• 对 Elasticsearch 6.8 的支持删除于 15.0 版本。

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

高级搜索遵循 Elasticsearch 的生命周期结束策略。

OpenSearch 版本要求

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

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

系统要求

Elasticsearch 需要极狐GitLab 系统要求中记录的资源之外的其他资源。

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

访问要求

极狐GitLab 同时支持HTTP 和基于角色的认证方法，但是这取决于您的需求和您所使用的后段服务。

Elasticsearch 基于角色的访问控制（RBAC）

Elasticsearch 可以提供基于角色的访问控制来进一步加强集群的安全。要想在 Elasticsearch 集群上访问或执行操作，Admin 区域中配置的 Username 必须拥有授予以下权限的角色。Username 从 极狐GitLab 向搜索集群发出请求。

更多信息，可以查看 Elasticsearch 基于角色的访问控制 和 Elasticsearch 安全权限。

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

AWS OpenSearch 服务的访问控制

先决条件：

• 当您创建 OpenSearch domains 时，您必须在您的 AWS 账号上有一个名为 AWSServiceRoleForAmazonOpenSearchService 的服务链接角色。
• AWS OpenSearch 域的访问策略必须允许 es:ESHttp* 操作。

AWSServiceRoleForAmazonOpenSearchService 是由 所有 OpenSearch domains 使用的。在大多数情况下，当您使用 AWS Management Console 创建第一个 OpenSearch domain 时，此角色会自动创建。要手动创建服务链接角色，请参阅 AWS 文档。

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

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

网络

针对此安全层，您可以在创建 OpenSearch domain 时选择 公共访问，以便任何客户端都可以访问域端点。如果您选择 VPC 访问，则客户端必须连接到 VPC 才能访问端点。

更多详情，可以查看AWS 文档。

域名访问策略

针对 AWS OpenSearch，极狐GitLab 支持以下几种域名访问策略：

• 基于资源（域名）的访问策略：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/*"
    }
  ]
}

基于身份识别的策略示例

下面是一个允许 es:ESHttp* 操作的基于身份识别的策略示例：

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

细粒度的访问控制

当您启用细粒度的访问控制，您必须通过以下方式中的一种来设置一个master user：

• 将 IAM ARN 设置为 master 用户.
• 创建 master 用户.

将 IAM ARN 设置为 master 用户

如果您将 IAM 主体作为 master 用户，所有请求到集群都必须使用 AWS 签名版本 4 进行签名。您也可以指定 IAM ARN，这是您分配给 EC2 实例的 IAM 角色。更多详情，可以查看 AWS 文档。

要将一个 IAM ARN 设置为 master 用户，您必须在您的极狐GitLab 实例上使用具有 IAM 凭据的 AWS OpenSearch 服务：

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

5. 选择 保存更改。

   对于部署在 EC2 实例上的极狐GitLab 实例，您不需要输入访问密钥。您的极狐GitLab 实例会自动从 AWS Instance Metadata Service (IMDS) 获取这些密钥。

创建 master 用户

如果您在内部用户数据库中创建一个 master 用户，您可以使用 HTTP basic 认证向集群发送请求。更多详情，可以查看 AWS 文档。

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

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

升级到新的 Elasticsearch 主要版本

• 对 Elasticsearch 6.8 的支持删除于 15.0 版本。

升级 Elasticsearch 时不需要更改极狐GitLab 配置。

在 Elasticsearch 升级期间，您必须：

• 暂停索引以便变更依旧可以被追踪。
• 禁用高级搜索以便搜索不会因为 HTTP 500 错误是失败。

当您的 Elasticsearch 集群全部升级和激活后，恢复索引并启用高级搜索。

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

Elasticsearch 仓库索引器

为了索引 Git 仓库数据，极狐GitLab 使用 Go 编写的索引器。

安装索引器

首先您需要安装一些依赖，然后构建和安装索引器本身。

安装依赖

此项目依赖 Unicode 的内部组件 (ICU) 进行文本编码，因此我们必须确保在运行 make 之前安装了平台研发软件包。

Debian / Ubuntu

在 Debian 或 Ubuntu 上，运行：

sudo apt install libicu-dev

CentOS / RHEL

在 CentOS 或 RHEL 上，运行：

sudo yum install libicu-devel

macOS

NOTE： 首先，您必须安装 Homebrew。

在 macOS 上安装，运行：

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

构建和安装

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

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

# Run the installation task for 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 环境变量修改安装路径。如果您在执行 sudo 的时候需要加上 -E 标志。

比如：

PREFIX=/usr sudo -E make install

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

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

查看索引错误

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

启用高级搜索

先决条件：

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

要启用高级搜索：

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

对于超过 50GB 仓库数据的极狐GitLab 实例来说，请查阅高效索引大型实例。

索引实例

从用户界面索引

• 自极狐GitLab 17.3 引入。

先决条件：

• 您必须是具有访问权限的管理员。

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

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

1. 在左侧导航栏底部，选择 管理员。
2. 选择 设置 > 搜索。
3. 选择 Elasticsearch 索引 勾选框，然后选择 保存变更。
4. 选择 索引整个实例。

使用 Rake 任务

先决条件：

• 您必须是具有访问权限的管理员。

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

# WARNING: This task deletes all existing indices
# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index

# WARNING: This task deletes all existing indices
# For self-compiled installations
bundle exec rake gitlab:elastic:index RAILS_ENV=production

要索引特定数据，使用如下的 Rake 任务：

# For installations that use the Linux package
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

# For self-compiled installations
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。这些队列包含用于索引项目和群组的代码和维基数据的工作。

高级搜索配置

以下 Elasticsearch 设置可用：

限制索引的命名空间和项目数据数量

当您选择 限制索引的命名空间和项目数据数量 勾选框时，您可以指定命名空间和项目进行索引。如果命名空间是一个群组，任何属于这些子群组的子群组和项目都会被索引。

如果所有命名空间都被索引的话，高级搜索仅提供跨群组的代码/提交搜索（全局）。在只索引了部分命名空间的特殊场景下，全局搜索不提供代码或代码提交范围内的搜索。这只在已索引的命名空间范围内是可能的。没有版本在多个已索引的命名空间中进行代码/提交搜索（当只索引了命名空间的一部分时）。比如，如果索引了两个群组，则没法同时在两个群组上运行单个代码搜索。您只能在第一个群组上运行代码搜索，然后再在第二个群组上执行。

如果您没有指定任何命名空间和项目，只有项目记录会被索引。

所有的项目记录都被索引

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

当您选择 限制索引的命名空间和项目数据数量 勾选框时：

• 所有项目记录都会被索引。
• 相关的数据（议题、合并请求或代码）不会被索引。

如果您不指定任何命名空间或项目，则只有项目记录会被索引。

启用自定义语言分析器

先决条件：

• 您必须是具有访问权限的管理员。

您可以使用 Elastic 的 smartcn 分析插件来改善对于中文的支持。

要启用语言支持：

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

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

禁用高级搜索

要禁用 Elasticsearch 集成：

1. 在左侧导航栏底部，选择 管理员。
2. 在左侧边栏中，选择 设置 > 高级搜索。
3. 取消选中 Elasticsearch 索引 和 启用 Elasticsearch 的搜索。
4. 选择 保存更改。

5. 可选。删除现有索引：

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:delete_index
   
   # Installations from source
   bundle exec rake gitlab:elastic:delete_index RAILS_ENV=production
   

取消暂停索引

先决条件：

• 您必须是具有访问权限的管理员。

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

零停机时间重新索引

这种重新索引方法背后的想法是利用 Elasticsearch reindex API 和 Elasticsearch 索引别名功能来执行操作。我们设置了一个索引别名，它连接到极狐GitLab 用于读取/写入的 primary 索引。当重新索引过程开始时，我们会暂时暂停对 primary 索引的写入。然后，我们创建另一个索引并调用将索引数据迁移到新索引上的 Reindex API。重新索引作业完成后，我们通过将索引别名连接到新索引来切换到新索引，这将成为新的 primary 索引。最后，我们恢复写入并恢复正常操作。

使用零停机时间重新索引

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

触发重新索引

先决条件：

• 您必须是具有访问权限的管理员。

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

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

在此流程完成后，原始的索引将在 14 天后被删除。您可以在触发重新索引流程的页面上通过点击 取消 按钮来取消此操作。

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

触发零停机重新索引

先决条件：

• 您必须是具有访问权限的管理员。

要出发零停机重新索引：

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

3. 展开 Elasticsearch 零停机重新索引。

   以下设置可用：

   • Slice multiplier
   • 最大运行分片](#maximum-running-slices)

Slice multiplier

Slice multiplier 计算重新索引期间的分片数。

极狐GitLab 使用手动分片来有效和安全地控制重新索引，允许用户仅重试失败的分片。

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

最大运行分片

最大运行分片参数默认为 60，对应于在 Elasticsearch 重新索引期间允许并发运行的最大分片数。

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

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

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

有时，您可能希望放弃未完成的重新索引作业并恢复索引。您可以通过以下步骤实现此目的：

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

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:mark_reindex_failed
   
   # Installations from source
   bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production
   

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

索引完整性

• 引入于极狐GitLab 15.10，功能标志为 search_index_integrity。默认禁用。
• 普遍可用于极狐GitLab 16.4。移除功能标志 search_index_integrity。

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

高级搜索迁移

引入于 13.6 版本。

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

迁移目录文件

• 在极狐GitLab 16.3 引入。

每一次迁移都会在 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?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 文件。

极狐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 使用 or equal 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 索引使用以下范围：

微调

选择优化集群配置指南

选择集群配置的基础指南，您可以参考 Elastic Cloud Calculator。您可以在下面找到更多的信息。

• 一般来说，您要用至少有 2 节点、1 个副本的集群配置，这让您更有韧性。如果您的存储使用在快速增加，您可能需要计划水平扩容（增加更多节点）。
• 不推荐为搜索集群使用 HDD 存储，因为这会儿遇到性能问题。使用 SSD 存储更好些（比如，NVMe 或 SATA SSD 驱动）。
• You should not use coordinating-only nodes with large instances. Coordinating-only nodes are smaller than data nodes, which can impact performance and advanced search migrations.
• You can use the GitLab Performance Tool to benchmark search performance with different search cluster sizes and configurations.
• Heap size should be set to no more than 50% of your physical RAM. Additionally, it shouldn’t be set to more than the threshold for zero-based compressed oops. The exact threshold varies, but 26 GB is safe on most systems, but can also be as large as 30 GB on some systems. See Heap size settings and Setting JVM options for more details.
• refresh_interval is a per index setting. You may want to adjust that from default 1s to a bigger value if you don’t need data in real-time. This changes how soon you see fresh results. If that’s important for you, you should leave it as close as possible to the default value.
• You might want to raise indices.memory.index_buffer_size to 30% or 40% if you have a lot of heavy indexing operations.

高级搜索设置

Elasticsearch 分片数量

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

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

要为索引更新分片大小，修改设置并触发零停机重新索引。

Indices with database data

For indices that contain database data:

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

Run the Rake task gitlab:elastic:estimate_shard_sizes to determine the number of shards. The task returns approximate document counts and recommendations for shard and replica sizes.

Indices with repository data

For indices that contain repository data:

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

Keep the average shard size between a few GB and 30 GB. If the average shard size grows to more than 30 GB, increase the shard size for the index and trigger zero-downtime reindexing. To ensure the cluster is healthy, the number of shards per node must not exceed 20 times the configured heap size. For example, a node with a 30 GB heap must have a maximum of 600 shards.

Elasticsearch 副本数量

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

对多节点集群，将每个索引的 Elasticsearch 副本数设为 1（也就是每个分片有一个副本）。这个数字不能是 0，因为失去一个节点会损坏索引。

高效地索引大实例

先决条件：

• 您必须是具有访问权限的管理员。

WARNING： 索引大实例会生成大量 Sidekiq 作业。确保通过扩容设置或创建额外的 Sidekiq 进程来为此做好准备。

如果启用高级搜索而引起问题，因为大量的数据被索引，则：

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

2. 创建空的索引：

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:create_empty_index
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production
   

3. 如果这是针对您的极狐GitLab 实例，清楚索引状态：

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:clear_index_status
   
   # For self-compiled installations
   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 设置回期望的值。

   NOTE： 此项设置是可选的但是能够显著加速大型的索引操作。

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

6. 索引项目和他们相关的数据：

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:index_projects
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production
   

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

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:index_projects_status
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production
   
   Indexing is 65.55% complete (6555/10000 projects)
   

   如果您想为项目所内设定范围，提供 ID_FROM 和 ID_TO 参数即可：

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production
   

   ID_FROM 和 ID_TO 是项目 ID。两个参数都是可选的。上面的实例会索引从 1001 到 2000 的所有项目。

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

   您还可以使用 gitlab:elastic:clear_index_status Rake 任务来强制索引以“忘记”所有进程，因此，它会从开始处重试索引过程。

7. 史诗、群组 wiki、个人片段以及用户和项目并不关联，因此必须单独索引：

   # For installations that use the Linux package
   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
   
   # For self-compiled installations
   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 的高级搜索 复选框。

删除文档（documents)

不管什么时候对已经索引的极狐GitLab 项目做了变更或删除（例如，合并请求描述被更改，默认分支中的文件被删除，项目被删除等），索引中的文档都会被删除。然而，由于这些是“软”删除，”被删除的文档” 总数会增加而且会浪费空间。Elasticsearch 会非常智能的对片段进行合并以移除这些被删除的文档。然而，取决于这些被删除的文档的数量，以及您极狐GitLab 实例上的活动，在索引上可能看到多达 50% 的浪费空间。

一般情况下，我们推荐让 Elasticsearch 使用默认设置，自己自动合并和回收空间。从 Lucene 的删除文档处理，“总体而言，除了可能减少最大段大小之外，最好将 Lucene 默认值保持不变，不要过于担心何时回收删除。”

然而，对于大型实例，您可能希望调整合并策略设置：

• 考虑将 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.segments_per_tier，它控制了合并的频率。但是这会导致合并决策费用，所以除非您了解权衡，否则不建议更改此设置。

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

• 不要作强制合并 来移除删除的文档。文档中有一个警告，指出这可能导致永远不会被回收的非常大的片段，也可能导致显著的性能或可用性问题。

用专用的 Sidekiq 节点或进行索引大型实例

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

因为极狐GitLab 允许您启用多个 Sidekiq 进程，您可以创建一个额外的进程来专门索引队列（或队列群组）。这种方式下，您可以确保索引队列总是有一个专用的工作器，同时其他的队列还有其他的专用工作器，因此来避免资源竞争。

为了此目的，可以使用路由规则选项以允许 Sidekiq 基于工作器匹配查询将作业路由到特定的队列。

为了处理此情况，我们一般会推荐一下两种选项中的一种。您可以：

• 使用单节点，双队列群组.
• 使用双节点，双队列群组.

针对以下步骤，需要考虑 sidekiq['routing_rules'] 入口：

• 视 ["feature_category=global_search", "global_search"] 为所有索引作业并被路由到 global_search 队列。
• 视 ["*", "default"] 为所有非索引作业并被路由到 default 队列。

至少要在 sidekiq['queue_groups'] 的一个进程中包含 mailers 队列，否则邮件作业将无法被处理。

单个节点，两个进程

为了在一个节点上同时创建索引和非索引 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", # process that listens to global_search queue
      "default,mailers" # process that listens to default and mailers queue
   ]
   
   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 任务来迁移既有作业：

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

在两个节点上处理这些对接群组：

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", # process that listens to global_search queue
   ]
   
   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" # process that listens to default and mailers queue
   ]
   
   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
   

切回基础搜索

有时候您的 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 做快照来减少从数据丢失中恢复所需的时间，而无需从头重新索引所有内容。