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 服务端的版本对齐

MinIO 客户端与 MinIO 服务端独立发布。

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

可以安装比 MinIO 服务端更新的 MinIO 客户端版本。但如果 MinIO 客户端与 MinIO 服务端的版本偏差过大，可能因差异导致更多告警或错误。例如，虽然复制相关的核心 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 服务端

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 客户端还包含用于管理 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 客户端将部署使用的证书和 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
在终端显示命令用法摘要。