MinIO 客户端

MinIO Client mc 命令行工具为 ls、cat、cp、mirror 和 diff 等 UNIX 命令提供了现代替代方案，同时支持文件系统和兼容 Amazon S3 的云存储服务。

mc 命令行工具以兼容 AWS S3 API 为目标构建，并针对 MinIO 和 AWS S3 进行了测试，以验证预期的功能与行为。

对于其他 S3 兼容服务，MinIO 不提供任何保证，因为这些服务的 S3 API 实现未知，因此不在支持范围内。虽然 mc 命令可能仍能按文档说明工作，但此类用法需要你自行承担风险。

mc 的语法如下：

mc [GLOBALFLAGS] COMMAND --help

支持的命令列表参见命令速查。

与 MinIO Server 的版本对齐

MinIO Client 与 MinIO Server 独立发布。

为获得最佳功能与兼容性，建议使用与 MinIO Server 版本发布时间接近的 MinIO Client 版本。例如，使用与 MinIO Server 同一天发布或晚于 MinIO Server 版本发布的 MinIO Client。

可以安装比 MinIO Server 更新的 MinIO Client 版本。但如果 MinIO Client 与 MinIO Server 的版本偏差过大，可能因差异导致更多告警或错误。例如，虽然复制相关的核心 S3 API（mc cp）可能保持不变，但某些功能或 flag 仅在客户端与服务端版本对齐时才可用或稳定。

快速开始

1) 安装 `mc`

在主机上安装 mc 命令行工具。点击与主机操作系统或环境对应的标签页：

Linux

以下命令会向系统 PATH 临时追加一项，以便运行 mc 工具。若要永久修改系统 PATH，请遵循你的操作系统说明。

或者，你也可以进入 mc 所在目录并运行 ./mc --help。

64 位 Intel

curl https://dl.min.io/client/mc/release/linux-amd64/mc \
  --create-dirs \
  -o $HOME/minio-binaries/mc

chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/

mc --help

64 位 PPC

curl https://dl.min.io/client/mc/release/linux-ppc64le/mc \
  --create-dirs \
  -o ~/minio-binaries/mc

chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/

mc --help

ARM64

curl https://dl.min.io/client/mc/release/linux-arm64/mc \
  --create-dirs \
  -o ~/minio-binaries/mc

chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/

mc --help

从 MinIO 下载页面安装

MinIO 不会通过常见 Linux 软件仓库或包管理器（Ubuntu、RHEL、Archlinux/AUR）正式发布其二进制文件。 MinIO 二进制文件唯一的官方来源是 MinIO Download Page。

MinIO 不建议通过包管理器安装，因为上游仓库可能会安装错误的软件包，或安装被重命名的软件包。

所有文档都假定你仅通过下载页面安装官方 mc 客户端二进制文件，且二进制名称未做任何修改。

macOS

brew install minio/stable/mc
mc --help

Windows

在浏览器中打开以下文件：

https://dl.min.io/client/mc/release/windows-amd64/mc.exe

双击该文件即可执行，或者在命令提示符或 PowerShell 中运行以下命令：

\path\to\mc.exe --help

Source

从源码安装适用于开发者和高级用户，并要求具备可用的 Golang 环境。请参阅 How to install Golang.

在终端环境中运行以下命令，从源码安装 mc：

go install github.com/minio/mc@latest

mc update 不支持源码安装方式。

2) 为兼容 S3 的服务创建别名

Important

以下示例会临时禁用 bash history，以降低身份认证凭据明文泄露的风险。这是一项基础安全措施，无法覆盖所有可能的攻击向量。对于在命令行输入敏感信息，请遵循你所用操作系统的安全最佳实践。

使用 mc alias set 命令将 Amazon S3 兼容服务添加到 mc 配置中。

bash +o history
mc alias set ALIAS HOSTNAME ACCESS_KEY SECRET_KEY
bash -o history

将 ALIAS 替换为与 S3 服务关联的名称。 mc 命令通常要求提供 ALIAS 作为参数，以标识要执行操作的 S3 服务。
将 HOSTNAME 替换为 S3 服务的 URL endpoint 或 IP 地址。
将 ACCESS_KEY 和 SECRET_KEY 替换为该 S3 服务上某个用户的 access key 和 secret key。

将各参数替换为所需值。如果省略 ACCESS_KEY 和 SECRET_KEY，命令会在 CLI 中提示输入这两个值。

以下每个标签页都包含一个特定提供商示例：

MinIO Server

mc alias set myminio https://minioserver.example.net ACCESS_KEY SECRET_KEY

AWS S3 Storage

mc alias set myS3 https://s3.{your-region-code}.amazonaws.com/endpoint ACCESS_KEY SECRET_KEY

Google Cloud Storage

mc alias set myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET_KEY

3) 测试连接

使用 mc admin info 命令测试与新添加 MinIO 部署的连接：

mc admin info myminio

如果命令执行成功，会返回该 S3 服务的信息。如果失败，请检查以下各项：

主机可连通 S3 服务 URL（例如使用 ping 或 traceroute）。
指定的 ACCESSKEY 和 SECRETKEY 对应 S3 服务上的有效用户。该用户必须有权限在该服务上执行操作。

对于 MinIO 部署，参见 Access Management 获取更多用户访问权限信息。对于其他兼容 S3 的服务，请参考该服务文档。

命令速查

下表列出了 mc 命令：

Note

MinIO Client 还包含用于管理 MinIO 部署的管理扩展。更完整文档参见 mc admin。

下表不包含这些命令。

命令	说明
`mc alias list` `mc alias remove` `mc alias set` `mc alias import` `mc alias export`	`mc alias` 命令提供了一个便捷接口，用于管理 `mc` 可连接并执行操作的 S3 兼容主机列表。
`mc anonymous get` `mc anonymous get-json` `mc anonymous links` `mc anonymous list` `mc anonymous set` `mc anonymous set-json`	`mc anonymous` 命令支持为存储桶及其内容设置或移除匿名 policies。配置了匿名策略的存储桶允许公开访问，客户端无需进行 authentication 即可执行策略授予的任意操作。
`mc batch describe` `mc batch generate` `mc batch list` `mc batch start` `mc batch status`	`mc batch` 命令允许您在 MinIO 部署上运行一个或多个作业任务。
`mc cat`	`mc cat` 命令将文件或对象的内容连接到另一个文件或对象。你也可以使用该命令将指定文件或对象的内容输出到 `STDOUT`。 `cat` 的功能与 `cat` 类似。
`mc cp`	`mc cp` 命令用于在 MinIO 部署与本地文件系统之间复制对象，其中源端可以是 MinIO 或本地文件系统。
`mc diff`	`mc diff` 命令用于计算两个文件系统目录或 MinIO 存储桶之间的差异。 `mc diff` 仅列出缺失的对象或大小不同的对象。`mc diff` 不会比较对象内容。
`mc du`	`mc du` 命令用于汇总存储桶和文件夹的磁盘使用量。你也可以对本地文件系统使用 `du`，以生成与 `du` 命令类似的结果。
`mc encrypt clear` `mc encrypt info` `mc encrypt set`	`mc encrypt` 命令用于设置、更新或禁用存储桶默认的服务端加密（SSE）模式。 MinIO 会使用指定的 SSE 模式自动加密对象。
`mc event add` `mc event ls` `mc event rm`	`mc event` 命令支持添加、删除和列出存储桶事件通知。
`mc find`	`mc find` 命令支持在 MinIO 部署上搜索对象。你也可以使用该命令在文件系统上搜索文件。
`mc get`	`mc get` 命令将对象从目标 S3 部署下载到本地文件系统。
`mc head`	`mc head` 命令显示对象的前 `n` 行，其中 `n` 是传递给该命令的参数。
`mc idp ldap accesskey` `mc idp ldap accesskey create-with-login` `mc idp ldap add` `mc idp ldap disable` `mc idp ldap enable` `mc idp ldap info` `mc idp ldap ls` `mc idp ldap policy` `mc idp ldap rm` `mc idp ldap update`	`mc idp ldap` 命令用于管理第三方 Active Directory 或 LDAP 身份与访问管理（IAM）集成的配置。
`mc idp openid add` `mc idp openid disable` `mc idp openid enable` `mc idp openid info` `mc idp openid ls` `mc idp openid rm` `mc idp openid update`	`mc idp openid` 命令允许你管理第三方 OpenID 身份与访问管理（IAM）集成的配置。
`mc idp ldap policy attach` `mc idp ldap policy detach` `mc idp ldap policy entities`	`mc idp ldap policy` 命令用于显示策略与关联组或用户之间的映射关系。
`mc ilm restore` `mc ilm rule add` `mc ilm rule edit` `mc ilm rule export` `mc ilm rule import` `mc ilm rule ls` `mc ilm rule rm` `mc ilm tier add` `mc ilm tier check` `mc ilm tier info` `mc ilm tier ls` `mc ilm tier rm` `mc ilm tier update`	`mc ilm` 命令用于管理 MinIO 部署中的对象生命周期管理规则和分层。
`mc legalhold clear` `mc legalhold info` `mc legalhold set`	`mc legalhold` 命令用于为一个或多个对象设置、移除或获取 object legal hold (WORM) 配置。
`mc license info` `mc license register` `mc license update`	`mc license` 命令用于管理 MinIO SUBNET 的集群注册。可使用这些命令注册部署、显示集群当前许可证信息，或更新集群的许可证密钥。
`mc ls`	`mc ls` 命令用于列出 MinIO 或其他 S3 兼容服务上的存储桶和对象。
`mc mb`	`mc mb` 命令在指定路径创建新的存储桶或目录。
`mc mirror`	`mc mirror` 命令用于将内容同步到 MinIO 部署，类似于 `rsync` 工具。 `mc mirror` 支持以文件系统、MinIO 部署和其他 S3 兼容主机作为同步源。
`mc mv`	`mc mv` 命令将对象从源移动到目标，例如在不同 MinIO 部署之间移动，或在同一 MinIO 部署的不同存储桶之间移动。 `mc mv` 还支持在本地文件系统与 MinIO 之间移动对象。
`mc od`	`mc od` 命令将本地文件按指定的分片数量与分片大小复制到远程位置。该命令会输出上传该文件所耗费的时间。
`mc ping`	`mc ping` 命令对指定目标执行存活性检查。
`mc pipe`	`mc pipe` 命令将内容从 STDIN 流式传输到目标对象。
`mc put`	`mc put` 将对象从本地文件系统上传到目标 S3 部署中的存储桶。
`mc rb`	`mc rb` 命令用于删除 MinIO 或其他兼容 S3 服务上的一个或多个存储桶。如仅需删除存储桶内容，请改用 `mc rm`。
`mc ready`	`mc ready` 命令用于检查集群状态，以及集群是否具有 `read` 和 `write` quorum。
`mc replicate add` `mc replicate backlog` `mc replicate export` `mc replicate import` `mc replicate ls` `mc replicate resync` `mc replicate rm` `mc replicate status` `mc replicate update`	`mc replicate` 命令用于为 MinIO 部署配置和管理服务端存储桶复制，包括双活复制配置和重新同步。
`mc retention clear` `mc retention info` `mc retention set`	`mc retention` 命令用于为存储桶中的一个或多个对象配置 Write-Once Read-Many (WORM) locking 设置。你还可以为存储桶设置默认的对象锁设置；未显式配置对象锁设置的所有对象都会继承该存储桶默认值。
`mc rm`	`mc rm` 命令用于从 MinIO 部署的存储桶中删除对象。如需彻底删除存储桶，请改用 `mc rb`。
`mc share download` `mc share ls` `mc share upload`	使用 `mc share` 命令管理预签名 URL，以便下载和上传 MinIO 存储桶中的对象。
`mc sql`	`mc sql` 命令提供 S3 Select 接口，用于对指定 MinIO 部署中的对象执行 SQL 查询。
`mc stat`	`mc stat` 命令用于显示 MinIO 存储桶中对象的信息，包括对象元数据。你也可以使用它来检索存储桶元数据。
`mc support callhome` `mc support diag` `mc support inspect` `mc support perf` `mc support profile` `mc support proxy` `mc support top api` `mc support top disk` `mc support top locks` `mc support upload`	MinIO Client `mc support` 命令提供用于分析部署健康状况或性能、并运行诊断的工具。你还可以上传生成的健康报告，供 MinIO 工程团队进一步分析。
`mc tag list` `mc tag remove` `mc tag set`	`mc tag` 命令用于添加、删除和列出与存储桶或对象关联的标签。
`mc tree`	`mc tree` 命令以树形格式列出 MinIO 存储桶中的所有前缀。该命令还可选支持在每个前缀处列出存储桶内的所有对象，包括存储桶根。
`mc undo`	`mc undo` 命令用于撤销指定路径上由 `PUT` 或 `DELETE` 操作引起的更改。
`mc update`	`mc update` 命令会自动将 mc 二进制更新到最新稳定版本。
`mc version enable` `mc version info` `mc version suspend`	`mc version` 命令可为 MinIO 存储桶启用、禁用并获取版本控制状态。
`mc watch`	`mc watch` 命令用于监视指定 MinIO 存储桶或本地文件系统路径上的事件。对于 S3 服务，请使用 `mc event add` 在兼容 S3 的服务上配置存储桶事件通知。

配置文件

mc 使用 JSON 格式的配置文件来存储某些类型的信息，例如每个已配置兼容 S3 服务的 aliases。

在 Linux 和 macOS 上，默认配置文件位置为 ~/.mc/config.json。

在 Windows 上，mc 会尝试通过特定环境变量构造默认文件路径。如果某个变量未设置，mc 会继续尝试下一个变量。如果所有尝试都失败，mc 会返回错误。下列列表按 mc 检查顺序说明了可能的文件路径位置：

HOME\.mc\config.json
USERPROFILE\.mc\config.json
HOMEDRIVE+HOMEPATH\.mc\config.json

可使用 --config-dir

证书

MinIO Client 将部署使用的证书和 CA 存储在以下路径：

Linux、macOS 和其他类 Unix 系统：

~/.mc/certs/ # certificates
~/.mc/certs/CAs/ # Certificate Authorities

Windows 系统：

C:\Users\[username]\mc\certs\ # certificates
C:\Users\[username]\mc\certs\CAs\ # Certificate Authorities

创建新的 alias 时，MinIO Client 会拉取对端证书、计算公钥指纹，并询问用户是否接受该部署的证书。如果你决定信任该证书，MinIO Client 会将其添加到上述证书颁发机构路径。

Note

在测试环境中，你可以通过传入 --insecure flag，跳过部分 MinIO Client 命令的证书检查。

模式匹配

某些命令和 flag 支持模式匹配。启用后，模式可包含以下任一通配符用于字符替换：

* 表示要匹配的一串字符，可位于中间或末尾。
? 表示单个字符。

例如，可参考以下通配符使用示例及其结果。

模式	文本	匹配结果
`abc*`	ab	匹配
`abc*`	abd	不匹配
`abc*c`	abcd	匹配
`ab*??d`	abxxc	匹配
`ab*??d`	abxc	匹配
`ab??d`	abxc	匹配
`ab??d`	abc	匹配
`ab??d`	abcxdd	不匹配

全局选项

所有 commands 都支持以下全局选项。你也可以使用 Environment Variables 来定义其中部分选项。

--config-dir

指向 JSON 格式配置文件的路径， mc 使用该文件存储数据。有关 mc 如何使用配置文件的更多信息，请参见配置文件。

或者，设置环境变量 MC_CONFIG_DIR。

--debug

启用控制台详细输出。

例如，以下操作会为 mc ls 命令增加详细输出：

mc --debug ls play

或者，设置环境变量 MC_DEBUG。

--disable-pager, --dp: New in version mc: RELEASE.2024-04-29T09-56-05Z

在 CLI 中禁用 MinIO Client 的分页功能。使用后，输出会直接打印到原始 STDOUT。

--insecure

禁用 TLS/SSL 证书校验。允许与证书无效的服务器建立 TLS 连接。对不受信任的 S3 主机使用该选项时请谨慎。

或者，设置环境变量 MC_INSECURE。

--json

启用 JSON lines 格式输出到控制台。

例如，以下操作会为 mc ls 命令增加 JSON Lines 输出：

mc --json ls play

或者，设置环境变量 MC_JSON。

--no-color

禁用控制台输出的内置配色主题。适用于 dumb 终端。

或者，设置环境变量 MC_NO_COLOR。

--quiet

抑制控制台输出。

或者，设置环境变量 MC_QUIET。

--resolve

New in version mc: RELEASE.2024-08-13T05-33-17Z

创建自定义 DNS 映射，将 HOST 解析到指定 IP 地址。

使用以下语法：

--resolve HOST[:PORT]=IP

例如：

mc alias set --resolve myminio.example.com:9000=192.168.188.118 'myminio' 'https://myminio.example.com:9000' 'miniouser' 'miniosecret'

可重复该 flag 多次以添加更多自定义 DNS 映射。

--version: 显示 mc 的当前版本。

--help: Optional
在终端显示命令用法摘要。