MinIO 客户端 mc 命令使用指南

mc（MinIO Client） 是 MinIO 官方提供的命令行客户端，兼容 S3 协议，可用于管理 MinIO、AWS S3、阿里云 OSS 等对象存储。日常运维中常用于桶（Bucket）管理、文件上传下载、同步备份、权限策略与运维排障。

本文整理 mc 的安装、Alias 配置，以及高频命令的参数说明与注释示例。

---

1. 安装 mc

Linux / macOS（推荐二进制）

# 下载官方二进制到 /usr/local/bin（Linux amd64）
curl -O https://dl.min.io/client/mc/release/linux-amd64/mc

# 赋予可执行权限
chmod +x mc

# 移动到 PATH 目录
sudo mv mc /usr/local/bin/

# 验证版本
mc --version

macOS（Homebrew）

# 通过 Homebrew 安装
brew install minio/stable/mc

# 验证版本
mc --version

容器内临时使用

# 在容器中直接运行 mc（不持久化配置）
docker run --rm -it --entrypoint=/bin/sh minio/mc

---

2. Alias：配置对象存储连接

mc 通过 Alias（别名） 保存远端服务地址与凭证。后续命令里用 ALIAS/BUCKET/OBJECT 形式访问。

核心命令

# 新增或更新一个 Alias
# --api：指定签名版本，S3v4 为常见默认
mc alias set <ALIAS> <URL> <ACCESS_KEY> <SECRET_KEY> [--api S3v4]

# 列出本地已配置的所有 Alias
mc alias list

# 删除某个 Alias
mc alias remove <ALIAS>

参数说明

参数 / 位置参数	说明
<ALIAS>	本地别名，如 myminio、prod-s3，后续命令用它代替完整 URL
<URL>	对象存储 Endpoint，如 http://192.168.1.10:9000 或 https://s3.amazonaws.com
<ACCESS_KEY>	访问密钥 Access Key
<SECRET_KEY>	秘密密钥 Secret Key
--api	API 签名版本，常用 S3v4；个别老环境可能用 S3v2

示例

# 配置本地 MinIO：别名 myminio，地址 9000 端口，AccessKey/SecretKey 按实际填写
mc alias set myminio http://127.0.0.1:9000 minioadmin minioadmin --api S3v4

# 查看已配置 Alias 及其 Endpoint
mc alias list

# 测试连通性：列出该 Alias 下的所有桶
mc ls myminio

安全提示

生产环境不要把 AccessKey / SecretKey 写进公开仓库。可用环境变量或 CI 密钥注入，并限制账号权限。

---

3. 桶（Bucket）管理

常用命令

# 创建桶
mc mb <ALIAS>/<BUCKET> [--region <REGION>] [--ignore-existing]

# 删除空桶（桶内有对象时会失败）
mc rb <ALIAS>/<BUCKET>

# 强制删除桶及其全部内容（危险操作）
mc rb --force --dangerous <ALIAS>/<BUCKET>

# 列出桶或对象
mc ls <ALIAS>[/<BUCKET>[/<PREFIX>]] [--recursive]

参数说明

参数	说明
<ALIAS>/<BUCKET>	目标路径：别名 + 桶名
--region <REGION>	创建桶时指定区域，如 us-east-1；MinIO 本地常可省略
--ignore-existing	桶已存在时不报错，适合脚本幂等创建
--recursive / -r	递归列出子前缀下所有对象
--force	配合 rb 强制删除
--dangerous	确认可删除非空桶（需与 --force 一起用）

示例

# 创建名为 backup 的桶；若已存在则忽略错误
mc mb myminio/backup --ignore-existing

# 列出 myminio 下所有桶
mc ls myminio

# 递归列出 backup 桶内所有对象
mc ls --recursive myminio/backup

# 仅当桶为空时删除
mc rb myminio/backup

# 【高危】强制删除桶及桶内全部对象，生产慎用
# mc rb --force --dangerous myminio/backup

---

4. 上传、下载与复制

常用命令

# 上传本地文件/目录到远端
mc cp <LOCAL_PATH> <ALIAS>/<BUCKET>/<PREFIX> [--recursive]

# 下载远端对象到本地
mc cp <ALIAS>/<BUCKET>/<OBJECT> <LOCAL_PATH> [--recursive]

# 远端对象之间复制
mc cp <ALIAS>/<SRC_BUCKET>/<OBJECT> <ALIAS>/<DST_BUCKET>/<OBJECT>

# 移动（复制后删除源，远端操作需谨慎）
mc mv <SRC> <DST> [--recursive]

参数说明

参数	说明
<LOCAL_PATH>	本地文件或目录路径
<ALIAS>/<BUCKET>/<OBJECT>	远端对象完整路径
--recursive / -r	递归处理目录或前缀下所有对象
--attr	上传时附加自定义元数据（键值对）
--newer-than / --older-than	按修改时间过滤对象（相对时长，如 7d、24h）
--continue	失败后可续传（大文件场景）

示例

# 上传单个文件到桶根目录，对象名保持 app.log
mc cp ./app.log myminio/backup/app.log

# 递归上传本地 logs 目录到远端 logs/ 前缀下
mc cp --recursive ./logs/ myminio/backup/logs/

# 下载远端单个对象到当前目录
mc cp myminio/backup/app.log ./app.log

# 递归下载远端 prefix 到本地目录
mc cp --recursive myminio/backup/logs/ ./logs-download/

# 同集群内把对象从 A 桶复制到 B 桶
mc cp myminio/backup/app.log myminio/archive/app.log

---

5. 同步（mirror）与差异比对

mc mirror 常用于备份、目录镜像；mc diff 用于比对两端差异。

常用命令

# 将源目录/桶镜像同步到目标（增量）
mc mirror <SRC> <DST> [--overwrite] [--remove] [--watch]

# 比对两端差异
mc diff <SRC> <DST>

参数说明

参数	说明
<SRC> / <DST>	源与目标，可为本地路径或 ALIAS/BUCKET/PREFIX
--overwrite	目标已存在同名对象时覆盖
--remove	删除目标中源侧已不存在的对象（使目标与源完全一致）
--watch	持续监听源变化并自动同步（适合热备份）
--exclude	排除匹配模式的文件，如 --exclude "*.tmp"

示例

# 增量同步本地 data 目录到 MinIO，不删除远端多余文件
mc mirror ./data/ myminio/backup/data/

# 同步并覆盖已存在对象
mc mirror --overwrite ./data/ myminio/backup/data/

# 【慎用】同步且删除目标侧多余对象，实现严格镜像
mc mirror --overwrite --remove ./data/ myminio/backup/data/

# 持续监听本地目录变化并自动同步到远端
mc mirror --watch ./data/ myminio/backup/data/

# 比对本地与远端差异（仅显示不一致项）
mc diff ./data/ myminio/backup/data/

---

6. 删除与批量清理

常用命令

# 删除单个对象
mc rm <ALIAS>/<BUCKET>/<OBJECT>

# 递归删除前缀下对象
mc rm --recursive [--force] <ALIAS>/<BUCKET>/<PREFIX>

# 按时间过滤删除
mc rm --recursive --force --older-than <DURATION> <ALIAS>/<BUCKET>/<PREFIX>

参数说明

参数	说明
--recursive / -r	递归删除目录/前缀
--force	不二次确认，强制执行（脚本中常用）
--older-than <DURATION>	只删早于指定时长的对象，如 7d、30d、24h
--newer-than <DURATION>	只删新于指定时长的对象
--versions	删除对象的所有版本（开启版本控制时）
--dangerous	允许删除整桶内容等危险操作（视版本而定）

示例

# 删除单个对象
mc rm myminio/backup/app.log

# 递归强制删除 logs/ 前缀下全部对象
mc rm --recursive --force myminio/backup/logs/

# 清理 30 天前的临时文件（按对象修改时间）
mc rm --recursive --force --older-than 30d myminio/backup/tmp/

危险操作

mc rm --recursive --force 不可恢复（未开版本控制时）。生产环境删除前建议先 mc ls 确认范围，或先 mc mirror 备份。

---

7. 查看对象信息与内容

常用命令

# 查看对象元数据（大小、ETag、Content-Type 等）
mc stat <ALIAS>/<BUCKET>/<OBJECT>

# 查看对象内容（类似 cat）
mc cat <ALIAS>/<BUCKET>/<OBJECT>

# 查看对象头部若干字节（类似 head）
mc head <ALIAS>/<BUCKET>/<OBJECT>

参数说明

命令 / 参数	说明
mc stat	输出对象或桶的元信息，不下载完整内容
mc cat	把对象内容打印到标准输出，适合小文本/配置
mc head	只看开头部分，避免大文件刷屏
--json	多数 mc 子命令支持，输出 JSON，便于脚本解析

示例

# 查看对象大小、修改时间、ETag
mc stat myminio/backup/app.log

# 以 JSON 格式输出，方便 jq 处理
mc stat --json myminio/backup/app.log

# 直接打印远端配置文件内容
mc cat myminio/backup/config/app.yaml

# 只看对象开头内容
mc head myminio/backup/app.log

---

8. 权限、匿名访问与共享链接

桶策略与匿名权限

# 设置桶匿名只读（公开读）
mc anonymous set download <ALIAS>/<BUCKET>

# 设置桶匿名读写（极度危险，仅测试环境）
mc anonymous set public <ALIAS>/<BUCKET>

# 取消匿名访问
mc anonymous set none <ALIAS>/<BUCKET>

# 查看当前匿名策略
mc anonymous get <ALIAS>/<BUCKET>

策略值	说明
download	匿名可读（下载），不可写
upload	匿名可写（上传），一般不推荐
public	匿名可读可写
none	禁止匿名访问（默认安全）

预签名分享链接

# 生成临时下载链接
# --expire：链接有效期，如 1h、24h、7d
mc share download --expire <DURATION> <ALIAS>/<BUCKET>/<OBJECT>

# 生成临时上传链接
mc share upload --expire <DURATION> <ALIAS>/<BUCKET>/<PREFIX>

参数	说明
--expire <DURATION>	链接过期时间，如 1h、24h、7d
download / upload	分别生成下载或上传用的预签名 URL

示例

# 桶设为公开只读（静态资源场景；生产需评估风险）
mc anonymous set download myminio/public-assets

# 生成 24 小时有效的下载链接
mc share download --expire 24h myminio/backup/report.pdf

# 关闭匿名访问，恢复私有
mc anonymous set none myminio/public-assets

---

9. 运维诊断与服务信息

# 查看服务端信息（版本、区域、磁盘等，视权限而定）
mc admin info <ALIAS>

# 查看当前配置的别名与连通性相关信息
mc alias list

# 对桶做健康/完整性相关检查（部分版本提供）
mc find <ALIAS>/<BUCKET> --name "*.log" --older-than 7d

mc find 常用参数

参数	说明
--name <PATTERN>	按对象名通配符匹配，如 "*.log"
--older-than / --newer-than	按时间过滤
--larger / --smaller	按对象大小过滤，如 --larger 100MB
--exec <CMD>	对匹配结果执行命令（高级用法）

示例

# 查找桶内 7 天前的 .log 文件
mc find myminio/backup --name "*.log" --older-than 7d

# 查找大于 100MB 的对象（排查异常大文件）
mc find myminio/backup --larger 100MB

# 查看 MinIO 集群/节点概要（需要 admin 权限）
mc admin info myminio

---

10. 日常运维速查清单

# ---------- Alias ----------
mc alias set myminio http://127.0.0.1:9000 ACCESS SECRET   # 配置连接
mc alias list                                              # 查看别名
mc ls myminio                                              # 测连通、列桶

# ---------- 桶 ----------
mc mb myminio/backup --ignore-existing                     # 创建桶
mc ls --recursive myminio/backup                           # 递归列对象

# ---------- 传输 ----------
mc cp ./file.txt myminio/backup/file.txt                   # 上传文件
mc cp --recursive ./dir/ myminio/backup/dir/               # 上传目录
mc cp myminio/backup/file.txt ./file.txt                   # 下载文件
mc mirror --overwrite ./data/ myminio/backup/data/         # 增量镜像同步

# ---------- 清理 ----------
mc rm myminio/backup/file.txt                              # 删单文件
mc rm --recursive --force --older-than 30d myminio/tmp/    # 按时间批量删

# ---------- 分享 ----------
mc share download --expire 24h myminio/backup/file.txt     # 临时下载链

---

11. 常见问题

1. mc: <ERROR> Access Denied

• 检查 AccessKey / SecretKey 是否正确。
• 检查该账号对目标桶是否有对应 IAM / Policy 权限。
• 时间偏差过大会导致签名失败，确认服务器 NTP 正常。

2. 路径写成了 s3://bucket/... 报错

• mc 使用的是 ALIAS/BUCKET/OBJECT，不是 AWS CLI 的 s3:// 写法。

3. HTTPS 自签名证书报错

# 仅测试环境：跳过 TLS 校验（不安全，勿用于生产）
mc alias set myminio https://minio.example.com ACCESS SECRET --api S3v4
# 部分版本可通过环境变量或配置忽略证书，优先还是安装正确 CA 证书

4. 大文件上传中断

• 使用 mc cp / mc mirror 时确认网络稳定；必要时分段重试或先 mirror 增量同步。
• 检查磁盘与桶配额是否充足：mc du myminio/backup（查看占用）。