对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。
Docs 菜单
Docs 主页
/ /
部署搜索和向量搜索
Docs 主页
/
管理
/
Kubernetes Operator 的控制器
/
部署搜索和向量搜索
Docs 主页
/
管理
/
Kubernetes Operator 的控制器
/
部署搜索和向量搜索

对 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 Operator 托管的 Envoy 负载负载均衡器

  • 可选的Cloud Manager或Ops Manager指标转发器。

在多集群部署中，每个节点都针对每个节点集群运行。当搜索未按预期运行时，请在检查 Pod 或日志之前使用资源状态将问题定位到特定集群和组件。

要读取状态：

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

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

字段
它告诉您什么

status.phase

整体资源阶段。这既反映了所有集群（最差的）的mongot StatefulSet 准备情况，也反映了托管负载均衡器的准备情况。如果任何集群的Pending mongot或Kubernetes Operator 托管的负载负载均衡器未准备就绪，则资源处于 阶段。指标转发器不会影响此阶段。

status.loadBalancer

跨所有集群的聚合托管Envoy 负载负载均衡器阶段。仅当设立了 spec.clusters[].loadBalancer.managed 时才会填充此项。

status.metricsForwarder

所有集群的聚合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 检查相应的组件：

  • search对于不是Running mongot的 子阶段，请检查该集群的 StatefulSet 和 Pod。 通常会报告哪个searchMessage StatefulSet 未准备就绪。请参阅mongot Pod 无法启动。

  • 对于不是 Running 的 loadBalancer 子阶段，请检查该集群的 Envoy 部署。 rollout in progress 或 unavailable replica(s) 等消息表示新的 Envoy Pod 未进行调度或未准备就绪。

  • 对于不是 Running 的 metricsForwarder 子阶段，请检查该集群的指标转发器部署。

要收集已识别组件的 Pod 状态、日志和事件，请参阅收集诊断信息。

mongot Pod 启动失败

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

诊断：运行收集诊断信息中的命令，并查看节点事件和 MongoDBSearch 状态。常见指示包括调度失败、卷挂载错误和图像拉取错误。

解决：

  • 如果 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 日志中引用搜索托管的错误。

解决：

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}

解决：

  • 如果退出原因是 OOMKilled，请增加 mongot 的内存资源。请参阅mongot 内存不足。

  • 如果日志显示配置或身份验证错误，请更正设置，并让 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 的内存映射工作负载。内存压力通常是由于内存限制相对于索引大小和查询负载过小而导致的。

解决：

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

症状：新创建的索引长时间处于建立状态，或查询结果落后于最近对 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 集群访问嵌入提供商终结点。

捕获诊断以获取支持

如果您联系MongoDB 支持，请附上 mongot 日志、MongoDBSearch 资源说明和最近的命名空间事件：

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}

了解详情

后退

已知限制

来年

常见问题解答

在此页面上