/ /

排除 `mongot` 部署故障

Kubernetes 操作符的 MongoDB 控制器将 mongot 部署为单独的进程，该进程位于其自己的 Pod 中，由 MongoDBSearch 资源定义。客户端从不直接连接到 mongot：MongoDB Search 和向量搜索查询在 mongod 上运行，将它们代理到 mongot。mongot 连接回 mongod 以流式传输更改事件，并在专用 Persistent Volume 上构建其索引。

本页面介绍如何诊断和解决 mongot 部署中的常见运行时问题。有关初始设置期间索引创建的特定疑难排查，请参阅使用 MongoDB Search 和向量搜索。在调查之前设置指标和日志记录，请参阅监控部署。

本页面上的程序假设您设置了以下环境变量以匹配您的部署：

export MDB_NS="<your-namespace>"
export K8S_CTX="<your-kubectl-context>"
export MDB_RESOURCE_NAME="<your-mongodbsearch-resource-name>"

收集诊断信息

在处理特定场景之前，请收集 mongot pod 的当前状态、其日志以及最近的 Kubernetes 事件：

# Check the status and restart count of the mongot pod
kubectl get pods -n ${MDB_NS} --context ${K8S_CTX} | grep search
# Review the most recent mongot logs
kubectl logs statefulset/${MDB_RESOURCE_NAME}-search-0 \
  -n ${MDB_NS} --context ${K8S_CTX} --tail=100
# Inspect the MongoDBSearch resource status and conditions
kubectl describe mongodbsearch ${MDB_RESOURCE_NAME} \
  -n ${MDB_NS} --context ${K8S_CTX}
# List recent events in the namespace
kubectl get events -n ${MDB_NS} --context ${K8S_CTX} \
  --sort-by='.lastTimestamp'

如果节点循环重启，请查看上一个容器实例的日志，以捕获导致重启的错误：

kubectl logs statefulset/${MDB_RESOURCE_NAME}-search-0 \
  -n ${MDB_NS} --context ${K8S_CTX} --previous

使用资源状态本地化问题

MongoDBSearch 资源运行多个独立的组件：

一个或多个 mongot StatefulSet
可选的 Kubernetes 操作符托管的 Envoy 负载均衡器
可选的 Cloud Manager 或 MongoDB Ops Manager 指标转发器。

在多集群部署中，每个集群每个节点集群都会运行这些组件。当搜索行为不符合预期时，请先使用资源状态将问题定位到特定的集群和组件，然后再检查 Pod 或日志。

读取状态：

kubectl get mongodbsearch ${MDB_RESOURCE_NAME} \
  -n ${MDB_NS} --context ${K8S_CTX} -o yaml

从顶级字段开始，然后使用 status.clusters：缩小范围

字段	它告诉您什么
`status.phase`	整体资源阶段。这反映了所有集群的 `mongot` StatefulSet 就绪状态（最差状态）以及托管式负载均衡器的就绪状态。如果任何集群的 `mongot` 或 Kubernetes 操作符托管式负载均衡器尚未就绪，则资源处于 `Pending` 阶段。指标转发器不影响此阶段。
`status.loadBalancer`	跨所有集群的聚合托管 Envoy 负载均衡器阶段。仅在设置 `spec.clusters[].loadBalancer.managed` 时填充此字段。
`status.metricsForwarder`	所有集群的汇总 MongoDB Ops Manager 指标转发器阶段。仅在启用指标转发器时填充此字段。
`status.clusters[]`	每个节点集群一个条目，每个条目都有自己的 `name` 和 `index`，并且具有 `search`、`loadBalancer` 和 `metricsForwarder` 的独立子阶段。每个子阶段都有一个匹配的 `*Message` 字段（例如 `searchMessage`），用于解释子阶段不是 `Running` 的原因。

提示

即使每个集群的 search 子阶段为 Running，MongoDBSearch 资源也可以为 Pending，因为任何集群上的降级托管 loadBalancer 都可以将整个资源保持在 Pending 阶段。阅读每集群子阶段以确定哪个集群和组件负责。

以下示例展示了一个双集群部署，其中第二个集群的 Envoy 负载均衡器在推出过程中受阻。尽管两个集群上的 mongot 均处于正常状态，但资源仍为 Pending，因为托管负载均衡器的就绪状态会影响整体阶段。

示例：待处理阶段

status:
  phase: Pending
  message: "Waiting for managed load balancer to be ready"
  clusters:
    - name: member-cluster-1
      index: 0
      search: Running
      loadBalancer: Running
    - name: member-cluster-2
      index: 1
      search: Running
      loadBalancer: Pending
      loadBalancerMessage: "Load balancer deployment mdb-search-search-lb-1
        rollout in progress: 1 unavailable replica(s)"

使用受影响集群的 name 和 index 来检查对应的组件：

For a search sub-phase that is not Running, inspect that cluster's mongot StatefulSet and Pods. The searchMessage typically reports which StatefulSet is not ready. See The mongot Pod Fails to Start.
对于不是 Running 的 loadBalancer 子阶段，请检查该集群的 Envoy 部署。rollout in progress 或 unavailable replica(s) 等消息表明新的 Envoy Pod 未安排或未就绪。
对于不是 Running 的 metricsForwarder 子阶段，请检查该集群的指标转发器部署。

To collect the Pod state, logs, and events for the identified component, see Gather Diagnostic Information.

`mongot` Pod 无法启动

症状： mongot pod 保持 Pending、ContainerCreating 或 Error 状态，从未达到 Running，或 MongoDBSearch 资源未达到 Running 状态。

Diagnose: Run the commands in Gather Diagnostic Information and review the pod events and MongoDBSearch status. Common indicators include scheduling failures, volume-mount errors, and image-pull errors.

解决：

如果 Pod 无法被调度，请确认是否有具备足够 CPU 和内存的节点可用，并且您的 StorageClass 能够绑定所请求的 Persistent Volume Claim。若要了解关于 mongot 大小的更多信息，请参阅搜索和向量搜索资源规划与大小调整。
如果缺少 search-sync-source 用户的密码秘钥，请创建。MongoDBSearch 资源需要名为 ${MDB_RESOURCE_NAME}-search-sync-source-password 的秘钥。
如果无法拉取 mongot 容器映像，请验证映像名称和注册表凭证。使用 kubectl get events -n ${MDB_NS} | grep -i pull 检查映像拉取错误。
如果源 mongod 副本集不处于 Running 状态，请先解决该问题。Kubernetes 操作符的 MongoDB 控制器会等待源资源，然后再部署 mongot。

搜索查询无法到达 `mongot`

症状： $search, $searchMeta 或 $vectorSearch 查询失败，并显示 mongod 无法访问搜索服务。

诊断：确认 mongot pod 为 Running，并且其服务存在：

kubectl get pods,svc -n ${MDB_NS} --context ${K8S_CTX} \
  | grep search

查看 mongot 日志中的连接或身份验证错误，并查看 mongod 日志中引用搜索托管的错误。

解决：

If the mongot pod is not Running, work through The mongot Pod Fails to Start.
如果日志显示身份验证错误，请验证 search-sync-source 用户凭证和角色。要了解更多信息，请参阅保护从搜索到 MongoDB 的连接。
如果日志显示 TLS 错误，请确认 mongod 和 mongot 信任同一个 CA。要学习；了解更多信息，请参阅保护从MongoDB到 Search 的连接。

`mongot` 重复重启

症状： mongot pod 显示重启次数过高或报告 CrashLoopBackOff。

诊断：查看上一个容器实例的日志，捕获触发重启的错误：

kubectl logs statefulset/${MDB_RESOURCE_NAME}-search-0 \
  -n ${MDB_NS} --context ${K8S_CTX} --previous

检查 Pod 的最后省/市/自治区和退出原因：

kubectl describe pod ${MDB_RESOURCE_NAME}-search-0-0 \
  -n ${MDB_NS} --context ${K8S_CTX}

解决：

If the exit reason is OOMKilled, increase the memory resources for mongot. See mongot Runs Out of Memory.
如果日志显示配置或身份验证错误，请更正设置，并让 Kubernetes 操作员的 MongoDB 控制器协调更改。
如果日志显示 mongot 无法读取或写入其索引数据，请确认持久卷声明已绑定且可写入。请参阅mongot Pod 无法启动。

`mongot` 内存不足

症状： mongot Pod 因 OOMKilled 原因而终止，并且重启计数增加。

诊断：确认节点的终止原因：

kubectl describe pod ${MDB_RESOURCE_NAME}-search-0-0 \
  -n ${MDB_NS} --context ${K8S_CTX}

mongot 是基于 Lucene 的内存映射工作负载。内存压力通常是由于内存限制相对于索引大小和查询负载过小而导致的。

解决：

增加分配给 MongoDBSearch 资源中 mongot 的内存资源。mongot 将重新启动以应用更改。
根据搜索和向量搜索资源规划和大小设置中的大小设置指导查看索引大小和查询负载。

初始同步较慢或复制延迟增加

症状：新创建的索引长时间处于建立状态，或查询结果落后于最近对 mongod 的写入。

诊断: 查看 mongot 日志中的复制进度和错误。使用在监控部署中配置的指标来追踪索引构建进度和复制延迟随时间的变化。

解决：

允许完成初始同步。构建索引的时间会随着源数据的大小而扩展。
如果在稳定负载下仍存在延迟，则 mongot 实例的资源可能不足以支持写入量。查看“搜索和向量搜索资源规划和大小调整”。
确认存储性能符合随机读取密集型 Lucene 工作负载的建议。缓慢存储是持续延迟的常见原因。

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

症状：mongot 日志显示 TLS 握手或证书验证错误，并且 mongod 无法建立与 mongot 的连接。

诊断：查看 mongot 日志是否存在证书错误，并确认 MongoDBSearch资源引用的 TLS 密钥存在：

kubectl get secrets -n ${MDB_NS} --context ${K8S_CTX} \
  | grep -i tls

解决：

确认 mongod 和 mongot 信任同一个 CA。
替换或轮换证书后，请重启 mongot，以便其读取新证书。mongot 在启动时读取证书，在运行时不会重新加载证书。
要学习更多信息，请参阅从 MongoDB 到搜索的安全连接。

自动嵌入失败

注意

自动嵌入是预览功能，仅与 Voyage AI 模型集成。

症状：使用自动嵌入的索引无法构建，或嵌入请求在 mongot 日志中返回错误。

诊断：查看 mongot 日志中引用嵌入提供商的错误，例如身份验证失败或请求超时。

解决：

验证您的 Voyage AI API 密钥有效，并且包含该密钥的 Secret 存在于命名空间中。
确认 mongot 可以从 Kubernetes 集群访问嵌入提供商终结点。

捕获诊断以获取支持

If you contact MongoDB Support, include the mongot logs, the MongoDBSearch resource description, and recent namespace events:

kubectl logs statefulset/${MDB_RESOURCE_NAME}-search-0 \
  -n ${MDB_NS} --context ${K8S_CTX} > mongot.log
kubectl describe mongodbsearch ${MDB_RESOURCE_NAME} \
  -n ${MDB_NS} --context ${K8S_CTX} > mongodbsearch-describe.txt
kubectl get events -n ${MDB_NS} --context ${K8S_CTX} \
  --sort-by='.lastTimestamp' > events.txt

您还可以包含每个受影响的搜索Pod 中的 FTDC 文件。 mongot 将 FTDC 文件写入 Pod 内的 /mongot/data/diagnostic.data/。

/mongot/data 路径是 PersistentVolumeClaim，Kubernetes 操作符通过搜索 StatefulSet 上的 volumeClaimTemplate 将其挂载到 Pod 上，因此诊断数据在 Pod 重启后仍可保留。当 Pod 被替换时，StatefulSet 会重新附加相同的 PersistentVolumeClaim，因此诊断数据得以保留。

将 FTDC 数据从搜索 pod 复制到您的本地机器。对于分片集群，请将 FTDC 数据从每个分片搜索 Pod 复制到您的本地机器。对每个分片重复上述步骤：

kubectl cp -n ${MDB_NS} --context ${K8S_CTX} \
   ${MDB_SEARCH_RESOURCE_NAME}-search-0-${MDB_EXTERNAL_SHARD_0_NAME}-0:/mongot/data/diagnostic.data \
   ./mongot-diagnostic.data-${MDB_EXTERNAL_SHARD_0_NAME}