mongofiles

Synopsis

mongofiles 实用程序可通过命令行来操作存储在 GridFS 对象中 MongoDB 实例内的文件。它可在文件系统中存储的对象与 GridFS 之间提供一个接口，因此非常有用。

从系统命令行运行mongofiles ，而不是mongo shell 。

兼容性

安装

mongofiles工具是MongoDB database工具包的一部分：

➤ 按照Database Tools 安装指南安装mongofiles 。

语法

mongofiles 命令采用以下形式：

mongofiles <options> <connection-string> <command> <filename or _id>

从系统命令行运行mongofiles ，而不是mongo shell 。

mongofiles命令的组成部分包括：

1. 选项。您可以使用一个或多个选项来控制 mongofiles 的行为。

2. Connection String 。 要与string 连接的mongod /mongos 的连接mongofiles 。

3. 命令。使用这些命令之一来确定 mongofiles 操作。

4. 标识符：本地文件系统上的文件名或 GridFS 对象。

必需的访问权限

要连接到使用mongod 选项执行授权的--auth ，您必须使用--username 和--password 选项。连接用户必须至少具备：

• 使用list 、 search或get命令时所访问数据库的read角色，

• 使用 put 或 delete 命令时所访问数据库的 readWrite 角色。

行为

选项

--help

返回 mongofiles 的选项和使用的信息。

--verbose, -v

增加标准输出或日志文件中返回的内部报告数量。通过包括多个 -v 选项来提高详细程度，（例如 -vvvvv。）

--quiet

在尝试限制输出量的安静模式下运行 mongofiles。

该选项会抑制：

• 数据库命令输出

• 复制活动

• 连接接受事件

• 连接关闭事件

--version

返回 mongofiles 版本号。

--config=<filename>

100.3.0版本新增。：

指定 YAML 配置文件的完整路径，该文件包含以下 mongofiles 选项的敏感值：

• --password

• --uri

• --sslPEMKeyPassword

除通过密码提示来指定密码之外，这是为 mongofiles 指定密码的另一推荐方法。您可以在文件中使用任何参数的组合。

配置文件采用以下形式：

password: <password>
uri: mongodb://mongodb0.example.com:27017
sslPEMKeyPassword: <password>

如果指定了password 选项而不指定uri ，则可以使用mongofiles 命令行选项来指定连接字符串的其他组件，例如--username 和--host 。

请务必使用相应的文件系统权限保护此文件。

重要

使用 --config 选项时，请注意以下限制和行为：

• 如果您提供 password 字段，并在 uri 字段中提供一个与密码冲突的连接字符串，则 mongorestore 会抛出错误。

• 如果您使用 指定配置文件，并使用--config --password、--uri 或--sslPEMKeyPasswordmongofiles 命令行选项，则命令行选项将覆盖相应的配置文件选项。

--uri=<connectionString>

指定 MongoDB 部署的可解析 URI 连接字符串（用引号括起）：

--uri="mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]"

从mongofiles的 100.0 版本开始，也可以将连接string作为位置参数提供，而无需使用--uri选项：

mongofiles mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

作为位置参数，可以在命令行上的任何位置指定连接字符串，前提是它以 mongodb:// 或 mongodb+srv:// 开头。例如：

mongofiles --username joe --password secret1 mongodb://mongodb0.example.com:27017 --ssl

只能提供一个连接字符串。无论是使用 --uri 选项还是作为位置参数，尝试纳入多个连接字符串都会导致错误。

有关连接字符串的组件信息，请参阅连接字符串 URI 格式文档。

注意

connection string 中的某些组件也可以使用各自的显式命令行选项来指定，例如 --username 和 --password。在提供连接字符串的同时，使用显式选项并指定冲突信息会导致错误。

注意

如果在Ubuntumongofiles 上使用18.04 ，则在使用带有 选项的cannot unmarshal DNS SRV 连接字符串（采用mongodb+srv:// 形式）时，您可能会遇到--uri 错误消息。如果是这样，请改用以下选项之一：

• --uri带有非 SRV连接字符串的 选项（采用mongodb:// 形式）

• --host 选项指定直接连接的主机

警告

在某些系统上，使用 --uri 选项在连接字符串中提供的密码可能会对其他用户调用的系统状态程序（例如 ps）可见。请考虑：

• 在连接字符串中省略密码，接收交互式密码提示，或者

• 使用 --config 选项指定包含密码的配置文件。

--host=<hostname><:port>

为保存 GridFS 系统的 mongod 指定可解析的主机名。默认情况下，mongofiles 会尝试连接到在本地主机端口号 27017 上运行的 MongoDB 进程。

可以选择指定端口号，以连接在 27017 以外的端口上运行的 MongoDB 实例。

或者，也可直接在 URI connection string 中指定主机名。在使用 --host 的同时提供连接字符串并指定冲突信息将导致错误。

--port=<port>

默认值：27017

指定 MongoDB 实例侦听客户端连接的 TCP 端口。

或者，也可以直接在 URI connection string 中指定端口。在提供连接字符串的同时使用 --port 并指定冲突信息将导致错误。

--ssl

支持链接到启用 TLS/SSL 支持的 mongod 或 mongos。

或者，也可以直接在URI connection string 中配置 TLS/SSL 支持。在提供连接字符串的同时使用 --ssl 并指定冲突信息将导致错误。

有关 TLS/SSL 和 MongoDB 的更多信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 和客户端的 TLS/SSL 配置。

--sslCAFile=<filename>

指定包含来自证书颁发机构的根证书链的 .pem 文件。使用相对或绝对路径指定 .pem 文件的文件名。

或者，也可以直接在 URI connection string 中指定 .pem 文件。在提供连接字符串的同时使用 --sslCAFile 并指定冲突信息将导致错误。

有关 TLS/SSL 和 MongoDB 的更多信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 和客户端的 TLS/SSL 配置。

--sslPEMKeyFile=<filename>

指定同时包含 TLS/SSL 证书和密钥的 .pem 文件。使用相对或绝对路径指定 .pem 文件的文件名。

使用--ssl选项连接到已启用CAFile且未启用allowConnectionsWithoutCertificates的mongod或mongos时，需要使用此选项。

或者，也可以直接在 URI connection string 中指定 .pem 文件。在提供连接字符串的同时使用 --sslPEMKeyFile 并指定冲突信息将导致错误。

有关 TLS/SSL 和 MongoDB 的更多信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 和客户端的 TLS/SSL 配置。

--sslPEMKeyPassword=<value>

指定解密证书密钥文件的密码（即 --sslPEMKeyFile）。仅当证书密钥文件已加密时才能使用 --sslPEMKeyPassword 选项。在所有情况下，mongofiles 都会从所有日志记录和报告输出中编辑密码。

如果 PEM 文件中的私钥已加密并且您未指定--sslPEMKeyPassword选项，则mongofiles将提示输入密码。 请参阅TLS/SSL 证书密码。

或者，也可以直接在 URI connection string 中指定密码。在提供连接字符串的同时使用 --sslPEMKeyPassword 并指定冲突信息将导致错误。

有关 TLS/SSL 和 MongoDB 的更多信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 和客户端的 TLS/SSL 配置。

警告

在某些系统上，直接使用 --sslPEMKeyPassword 选项提供的密码，可能会被其他用户调用的系统状态程序（如 ps ）探测到。可以考虑使用 --config 选项，指定一个包含密码的配置文件。

--sslCRLFile=<filename>

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

有关 TLS/SSL 和 MongoDB 的更多信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 和客户端的 TLS/SSL 配置。

--sslAllowInvalidCertificates

绕过对服务器证书的验证检查并允许使用无效证书。 使用allowInvalidCertificates设置时，MongoDB 将使用无效证书记录为警告。

警告

尽管可用，但请尽可能避免使用 --sslAllowInvalidCertificates 选项。如果需要使用 --sslAllowInvalidCertificates，请仅在不可能入侵的系统上使用该选项。

在未验证服务器证书的情况下，连接到 mongod 或 mongos 实例存在潜在的安全风险。如果只需禁用 TLS/SSL 证书中的主机名验证，请参阅 --sslAllowInvalidHostnames。

或者，也可以直接在 URI connection string 中禁用证书验证。在提供连接字符串的同时使用 --sslAllowInvalidCertificates 并指定冲突信息将导致错误。

有关 TLS/SSL 和 MongoDB 的更多信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 和客户端的 TLS/SSL 配置。

--sslAllowInvalidHostnames

禁用 TLS/SSL 证书中的主机名验证。即使证书中的主机名与指定的主机名不匹配，也支持 mongofiles 连接到 MongoDB 实例。

或者，也可以直接在 URI connection string 中禁用主机名验证。在提供连接字符串的同时使用 --sslAllowInvalidHostnames 并指定冲突信息将导致错误。

有关 TLS/SSL 和 MongoDB 的更多信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 和客户端的 TLS/SSL 配置。

--username=<username>, -u=<username>

指定用户名，用于对使用身份验证的 MongoDB 数据库进行身份验证。与 --password 和 --authenticationDatabase 选项配合使用。

或者，也可直接在 URI connection string 中指定用户名。在使用 --username 的同时提供连接字符串并指定冲突信息将导致错误。

如果使用 MONGODB-AWS authentication mechanism 连接到 MongoDB Atlas 集群，您可以在以下位置指定您的 AWS 访问密钥 ID：

• 这个字段，

• connection string，或

• AWS_ACCESS_KEY_ID 环境变量。

请参阅使用 AWS IAM 凭据连接到 MongoDB Atlas 集群，了解每个凭据的示例。

--password=<password>, -p=<password>

指定密码，用于对使用身份验证的 MongoDB 数据库进行身份验证。与 --username 和 --authenticationDatabase 选项结合使用。

如要提示用户输入密码，可使用不带 --password 的 --username 选项，或指定空字符串作为 --password 值，如 --password ""。

或者，也可以直接在 URI connection string 中指定密码。在提供连接字符串的同时使用 --password 并指定冲突信息将导致错误。

如果使用 MONGODB-AWS authentication mechanism 连接到 MongoDB Atlas 集群，您可以在以下位置指定您的 AWS 秘密访问密钥：

• 这个字段，

• connection string，或

• AWS_SECRET_ACCESS_KEY 环境变量。

请参阅使用 AWS IAM 凭据连接到 MongoDB Atlas 集群，了解每个凭据的示例。

警告

在某些系统上，直接使用 --password 选项提供的密码，可能会被其他用户调用的系统状态程序（如 ps）探测到。请考虑：

• 省略 --password 选项以接收交互式密码提示，或

• 使用 --config 选项指定包含密码的配置文件。

--awsSessionToken=<AWS Session Token>

如果使用 MONGODB-AWSauthentication mechanism 连接到 MongoDB Atlas 集群，并且除了 AWS 访问密钥 ID 和私密访问密钥之外还使用会话令牌，则可以在以下情况中指定 AWS 会话令牌：

• 这个字段，

• connection string 的 AWS_SESSION_TOKEN authMechanismProperties 参数，或

• AWS_SESSION_TOKEN 环境变量。

请参阅使用 AWS IAM 凭据连接到 MongoDB Atlas 集群，了解每个凭据的示例。

仅在使用 MONGODB-AWS authentication mechanism 时有效。

--authenticationDatabase=<dbname>

指定已创建指定 --username 的身份验证数据库。请参阅身份验证数据库。

如果您使用 GSSAPI (Kerberos)、PLAIN (LDAP SASL) 或MONGODB-AWSauthentication mechanisms ，则必须将--authenticationDatabase 设立为$external 。

或者，也可以直接在 URI connection string 中指定身份验证数据库。在提供连接字符串的同时使用 --authenticationDatabase 并指定冲突信息，将导致错误。

--authenticationMechanism=<name>

默认值：SCRAM-SHA-1

指定 mongofiles 实例用于向 mongod 或 mongos 进行身份验证的身份验证机制。

在版本100.1.0中进行了更改。：

从版本100.1.0 mongofiles开始，MONGODB-AWS 在连接到MongoDB Atlas 群集时增加了对 身份验证机制的支持。

值	说明
SCRAM-SHA-1	RFC 5802 使用 SHA-1 哈希函数的标准 Salted Challenge Response Authentication Mechanism
SCRAM-SHA-256	RFC 7677 使用 SHA-256 哈希函数的标准 Salted Challenge Response Authentication Mechanism 需将 featureCompatibilityVersion 设为 4.0。
MONGODB-X.509	MongoDB TLS/SSL 证书身份验证。
MONGODB-AWS	使用 AWS IAM 凭据进行外部身份验证，用于连接到 MongoDB Atlas 集群。请参阅使用 AWS IAM 凭证连接到 MongoDB Atlas 集群。 100.1.0版本新增。：
GSSAPI (Kerberos)	使用 Kerberos 的外部身份验证。此机制仅在 MongoDB Enterprise 中可用。
普通版 (LDAP SASL)	使用 LDAP 进行外部身份验证。也可使用 PLAIN 对数据库内用户进行身份验证。PLAIN 以纯文本形式传输密码。此机制仅在 MongoDB Enterprise 中可用。

或者，也可以直接在 URI connection string 中指定身份验证机制。在提供连接字符串的同时使用 --authenticationMechanism 并指定冲突信息，将导致错误。

--gssapiServiceName=<serviceName>

使用 GSSAPI/Kerberos 指定服务名称。仅当服务未使用默认名称 mongodb 时才需要。

此选项仅在 MongoDB Enterprise 中可用。

--gssapiHostName=<hostname>

使用 GSSAPI/Kerberos 指定服务的主机名。仅当机器的主机名与 DNS 解析的主机名不匹配时才需要。

此选项仅在 MongoDB Enterprise 中可用。

--db=<database>, -d=<database>

指定在其上运行 mongofiles 的数据库的名称。

或者也可以直接在 URI connection string 中指定数据库。在提供连接字符串的同时使用 --db 并指定冲突信息将导致错误。

--local=<filename>, -l=<filename>

指定文件的本地文件系统名称，用于获取和放置操作。

在 mongofiles put 和 mongofiles get 命令中，必需的 <filename> 修饰符是指该对象在 GridFS 中采用的名称。mongofiles 假定它反映了此文件在本地文件系统中的名称。此设置将覆盖该默认值。

--type=<MIME>

提供指定MIME类型来描述插入 GridFS 存储的文件的功能。 mongofiles在默认操作中省略此选项。

仅与 mongofiles put 操作一起使用。

--replace, -r

更改 mongofiles put 的行为，用指定的本地文件替换现有的 GridFS 对象，而不是添加具有相同名称的其他对象。

在默认操作中，mongofiles put 选项不会覆盖文件。

--prefix=<string>

默认值：fs

要使用的 GridFS 前缀。

--writeConcern=<document>

默认：多数

为 执行的每个写入操作指定 写关注mongofiles 。

使用w 选项将写关注指定为文档：

--writeConcern="{w:'majority'}"

如果写关注也包含在--uri connection string中，则命令行--writeConcern将覆盖 URI string中指定的写关注。

--readPreference=<string|document>

默认值：primary

指定 的 读取偏好 mongofiles。--readPreference选项可以使用：

• 如果仅指定读取偏好模式，则为一个字符串：

  --readPreference=secondary

• 用引号括起的文档，用于指定模式、可选的读取偏好标记集以及可选的 maxStalenessSeconds：

  --readPreference='{mode: "secondary", tagSets: [ { "region": "east" } ], maxStalenessSeconds: 120}'

  如果指定 maxStalenessSeconds，该值则须大于或等于 90。

mongofiles默认为primary读取偏好。

如果读取偏好也包含在--uri connection string中，则命令行--readPreference将覆盖 URI string中指定的读取偏好。

命令

list <prefix>

列出 GridFS 存储中的文件。list之后指定的字符（例如<prefix>）可以选择将返回的项目列表限制为以该字符串开头的文件。

search <string>

列出 GridFS 存储中其名称与 <string> 任何部分匹配的文件。

put <filename1[ filename2] ...>

将一个或多个指定文件从本地文件系统复制到 GridFS 存储中。 可以将多个文件指定为以空格分隔的列表。

每个指定的文件名指的是对象在 GridFS 中的名称，mongofiles 假定这反映了文件在本地文件系统中的名称。如果本地文件名不同，请使用 mongofiles --local 选项。

get <filename1[ filename2] ...>

将指定的一个或多个文件从 GridFS 存储复制到本地文件系统。

每个指定的文件名是指对象在 GridFS 中的名称， mongofiles在写入本地文件系统时将使用该文件名。

如果仅为 get 命令指定一个 filename，那么您可以根据需要使用 --local 选项指定要写入的其他本地文件名。如果为 get 命令指定超过一个 filename，那么您无法使用 --local 选项。

注意

要从 GridFS 存储中复制与正则表达式匹配的文件，请改用 get_regex 命令。

get_id "<_id>"

将 <_id> 指定的文件从 GridFS 存储复制到本地文件系统。<_id> 是指 GridFS 中对象的扩展 JSON _id。get_id 可以接受 <_id> 的 ObjectId 值或非 ObjectId 值。

mongofiles使用 GridFS 中的文件名将文件写入本地文件系统。 要在本地文件系统中为文件选择不同的位置，请使用--local选项。

get_regex <regex> --regexOptions <regex-options>

将与指定 <regex> 表达式匹配的文件从 GridFS 存储复制到本地文件系统。get_regex 命令使用支持 UTF-8 的与 Perl 兼容的正则表达式（“PCRE”）8.42 版。

您可以选择使用--regexOptions标志指定一个或多个<regex-options> 。 这些可以是$regex 操作符支持的任何选项，包括不区分大小写等设置。 应同时提供多个不带分隔符的选项，例如 --regexOptions si

mongofiles使用 GridFS 中每个文件的匹配文件名，将一个或多个文件写入本地文件系统。 不能将--local选项与get_regex命令一起使用。

delete <filename>

从 GridFS 存储中删除指定文件。

delete_id "<_id>"

从 GridFS 存储中删除由其 <_id> 指定的文件。delete_id 可以接受 <_id> 的 ObjectId 值或非 ObjectId 值。

示例

从系统命令行运行mongofiles ，而不是mongo shell 。

要返回 records 数据库中GridFS集合内所有文件的列表，请在系统shell中使用以下调用：

mongofiles -d=records list

此mongofiles实例将连接到在27017本地主机接口上运行的mongod实例，以在不同的端口或主机名上指定相同的操作，并发出类似于以下命令之一的命令：

mongofiles --port=37017 -d=records list
mongofiles --host=db1.example.net -d=records list
mongofiles --host=db1.example.net --port=37017 -d=records list

如果要在不同端口或主机上连接mongod实例，请根据需要修改以下任何命令。

如需将名为 32-corinth.lp 的文件上传到records 数据库的 GridFS 集合中，可以使用以下命令：

mongofiles -d=records put 32-corinth.lp

要从 records 数据库的 GridFS 集合中删除 32-corinth.lp 文件，可使用以下命令：

mongofiles -d=records delete 32-corinth.lp

要在 records 数据库的 GridFS 集合中搜索名称中包含 corinth 字符串的文件，可以使用以下命令：

mongofiles -d=records search corinth

要列出 records 数据库中 GridFS 集合中的名称以字符串 32 开头的所有文件，您可以使用以下命令：

mongofiles -d=records list 32

要从名为 32-corinth.lp 的 records 数据库中的 GridFS 集合获取文件，可以使用以下命令：

mongofiles -d=records get 32-corinth.lp

要从 records数据库的 GridFS 集合中获取名称以字符串 32 开头并以字符串 .lp 结尾的所有文件，可使用以下命令：

mongofiles -d=records get_regex 32*.lp

要使用 _id: ObjectId("56feac751f417d0357e7140f") 从 records 数据库中的 GridFS 集合提取文件，可以使用以下命令：

mongofiles -d=records get_id '{"$oid": "56feac751f417d0357e7140f"}'

您必须在 _id 两边加上引号。

mongofiles 'mongodb+srv://<aws access key id>:<aws secret access key>@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' <other options>

mongofiles 'mongodb+srv://<aws access key id>:<aws secret access key>@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<aws session token>' <other options>

: / ? # [ ] @

mongofiles 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' --username <aws access key id> --password <aws secret access key> --awsSessionToken <aws session token> <other options>

export AWS_ACCESS_KEY_ID='<aws access key id>'
export AWS_SECRET_ACCESS_KEY='<aws secret access key>'
export AWS_SESSION_TOKEN='<aws session token>'

env | grep AWS

mongofiles 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS'  <other options>