故障排除自管理 mongot 部署

开始之前

在执行场景之前，请确认部署的状态：

• 如果您的指标出现异常，但尚不知道问题出在何处，请从 mongot 的指标参考中的指标定义和 mongot 的推荐警报中的阈值开始。

• 如果您最近完成了部署或配置更改，请从 验证 mongot 连接开始。

如果您的症状与任何场景都不匹配，请按照 捕获诊断信息以获取支持中的描述捕获文件，并打开支持工单。

mongot 未启动

mongot 进程在启动后无法启动。

症状

• 该过程在启动后几秒内退出。

• 在容器中，进程会循环重启。

• 未出现“ready”日志消息。

常见原因

优先顺序：

1. 配置文件格式错误或缺少必需字段。

2. 启动时对 mongod 的身份验证失败。

3. mongot 无法在配置的地址访问 mongod。

4. 发生 TLS 配置错误。

5. 配置端口已在使用。

6. 数据路径不可写。

诊断

查看最新的启动日志行。错误消息指明失败的子系统。

容器

Linux

日志文件

docker logs --tail 100 <container-id>

journalctl -u mongot --no-pager | tail -n 200

tail -n 200 /var/log/mongot/mongot.log

查找以下模式：

• Failed to parse config file 表示 YAML 无效。

• Authentication failed 或 Unauthorized 表示凭证或 x.509 信任问题。

• Connection refused 或 unable to connect to host 表示主机或端口错误，或 mongod 未运行。

• SSL handshake failed 表示 CA 信任或证书 SAN 不匹配。

• Address already in use 表示另一个进程绑定到同一端口。

• Cannot write to <dataPath> 表示权限或路径问题。

解析

• 配置：修复 YAML。要了解有效设置，请参阅配置 mongot。

• 身份验证：验证用户是否在 mongod 上存在并具有所需角色。请参阅 配置 mongot 的身份验证和授权。

• 可访问性：从 mongot 主机运行 nc -zv <mongod-host> <mongod-port>。检查防火墙、DNS 和 mongod bindIp 设置。

• TLS：验证 mongot 和 mongod 都信任同一证书权限 (CA)，以便各方的证书链都连接到可信的 CA。另外，请验证证书 SAN 与 mongot 使用的主机名匹配。请参阅 配置 mongot 的 TLS 加密。

• 端口占用：使用 ss -lntp 或 lsof -i :<port> 来识别冲突进程。更改 mongot 端口或停止其他进程。

• 数据路径：验证该目录是否存在，且 mongot 进程用户对其具有写入权限。根据需要更新所有权和权限。

查询失败并出现连接错误

查询失败，因为 mongod 无法访问 mongot。

症状

• $search、$searchMeta 或 $vectorSearch 查询返回连接错误，例如 Error connecting to <host>:<port> :: Connection refused。

• 或查询返回 Error connecting to Search Index Management service。

常见原因

1. mongot 未在 mongod 尝试访问的主机上运行。

2. mongot 的 mongod 托管或端口设置错误，与 mongot 监听器不匹配。

3. mongot 正在运行但已崩溃或正在重启。

4. TLS 不匹配。mongod 配置为 TLS，但 mongot 未配置，反之亦然。

诊断

从 mongod 主机测试与 mongot 的连接：

nc -zv <mongot-host> <mongot-port>

从 mongot 主机确认进程正在运行和监听：

ps aux | grep '[m]ongot'
ss -lntp | grep <mongot-port>

检查 mongod 日志中的匹配错误和配置的 mongot 主机：

grep -E 'mongotHost|searchIndexManagementHostAndPort' \
  /var/log/mongodb/mongod.log

解析

• 如果 mongot 未运行，请重启。如果无法启动，请按照mongot 未启动。操作。

• 如果 mongot 托管设置错误，请更正 mongod 参数并重启 mongod。

• 如果 TLS 不匹配，请在两侧调和 TLS 配置。请参阅配置 mongot 的 TLS 加密。

mongot 保持重新同步

索引反复脱离稳定状态并开始初始同步。

症状

• 日志重复 Initial sync starting，其后是异常。

• 在稳定状态下，日志显示 Exception requiring resync occurred during steady state replication。

• 索引管理器状态返回 INITIAL_SYNC。

• 在重新同步窗口期间，搜索返回过时结果。

常见原因

1. mongod oplog 在 mongot 追上之前已经卷动，通常是因为 mongot 速度过慢或已关闭，或因为 oplog 过小。

2. 短暂性问题，例如网络中断或短暂 mongod 重启，导致稳态异常。单次发生可以恢复，但重复发生则不能。

3. 文档映射爆炸会反复填充 mongot 堆，触发内存不足错误并重新同步。

4. 索引数据已损坏。

5. 大量索引、动态映射或成本高昂的字段选择会导致持续复制延迟。

诊断

查看以下指标：

• mongot_replication_mongodb_indexManagerState 在 INITIAL_SYNC 和 STEADY_STATE 之间循环。

• mongot_index_stats_numLuceneMaxDocs 是循环的或卡住的。

• mongot_index_stats_indexing_replicationLagMs 继续上升。

• mongot_jvm_memory_used_bytes 和 mongot_jvm_gc_pause_seconds_sum 在内存压力下升高。

在 mongot 日志中查找在重新同步之前发生的错误，然后检查 oplog window 和堆：

grep -E 'SteadyStateException|CappedPositionLost|OutOfMemoryError' \
  mongot.log

在 mongosh 中，使用 db.getReplicationInfo() 检查 mongod oplog 大小。

解析

• 如果 oplog 对 mongot 应用速率而言太小，请增加 mongod oplog 大小，或通过增加 mongot 容量或减少并发索引来缩小差距。

• 如果稳定状态异常重复发生，请捕获 FTDC 并打开支持工单。

• 对于文档映射爆炸，请找到出问题的索引，通常是具有 dynamic: true 映射的索引，该索引会批量吸收具有任意密钥的文档。切换到 静态映射 或限制字段集，然后重启 mongot 以清除堆状态。

• 对于索引损坏（很少发生），请捕获 FTDC，然后删除并重建受影响的索引。请勿手动删除数据路径下的文件。

内存不足错误或 mongot 被操作系统终止

mongot 因为内存不足而退出。

症状

• mongot 意外退出，容器重启计数增加。

• 日志以 OutOfMemoryError: Java heap space，即 Java虚拟机（JVM） 侧内存不足错误结尾。

• dmesg 或 journalctl 的系统日志显示 OOM killer 终止了该进程，这是主机端内存不足错误。

常见原因

1. 堆对工作负载而言太小，尤其是在大型初始同步或合并期间。

2. 文档映射爆炸会消耗堆。请参阅mongot 保持同步。

3. 容器内存限制过低。即使堆大小正确，JVM 非堆开销也可能超过限制。

4. 索引定义不当，例如索引过多或定义过于复杂，会增加内存压力。

5. 发生内存泄漏，这在预览构建版本中很少见，但有可能。

诊断

查看以下指标：

• mongot_jvm_memory_used_bytes 随着内存密集型查询和索引定义的增加而增加。

• mongot_jvm_gc_pause_seconds_sum 显示垃圾回收暂停中花费的累积时间。

• machine_swap_bytes 在健康的部署中保持接近零。交换使用情况表明存储器压力过大。

检查 mongot 日志中的内存不足堆栈追踪和配置的堆大小：

grep -E 'OutOfMemoryError|Java heap space' mongot.log
ps -ef | grep '[m]ongot' | grep -oE '\-Xmx[0-9a-zA-Z]+'

对于容器，请检查配置的内存限制：

docker inspect <container> | grep -i memory

解析

• 如果主机具有内存余量，请增加 -Xmx。

• 在容器中，将内存限制设置为明显大于 -Xmx 的值，以适应非堆开销。作为起始点，将容器限制设置为至少 -Xmx 值加 30% 。

• 如果堆够大，但仍然出现内存不足，请查找导致爆炸的索引模式。mongot 日志标识索引。

• 如果索引是内存压力的来源，则减少索引数量或简化开销较高的索引定义。

• 如果您怀疑存在内存泄漏，请捕获 FTDC 和堆转储以获取支持。

初始同步缓慢或卡住

新索引完成初始同步需要很长时间。

症状

• 索引状态在 INITIAL_SYNC 中保持很长时间。

• 在某些情况下，复制经理在重试初始同步之前进入 INITIAL_SYNC_BACKOFF。

• mongot_index_stats_numLuceneMaxDocs 只是缓慢增长。

• 在初始同步运行时，索引不可查询。

常见原因

1. mongod 源主机配置不足，无法够快地提供初始同步。

2. 其他地方的磁盘、CPU 或内存压力会延缓构建。

3. 大量初始回填超出当前硬件套件。

诊断

观察 mongot_replication_mongodb_indexManagerState 和 mongot_index_stats_numLuceneMaxDocs 的文档增长。

在初始同步期间，请勿将 mongot_index_stats_indexing_replicationLagMs 视为权威。在初始同步期间，此指标不会有意义地填充。相反，请查看系统健康指标，以确认系统具有足够的资源。

解析

• 如果mongod源主机是瓶颈，请扩展该主机。

• 在系统资源受限的情况下添加 CPU 或内存。

• 在重试大型初始构建之前，请重新检查磁盘内存容量。

索引停滞在 PENDING 或 BUILDING 状态

索引无法超过 PENDING 或 BUILDING 状态。

症状

• 在不大的集合上，索引在 PENDING 或 BUILDING 中保持超过几分钟。

• mongot 日志未显示任何故障，仅显示缺乏进度。

常见原因

1. mongot 没有取得同步进度。请参阅大型复制延迟。

2. 自动嵌入索引的嵌入终结点失败。

3. 索引执行程序池被同时构建的其他索引占用。

4. mongot 最近重启，索引正在追赶。

5. 即使定义已被接受，磁盘压力仍会暂停新的构建或重新构建。

诊断

查看 mongot_replication_mongodb_indexManagerState 和 mongot_index_stats_numLuceneMaxDocs 以了解进度。

在 mongosh 中，检查索引状态和任何错误字段：

db.<collection>.getSearchIndexes()

确认索引吞吐量正在增加：

rate(mongot_index_stats_indexing_insert_total[5m])

对于自动嵌入索引，请检查嵌入重试计数器是否大于零：

rate(mongot_indexing_steadyStateChangeStream_rescheduledEmbeddingGetMores_total[5m])
rate(mongot_initialsync_queue_requeuedEmbeddingInitialSyncs_total[5m])

解析

• 如果索引吞吐量平坦，请查看 mongot 日志以获取索引名称和任何异常。

• 如果嵌入重试次数大于零，请修复嵌入路径。请参阅 为 MongoDB 向量搜索自动嵌入配置 mongot。

• 如果执行程序池已饱和，请减少并发索引构建或扩展 mongot。

• 如果磁盘是阻塞，请添加头部空间或将构建移动到较大节点。

查询返回空结果

即使存在匹配文档，查询也不返回结果。

症状

• 您可以在预期会在搜索索引中找到的文档上运行 findOne()。

• 对同一字段的 $search 查询返回空值，或返回的结果少于预期。

常见原因

1. 您所期望匹配的文档，其索引尚未构建完成。

2. 复制延迟意味着 mongot 尚未收到文档。

3. 索引定义不包含您搜索的字段。

4. 查询表达式错误，例如对索引为 string 的字段使用数值表达式。

5. 索引特定文档失败。

诊断

在 mongosh 中，检查索引状态并确认索引是否已经查看了文档：

db.<collection>.getSearchIndexes()

然后查看 mongot_index_stats_indexing_replicationLagMs 以检查复制延迟。

解析

• 等待索引达到就绪状态。

• 等待复制延迟清除。

• 调整索引定义或查询。

• 如果索引特定文档失败，mongot 日志会标识失败原因。修复或过滤这些文档。

CPU 饱和或限流

持续的 CPU 压力会降低查询和复制性能。

症状

• 在持续的 CPU 压力下，查询延迟会增加。

• 复制延迟会增加，因为查询工作和索引工作会争用 CPU。

• 在严重情况下，健康检查失败，进程重新启动。

常见原因

1. mongot 托管的资源不足，无法满足当前的查询和索引工作组合的需求。

2. 过多的并发索引工作会与查询执行相互竞争。

3. 工作负载需要负载分流或容量扩展。

诊断

查看以下指标：

• mongot_command_searchCommandTotalLatency_seconds_max

• mongot_index_stats_indexing_replicationLagMs

• 主机 CPU 和负载指标，在饱和状态下会出现峰值。

没有明确的日志消息表明主机受到 CPU 限制。

解析

• 扩展 mongot 主机上的 CPU。

• 如果可用，请通过负载削减做法减少负载。

• 如果复制活动与查询发生冲突，请简化索引工作。

磁盘压力或数据路径几乎已满

mongot 数据路径的可用空间不足。

症状

• mongot 数据路径上的空间变小至零。

• 一旦磁盘使用率过高，现有索引会累积复制延迟。

• 当磁盘压力过大时，新建或重建的索引可能会保持在 INITIAL_SYNC。

• 即使复制因磁盘保护而暂停，查询也会继续成功。

常见原因

1. 托管没有足够的空间来满足正常索引增长。

2. 新建或重建索引所需的临时空间超过了当前磁盘的可用容量。

诊断

查看以下指标：

• mongot_system_disk_space_data_path_free_bytes 报告数据目录中的可用字节。

• mongot_system_disk_space_data_path_total_bytes 报告数据目录中的总字节数。

关注与磁盘阈值相关的复制暂停行为。当磁盘使用率超过大约 90% 时，复制将停止；当使用率低于大约 85% 时，复制将恢复。对于新索引或重建，如果磁盘压力已经超过保护阈值，则定义将被接受，但构建将会停滞。

解析

• 如果可以安全扩展托管或卷，请添加磁盘容量。

• 如果这在操作上可以接受，则删除不必要的索引以释放空间。

• 在构建或重建大型索引之前保留额外的内存。在重建过程中，计划占用预计稳态足迹的大约 125% 。

• 在本地实例存储 NVMe 上，请勿使用可以就地调整大小的功能。当本地实例存储容量不足时，通常需要更大的机器类和重新索引。

• 如果使用 EBS 支持的存储，则实时调整更可行，但 NVMe 仍然是 mongot 性能的首选指导。请参阅mongot 的存储类建议。

从 16 MB BSON 限制复制延迟

变更流事件超过 16 MB BSON 限制，导致复制停止。

症状

• 在稳态复制错误后，索引会变得过时或开始重建。

• mongot 日志显示 change stream payload exceeding 16MB BSON limit、BSONObjectTooLarge 或 getMore 期间的错误代码 10334。

• 您存储的文档可能显示小于 16 MB，但仍会发生故障。

常见原因

1. 变更流事件超过 16 MB，因为它包含文档和其他变更流元数据。

2. 对既有的大型文档进行大规模更新，会导致变更流负载比仅凭存储的文档大小所体现的要大得多。

诊断

查看以下指标：

• mongot_changestream_numSplitEvents_total 计数超过 16 MB 有效负载大小的事件。

• mongot_index_stats_indexing_replicationLagMs 报告特定索引的复制延迟。

在 mongot 日志中搜索以下字符串：

• change stream payload exceeding 16MB BSON limit

• BSONObjectTooLarge

• Executor error during getMore

• code 10334

如果文档大小检查显示最大文档小于 16 MB，则不要排除此场景。除文档本身外，更改事件还包含元数据。

解析

• 尽可能减少文档大小，避免对已经很大的文档进行大量更新。

• 在可能的情况下，请替换文档，而不是对现有的大文档应用大量更新。

• 如果大多数写入都是更新，请查看更新查询以减少变更流事件元数据大小。

• 修正工作负载后，允许重建完成。如果工作负载模式没有改变，索引可能会再次出现相同的故障。

• 如果调整工作负载后问题仍然存在，请捕获日志并使用事件详情进行升级。

复制延迟较大

复制延迟随时间稳步增长。

症状

• 复制延迟稳步增长，并可能达到多个小时或多天。

• mongot 在尝试跟上时变得内存受限或反复内存不足。

• 主机仍可以服务查询，但由于复制工作和大型索引足迹，查询性能可能会下降。

常见原因

1. 大量索引会增加复制和索引开销。

2. 广泛使用 dynamic: true 会增加字段数和索引大小，这会增加内存压力。

3. 重复发生的内存不足事件会加剧延迟，并使指标显示不连贯或不完整。

4. 瓶颈在源数据库上。配置不足的 mongod 从节点和高 CPU 及缓存压力会阻止变更流事件发出速度过快。

诊断

查看以下指标：

• mongot_index_stats_indexing_replicationLagMs 报告特定索引的复制延迟。

• mongot_indexing_steadyStateChangeStream_getMoresScheduled 报告已计划的 getMore 操作。

• mongot_replication_mongodb_indexManagerState 标识哪些索引没有进展。

• mongot_jvm_memory_used_bytes 主机 CPU 和负载指标显示资源压力。

计算索引的总数量，并查看是否有许多索引依赖于 dynamic: true 或索引不必要的高关联基数字段。

解析

• 如果节点内存不足或受到内存限制，请先扩展 mongot CPU 和内存。

• 减少索引总数。在索引数量很高的情况下，增加更多的搜索节点会使负载模式恶化，除非您首先控制变更流负载。

• 在不需要动态模式映射的地方关闭动态模式映射。优先使用 dynamic: false，并仅显式映射查询所需的子字段。

• 减少索引字段的数量，尤其是时间戳或用户 ID 等高基数字段，并删除未用于分面的深层分面映射。

• 如果 mongod 从节点是瓶颈，则扩展核心数据库以提高变更流吞吐量。

TLS 握手失败

mongot 和 mongod 之间的 TLS 握手失败。

症状

• mongot 日志显示 SSL handshake failed、Certificate verification failed 或 bad certificate。

• mongod 日志在尝试访问 mongot 时显示类似错误。

常见原因

1. CA 不匹配：两端不信任同一个 CA。

2. 证书 SAN 不包含使用中的主机名。

3. 证书已过期。

4. TLS 模式不匹配：一方要求 TLS，另一方却将其禁用。

5. 密码套件或 TLS 版本不匹配，这很少见。

诊断

检查各方提供的证书，并核实链与 CA 的关系：

openssl s_client -connect <mongot-host>:<mongot-port> -showcerts
openssl s_client -connect <mongod-host>:<mongod-port> -showcerts
openssl verify -CAfile <ca-bundle> <cert-file>
openssl x509 -in <cert-file> -text -noout

解析

• 将正确的 CA 分发到两个终结点。

• 使用正确的 SAN 列表重新颁发证书。

• 续订已过期证书。

• 协调两侧的 TLS 模式。请参阅配置 mongot 的 TLS 加密。

索引达到 Lucene 文档限制

单个索引超过 Lucene 最大文档数。

症状

• 在 Lucene 文档计数限制附近，非常大的索引停止向前进展。

• 日志显示 java.lang.IllegalArgumentException: number of documents in the index cannot exceed 2147483519。

• mongot_index_stats_numLuceneMaxDocs 接近硬性限制，并可能在达到限制后停止发布。

• 索引经理状态变为失败状态。

常见原因

1. 单个未分区索引超过了 Lucene 的最大文档数 2147483519。

2. 接受了一个新索引并开始建立，但在达到相同的硬限制后失败。

诊断

将 mongot_index_stats_numLuceneMaxDocs 作为此失败模式的主要预防信号，并检查日志中的具体异常 string：

java.lang.IllegalArgumentException: number of documents in the index cannot exceed 2147483519

解析

对索引进行分区，使每个分区都低于 Lucene 文档计数限制，然后使用适当设置的 numPartitions 重建索引。预计会有权衡：分区可能需要在多个分区中进行查询扩展，并可能会影响搜索性能。

{
  "numPartitions": 4,
  "mappings": {
    "dynamic": true
  }
}

自动嵌入失败

自动嵌入索引无法访问嵌入终结点。

症状

• 自动嵌入索引保持 PENDING 或 BUILDING。

• mongot 日志显示针对嵌入终结点的错误。

• 嵌入重试计数器 mongot_indexing_steadyStateChangeStream_rescheduledEmbeddingGetMores_total 或 mongot_initialsync_queue_requeuedEmbeddingInitialSyncs_total 大于零。使用这些计数器作为间接指标，并检查日志以获取嵌入终结点的实际 HTTP 错误。

常见原因

1. 模型 API 密钥无效或已过期。

2. 网络无法访问嵌入终结点。

3. 嵌入提供商正在限制请求速率。

4. 嵌入提供商发生服务中断。

诊断

测试从 mongot 主机到嵌入终结点的连接，然后检查日志：

grep -E 'voyage|embedding' mongot.log

解析

• 替换模型 API 密钥并重启 mongot。

• 向嵌入终结点开放网络出口。

• 如果提供商限制请求速率，请提高限制或降低索引并发性。

• 如果提供商发生服务中断，请监控 Voyage AI 状态 并考虑切换终结点。

有关完整嵌入配置模型，请参阅 配置 mongot 以实现 MongoDB 向量搜索自动嵌入。

存储信号，例如持续的 IOPS 或页面错误

持续存储IOPS或页面错误表示存储瓶颈。如果您在本地NVMe上运行，请先查看内存余量。如果您在任何其他存储类别上运行，例如SAN、通用云固态硬盘或SATA 固态硬盘，则存储类别可能是根本原因，并且需要进行迁移。请参阅mongot的存储类建议。

性能下降而无明显原因

如果没有最近的部署更改，性能会下降。

症状

• 查询延迟增加，没有明显的部署变化。

• CPU 或内存使用量上升。

常见原因

1. 工作负载发生变化，查询数量增加或查询范围扩大。

2. 现在，新索引会消耗资源。

3. 文档映射爆炸会消耗堆。

4. 存储降级，例如噪杂邻居、RAID 重建或云提供商问题。

5. 在 Java 虚拟机（JVM）更新后，发生了垃圾回收调优退化。

诊断

通过查询延迟、堆、执行程序队列和存储 IOPS 等症状来查看指标。有关指标定义和阈值，请参阅mongot 指标参考和mongot 推荐警报。

解析

解决方案取决于根本原因。选项包括扩展、容量规划或索引查看，例如删除未使用的索引和优化映射。

捕获诊断以获取支持

当您无法在本地解决问题时，请在打开支持用例之前捕获以下内容：

1. mongot 日志覆盖问题时间段加上一小时前的时间段。转发同一窗口的 mongod 日志。

2. 针对受影响的 mongot 实例的 FTDC。请参阅 mongot 日志和 FTDC。

3. 问题时间段内指标的仪表盘快照。

4. mongot 和 mongod 的版本。

5. 变化的内容，例如最近的部署、配置变更或流量模式。

6. 复现问题的方法（如果您可以按需复现该问题）。