MinIO Object Storage

MinIO 对象存储

Use the MinIO API via

mc

(MinIO Client) or

curl

to manage S3-compatible object storage for file uploads, downloads, and bucket operations.

Official docs:

https://min.io/docs/minio/linux/reference/minio-mc.html

通过

mc

（MinIO客户端）或

curl

使用MinIO API，管理兼容S3的对象存储，实现文件上传、下载及存储桶操作。

官方文档：

https://min.io/docs/minio/linux/reference/minio-mc.html

When to Use

适用场景

Use this skill when you need to:

Upload/download files to S3-compatible storage
Manage buckets (create, list, delete)
Generate pre-signed URLs for temporary file access
List and search objects in storage
Mirror/sync directories between local and remote

在以下场景中可使用该技能：

上传/下载文件至兼容S3的存储服务
管理存储桶（创建、列出、删除）
生成预签名URL以实现临时文件访问
列出并搜索存储中的对象
镜像/同步本地与远程目录

Prerequisites

前提条件

Deploy MinIO server or use MinIO Play (public test server)
Get access credentials (Access Key and Secret Key)
Install MinIO Client (
```
mc
```
)

部署MinIO服务器或使用MinIO Play（公开测试服务器）
获取访问凭证（Access Key和Secret Key）
安装MinIO客户端（
```
mc
```
）

Install MinIO Client

安装MinIO客户端

bash

undefined

bash

undefined

macOS

brew install minio/stable/mc

Linux (amd64)

curl -O https://dl.min.io/client/mc/release/linux-amd64/mc chmod +x mc && sudo mv mc /usr/local/bin/

Verify installation

验证安装

mc --version

undefined

mc --version

undefined

Set Environment Variables

设置环境变量

bash

export MINIO_ENDPOINT="play.min.io"
export MINIO_ACCESS_KEY="your-access-key"
export MINIO_SECRET_KEY="your-secret-key"

For testing, use MinIO Play (public sandbox):

bash

export MINIO_ENDPOINT="play.min.io"
export MINIO_ACCESS_KEY="Q3AM3UQ867SPQQA43P2F"
export MINIO_SECRET_KEY="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG"

bash

export MINIO_ENDPOINT="play.min.io"
export MINIO_ACCESS_KEY="your-access-key"
export MINIO_SECRET_KEY="your-secret-key"

用于测试时，可使用MinIO Play（公开沙箱）：

bash

export MINIO_ENDPOINT="play.min.io"
export MINIO_ACCESS_KEY="Q3AM3UQ867SPQQA43P2F"
export MINIO_SECRET_KEY="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG"

Configure mc Alias

配置mc别名

bash

mc alias set myminio https://${MINIO_ENDPOINT} ${MINIO_ACCESS_KEY} ${MINIO_SECRET_KEY}

Important: When using
$VAR
in a command that pipes to another command, wrap the command containing
$VAR
in
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

bash

mc alias set myminio https://${MINIO_ENDPOINT} ${MINIO_ACCESS_KEY} ${MINIO_SECRET_KEY}

重要提示： 当在管道命令中使用
$VAR
时，请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的一个bug，直接使用管道时环境变量会被静默清除。
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

How to Use

使用方法

1. List Buckets

1. 列出存储桶

bash

mc ls myminio

bash

mc ls myminio

2. Create a Bucket

2. 创建存储桶

bash

mc mb myminio/my-bucket

bash

mc mb myminio/my-bucket

3. Upload a File

3. 上传文件

bash

undefined

bash

undefined

Upload single file

上传单个文件

mc cp /path/to/file.txt myminio/my-bucket/

Upload with custom name

自定义文件名上传

mc cp /path/to/file.txt myminio/my-bucket/custom-name.txt

Upload directory recursively

递归上传目录

mc cp --recursive /path/to/folder/ myminio/my-bucket/folder/

undefined

mc cp --recursive /path/to/folder/ myminio/my-bucket/folder/

undefined

4. Download a File

4. 下载文件

bash

undefined

bash

undefined

Download single file

下载单个文件

mc cp myminio/my-bucket/file.txt /local/path/

Download entire bucket

下载整个存储桶

mc cp --recursive myminio/my-bucket/ /local/path/

undefined

mc cp --recursive myminio/my-bucket/ /local/path/

undefined

5. List Objects in Bucket

5. 列出存储桶中的对象

bash

undefined

bash

undefined

List all objects

列出所有对象

mc ls myminio/my-bucket

List recursively with details

递归列出并显示详情

mc ls --recursive --summarize myminio/my-bucket

undefined

mc ls --recursive --summarize myminio/my-bucket

undefined

6. Delete Objects

6. 删除对象

bash

undefined

bash

undefined

Delete single file

删除单个文件

mc rm myminio/my-bucket/file.txt

Delete all objects in bucket

删除存储桶中的所有对象

mc rm --recursive --force myminio/my-bucket/

Delete bucket (must be empty)

删除存储桶（必须为空）

mc rb myminio/my-bucket

undefined

mc rb myminio/my-bucket

undefined

7. Generate Pre-signed URL

7. 生成预签名URL

Create temporary shareable links:

bash

undefined

创建可临时共享的链接：

bash

undefined

Download URL (expires in 7 days by default)

下载URL（默认7天后过期）

mc share download myminio/my-bucket/file.txt

Download URL with custom expiry (max 7 days)

自定义过期时间的下载URL（最长7天）

mc share download --expire 2h myminio/my-bucket/file.txt

Upload URL (for external uploads)

上传URL（用于外部上传）

mc share upload myminio/my-bucket/uploads/

undefined

mc share upload myminio/my-bucket/uploads/

undefined

8. Mirror/Sync Directories

8. 镜像/同步目录

bash

undefined

bash

undefined

One-way sync local to remote

单向同步本地至远程

mc mirror /local/folder/ myminio/my-bucket/folder/

One-way sync remote to local

单向同步远程至本地

mc mirror myminio/my-bucket/folder/ /local/folder/

Watch and sync changes continuously

监控并持续同步变更

mc mirror --watch /local/folder/ myminio/my-bucket/folder/

undefined

mc mirror --watch /local/folder/ myminio/my-bucket/folder/

undefined

9. Get Object Info

9. 获取对象信息

bash

undefined

bash

undefined

Get file metadata

获取文件元数据

mc stat myminio/my-bucket/file.txt

Get bucket info

获取存储桶信息

mc stat myminio/my-bucket

undefined

mc stat myminio/my-bucket

undefined

10. Search Objects

10. 搜索对象

bash

undefined

bash

undefined

Find by name pattern

按名称模式查找

mc find myminio/my-bucket --name "*.txt"

Find files larger than 10MB

查找大于10MB的文件

mc find myminio/my-bucket --larger 10MB

Find files modified in last 7 days

查找最近7天内修改的文件

mc find myminio/my-bucket --newer-than 7d

---

mc find myminio/my-bucket --newer-than 7d

---

Using curl with Pre-signed URLs

使用curl与预签名URL

For environments without

mc

, use pre-signed URLs with curl:

在没有

mc

的环境中，可结合curl使用预签名URL：

Upload with Pre-signed URL

通过预签名URL上传

bash

undefined

bash

undefined

First, generate upload URL with mc

首先，使用mc生成上传URL

UPLOAD_URL=$(bash -c 'mc share upload --json myminio/my-bucket/file.txt' | jq -r '.share')

Then upload with curl

然后使用curl上传

curl -X PUT --upload-file /path/to/file.txt "$UPLOAD_URL"

undefined

curl -X PUT --upload-file /path/to/file.txt "$UPLOAD_URL"

undefined

Download with Pre-signed URL

通过预签名URL下载

bash

undefined

bash

undefined

Generate download URL

生成下载URL

DOWNLOAD_URL=$(bash -c 'mc share download --json myminio/my-bucket/file.txt' | jq -r '.share')

Download with curl

使用curl下载

curl -o /local/path/file.txt "$DOWNLOAD_URL"

---

curl -o /local/path/file.txt "$DOWNLOAD_URL"

---

Using curl with AWS Signature V2

使用curl与AWS签名版本2

For direct API access without mc (simple authentication):

bash

#!/bin/bash

无需mc，直接通过API访问（简单认证）：

bash

#!/bin/bash

minio-upload.sh - Upload file to MinIO

minio-upload.sh - 上传文件至MinIO

bucket="$1" file="$2" host="${MINIO_ENDPOINT}" s3_key="${MINIO_ACCESS_KEY}" s3_secret="${MINIO_SECRET_KEY}"

resource="/${bucket}/${file}" content_type="application/octet-stream" date=$(date -R) signature_string="PUT\n\n${content_type}\n${date}\n${resource}" signature=$(echo -en "${signature_string}" | openssl sha1 -hmac "${s3_secret}" -binary | base64)

curl -X PUT -T "${file}" --header "Host: ${host}" --header "Date: ${date}" --header "Content-Type: ${content_type}" --header "Authorization: AWS ${s3_key}:${signature}" "https://${host}${resource}"


Usage:

```bash
chmod +x minio-upload.sh
./minio-upload.sh my-bucket myfile.txt

bucket="$1" file="$2" host="${MINIO_ENDPOINT}" s3_key="${MINIO_ACCESS_KEY}" s3_secret="${MINIO_SECRET_KEY}"

resource="/${bucket}/${file}" content_type="application/octet-stream" date=$(date -R) signature_string="PUT\n\n${content_type}\n${date}\n${resource}" signature=$(echo -en "${signature_string}" | openssl sha1 -hmac "${s3_secret}" -binary | base64)

curl -X PUT -T "${file}" --header "Host: ${host}" --header "Date: ${date}" --header "Content-Type: ${content_type}" --header "Authorization: AWS ${s3_key}:${signature}" "https://${host}${resource}"


使用方法：

```bash
chmod +x minio-upload.sh
./minio-upload.sh my-bucket myfile.txt

Using AWS CLI

使用AWS CLI

MinIO is fully compatible with AWS CLI:

bash

undefined

MinIO完全兼容AWS CLI：

bash

undefined

Configure AWS CLI for MinIO

为MinIO配置AWS CLI

aws configure set aws_access_key_id "${MINIO_ACCESS_KEY}" aws configure set aws_secret_access_key "${MINIO_SECRET_KEY}" aws configure set default.s3.signature_version s3v4

List buckets

列出存储桶

aws --endpoint-url "https://${MINIO_ENDPOINT}" s3 ls

Upload file

上传文件

aws --endpoint-url "https://${MINIO_ENDPOINT}" s3 cp file.txt s3://my-bucket/

Download file

下载文件

aws --endpoint-url "https://${MINIO_ENDPOINT}" s3 cp s3://my-bucket/file.txt ./

List objects

列出对象

aws --endpoint-url "https://${MINIO_ENDPOINT}" s3 ls s3://my-bucket/

---

aws --endpoint-url "https://${MINIO_ENDPOINT}" s3 ls s3://my-bucket/

---

Bucket Policies

存储桶策略

Set Bucket to Public Read

设置存储桶为公开可读

bash

mc anonymous set download myminio/my-bucket

bash

mc anonymous set download myminio/my-bucket

Set Bucket to Private

设置存储桶为私有

bash

mc anonymous set none myminio/my-bucket

bash

mc anonymous set none myminio/my-bucket

Apply Custom Policy

应用自定义策略

bash

undefined

bash

undefined

Create policy.json

创建policy.json

cat > /tmp/policy.json << 'EOF' { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": {"AWS": [""]}, "Action": ["s3:GetObject"], "Resource": ["arn:aws:s3:::my-bucket/public/"] } ] } EOF

mc anonymous set-json /tmp/policy.json myminio/my-bucket

---

cat > /tmp/policy.json << 'EOF' { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": {"AWS": [""]}, "Action": ["s3:GetObject"], "Resource": ["arn:aws:s3:::my-bucket/public/"] } ] } EOF

mc anonymous set-json /tmp/policy.json myminio/my-bucket

---

Guidelines

指导原则

Use mc for most operations - It handles authentication and signing automatically
Pre-signed URLs for external access - Share files without exposing credentials
Use port 9000 for API - Port 9001 is typically the web console
Set appropriate expiry - Pre-signed URLs should expire as soon as practical (max 7 days)
Use mirror for backups -
```
mc mirror --watch
```
for continuous sync
Bucket naming rules - Lowercase, 3-63 characters, no underscores or consecutive dots

大多数操作使用mc - 它会自动处理认证和签名
预签名URL用于外部访问 - 无需暴露凭证即可共享文件
使用9000端口进行API访问 - 9001端口通常为Web控制台
设置合适的过期时间 - 预签名URL应尽可能快地过期（最长7天）
使用mirror进行备份 -
```
mc mirror --watch
```
用于持续同步
存储桶命名规则 - 小写、3-63个字符，不含下划线或连续点号

minio

Original

Translation

MinIO Object Storage

MinIO 对象存储

When to Use

适用场景

Prerequisites

前提条件

Install MinIO Client

安装MinIO客户端

macOS

macOS

Linux (amd64)

Linux (amd64)

Verify installation

验证安装

Set Environment Variables

设置环境变量

Configure mc Alias

配置mc别名

How to Use

使用方法

1. List Buckets

1. 列出存储桶

2. Create a Bucket

2. 创建存储桶

3. Upload a File

3. 上传文件

Upload single file

上传单个文件

Upload with custom name

自定义文件名上传

Upload directory recursively

递归上传目录

4. Download a File

4. 下载文件

Download single file

下载单个文件

Download entire bucket

下载整个存储桶

5. List Objects in Bucket

5. 列出存储桶中的对象

List all objects

列出所有对象

List recursively with details

递归列出并显示详情

6. Delete Objects

6. 删除对象

Delete single file

删除单个文件

Delete all objects in bucket

删除存储桶中的所有对象

Delete bucket (must be empty)

删除存储桶（必须为空）

7. Generate Pre-signed URL

7. 生成预签名URL

Download URL (expires in 7 days by default)

下载URL（默认7天后过期）

Download URL with custom expiry (max 7 days)

自定义过期时间的下载URL（最长7天）

Upload URL (for external uploads)

上传URL（用于外部上传）

8. Mirror/Sync Directories

8. 镜像/同步目录

One-way sync local to remote

单向同步本地至远程

One-way sync remote to local

单向同步远程至本地

Watch and sync changes continuously

监控并持续同步变更

9. Get Object Info

9. 获取对象信息

Get file metadata

获取文件元数据

Get bucket info

获取存储桶信息

10. Search Objects

10. 搜索对象

Find by name pattern