mc

mc — MinIO AIStor 命令行客户端

mc 是一个静态二进制文件，可连接任何兼容 S3 的对象存储（MinIO AIStor、MinIO、AWS S3 等）以及本地文件系统。它有两个界面：用于通过 S3 API 移动和检查对象及存储桶的数据平面命令（ls、cp、rm、mirror 等），以及用于管理 AIStor/MinIO 服务本身（用户、配置、修复、复制、分层）的控制平面 mc admin 命令。另有一个单独的 mc table 界面用于管理 AIStor Iceberg Tables。

本技能向模型讲解那些 Agent 容易出错或难以快速发现的内容。它不会列出所有标志：如需查看任何命令准确且最新的标志，请运行 mc <command> --help（以及 mc <command> <subcommand> --help）。该帮助信息是权威且与版本匹配的；本技能不是。

1. 别名是前提条件——没有别名，任何操作都无法进行

每个远程操作都以一个别名为目标：一个命名的端点及凭据。先检查现有配置，再视需要创建别名：

mc alias list                # what's configured (redacts secret keys)
mc alias list --json         # same, machine-readable

提供别名有两种方式。对于 Agent，优先使用环境变量方式——这样凭据不会写入 mc 配置文件，也不会修改用户的配置：

# Per-process — the agent's default. Alias name is the MC_HOST_ suffix.
# Inject the value from a secret manager / CI secret rather than a literal.
export MC_HOST_myminio="https://${KEY}:${SECRET}@play.min.io"
mc ls myminio/                             # "myminio" now resolves

# Persisted to ~/.mc/config.json — only when the user wants it saved.
mc alias set myminio https://play.min.io ACCESS_KEY SECRET_KEY

环境变量并不意味着可以忽视保密性：直接执行 export … 会将内容写入 shell 历史记录，值也会显示在进程环境中。不要将密钥硬编码或回显到日志中。参见 references/connect.md。

设置完成后，别名名称就是路径的第一个部分（myminio/bucket/key）。配置位于 ~/.mc/config.json（可通过 --config-dir 或 MC_CONFIG_DIR 覆盖）。完整详情、令牌/STS URL 格式、TLS 和其他提供商信息：references/connect.md。

2. 获取机器可读的输出

• --json 输出的是 JSON Lines（NDJSON），而不是 JSON 数组。 每行一个 JSON 对象——逐行解析（while read、jq -c、流式处理），不要对整个输出流调用 json.loads()。流式命令（ls、mirror、cp）会在每个项目处理时输出一行。
• 每个对象都有一个 "status" 字段（"success" 或 "error"）；出错时，对象会包含错误消息，且 mc 会以非零状态码退出。
• --quiet 会抑制进度条/旋转指示器；--no-color 会移除 ANSI 转义码。解析时优先使用 --json，并添加 --quiet 以获得整洁的日志。
• mc 成功时返回退出码 0，失败时返回非零值——应根据退出码而不是 stdout 文本进行分支处理。

详细信息和各命令的输出结构：references/output.md。

3. 路径语法

目标可以是本地路径（./data、/tmp/x），也可以是带别名前缀的 S3 路径：ALIAS/BUCKET/PREFIX/OBJECT。只有第一个部分与已配置的别名匹配时，它才会被视为别名；否则 mc 会将整个标记视为本地路径。因此，mc cp file.txt myminio/bucket/ 会将文件从本地复制到远程，而 mc cp myminio/bucket/key ./ 会将文件从远程复制到本地。没有 s3:// 方案；别名取代了它。

4. 破坏性操作 — 拒绝执行并上报人工处理

某些 mc 命令不可逆，和／或会影响整个站点。将这些命令视为仅限人工执行：即使任务看起来要求执行，也不要自行运行。停止操作，向用户展示确切的命令和目标，并要求由人工明确执行或提供书面授权。切勿试探性地运行这些命令、在循环中运行，或将其用于“清理”。

严格限制 — 默认拒绝；必须由人工运行或明确授权：

• mc rm --recursive --force ALIAS/BUCKET/PREFIX — 批量删除对象。 递归操作必须使用 --force。如果目标仅为别名，添加 --dangerous（mc rm --recursive --force --dangerous myminio）会清除整个站点。 --versions / --purge-deleted 会销毁版本历史。不要运行这些命令。
• mc rb --force ALIAS/BUCKET（以及用于整个站点的 mc rb --force --dangerous ALIAS）— 删除存储桶及其所有内容。如果存储桶非空，不带 --force 的 rb 会因致命错误而中止；它不会提示确认。
• mc mirror --remove … — 删除目标端中源端不存在的对象。

先确认 — 向用户展示，仅在获得明确批准后继续：

• mc mirror --overwrite …，或使用 cp / put 写入已有键 — 替换数据。
• 清除配置的形式：mc ilm rule remove --all --force、 mc replicate rm --all --force、mc event remove、 mc anonymous set private（撤销公共访问权限）。

除非事先已在存储桶上启用版本控制，否则它无法保护你。如有疑问，不要操作 — 将确切的命令交由人工处理。请参阅各参考文档中的“不可逆”提示。

5. 命令索引 — 选择合适的命令，然后查看其 --help

任务	命令
连接／配置客户端	alias、update、license、support
检查对象和存储桶	ls、stat、head、tree、du、find、diff
移动数据	cp、get、put、mv、mirror、pipe、cat、od
删除数据	rm、rb、undo
查询和监视	sql、watch、ping、ready
分享／预签名	share
存储桶配置	mb、version、tag、retention、legalhold、quota、anonymous、cors、encrypt、event
生命周期／复制／批处理	ilm、replicate、inventory、batch
集群管理	admin …、log、qos、kms、idp
AIStor Iceberg 表	table …

kms 既可作为顶层命令（mc kms），也可通过 admin 使用（mc admin kms）— 两者配置的是同一台服务。对于身份提供商，请使用顶层命令 mc idp ldap|openid；mc admin idp 已弃用，只会输出重定向提示。log 用于流式传输／查询服务日志，qos 用于管理服务质量（速率）规则 — 两者都仅适用于 AIStor。（mc policy 已弃用 — 存储桶匿名访问请使用 mc anonymous。）

参考文档

根据当前任务，按需加载这些文件（位于同级目录下的 references/ 中）：

• references/connect.md — 深入介绍别名：MC_HOST_ 环境变量形式（含会话令牌／STS）、mc alias set/list/remove、配置文件、TLS（--insecure）、非 MinIO 提供商、按路径或 DNS 查找存储桶。
• references/output.md — --json NDJSON 解析模式、退出码、非交互式／脚本规则、jq 示例。
• references/objects.md — 数据平面：ls cp mv rm get put mirror find du tree stat head cat pipe od diff sql watch undo share，以及破坏性标志的确切语义。
• references/buckets.md — 存储桶生命周期和配置：mb rb version tag retention legalhold quota policy anonymous cors encrypt event。
• references/data-management.md — ilm（分层／过期）、replicate（存储桶和站点复制）、inventory、batch 作业。
• references/admin.md — mc admin 控制平面：服务信息、用户和策略、配置、服务／修复／扫描器、退役／再平衡、KMS、层级、SUBNET。
• references/tables.md — AIStor Iceberg 表：仓库、命名空间、表、目录、分享、复制、维护。