mongofiles

Synopsis

mongofiles 实用程序可以命令行操作存储在GridFS对象中的MongoDB实例中的文件。它特别有用，因为它在文件系统中存储的对象和GridFS之间提供了一个接口。

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

兼容性

安装

mongofiles 工具是MongoDB Database Tools包的一部分：

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

语法

mongofiles 命令采用以下形式：

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

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

mongofiles 命令的组成部分包括：

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

2. Connection String。要与 mongofiles 连接的 mongod / mongos 的连接字符串。

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

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

必需的访问权限

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

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

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

行为

选项

--help

返回有关以下选项和使用的信息 mongofiles.

--verbose, -v

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

--quiet

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

该选项会抑制：

• 数据库命令的输出

• 复制活动

• 连接接受事件

• 连接关闭事件

--version

返回 mongofiles发布号。

--config=<filename>

100.3.0版本新增。

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

• --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 或 --sslPEMKeyPassword mongofiles命令行选项，则命令行选项将覆盖相应的配置文件选项。

--uri=<connectionString>

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

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

从 mongofiles 的 100.0 版本开始，连接字符串也可以作为位置参数提供，而无需使用 --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。在提供连接字符串的同时，使用显式选项并指定冲突信息会导致错误。

注意

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

• 带有非 SRV连接字符串的 --uri 选项（格式为 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-AWS authentication mechanism 连接到MongoDB Atlas 群集，并且除了 AWS访问权限密钥ID和秘密访问权限密钥之外还使用会话令牌，则可以在以下位置指定 AWS 会话令牌：

• 这个字段，

• AWS_SESSION_TOKEN authMechanismProperties 参数设置为 connection string，或者

• AWS_SESSION_TOKEN 环境变量。

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

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

--authenticationDatabase=<dbname>

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

如果使用的是 GSSAPI (Kerberos)、PLAIN (LDAP SASL) 或 MONGODB-AWS authentication mechanisms，则须将 --authenticationDatabase 设为 $external。

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

--authenticationMechanism=<name>

默认值：SCRAM-SHA-1

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

在版本 100.1.0 中进行了更改：

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

值	说明
SCRAM-SHA-1	使用 SHA-1 哈希函数的 RFC 5802 标准 Salted 挑战响应身份验证机制。
SCRAM-SHA-256	使用 SHA-256 哈希函数的 RFC 7677 标准 Salted 挑战响应身份验证机制。 需将 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中可用。
PLAIN (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 执行的每个写入操作的写关注（write concern）。

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

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

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

--readPreference=<string|document>

默认值：primary

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

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

  --readPreference=secondary

• 带引号的文档，用于指定模式、可选的读取偏好（read preference）标签集和可选的 maxStalenessSeconds：

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

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

mongofiles 默认为 primary读取偏好（read preference）。

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

命令

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>