Docs 菜单
Docs 主页
/
MongoDB Manual
/

MongoDB 有线协议

在此页面上

  • 简介
  • TCP/IP 套接字
  • 消息类型和格式
  • 标准消息头
  • 操作码

注意

本 MongoDB 传输协议规范根据 Creative Commons Attribution-NonCommercial-ShareAlike 3.0 美国许可证 进行许可。您不得出于任何商业目的使用或改编本材料,例如创建商业数据库或数据库即服务产品。

MongoDB 传输协议是一种基于套接字的简易请求-响应式协议。客户端可通过常规 TCP/IP 套接字与数据库服务器进行通信。

客户端应使用常规 TCP/IP 套接字连接数据库。

mongodmongos 实例的默认端口号为 27017 。mongodmongos 的端口号可配置,且可能不同。

MongoDB 传输协议中的所有整数均采用小端字节顺序:即,最低有效字节在前。

MongoDB 将 OP_MSG 操作码同时用于客户端请求和数据库回复。旧版本的 MongoDB 采用多种消息格式,而这些格式现已弃用并替换为 OP_MSG

注意

该页面使用类似 C 语言的 struct 来描述消息结构。

本文档中使用的类型(例如int32)与 BSON 规范 中定义的类型相同。

一般来说,每条消息均包含一个标准消息头,并后跟特定于请求的数据。标准消息头的结构如下:

struct MsgHeader {
int32 messageLength; // total message size, including this
int32 requestID; // identifier for this message
int32 responseTo; // requestID from the original request
// (used in responses from the database)
int32 opCode; // message type
}
字段
说明
messageLength
消息的总大小(以字节为单位)。该总数包括保存消息长度的 4 个字节。
requestID
客户端或数据库生成的标识符,可用于唯一标识此消息。
responseTo
从客户端消息中获取的 requestID
opCode
消息类型。请参阅操作码以了解详细信息。

MongoDB 使用以下 opCode 值:

操作码名称
Comment
OP_COMPRESSED
2012
使用压缩包装其他操作码
OP_MSG
2013
使用标准格式发送消息。同时用于客户端请求和数据库回复。
OP_REPLY
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
1
回复客户端请求。 responseTo 已设置。
OP_UPDATE
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2001 年
Update document.
OP_INSERT
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2002
插入新文档。
RESERVED
2003
之前曾供 OP_GET_BY_OID 使用。
OP_QUERY
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2004 年
查询一个集合。
OP_GET_MORE
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2005
从查询中获取更多数据。参见游标。
OP_DELETE
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2006
删除文档。
OP_KILL_CURSORS
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2007
通知数据库该客户端已完成游标操作。

任何操作码都可以压缩并包装在 OP_COMPRESSED 标头中。OP_COMPRESSED 消息包含原始压缩操作码消息以及处理和解压缩该消息所需的元数据。

OP_COMPRESSED 消息的格式为:

struct {
MsgHeader header; // standard message header
int32 originalOpcode; // value of wrapped opcode
int32 uncompressedSize; // size of deflated compressedMessage, excluding MsgHeader
uint8 compressorId; // ID of compressor that compressed message
char *compressedMessage; // opcode itself, excluding MsgHeader
}
字段
说明
MsgHeader
消息头,如标准消息头中所述。
originalOpcode
包含封装操作码的值。
uncompressedSize
缩小后的 compressedMessage 的大小,其中不含 MsgHeader
compressorId
压缩此消息的压缩器的 ID。compressorId 值的列表如下所示。
compressedMessage
操作码本身,不包括 MsgHeader

为每个压缩器均分配了一个预定义的压缩器 ID,如下所示:

compressorId
握手值
说明
0
noop
此消息的内容未压缩。此举意在用于测试。
1
snappy
此消息的内容使用 snappy 进行压缩。
2
zlib
此消息的内容使用 zlib 进行压缩。
3
zstd
此消息的内容使用 zstd 进行压缩。
4-255
reserved
保留以供将来使用。

OP_MSG 是一种可扩展消息格式,它可用于对线路上的客户端请求和服务器回复进行编码。

OP_MSG 格式如下:

OP_MSG {
MsgHeader header; // standard message header
uint32 flagBits; // message flags
Sections[] sections; // data sections
optional<uint32> checksum; // optional CRC-32C checksum
}
字段
说明
header
标准消息头,如标准消息头中所述。
flagBits
包含消息标志的整数位掩码,如标志位中所述。
sections
消息正文部分,如消息部分中所述。
checksum
可选的 CRC-32C 校验和,如校验和中所述。

flagBits 整数是位掩码编码标志,用于修改 OP_MSG 的格式和行为。

前 16 位 (0-15) 必须进行设置;如果设置了未知位,解析器则必须报错。

最后 16 位 (16-31) 是可选的,解析器必须忽略任何未知的计算置位。代理和其他消息转发器必须在转发消息之前清除任何未知的可选位。

Bit
名称
请求
响应
说明
0
checksumPresent

该消息以 4 字节结尾,其中包含 CRC-32C [2] 校验和。有关详细信息,请参阅校验和
1
moreToCome

另一条消息将紧随其后,而接收者无需执行后续操作。接收者在收到 moreToCome 设为 0 的消息之前不得发送其他消息;因为发送操作可能会阻塞,从而导致死锁。已设置 moreToCome 位的请求不会收到回复。仅当响应已设置 exhaustAllowed 位的请求时,回复才会设置此位。
16
exhaustAllowed

客户端已准备好使用 moreToCome 位对此请求进行多次回复。除非该请求已设置此位,否则服务器永不会生成已设置 moreToCome 位的回复。

此举可仅当请求者的网络层已为多个回复做好准备时才发送多个回复。

一条 OP_MSG 消息包含一个或多个部分。每个部分都以指示其类型的 kind 字节开头。kind 字节之后的所有内容构成该部分的有效负载。

可用的部分类型如下。

正文部分会编码为BSON 对象。BSON 对象中的此大小也会用作该部分的大小。此部分类型为标准命令请求和回复正文。

所有顶级字段均具有唯一名称。

类型
说明
int32
该部分的大小(以字节为单位)。
C 字符串

文档序列标识符。在所有当前命令中,该字段是它从正文部分替换的(可能是嵌套的)字段。

此字段不得同时存在于正文部分。

零个或多个 BSON 对象
  • 对象会连续进行排序,而不使用分隔符。

  • 每个对象仅限于服务器的 maxBSONObjectSize。所有对象的组合不限于maxBSONObjSize

  • 文档序列在消耗完 size 字节后结束。

  • 当转换为语言级对象时,解析器可能会选择将这些对象作为数组合并到序列标识符所指定路径处的正文中。

此部分专供内部使用。

每条消息均可能以 CRC-32C [2] 校验和结尾,而其中涵盖了消息中除校验和自身之外的所有字节。

如果不使用 TLS/SSL 连接,则 mongod 个实例和 mongos 个实例将通过校验和来交换消息。

如果使用 TLS/SSL 连接,mongod 实例和 mongos 实例会跳过校验和。

如果显示带有校验和的消息,驱动程序和较旧的二进制文件将忽略校验和。

校验和的存在由 checksumPresent 标记位指示。

从 MongoDB 5.1 开始,这些操作码已被移除,取而代之的是 OP_MSG:

  • OP_DELETE

  • OP_GET_MORE

  • OP_INSERT

  • OP_KILL_CURSORS

  • OP_QUERY [1]

  • OP_REPLY

  • OP_UPDATE

如果您运行的是旧版本的 MongoDB 并且需要有关先前操作码的详细信息,请参阅旧版操作码

脚注

[1] MongoDB 5.1 已删除对 OP_QUERY 查找操作和 OP_QUERY 命令的支持。但有一例外:运行 helloisMaster 命令以作为连接握手的一部分仍然支持 OP_QUERY
[2]使用 Castagnoli 多项式计算出的 (12)32 位 CRC ,如 https://tools.ietf.org/html/rfc4960#page-140所述。

后退

限制和阈值