杂记

菜单

Administrator
发布于 2026-04-09 / 1 阅读
0

MongoDB 8.2.6 二进制安装与 Vector Search 部署实践

概述

MongoDB 8.2.6 在二进制安装场景下支持 Vector Search，但部署并非仅启动 mongod 即可完成。要使 $vectorSearch、createSearchIndex()、listSearchIndexes 等能力可用，除了 mongod 之外，还必须部署并运行 mongot。同时，Vector Search 依赖副本集环境，即使是单机测试环境，也需要初始化 replica set。

本文基于如下配置进行梳理：

  • mongod 端口：27019
  • mongot 端口：27029
  • 副本集名称：rs0
  • 数据目录：/data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/mongoData
  • 日志目录：/data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/logs

适用场景：

  • Linux 环境下 MongoDB 8.2.6 二进制部署
  • 单机副本集测试环境
  • 本地验证 Vector Search 功能

一、前置条件

在开始部署之前，需要准备以下内容：

  1. MongoDB 8.2.6 二进制安装包
  2. mongot 二进制安装包
  3. 可执行的 mongosh
  4. 已创建的数据目录与日志目录
  5. 确保 mongod 与 mongot 所使用端口未被占用

目录准备命令如下：

mkdir -p /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/mongoData  
mkdir -p /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/logs

如需避免权限问题，可执行：

chown -R $USER:$USER /data1/test/mongo-8.2.6-withVectorSearch

二、mongod 配置文件

mongod.conf 配置如下：

net:  
 port: 27019  
 bindIp: 0.0.0.0

storage:  
 dbPath: /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/mongoData

replication:  
 replSetName: rs0

setParameter:  
 mongotHost: 127.0.0.1:27029  
 searchIndexManagementHostAndPort: 127.0.0.1:27029

processManagement:  
 fork: true

systemLog:  
 destination: file  
 path: /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/logs/mongod.log  
 logAppend: true

配置说明如下：

  • port: 27019：指定 mongod 监听端口
  • bindIp: 0.0.0.0：允许所有网卡访问
  • dbPath：指定 MongoDB 数据文件目录
  • replSetName: rs0：启用副本集模式
  • mongotHost：指定 mongot 服务地址
  • searchIndexManagementHostAndPort：指定 Search/Vector Search 索引管理服务地址
  • fork: true：后台运行
  • systemLog.path：指定 mongod 日志文件路径

需要特别注意的是，mongotHost 与 searchIndexManagementHostAndPort 必须与 mongot 的实际监听地址保持一致，否则 Vector Search 无法正常工作。

三、启动 mongod

进入 MongoDB 安装目录后执行：

cd /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/bin  
./mongod --config ../mongod.conf

启动完成后可通过以下命令检查进程、端口与日志：

ps -ef | grep mongod | grep -v grep  
ss -lntp | grep 27019  
tail -100 ../logs/mongod.log

四、初始化副本集

即使是单机部署，Vector Search 仍然要求 replica set 环境。因此，mongod 启动成功后，必须执行副本集初始化。

连接命令如下：

cd /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/bin  
./mongosh --host 127.0.0.1 --port 27019

在 mongosh 中执行：

rs.initiate({  
 _id: "rs0",  
 members: [  
 { _id: 0, host: "127.0.0.1:27019" }  
 ]  
})

初始化完成后，可通过以下命令查看状态：

rs.status()

当节点状态变为 PRIMARY 后，副本集初始化成功。

五、创建管理用户与 mongot 用户

1. 创建管理员用户

在未启用认证阶段，可先创建管理员账户：

use admin  
db.createUser({  
 user: "myAdmin",  
 pwd: "MyAdmin@123456",  
 roles: [ { role: "root", db: "admin" } ]  
})

2. 创建 mongot 专用账户

mongot 连接 mongod 时，需要使用带 searchCoordinator 角色的账户：

use admin  
db.createUser({  
 user: "mongotUser",  
 pwd: "Mongot@123456",  
 roles: [ { role: "searchCoordinator", db: "admin" } ]  
})

该账户仅用于 mongot 与 mongod 之间的认证与协作。

六、mongot 配置文件

mongot 需要单独配置，并与 mongod 建立连接。配置文件示例如下：

echo "mongotpass" > ./conf/onf/mongot.pass

syncSource:
  replicaSet:
    hostAndPort: "127.0.0.1:27019"
    username: "mongotUser"
    passwordFile: "/data1/test/mongo-8.2.6-withVectorSearch/mongot-community/conf/mongot.password"
    authSource: "admin"
    tls: false

storage:
  dataPath: "/data1/test/mongo-8.2.6-withVectorSearch/mongot-community/data"

server:
  grpc:
    address: "127.0.0.1:27029"

metrics:
  enabled: true
  address: "127.0.0.1:27030"

healthCheck:
  address: "127.0.0.1:27031"

logging:
  logPath: "/data1/test/mongo-8.2.6-withVectorSearch/mongot-community/logs/mongot.log"
  verbosity: "INFO"

配置说明如下：

  • port: 27029：指定 mongot 监听端口
  • bindIp: 127.0.0.1：仅本地访问
  • mongodb.uri：用于连接 mongod
  • authSource=admin：指定认证库
  • replicaSet=rs0：指定副本集名称

若密码中包含特殊字符，例如 @，则必须进行 URL 编码。上述示例中，@ 被编码为 %40。

七、启动 mongot

进入 mongot 安装目录后执行：

cd /data1/test/mongo-8.2.6-withVectorSearch/mongot/bin  
./mongot --config /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/mongot.conf

检查运行状态：

ps -ef | grep mongot | grep -v grep  
ss -lntp | grep 27029  
tail -100 /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/logs/mongot.log

八、验证 Search 链路

在 mongod 和 mongot 都启动成功后，可通过 listSearchIndexes 验证 Search 链路是否打通。

连接 MongoDB：

cd /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/bin  
./mongosh "mongodb://myAdmin:MyAdmin%40123456@127.0.0.1:27019/admin?replicaSet=rs0"

执行测试命令：

use test  
db.test1.insertOne({ name: "ok" })  
db.runCommand({ listSearchIndexes: "test1" })

若返回结果中包含 ok: 1，则说明 mongod 与 mongot 的联动已经正常建立。

九、创建测试库与测试集合

测试库与测试集合可使用以下命令创建：

use vectordb  
db.createCollection("docs")

插入测试数据：

db.docs.insertMany([
  {
    title: "苹果手机",
    category: "phone",
    embedding: [0.91, 0.02, 0.11, 0.33]
  },
  {
    title: "安卓手机",
    category: "phone",
    embedding: [0.89, 0.01, 0.09, 0.30]
  },
  {
    title: "笔记本电脑",
    category: "laptop",
    embedding: [0.15, 0.82, 0.20, 0.12]
  },
  {
    title: "游戏本",
    category: "laptop",
    embedding: [0.10, 0.86, 0.22, 0.10]
  }
])

这里使用的是 4 维向量，便于快速验证 Vector Search 功能。

验证数据：

db.docs.find({}, { _id: 0 }).toArray()

十、创建 Vector Search 索引

为向量字段创建索引命令如下：

db.docs.createSearchIndex(
  "vec_idx",
  "vectorSearch",
  {
    fields: [
      {
        type: "vector",
        path: "embedding",
        numDimensions: 4,
        similarity: "cosine"
      },
      {
        type: "filter",
        path: "category"
      }
    ]
  }
)

参数说明：

  • type: "vectorSearch"：声明索引类型为向量检索索引
  • path: "embedding"：指定向量字段
  • numDimensions: 4：向量维度
  • similarity: "cosine"：相似度算法
  • type: "filter"：为普通过滤字段建立过滤支持

创建完成后，可通过以下命令查看索引状态：

db.docs.aggregate([  
 { $listSearchIndexes: {} }  
]).toArray()

或者：

db.runCommand({ listSearchIndexes: "docs" })

只有当索引状态可用后，向量查询才可以正常执行。

十一、执行 Vector Search 查询

最小查询示例如下：

db.docs.aggregate([
  {
    $vectorSearch: {
      index: "vec_idx",
      path: "embedding",
      queryVector: [0.90, 0.01, 0.10, 0.31],
      numCandidates: 4,
      limit: 2
    }
  },
  {
    $project: {
      _id: 0,
      title: 1,
      category: 1,
      score: { $meta: "vectorSearchScore" }
    }
  }
]).toArray()

查询结果中，score 表示向量相似度得分。

十二、将配置文件更改为生产环境配置

mongod.conf

net:
  port: 27019
  bindIp: 0.0.0.0

storage:
  dbPath: /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/mongoData

replication:
  replSetName: rs0
security:
  authorization: enabled
  keyFile: /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/conf/mongodb.key
setParameter:
  mongotHost: 127.0.0.1:27029
  searchIndexManagementHostAndPort: 127.0.0.1:27029
  useGrpcForSearch: true
  searchTLSMode: "disabled"
processManagement:
  fork: true

systemLog:
  destination: file
  path: /data1/test/mongo-8.2.6-withVectorSearch/mongodb-linux-x86_64-ubuntu2204-8.2.6/logs/mongod.log
  logAppend: true

mongot.conf

syncSource:
  replicaSet:
    hostAndPort: "127.0.0.1:27019"
    username: "mongotUser"
    passwordFile: "/data1/test/mongo-8.2.6-withVectorSearch/mongot-community/conf/mongot.password"
    authSource: "admin"
    tls: false

storage:
  dataPath: "/data1/test/mongo-8.2.6-withVectorSearch/mongot-community/data"

server:
  grpc:
    address: "127.0.0.1:27029"

metrics:
  enabled: true
  address: "127.0.0.1:27030"

healthCheck:
  address: "127.0.0.1:27031"

logging:
  logPath: "/data1/test/mongo-8.2.6-withVectorSearch/mongot-community/logs/mongot.log"
  verbosity: "INFO"

十二、常见问题排查

1. 仅启动 mongod，未启动 mongot

现象：

  • createSearchIndex() 报错
  • listSearchIndexes 无法正常执行
  • $vectorSearch 查询失败

原因：

  • Search 与 Vector Search 需要 mongot 参与工作流，仅运行 mongod 无法完成向量索引与检索。

2. 未初始化副本集

现象：

  • Search/Vector Search 功能不可用

原因：

  • 当前部署模型要求 replica set 环境，即使为单机测试模式也必须执行 rs.initiate()。

3. mongot 端口与 mongod 配置不一致

现象：

  • mongod 无法连接 mongot
  • 向量索引操作失败

排查点：

  • mongod.conf 中的 mongotHost
  • mongod.conf 中的 searchIndexManagementHostAndPort
  • mongot.conf 中的 net.port

三者必须严格一致。

4. mongot 账户角色错误

现象：

  • mongot 启动后连接认证失败

排查点：

  • mongotUser 必须具备如下角色：

roles: [ { role: "searchCoordinator", db: "admin" } ]

5. 向量维度不一致

现象：

  • 索引创建失败
  • 查询时报维度错误

排查点：

  • numDimensions
  • 插入数据的向量长度
  • queryVector 的维度

三者必须保持一致。

十三、安全建议

当前示例配置可用于测试环境快速验证，但在正式环境中还需要补充以下内容：

  1. 启用认证
  2. 配置 keyFile
  3. 限制 bindIp
  4. 通过防火墙限制外部访问
  5. 为日志、数据目录设置合理权限

若后续需要切换到更完整的副本集访问控制模式，可在 mongod.conf 中增加如下配置：

security:  
 authorization: enabled  
 keyFile: /path/to/mongodb.key

结语

MongoDB 8.2.6 的 Vector Search 在二进制部署场景中可以顺利落地，但部署过程与传统 mongod 单实例不同，重点在于以下几个方面：

  • 必须部署 mongot
  • 必须运行在 replica set 模式下
  • 必须正确配置 mongotHost
  • 必须创建 searchCoordinator 角色账户
  • 必须确保向量索引定义与实际数据维度一致

只要完成上述关键步骤，便可以在本地环境中完成从 MongoDB 启动、副本集初始化、Search 链路验证、向量索引创建到 $vectorSearch 查询验证的完整闭环。

如需进一步扩展到生产环境，可继续补充认证、密钥文件、监控与高可用配置。

从一次 docker pull 异...