MinIO 安装与使用指南

macOS 环境 | Homebrew | 2026-04-24

一、安装步骤

1. 安装 MinIO Server

# 安装 MinIO
brew install minio

# 安装 MinIO 客户端
brew install minio-mc

2. 启动服务

# 作为 brew 服务启动（推荐，开机自启）
brew services start minio

# 查看服务状态
brew services list | grep minio

# 查看日志
brew services logs minio

3. 验证安装

# 检查端口
lsof -i :9000

# 健康检查
curl http://localhost:9000/minio/health/live

# 配置 mc 别名
mc alias set local http://localhost:9000 minioadmin minioadmin

# 查看集群信息
mc admin info local

4. 当前配置

参数值
-----------
版本2025-10-15T17-29-55Z
API 端口9000
控制台http://localhost:9000
数据目录/opt/homebrew/var/minio
配置目录/opt/homebrew/etc/minio
默认账号minioadmin
默认密码minioadmin

二、服务管理

1. 常用命令

# 启动
brew services start minio

# 停止
brew services stop minio

# 重启
brew services restart minio

# 查看状态
brew services list | grep minio

# 卸载
brew services stop minio
brew uninstall minio

2. 手动启动（非服务方式）

/opt/homebrew/opt/minio/bin/minio server \
  --certs-dir=/opt/homebrew/etc/minio/certs \
  --address=:9000 \
  /opt/homebrew/var/minio

3. 修改端口

编辑 plist 文件：

# 停止服务
brew services stop minio

# 编辑配置
nano ~/Library/LaunchAgents/homebrew.mxcl.minio.plist
# 修改 --address=:9000 为其他端口

# 重启服务
brew services start minio

三、安全配置

1. 修改默认凭证

方法一：环境变量（推荐）

编辑 ~/Library/LaunchAgents/homebrew.mxcl.minio.plist，在 <array> 中添加：

<key>EnvironmentVariables</key>
<dict>
    <key>MINIO_ROOT_USER</key>
    <string>your-access-key</string>
    <key>MINIO_ROOT_PASSWORD</key>
    <string>your-secret-key</string>
</dict>

方法二：启动时指定

MINIO_ROOT_USER=myadmin MINIO_ROOT_PASSWORD=MyStrongPassword123! \
  minio server /opt/homebrew/var/minio --address=:9000

2. 密码要求

四、mc 客户端使用

1. 配置别名

# 添加本地 MinIO
mc alias set local http://localhost:9000 minioadmin minioadmin

# 添加远程 MinIO
mc alias set production https://minio.example.com access-key secret-key

# 查看别名列表
mc alias list

# 删除别名
mc alias remove production

2. Bucket 操作

# 创建 Bucket
mc mb local/my-bucket

# 列出所有 Bucket
mc ls local

# 删除 Bucket（必须为空）
mc rb local/my-bucket

# 强制删除（包含内容）
mc rb --force local/my-bucket

# 设置 Bucket 访问策略
mc anonymous set public local/my-bucket
mc anonymous set download local/my-bucket
mc anonymous set private local/my-bucket

# 查看 Bucket 策略
mc anonymous get local/my-bucket

3. 文件操作

# 上传文件
mc cp ./myfile.txt local/my-bucket/

# 上传目录
mc cp --recursive ./mydir/ local/my-bucket/

# 下载文件
mc cp local/my-bucket/myfile.txt ./

# 下载目录
mc cp --recursive local/my-bucket/ ./mydir/

# 列出文件
mc ls local/my-bucket/

# 列出文件（递归）
mc ls --recursive local/my-bucket/

# 删除文件
mc rm local/my-bucket/myfile.txt

# 删除目录
mc rm --recursive local/my-bucket/mydir/

# 复制文件
mc cp local/my-bucket/file.txt local/other-bucket/

# 移动文件
mc mv local/my-bucket/file.txt local/other-bucket/

# 查看文件信息
mc stat local/my-bucket/myfile.txt

# 查找文件
mc find local/my-bucket/ --name "*.jpg"

4. 文件同步

# 同步目录（只复制新/更新的文件）
mc mirror ./local-dir local/my-bucket/

# 同步后删除目标多余文件
mc mirror --remove ./local-dir local/my-bucket/

# 查看同步差异
mc mirror --diff ./local-dir local/my-bucket/

五、存储桶策略

1. 读写策略

# 公开读写
mc anonymous set public local/my-bucket

# 只读
mc anonymous set download local/my-bucket

# 只写
mc anonymous set upload local/my-bucket

# 私有
mc anonymous set private local/my-bucket

2. JSON 策略（高级）

创建 policy.json：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {"AWS": ["*"]},
      "Action": ["s3:GetObject"],
      "Resource": ["arn:aws:s3:::my-bucket/*.jpg"]
    }
  ]
}

应用策略：

mc anonymous set-json policy.json local/my-bucket

六、用户与权限管理

1. 创建用户

# 创建用户
mc admin user add local myuser MyPassword123!

# 列出用户
mc admin user list local

# 查看用户信息
mc admin user info local myuser

# 禁用用户
mc admin user disable local myuser

# 启用用户
mc admin user enable local myuser

# 删除用户
mc admin user remove local myuser

2. 创建策略

创建 readwrite.json：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:*"],
      "Resource": ["arn:aws:s3:::my-bucket/*"]
    }
  ]
}
# 创建策略
mc admin policy create local readwrite readwrite.json

# 列出策略
mc admin policy list local

# 查看策略
mc admin policy info local readwrite

# 删除策略
mc admin policy remove local readwrite

3. 绑定策略到用户

# 绑定策略
mc admin policy set local readwrite user=myuser

# 查看用户策略
mc admin policy info local readwrite

# 解绑策略
mc admin policy unset local readwrite user=myuser

七、与 Spring Boot 集成

1. 依赖

<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.7</version>
</dependency>

2. 配置

# application.yml
minio:
  endpoint: http://localhost:9000
  access-key: minioadmin
  secret-key: minioadmin
  bucket: my-bucket

3. Java 配置类

@Configuration
public class MinioConfig {
    
    @Value("${minio.endpoint}")
    private String endpoint;
    
    @Value("${minio.access-key}")
    private String accessKey;
    
    @Value("${minio.secret-key}")
    private String secretKey;
    
    @Bean
    public MinioClient minioClient() {
        return MinioClient.builder()
                .endpoint(endpoint)
                .credentials(accessKey, secretKey)
                .build();
    }
}

4. 文件上传/下载

@Service
public class MinioService {
    
    @Autowired
    private MinioClient minioClient;
    
    @Value("${minio.bucket}")
    private String bucket;
    
    // 上传文件
    public String upload(MultipartFile file) throws Exception {
        String objectName = UUID.randomUUID().toString() + 
            "_" + file.getOriginalFilename();
        
        minioClient.putObject(
            PutObjectArgs.builder()
                .bucket(bucket)
                .object(objectName)
                .stream(file.getInputStream(), file.getSize(), -1)
                .contentType(file.getContentType())
                .build()
        );
        
        return objectName;
    }
    
    // 下载文件
    public InputStream download(String objectName) throws Exception {
        return minioClient.getObject(
            GetObjectArgs.builder()
                .bucket(bucket)
                .object(objectName)
                .build()
        );
    }
    
    // 删除文件
    public void delete(String objectName) throws Exception {
        minioClient.removeObject(
            RemoveObjectArgs.builder()
                .bucket(bucket)
                .object(objectName)
                .build()
        );
    }
    
    // 获取预签名 URL（临时访问链接）
    public String getPresignedUrl(String objectName, int expiry) throws Exception {
        return minioClient.getPresignedObjectUrl(
            GetPresignedObjectUrlArgs.builder()
                .method(Method.GET)
                .bucket(bucket)
                .object(objectName)
                .expiry(expiry, TimeUnit.SECONDS)
                .build()
        );
    }
}

八、Docker 方式部署

1. 单机运行

docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  -v /data/minio:/data \
  minio/minio server /data --console-address ":9001"

2. Docker Compose

# docker-compose.yml
version: '3.8'

services:
  minio:
    image: minio/minio:latest
    container_name: minio
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - ./data:/data
    command: server /data --console-address ":9001"
    restart: always
# 启动
docker compose up -d

# 停止
docker compose down

九、常见问题

1. 默认凭证无法登录

# 检查凭证
mc admin info local

# 重新配置别名
mc alias remove local
mc alias set local http://localhost:9000 minioadmin minioadmin

2. 端口被占用

# 查看端口占用
lsof -i :9000

# 修改端口（编辑 plist）
brew services stop minio
# 编辑 ~/Library/LaunchAgents/homebrew.mxcl.minio.plist
brew services start minio

3. 数据目录权限

# 检查权限
ls -la /opt/homebrew/var/minio

# 修复权限
sudo chown -R $(whoami) /opt/homebrew/var/minio

4. 日志查看

# brew 服务日志
brew services logs minio

# 查看最近 100 行
brew services logs minio --tail=100

十、性能优化

1. 擦除码设置

# 默认擦除码
export MINIO_ERASURE_SET_DRIVE_COUNT=4

2. 缓存配置

export MINIO_CACHE_DRIVES="/data1/cache,/data2/cache"
export MINIO_CACHE_EXCLUDE="*.pdf,*.zip"
export MINIO_CACHE_AFTER=3
export MINIO_CACHE_WATERMARK_LOW=75
export MINIO_CACHE_WATERMARK_HIGH=90

3. 压缩配置

export MINIO_COMPRESS_MIME_TYPES="application/json,text/xml,text/plain"
export MINIO_COMPRESS_EXTENSIONS=".xml,.json,.txt"

十一、监控与健康检查

1. 健康检查

# 存活检查
curl http://localhost:9000/minio/health/live

# 就绪检查
curl http://localhost:9000/minio/health/ready

# 集群健康
curl http://localhost:9000/minio/health/cluster

2. 指标监控

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

# 节点指标
curl http://localhost:9000/minio/v2/metrics/node

⚠️ 安全提示： 1. 生产环境务必修改默认凭证 2. 使用 HTTPS（配置 TLS 证书） 3. 定期备份数据目录 4. 限制网络访问（防火墙/安全组） 5. 启用审计日志