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

Elasticsearch 索引和搜索故障排除

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

在使用 Elasticsearch 索引或搜索时，您可能会遇到以下问题。

创建空索引

对于索引问题，首先尝试创建一个空索引。检查 Elasticsearch 实例，查看是否存在 gitlab-production 索引。如果存在，请在 Elasticsearch 实例上手动删除该索引，然后尝试从 recreate_index Rake 任务重新创建。

如果仍然遇到问题，尝试在 Elasticsearch 实例上手动创建索引。如果您：

无法创建索引，请联系您的 Elasticsearch 管理员。
可以创建索引，请联系 GitLab 支持。

检查已索引项目的状态

您可以检查项目索引过程中的错误。错误可能出现在：

GitLab 实例上：如果您无法自行修复，请联系 GitLab 支持获取指导。
Elasticsearch 实例上：如果错误未列出，请联系您的 Elasticsearch 管理员。

如果索引没有返回错误，请使用以下 Rake 任务检查已索引项目的状态：

sudo gitlab-rake gitlab:elastic:index_projects_status 查看整体状态
sudo gitlab-rake gitlab:elastic:projects_not_indexed 查看未索引的具体项目

如果索引：

已完成，请联系 GitLab 支持。
未完成，尝试通过运行 sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=<项目 ID> ID_TO=<项目 ID> 来重新索引该项目。

如果重新索引项目时出现错误：

GitLab 实例上：请联系 GitLab 支持。
Elasticsearch 实例上或完全没有错误：请联系您的 Elasticsearch 管理员检查实例。

更新 GitLab 后没有搜索结果

我们持续更新索引策略，并支持更新版本的 Elasticsearch。当进行索引更改时，您可能需要在更新 GitLab 后进行重新索引。

索引所有仓库后没有搜索结果

不要将这些说明用于仅索引命名空间子集的场景。

确保您索引了所有数据库数据。

如果 UI 搜索中没有结果（hits），请通过 rails 控制台（sudo gitlab-rails console）检查是否看到相同的结果：

u = User.find_by_username('your-username')
s = SearchService.new(u, {:search => 'search_term', :scope => 'blobs'})
pp s.search_objects.to_a

除此之外，通过 Elasticsearch Search API 检查数据是否在 Elasticsearch 端显示：

curl --request GET <elasticsearch_server_ip>:9200/gitlab-production/_search?q=<search_term>

也可以进行更复杂的 Elasticsearch API 调用。

如果结果：

一致，请确保您使用的是支持的语法。高级搜索不支持精确子字符串匹配。
不一致，这表明从项目生成的文档存在问题。最好重新索引该项目。

有关搜索特定类型数据的更多信息，请参阅 Elasticsearch 索引范围。

切换 Elasticsearch 服务器后没有搜索结果

要重新索引数据库、仓库和 Wiki，请索引实例。

索引失败并显示 `error: elastic: Error 429 (Too Many Requests)`

如果在索引过程中 Search::Elastic::CommitIndexerWorker Sidekiq 工作线程出现此错误，通常意味着 Elasticsearch 无法跟上索引请求的并发性。要解决此问题，请更改以下设置：

要降低索引吞吐量，可以减少 批量请求并发数（参见高级搜索设置）。默认值为 10，但您可以将其降低到 1 以减少并发索引操作的数量。
如果更改 批量请求并发数 没有帮助，您可以使用路由规则选项将索引作业限制到特定的 Sidekiq 节点，这应该会减少索引请求的数量。

错误：`Elasticsearch::Transport::Transport::Errors::RequestEntityTooLarge`

[413] {"Message":"Request size exceeded 10485760 bytes"}

当您的 Elasticsearch 集群配置为拒绝超过特定大小的请求（本例中为 10 MiB）时，会出现此异常。这对应于 elasticsearch.yml 中的 http.max_content_length 设置。将其增加到更大的值并重启您的 Elasticsearch 集群。

AWS 根据底层实例的大小对 HTTP 请求载荷的最大大小有网络限制。将最大批量请求大小设置为低于 10 MiB 的值。

索引非常慢或失败并显示 `rejected execution of coordinating operation`

批量请求被 Elasticsearch 节点拒绝可能是由于负载和可用内存不足造成的。确保您的 Elasticsearch 集群满足系统要求并有足够的资源来执行批量操作。另请参阅错误 “429 (Too Many Requests)”。

索引失败并显示 `strict_dynamic_mapping_exception`

如果在进行重大升级之前所有高级搜索迁移未完成，索引可能会失败。此错误可能伴随着大量的 Sidekiq 积压。要修复索引失败，您必须重新索引数据库、仓库和 Wiki。

暂停索引，以便 Sidekiq 可以赶上：

sudo gitlab-rake gitlab:elastic:pause_indexing

从头重新创建索引。

恢复索引：

sudo gitlab-rake gitlab:elastic:resume_indexing

索引持续暂停并显示 `elasticsearch_pause_indexing setting is enabled`

您可能会注意到运行搜索时没有检测到新数据。

当新数据未被正确索引时，会出现此错误。

要解决此错误，请重新索引您的数据。

但是，在重新索引时，您可能会遇到索引过程持续暂停的错误，Elasticsearch 日志显示如下：

"message":"elasticsearch_pause_indexing setting is enabled. Job was added to the waiting queue"

如果重新索引无法解决此问题，并且您没有手动暂停索引过程，此错误可能是因为两个 GitLab 实例共享一个 Elasticsearch 集群。

要解决此错误，断开其中一个 GitLab 实例对 Elasticsearch 集群的使用。

有关更多信息，请参阅问题 3421。

搜索失败并显示 `too_many_clauses: maxClauseCount is set to 1024`

当查询的子句数超过 indices.query.bool.max_clause_count 设置中定义的值时，会出现此错误：

在 Elasticsearch 7.17 及更早版本中，默认值为 1024。
在 Elasticsearch 8.0 中，默认值为 4096。
在 Elasticsearch 8.1 及更高版本中，该设置已弃用，值是动态确定的。

要解决此问题，请增加该值或升级到 Elasticsearch 8.1 或更高版本。增加值可能导致性能下降。

最后手段：重新创建索引

在某些情况下，数据可能从未被索引，也不在队列中，或者索引处于某种状态，导致迁移无法进行。最好通过查看日志来尝试排查问题的根本原因。

作为最后手段，您可以从头开始重新创建索引。对于小型 GitLab 安装，重新创建索引可能是快速解决某些问题的方法。但是，对于大型 GitLab 安装，此方法可能需要很长时间。在索引完成之前，您的索引不会显示正确的搜索结果。您可能希望在索引运行时清除 启用 Elasticsearch 搜索 复选框。

如果您确定已阅读上述注意事项并希望继续，则应运行以下 Rake 任务从头开始重新创建整个索引。

# 警告：在阅读上述描述之前不要运行此命令
sudo gitlab-rake gitlab:elastic:index

# 警告：在阅读上述描述之前不要运行此命令
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:index

提高 Elasticsearch 性能

为了提高性能，请确保：

Elasticsearch 服务器不要运行在与 GitLab 相同的节点上。
Elasticsearch 服务器有足够的 RAM 和 CPU 内核。
正在使用 分片。

更详细地说，如果 Elasticsearch 与 GitLab 运行在同一台服务器上，资源竞争非常可能发生。理想情况下，需要充足资源的 Elasticsearch 应该在自己的服务器上运行（可能与 Logstash 和 Kibana 结合使用）。

对于 Elasticsearch，RAM 是关键资源。Elasticsearch 本身推荐：

对于非生产实例，至少 8 GB RAM。
对于生产实例，至少 16 GB RAM。
理想情况下，64 GB RAM。

对于 CPU，Elasticsearch 推荐至少 2 个 CPU 内核，但 Elasticsearch 表示常见设置使用多达 8 个内核。有关服务器规格的更多详细信息，请参阅 Elasticsearch 硬件指南。

除了明显的因素外，分片也起着作用。分片是 Elasticsearch 的核心部分。它允许索引的水平扩展，这在处理大量数据时很有帮助。

根据 GitLab 的索引方式，有大量文档被索引。通过使用分片，您可以加快 Elasticsearch 定位数据的速度，因为每个分片都是一个 Lucene 索引。

如果您不使用分片，在生产环境中使用 Elasticsearch 时很可能会遇到问题。

只有一个分片的索引 没有扩展因子，并且在频繁调用时很可能会遇到问题。请参阅 Elasticsearch 容量规划文档。

确定是否使用分片的最简单方法是检查 Elasticsearch Health API 的输出：

红色表示集群已关闭。
黄色表示集群已启动但没有分片/复制。
绿色表示集群健康（已启动、分片、复制）。

对于生产使用，它应该始终是绿色的。

除了这些步骤外，您还需要检查一些更复杂的事情，例如合并和缓存。这些可能会变得复杂，并且需要一些时间来学习，因此如果您需要进一步深入研究这些内容，最好与 Elasticsearch 专家一起解决或寻求帮助。

联系 GitLab 支持，但这很可能是经验丰富的 Elasticsearch 管理员更擅长处理的事情。

初始索引缓慢

您的 GitLab 实例拥有的数据越多，索引所需的时间就越长。您可以使用 Rake 任务 sudo gitlab-rake gitlab:elastic:estimate_cluster_size 来估算集群大小。

对于代码文档

确保有足够的 Sidekiq 节点和进程来高效索引代码、提交和 Wiki。如果初始索引缓慢，请考虑专用的 Sidekiq 节点或进程。

对于非代码文档

如果初始索引缓慢但 Sidekiq 有足够的节点和进程，您可以在 GitLab 中调整高级搜索工作线程设置。对于 重新排队索引工作线程，默认值为 false。对于 非代码索引的分片数，默认值为 2。这些设置将索引限制为每分钟 2000 个文档。

要调整工作线程设置：

在左侧边栏底部，选择 管理员。
选择 设置 > 搜索。
展开 高级搜索。
选中 重新排队索引工作线程 复选框。
在 非代码索引的分片数 文本框中，输入一个大于 2 的值。
选择 保存更改。