MinIO 对象存储指南

MinIO 是一个高性能的分布式对象存储系统，兼容 Amazon S3 API。它专为云原生应用程序设计，提供企业级功能，同时保持简单易用。

什么是 MinIO

MinIO 是一个开源的对象存储服务器，具有以下特点：

S3 兼容: 完全兼容 Amazon S3 API
高性能: 专为高性能 I/O 设计
分布式: 支持分布式部署和扩展
云原生: 专为容器和 Kubernetes 环境设计
企业级: 提供加密、版本控制、生命周期管理等企业功能

核心概念

Bucket: 存储对象的容器，类似于文件夹
Object: 存储在 bucket 中的实际数据
Access Key: 用于身份验证的密钥 ID
Secret Key: 用于身份验证的密钥密码

安装 MinIO

Docker 安装（推荐）

bash

# 拉取 MinIO 镜像
docker pull minio/minio

# 运行 MinIO 容器
docker run -p 9000:9000 -p 9001:9001 \
  --name minio \
  -v /mnt/data:/data \
  -e "MINIO_ROOT_USER=admin" \
  -e "MINIO_ROOT_PASSWORD=password123" \
  minio/minio server /data --console-address ":9001"

二进制安装

bash

# 下载 MinIO 二进制文件
wget https://dl.min.io/server/minio/release/linux-amd64/minio

# 设置执行权限
chmod +x minio

# 运行 MinIO
./minio server /data

Kubernetes 安装

yaml

apiVersion: v1
kind: Namespace
metadata:
  name: minio-system
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: minio
  namespace: minio-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: minio
  template:
    metadata:
      labels:
        app: minio
    spec:
      containers:
      - name: minio
        image: minio/minio
        ports:
        - containerPort: 9000
        - containerPort: 9001
        env:
        - name: MINIO_ROOT_USER
          value: "admin"
        - name: MINIO_ROOT_PASSWORD
          value: "password123"
        command:
        - /bin/bash
        - -c
        - minio server /data --console-address ":9001"
        volumeMounts:
        - name: data
          mountPath: /data
      volumes:
      - name: data
        emptyDir: {}

配置 MinIO

环境变量配置

bash

# 基本配置
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=password123
MINIO_BROWSER=on
MINIO_DOMAIN=minio.example.com

# 高级配置
MINIO_CACHE_DRIVES=ssd1,ssd2
MINIO_CACHE_EXCLUDE=*.pdf;*.doc
MINIO_CACHE_EXPIRY=90h
MINIO_CACHE_MAXUSE=80

配置文件

创建 ~/.minio/config.json:

json

{
  "version": "1",
  "address": ":9000",
  "console-address": ":9001",
  "credentials": {
    "accessKey": "admin",
    "secretKey": "password123"
  },
  "region": "us-east-1",
  "browser": "on",
  "logger": {
    "console": {
      "enabled": true,
      "level": "info"
    },
    "file": {
      "enabled": true,
      "level": "info",
      "filename": "/var/log/minio/minio.log"
    }
  }
}

基本使用

使用 MinIO Client (mc)

MinIO Client (mc) 是一个命令行工具，用于与 MinIO 和 Amazon S3 兼容的云存储服务进行交互。

安装 mc 客户端

bash

# Linux/macOS
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc

# macOS (使用 Homebrew)
brew install minio/stable/mc

# Windows (使用 Chocolatey)
choco install mc

# 或者下载 Windows 二进制文件
# https://dl.min.io/client/mc/release/windows-amd64/mc.exe

配置 MinIO 服务器

bash

# 添加 MinIO 服务器别名
mc alias set myminio http://localhost:9000 admin password123

# 添加 Amazon S3 别名
mc alias set mys3 https://s3.amazonaws.com AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# 列出所有别名
mc alias ls

# 删除别名
mc alias remove myminio

Bucket 操作

bash

# 创建 bucket
mc mb myminio/my-bucket

# 创建带区域的 bucket
mc mb myminio/my-bucket --region us-east-1

# 列出所有 bucket
mc ls myminio/

# 列出 bucket 内容
mc ls myminio/my-bucket/

# 递归列出 bucket 内容
mc ls myminio/my-bucket/ --recursive

# 删除空 bucket
mc rb myminio/my-bucket

# 强制删除非空 bucket
mc rb myminio/my-bucket --force

# 设置 bucket 策略
mc policy set download myminio/my-bucket
mc policy set upload myminio/my-bucket
mc policy set public myminio/my-bucket
mc policy set private myminio/my-bucket

# 设置匿名访问策略（适用于某些 MinIO 版本）
mc anonymous set download myminio/my-bucket
mc anonymous set upload myminio/my-bucket
mc anonymous set public myminio/my-bucket
mc anonymous set private myminio/my-bucket

# 查看匿名访问策略
mc anonymous get myminio/my-bucket

# 列出所有匿名访问策略
mc anonymous list myminio/my-bucket

关于 Bucket 策略命令的说明

MinIO 的不同版本使用不同的命令来设置 bucket 访问策略：

较新版本使用 mc policy：

bash

mc policy set download myminio/my-bucket
mc policy set upload myminio/my-bucket
mc policy set public myminio/my-bucket
mc policy set private myminio/my-bucket

较旧版本使用 mc anonymous：

bash

mc anonymous set download myminio/my-bucket
mc anonymous set upload myminio/my-bucket
mc anonymous set public myminio/my-bucket
mc anonymous set private myminio/my-bucket

策略类型说明：

download: 允许匿名用户下载/读取文件
upload: 允许匿名用户上传文件
public: 允许匿名用户完全访问（读写）
private: 禁止匿名访问，需要认证

检查命令可用性：

bash

# 检查 policy 命令是否可用
mc policy --help

# 检查 anonymous 命令是否可用
mc anonymous --help

版本兼容性建议：

MinIO Server 版本 < 2021-06-17: 使用 mc anonymous
MinIO Server 版本 >= 2021-06-17: 使用 mc policy
如果不确定，可以尝试两个命令，看哪个可用

文件操作

bash

# 上传单个文件
mc cp file.txt myminio/my-bucket/

# 上传文件到指定路径
mc cp file.txt myminio/my-bucket/path/to/file.txt

# 上传整个目录
mc cp /local/directory/ myminio/my-bucket/ --recursive

# 下载单个文件
mc cp myminio/my-bucket/file.txt ./

# 下载整个目录
mc cp myminio/my-bucket/ /local/directory/ --recursive

# 复制文件到另一个 bucket
mc cp myminio/bucket1/file.txt myminio/bucket2/

# 在不同服务器间复制
mc cp myminio/bucket1/file.txt mys3/bucket2/

# 移动文件
mc mv myminio/my-bucket/file1.txt myminio/my-bucket/file2.txt

# 删除文件
mc rm myminio/my-bucket/file.txt

# 递归删除目录
mc rm myminio/my-bucket/directory/ --recursive

# 删除指定前缀的文件
mc rm myminio/my-bucket/prefix/ --recursive

高级文件操作

bash

# 同步本地目录到 bucket
mc mirror /local/directory/ myminio/my-bucket/

# 同步 bucket 到本地目录
mc mirror myminio/my-bucket/ /local/directory/

# 排除特定文件类型
mc mirror /local/directory/ myminio/my-bucket/ --exclude "*.tmp" --exclude "*.log"

# 只同步新文件
mc mirror /local/directory/ myminio/my-bucket/ --newer

# 使用多线程上传
mc cp large-file.zip myminio/my-bucket/ --concurrent 10

# 设置文件元数据
mc cp file.txt myminio/my-bucket/ --attr "Content-Type=text/plain;Cache-Control=max-age=3600"

# 生成预签名 URL
mc share download myminio/my-bucket/file.txt --expire 1h

# 生成上传预签名 URL
mc share upload myminio/my-bucket/file.txt --expire 1h

文件管理

bash

# 查看文件信息
mc stat myminio/my-bucket/file.txt

# 查看 bucket 信息
mc stat myminio/my-bucket/

# 列出文件详细信息
mc ls myminio/my-bucket/ --json

# 查找文件
mc find myminio/my-bucket/ --name "*.txt"

# 查找大文件
mc find myminio/my-bucket/ --size +100MB

# 查找旧文件
mc find myminio/my-bucket/ --older-than 30d

# 查找新文件
mc find myminio/my-bucket/ --newer-than 7d

版本控制操作

bash

# 启用版本控制
mc version enable myminio/my-bucket

# 列出文件版本
mc ls myminio/my-bucket/file.txt --versions

# 恢复特定版本
mc cp myminio/my-bucket/file.txt --version-id "id" ./restored-file.txt

# 删除特定版本
mc rm myminio/my-bucket/file.txt --version-id "id"

# 暂停版本控制
mc version suspend myminio/my-bucket

生命周期管理

bash

# 设置生命周期规则
mc ilm add myminio/my-bucket --expiry-days 90

# 设置转换规则
mc ilm add myminio/my-bucket --transition-days 30 --transition-storage-class "GLACIER"

# 列出生命周期规则
mc ilm ls myminio/my-bucket

# 删除生命周期规则
mc ilm remove myminio/my-bucket --id "rule-id"

加密操作

bash

# 使用客户端加密上传
mc cp file.txt myminio/my-bucket/ --encrypt-key "my-key"

# 使用客户端加密下载
mc cp myminio/my-bucket/file.txt ./ --encrypt-key "my-key"

# 使用 KMS 加密
mc cp file.txt myminio/my-bucket/ --encrypt-kms "arn:aws:kms:region:account:key/key-id"

监控和诊断

bash

# 查看服务器状态
mc admin info myminio

# 查看服务器配置
mc admin config get myminio

# 查看服务器日志
mc admin trace myminio

# 查看性能指标
mc admin top myminio

# 测试连接
mc admin ping myminio

# 查看磁盘使用情况
mc admin disk-info myminio

批量操作

bash

# 批量上传多个文件
mc cp file1.txt file2.txt file3.txt myminio/my-bucket/

# 批量下载
mc cp myminio/my-bucket/file*.txt ./

# 批量删除
mc rm myminio/my-bucket/file*.txt

# 使用通配符
mc cp myminio/bucket1/*.jpg myminio/bucket2/

实用技巧

bash

# 显示进度条
mc cp large-file.zip myminio/my-bucket/ --progress

# 静默模式
mc cp file.txt myminio/my-bucket/ --quiet

# 调试模式
mc cp file.txt myminio/my-bucket/ --debug

# 设置超时
mc cp file.txt myminio/my-bucket/ --timeout 30s

# 使用配置文件
mc --config-dir /path/to/config cp file.txt myminio/my-bucket/

# 设置代理
mc --proxy http://proxy:8080 cp file.txt myminio/my-bucket/

常见使用场景

bash

# 备份数据库
mysqldump -u root -p database > backup.sql
mc cp backup.sql myminio/backups/$(date +%Y%m%d)/

# 日志归档
mc cp /var/log/app.log myminio/logs/$(date +%Y%m)/ --attr "Content-Type=text/plain"

# 静态网站部署
mc mirror ./dist/ myminio/website/ --exclude "*.map"

# 数据同步
mc mirror myminio/production/ myminio/backup/ --newer

# 文件清理
mc rm myminio/temp/ --recursive --older-than 7d

使用 Web 控制台

访问 http://localhost:9001 使用 Web 界面管理 MinIO。

API 示例

Python 示例

python

from minio import Minio
from minio.error import S3Error

# 创建客户端
client = Minio(
    "localhost:9000",
    access_key="admin",
    secret_key="password123",
    secure=False
)

# 创建 bucket
try:
    client.make_bucket("my-bucket")
    print("Bucket 'my-bucket' created successfully")
except S3Error as e:
    print(f"Error creating bucket: {e}")

# 上传文件
try:
    client.fput_object("my-bucket", "file.txt", "local-file.txt")
    print("File uploaded successfully")
except S3Error as e:
    print(f"Error uploading file: {e}")

# 下载文件
try:
    client.fget_object("my-bucket", "file.txt", "downloaded-file.txt")
    print("File downloaded successfully")
except S3Error as e:
    print(f"Error downloading file: {e}")

# 列出文件
try:
    objects = client.list_objects("my-bucket")
    for obj in objects:
        print(f"Object: {obj.object_name}, Size: {obj.size}")
except S3Error as e:
    print(f"Error listing objects: {e}")

JavaScript 示例

javascript

const Minio = require('minio');

// 创建客户端
const minioClient = new Minio.Client({
    endPoint: 'localhost',
    port: 9000,
    useSSL: false,
    accessKey: 'admin',
    secretKey: 'password123'
});

// 创建 bucket
async function createBucket() {
    try {
        await minioClient.makeBucket('my-bucket');
        console.log('Bucket created successfully');
    } catch (err) {
        console.error('Error creating bucket:', err);
    }
}

// 上传文件
async function uploadFile() {
    try {
        await minioClient.fPutObject('my-bucket', 'file.txt', './local-file.txt');
        console.log('File uploaded successfully');
    } catch (err) {
        console.error('Error uploading file:', err);
    }
}

// 下载文件
async function downloadFile() {
    try {
        await minioClient.fGetObject('my-bucket', 'file.txt', './downloaded-file.txt');
        console.log('File downloaded successfully');
    } catch (err) {
        console.error('Error downloading file:', err);
    }
}

// 列出文件
async function listObjects() {
    try {
        const stream = minioClient.listObjects('my-bucket', '', true);
        stream.on('data', (obj) => {
            console.log(`Object: ${obj.name}, Size: ${obj.size}`);
        });
    } catch (err) {
        console.error('Error listing objects:', err);
    }
}

Go 示例

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/minio/minio-go/v7"
    "github.com/minio/minio-go/v7/pkg/credentials"
)

func main() {
    // 创建客户端
    minioClient, err := minio.New("localhost:9000", &minio.Options{
        Creds:  credentials.NewStaticV4("admin", "password123", ""),
        Secure: false,
    })
    if err != nil {
        log.Fatal(err)
    }

    // 创建 bucket
    bucketName := "my-bucket"
    err = minioClient.MakeBucket(context.Background(), bucketName, minio.MakeBucketOptions{})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Bucket '%s' created successfully\n", bucketName)

    // 上传文件
    objectName := "file.txt"
    filePath := "./local-file.txt"
    contentType := "text/plain"

    _, err = minioClient.FPutObject(context.Background(), bucketName, objectName, filePath, minio.PutObjectOptions{ContentType: contentType})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("File '%s' uploaded successfully\n", objectName)

    // 下载文件
    err = minioClient.FGetObject(context.Background(), bucketName, objectName, "./downloaded-file.txt", minio.GetObjectOptions{})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("File '%s' downloaded successfully\n", objectName)

    // 列出文件
    objectsCh := minioClient.ListObjects(context.Background(), bucketName, minio.ListObjectsOptions{})
    for object := range objectsCh {
        if object.Err != nil {
            log.Fatal(object.Err)
        }
        fmt.Printf("Object: %s, Size: %d\n", object.Key, object.Size)
    }
}

最佳实践

安全配置

强密码: 使用强密码和定期轮换
HTTPS: 在生产环境中启用 HTTPS
IAM 策略: 使用细粒度的访问控制
加密: 启用服务器端加密

bash

# 启用 HTTPS
docker run -p 9000:9000 -p 9001:9001 \
  --name minio \
  -v /mnt/data:/data \
  -v /path/to/certs:/root/.minio/certs \
  -e "MINIO_ROOT_USER=admin" \
  -e "MINIO_ROOT_PASSWORD=password123" \
  minio/minio server /data --console-address ":9001"

性能优化

SSD 存储: 使用 SSD 存储提高 I/O 性能
网络优化: 使用高速网络连接
缓存配置: 合理配置缓存参数
并发控制: 根据硬件配置调整并发数

监控和日志

bash

# 启用详细日志
export MINIO_LOGGER_WEBHOOK_ENABLE=on
export MINIO_LOGGER_WEBHOOK_ENDPOINT=http://localhost:8080/webhook

# 监控指标
curl http://localhost:9000/minio/v2/metrics/cluster

故障排除

常见问题

连接被拒绝

bash

# 检查端口是否开放
netstat -tulpn | grep 9000

# 检查防火墙设置
sudo ufw allow 9000

权限错误

bash

# 检查文件权限
chmod 755 /data
chown -R minio:minio /data

磁盘空间不足

bash

# 检查磁盘使用情况
df -h

# 清理旧文件
./mc rm --recursive --older-than 30d myminio/my-bucket/

日志分析

bash

# 查看 MinIO 日志
docker logs minio

# 实时监控日志
docker logs -f minio

# 查看特定时间段的日志
docker logs --since="2023-01-01T00:00:00" minio

性能诊断

bash

# 检查系统资源
htop
iostat -x 1
iotop

# 网络性能测试
iperf3 -c localhost -p 9000

MinIO 对象存储指南 ​

目录 ​

什么是 MinIO ​

核心概念 ​

安装 MinIO ​

Docker 安装（推荐） ​

二进制安装 ​

Kubernetes 安装 ​

配置 MinIO ​

环境变量配置 ​

配置文件 ​

基本使用 ​

使用 MinIO Client (mc) ​

安装 mc 客户端 ​

配置 MinIO 服务器 ​

Bucket 操作 ​

关于 Bucket 策略命令的说明 ​

文件操作 ​

高级文件操作 ​

文件管理 ​

版本控制操作 ​

生命周期管理 ​

加密操作 ​

监控和诊断 ​

批量操作 ​

实用技巧 ​

常见使用场景 ​

使用 Web 控制台 ​

API 示例 ​

Python 示例 ​

JavaScript 示例 ​

Go 示例 ​

最佳实践 ​

安全配置 ​

性能优化 ​

监控和日志 ​

故障排除 ​

常见问题 ​

日志分析 ​

性能诊断 ​

更多资源 ​

MinIO 对象存储指南

目录

什么是 MinIO

核心概念

安装 MinIO

Docker 安装（推荐）

二进制安装

Kubernetes 安装

配置 MinIO

环境变量配置

配置文件

基本使用

使用 MinIO Client (mc)

安装 mc 客户端

配置 MinIO 服务器

Bucket 操作

关于 Bucket 策略命令的说明

文件操作

高级文件操作

文件管理

版本控制操作

生命周期管理

加密操作

监控和诊断

批量操作

实用技巧

常见使用场景

使用 Web 控制台

API 示例

Python 示例

JavaScript 示例

Go 示例

最佳实践

安全配置

性能优化

监控和日志

故障排除

常见问题

日志分析

性能诊断

更多资源