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

mongomirror

警告

当您使用 mongomirror 并指定命名空间过滤器时，具有超出 includeNamespace <database.collection> 范围的命名空间的源上的事务将被视为未定义行为，且可能导致数据丢失。

mongomirror 是一个工具，用于将数据从现有的 MongoDB 副本集手动迁移到 MongoDB Atlas 副本集。另请参阅下载 mongomirror。

语法

要运行 mongomirror，您必须指定：

  • 源副本集和目标 Atlas 副本集。

  • Atlas 集群中具有适当权限的用户，如果源副本集需要身份验证，则需要相应的密码和适当的权限。

mongomirror --host <sourceReplSet> \
   --destination <atlasCluster> \
   --destinationUsername <atlasAdminUser> \
   --destinationPassword <atlasPassword> \
   [Additional options]

您可以在 config file 中指定某些选项，而不是将其包含在命令中。

选项

--host <host>

源副本集的主机信息。指定副本集名称和成员的种子列表，如下所示： 

<RSname>/<host1>:<port1>,<host2>:<port2>,<host3>:<port3>
--username <username>

如果源副本集需要身份验证，则为源副本集中有权读取任何数据库（包括 local 数据库）的用户名称。具有 backup 角色的用户可提供相应的权限。有关所需的特定特权的详细信息，请参阅源副本集所需的访问权限。

--password <password>

--username 中所指定用户的密码。

--authenticationDatabase <authenticationDatabase>

源副本集中的数据库，在其中创建了在 --username 中指定的用户。面向以下对象的身份验证数据库：

  • 经过 SCRAM 身份验证的用户是 admin 数据库。

  • 经过 X.509 身份验证的用户是 $external 数据库。

  • 经过 AWS IAM 身份验证的用户是 $external 数据库。

要了解更多信息，请参阅身份验证数据库。

--authenticationMechanism <authenticationMechanism>

用于对源副本集的用户进行身份验证的身份验证机制。

值
说明

SCRAM-SHA-1

RFC 5802 使用 SHA-1 哈希函数的标准 Salted Challenge Response Authentication Mechanism

SCRAM-SHA-256

RFC 5802 使用 SHA-256 哈希函数的标准 Salted Challenge Response Authentication Mechanism

MONGODB-X509

MongoDB TLS/SSL 证书身份验证。

GSSAPI (Kerberos)

使用 Kerberos 的外部身份验证。此机制仅在 MongoDB Enterprise 中可用。

普通版 (LDAP SASL)

使用 LDAP 进行外部身份验证。也可使用 PLAIN 对数据库内用户进行身份验证。PLAIN 以纯文本形式传输密码。此机制仅在 MongoDB Enterprise 中可用。

MONGODB-IAM

0.10.0 版本新增

使用 AWS IAM 进行外部身份验证。

要使用 AWS IAM 档案进行身份验证，请使用以下选项：

要了解更多信息，请参阅身份验证机制。

--awsSessionToken

0.10.0 版本新增

用于 MONGODB-IAM 身份验证机制的 AWS 会话令牌。

--compressors <snappy,...>

版本 0.9.0 中的新增内容

以逗号分隔的要启用的压缩程序列表。使用“none”来禁用。默认： snappy,zstd,zlib

--config=<file>

用于存储 mongomirror 的选项和值的 YAML 文件。使用相对或绝对路径指定文件，以使用该文件包含的选项运行 mongomirror。

此配置文件支持以下选项：

使用 option: value 事务语法在配置文件中指定选项。不要在配置文件中的选项之前包含 --。如果在配置文件中设置了选项，则无需在 mongomirror 命令中指定该选项。

例子

创建一个名为 myconfig.yaml 的配置文件，其中包含以下内容：

password: <passwordForUser>
destinationPassword: <passwordForDestinationUser>

您可以在不包括 --password 和 --destinationPassword 标志的情况下运行 mongomirror：

mongomirror --host <sourceReplSet> \
   --ssl \
   --username <atlasAdminUser> \
   --destinationUsername <atlasAdminUser> \
   --config=myconfig.yaml \
   --destination <atlasCluster> \
   [Additional options]
--destination <destination>

目标 Atlas 副本集的主机信息。

指定副本集名称和成员的种子列表，如下所示： 

<RSname>/<host1>:<port1>,<host2>:<port2>,<host3>:<port3>
--destinationAuthenticationDatabase <authentication database>

Atlas 集群数据库用户的身份验证数据库。SCRAM 认证用户的身份验证数据库是 admin 数据库。

要了解更多信息，请参阅数据库用户身份验证。

--destinationAuthenticationMechanism <authentication mechanism>

Atlas 集群数据库用户的身份验证机制。 Atlas 为数据库用户提供以下形式的身份验证：

值
说明

SCRAM-SHA-1

RFC 5802 使用 SHA-1 哈希函数的标准 Salted Challenge Response Authentication Mechanism

SCRAM-SHA-256

RFC 5802 使用 SHA-256 哈希函数的标准 Salted Challenge Response Authentication Mechanism

普通版 (LDAP SASL)

使用 LDAP 进行外部身份验证。也可使用 PLAIN 对数据库内用户进行身份验证。PLAIN 以纯文本形式传输密码。此机制仅在 MongoDB Enterprise 中可用。

要了解更多信息，请参阅数据库用户身份验证。

--destinationUsername <Atlas user name>

Atlas 集群中具有读取、写入和管理任何数据库权限的数据库用户的名称。具有 Atlas 管理员角色的用户可提供相应的权限。 有关所需特定权限的详细信息，请参阅目标集群所需的访问权限。

--destinationPassword <password>

--destinationUsername 中所指定数据库用户的密码。

--drop

该标志指示 mongomirror 应删除目标集群上的所有用户集合（可在每个数据库中使用 listCollections 查看）。此选项不会删除 local.system* 等内部集合和 oplog。

--noIndexRestore

0.10.0 版本新增

迁移数据时忽略索引。

--includeNamespace <database.collection>

在源集群上指定要镜像到目标集群的命名空间。 可以多次提供此数据。

注意

如果事务跨越多个命名空间，则只有应用于在 --includeNamespace 或 --includeDB 所指定命名空间的写操作才会应用于目标集群。

--includeDB <database>

在源集群上指定要镜像到目标集群的数据库。 可以多次提供此数据。

注意

如果事务跨越多个命名空间，则只有应用于在 --includeNamespace 或 --includeDB 所指定命名空间的写操作才会应用于目标集群。

--ssl

启用与源副本集的 TLS/SSL 加密连接。

--sslPEMKeyFile <file>

如果源副本集要求客户端提交证书，则需要 .pem 文件。 .pem 文件包含 TLS/SSL 证书和密钥。 使用相对路径或绝对路径指定文件。

--sslPEMKeyPassword <value>

用于解密 --sslPEMKeyFile 中指定的证书密钥文件的密码。--sslPEMKeyFile 文件被加密时使用。

--sslCAFile <file>

.pem 文件，其中包含源副本集的证书颁发机构 (CA) 的根证书链。 使用相对路径或绝对路径指定文件。

--sslCRLFile <filename>

包含源副本集的证书吊销列表的 .pem 文件。 使用相对路径或绝对路径指定此文件。

--sslAllowInvalidHostnames

已弃用。使用 tlsInsecure 来代替。

禁用源副本集提供的 TLS/SSL 证书验证。如果证书中的主机名与指定主机名不匹配，则允许 mongomirror 连接到源副本集。

重要

该选项会跳过所有证书验证，可能导致接受无效证书。

--sslAllowInvalidCertificates

已弃用。使用 tlsInsecure 来代替。

绕过对源副本集提供的证书的验证检查。使用 --allowInvalidCertificates 设置时，MongoDB 将使用无效证书记录为警告。

重要

该选项会跳过所有证书验证，可能导致接受无效证书。

--tlsInsecure

绕过对服务器证书链和主机名的验证检查。 这允许您使用无效的证书和主机名。

这将替换已弃用的 sslAllowInvalidHostnames 和 sslAllowInvalidCertificates 选项。

--gssapiServiceName <name>

如果源副本集使用 Kerberos 身份验证，则为使用 GSSAPI/Kerberos 的服务的名称。仅当服务未使用默认名称 mongodb 时才需要。

此选项仅在 MongoDB Enterprise 中可用。

--gssapiHostName <host>

如果源副本集使用 Kerberos 身份验证，则应提供使用 GSSAPI/Kerberos 的服务的主机名。 仅当计算机的主机名与 DNS 解析的主机名不匹配时才需要。

此选项仅在 MongoDB Enterprise 中可用。

--readPreference <read preference>

自版本 0.9.0 起已弃用

mongomirror 始终从主节点读取，除非源是没有副本集名称的单个主机， 在这种情况下，它仅与该主机建立直接连接。

--writeConcern <write concern>

自版本 0.2.3 起已弃用。 : mongomirror 始终使用大多数写关注（write concern）。

--numParallelCollections <num>, -j <num>

默认值：4

要并行复制和恢复的集合数量。

--bypassDocumentValidation

自版本 0.2.3 起已弃用。 : mongomirror 始终绕过文档验证。

--bookmarkFile <file>

默认：mongomirror.bookmark

Oplog 时间戳书签文件的名称。

--forceDump

指示 mongomirror 重新同步所有源集合的标志，即使存在非空书签文件。

--oplogPath <path>

0.5.0 版本新增

启用 mongomirror 将初始同步 oplog window 缓冲到磁盘。当您为此选项指定值时，mongomirror 会将源 oplog 条目流式传输到单个文件中的指定目录：<oplogPath>/oplog-mongomirror.bson.sz。将整个 oplog 文件重放到目标集群后，mongomirror 移除该文件并开始在不缓冲的情况下跟踪源操作日志。

默认情况下，mongomirror 从来源流式传输 oplog 条目并将其应用到目标集群。但是，如果来源 oplog 不够大，无法包含整个初始同步 oplog 窗口，则迁移可能会失败。为避免出现此错误，可以增加来源 oplog 的大小，或指定此选项以确保在迁移过程中来源 oplog 不会耗尽空间。

重要

必须提供足够的磁盘空间，以容纳初始 mongomirror 同步期间出现的所有源 oplog 条目。

例如，如果源 oplog 为 10 GB 且涵盖 24 小时的更改，而 mongomirror 的同步预计需要 48 小时，则指定目录中必须至少有 20 GB 的可用磁盘空间。

--oplogBatchSize <num>

默认值：10,000

指定要批量发送的 oplog 条目数。mongomirror 允许批量发送最大数据量为 16 MB 的文档。

--httpStatusPort <num>

指示 mongomirror 在指定端口上启动 HTTP 服务器。您可以通过向 http://localhost:<num> 发出 HTTP GET 请求来检索 mongomirror 的当前状态。

与 --httpStatusPort 一起运行时，mongomirror 在出现错误时不会退出。相反，它会正常记录此错误并通过 HTTP 将此错误报告给指定端口。

mongomirror 会根据 HTTP 请求返回文档。 以下示例语法表示所有可能的输出字段， 实际响应可能仅返回这些字段的子集。有关字段的说明 以及何时需要这些字段，请参阅下表。

{
   "stage" : "<stage Name>",
   "phase" : "<phase Name>",
   "details" : {
      "currentTimestamp" : "<BSON timestamp>",
      "latestTimestamp" : "<BSON timestamp>",
      "lastWriteOnSourceTimestamp" : "<BSON timestamp>",
      "<namespace>" : {
         "complete" : <boolean>,
         "copiedBytes" : <integer>,
         "totalBytes" : <integer>,
         "createIndexes" : <integer>
      },
      ...
   },
   "errorMessage" : "<error message>"
}

下表描述了每个字段及其可能的值：

字段
说明

stage

正在进行的阶段的名称。可能的值为：

  • initializing

    mongomirror 已启动，但尚未复制任何数据。

  • initial sync

    mongomirror 正在复制源部署中已存在的文档和索引。mongomirror 还会追踪并应用 oplog 中的条目。

  • oplog sync

    mongomirror 正在追踪并应用 oplog 中的条目。

phase

阶段的名称。提供有关 stage 的哪一部分正在进行中的更具体信息。

details

详细描述当前阶段进展情况的文档。

在 initial sync 阶段，details 中的每个子文档都代表 mongomirror 正在复制的单个集合。

根据 stage 或 phase 的不同，mongomirror 可能不会在响应中包含此字段。

details.<namespace>

正在复制的集合的完整命名空间，显示为 <database>.<collection>。

仅在 initial sync 阶段复制文档或索引时显示。

details.<namespace>.complete

显示 true 或 false，取决于 mongomirror 是否已将所有文档或索引从集合复制到目标 Atlas 集群。

仅在 initial sync 阶段复制文档或索引时显示。

details.<namespace>.copiedBytes

目前已复制的字节数。请注意，这与 mongomirror 日志的衡量标准不同，后者报告复制文档的当前/总数。

仅在复制非索引数据时的 initial sync 阶段显示。

details.<namespace>.totalBytes

集合的总大小（以字节为单位）。

仅在复制非索引数据时的 initial sync 阶段显示。

details.<namespace>.createIndexes

已经创建或将要创建的索引数量。

仅在 initial sync 阶段复制索引时显示。

details.currentTimestamp

最近处理的 oplog 条目的 BSON 时间戳值。mongomirror 每 10 秒刷新一次此数据点，因此 mongomirror 可能比报告的时间稍早一些。

仅在 initial sync 或 oplog sync 阶段跟踪或应用 oplog 条目时显示。

details.latestTimestamp

在initial sync阶段，它表示在初始同步期间复制初始数据后出现的最新 oplog 条目的 BSON 时间戳值。

在 oplog sync 阶段，这表示源部署上可用的最新 oplog 条目的 BSON 时间戳值。

仅在 initial sync 或 oplog sync 阶段跟踪或应用 oplog 条目时显示。

details
.lastWriteOnSourceTimestamp

不是无需操作的最新 oplog 条目的 BSON 时间戳值。无需操作条目通常是系统级操作，例如不在数据库中写入或编辑数据的心跳。mongomirror 每 10 秒刷新一次该值。在下次刷新发生之前，可能不会报告在数据库中写入或编辑数据的操作。

lastWriteOnSourceTimestamp 字段可用于确认在迁移期间进行切换之前源部署中没有发生新的写入。

errorMessage

描述 mongomirror 遇到的任何错误的字符串。

--collStatsThreshold <num>

版本 0.9.0 中的新增内容

禁用 collStats 前可能存在的最大集合数。使用 -1 可始终运行 collStats，而使用 0 则永不运行 collStats。默认：-1

--removeAutoIndexId

0.12.0 版本新功能

在初始同步到目标集群期间从集合中删除 autoIndexId 选项。同时从迁移过程中 mongomirror 创建的任何集合中删除 autoIndexId 选项。

--preserveUUIDs

支持 Atlas 在实时迁移期间保留 UUID。此选项仅适用于 Atlas 运行的实时迁移过程。如果在命令行中使用 --preserveUUIDs 选项，则它会因权限错误而失败。这些错误是意料之中的，因为在运行 mongomirror 的自托管迁移过程中，此选项不适合在命令行上使用。

示例

迁移副本集到 Atlas：源副本集不需要身份验证

以下示例从不需要身份验证的源副本集进行迁移： 

mongomirror --host  sourceRS/source-host1:27017,source-host2:27017 \
         --destination myAtlasRS/atlas-host1:27017,atlas-host2:27017 \
         --destinationUsername myAtlasUser \
         --destinationPassword myAtlasPwd

要从不需要身份验证的源副本集迁移，请使用以下选项运行 mongomirror：

对于目标，请指定副本集名称，后跟以下格式的成员种子列表： 

<replicaSetName>/<host1>:<port1>,<host2>:<port2>,<host3>:<port3>,...

指定用户必须在Atlas上具有Atlas admin角色。

迁移副本集：源副本集使用 SCRAM-SHA1 身份验证

以下示例将使用 SCRAM-SHA1 身份验证的源副本集迁移到 Atlas： 

mongomirror --host sourceRS/source-host1:27017,source-host2:27017,source-host3:27017 \
   --username mySourceUser \
   --password mySourcePassword \
   --authenticationDatabase admin \
   --destination myAtlasRS/atlas-host1:27017,atlas-host2:27017 \
   --destinationUsername myAtlasUser \
   --destinationPassword atlasPassw0Rd

如要从使用 SCRAM-SHA1 身份验证的源副本集迁移，请使用以下选项运行 mongomirror：

源副本集用户必须对源集群具有所需的访问权限。backup 角色提供适当的权限。

对于目标，请指定副本集名称，后跟以下格式的成员种子列表： 

<replicaSetName>/<replicaMember>,<replicaMember>,<replicaMember>,...

指定的用户必须在Atlas上具有 Atlas admin。

迁移副本集：源副本集需要使用 X.509 客户端身份验证

以下示例使用 X.509 身份验证的源副本集进行迁移： 

mongomirror --host sourceRS/source-host1:27017,source-host2:27017,source-host3:27017 \
   --username "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry" \
   --authenticationDatabase '$external' \
   --authenticationMechanism MONGODB-X509 \
   --ssl \
   --sslPEMKeyFile <path-to-my-client-certificate.pem> \
   --sslCAFile <path-to-my-certificate-authority-certificate.pem> \
   --destination myAtlasRS/atlas-host1:27017,atlas-host2:27017 \
   --destinationUsername myAtlasUser \
   --destinationPassword atlasPassw0Rd

要从使用 X.509 身份验证的源副本集迁移，则使用以下选项运行 mongomirror：

源副本集用户必须对源集群具有所需的访问权限。backup 角色提供适当的权限。

对于目标，请指定副本集名称，后跟以下格式的成员种子列表： 

<replicaSetName>/<replicaMember>,<replicaMember>,<replicaMember>,...

指定的用户必须在Atlas上具有 Atlas admin。

迁移副本集：源副本集需要 Kerberos/GSSAPI 身份验证

以下示例使用 Kerberos 身份验证的源副本集进行迁移： 

mongomirror --host sourceRS/source-host1:27017,source-host2:27017,source-host3:27017 \
   --username sourceUser/administrator@MYREALM.COM \
   --authenticationDatabase '$external' \
   --authenticationMechanism GSSAPI \
   --destination myAtlasRS/atlas-host1:27017,atlas-host2:27017,atlas-host3:27017 \
   --destinationUsername atlasUser \
   --destinationPassword atlasPass

要从使用 Kerberos 身份验证的源副本集迁移，请使用以下选项运行 mongomirror：

源副本集用户必须对源集群具有所需的访问权限。backup 角色提供适当的权限。

对于目标，请指定副本集名称，后跟以下格式的成员种子列表： 

<replicaSetName>/<replicaMember>,<replicaMember>,<replicaMember>,...

指定的用户必须在Atlas上具有 Atlas admin。

将 mongomirror 输出保存到文件

您可以将mongomirror过程的输出日志保存到文件中，以供以后检查和调试。使用以下格式将输出保存到 mongomirror.log 文件：

mongomirror <args> 2>&1 | tee -a mongomirror.log

在此页面上