面向 Java 程序员的 MinIO 入门教程

2026-04-21 11:09

面向 Java 程序员的 MinIO 入门教程

1. 引言

MinIO 是一个高性能、兼容 Amazon S3 的对象存储服务。它专为私有云架构而设计，可以轻松部署在各种环境中，包括本地数据中心、Kubernetes 集群或公共云。对于 Java 开发者而言，MinIO 提供了一个功能丰富的 Java SDK，使得在 Java 应用程序中集成对象存储功能变得简单高效。本文将详细介绍如何搭建 MinIO 服务，并在 Java 项目中集成和使用 MinIO Java SDK 进行桶和对象的管理。

2. MinIO 搭建

MinIO 的部署方式多样，包括 Docker、Kubernetes、二进制安装等。对于初学者和开发环境，使用 Docker 是最快捷方便的方式。

2.1 使用 Docker 命令行部署

对于简单的测试环境，可以使用 docker run 命令快速启动：

bash

复制代码

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

2.2 使用 Docker Compose 部署 (推荐)

在生产或复杂的开发环境中，推荐使用 Docker Compose 来管理 MinIO 服务。它可以方便地配置持久化存储、网络和环境变量。

创建一个名为 docker-compose.yml 的文件，内容如下：

yaml

复制代码

version: '3.7'

services:
  minio:
    image: quay.io/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"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

配置说明：

image: 使用 quay.io/minio/minio 镜像，这是官方推荐的镜像源。
ports: 映射 9000 (API) 和 9001 (Console) 端口。
volumes: 将当前目录下的 data 文件夹挂载到容器内的 /data，实现数据持久化。
healthcheck: 配置健康检查，确保服务正常运行。

启动服务：
在 docker-compose.yml 所在目录下运行：

bash

复制代码

docker-compose up -d

成功运行后，您可以通过浏览器访问 http://localhost:9001，使用 minioadmin / minioadmin 登录 MinIO Console UI。

3. Java 项目集成

在 Java 项目中使用 MinIO，需要引入 MinIO Java SDK 的 Maven 或 Gradle 依赖。

3.1 Maven 依赖

在您的 pom.xml 文件中添加以下依赖：

xml

复制代码

<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.7</version> <!-- 请检查并使用最新稳定版本 -->
</dependency>

注意：请访问 MinIO Java SDK GitHub Releases 或 Maven Central 仓库，获取最新的稳定版本号。

4. MinIO Java SDK 使用

MinIO Java SDK 提供了丰富的 API 来操作桶（Bucket）和对象（Object）。

4.1 客户端初始化

所有 MinIO 操作都始于 MinioClient 实例的创建。您需要提供 MinIO 服务的地址、访问密钥（Access Key）和秘密密钥（Secret Key）。

java

复制代码

import io.minio.MinioClient;
import io.minio.errors.MinioException;
import java.io.IOException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

public class MinioClientExample {

    public static void main(String[] args) throws IOException, NoSuchAlgorithmException, InvalidKeyException, MinioException {
        // 使用 MinIO 服务的 URL、Access Key 和 Secret Key 初始化 MinioClient 对象
        MinioClient minioClient = MinioClient.builder()
                .endpoint("http://127.0.0.1:9000") // MinIO 服务地址，如果是 Docker 部署，通常是 localhost:9000
                .credentials("minioadmin", "minioadmin") // 登录 MinIO Console UI 的 Access Key 和 Secret Key
                .build();

        System.out.println("MinioClient 初始化成功！");
        // 后续操作将在这里进行
    }
}

4.2 桶操作 (Bucket Operations)

4.2.1 检查桶是否存在

在创建或操作桶之前，通常需要检查桶是否已存在。

java

复制代码

import io.minio.BucketExistsArgs;
// ... (其他导入)

        String bucketName = "my-test-bucket";
        boolean found = minioClient.bucketExists(BucketExistsArgs.builder().bucket(bucketName).build());
        if (found) {
            System.out.println("桶 '" + bucketName + "' 已经存在。");
        } else {
            System.out.println("桶 '" + bucketName + "' 不存在。");
        }

4.2.2 创建桶

如果桶不存在，可以创建它。

java

复制代码

import io.minio.MakeBucketArgs;
// ... (其他导入)

        if (!found) {
            minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucketName).build());
            System.out.println("桶 '" + bucketName + "' 创建成功。");
        }

4.2.3 列出所有桶

java

复制代码

import io.minio.ListBucketsArgs;
import io.minio.messages.Bucket;
import java.util.List;
// ... (其他导入)

        List<Bucket> bucketList = minioClient.listBuckets(ListBucketsArgs.builder().build());
        System.out.println("所有桶列表：");
        for (Bucket bucket : bucketList) {
            System.out.println("  " + bucket.name() + " (创建日期: " + bucket.creationDate() + ")");
        }

4.2.4 删除桶

删除桶前请确保桶内没有对象，否则会删除失败。

java

复制代码

import io.minio.RemoveBucketArgs;
// ... (其他导入)

        // 假设桶内没有对象，或者您已经清空了桶
        // minioClient.removeBucket(RemoveBucketArgs.builder().bucket(bucketName).build());
        // System.out.println("桶 '" + bucketName + "' 删除成功。");

4.3 对象操作 (Object Operations)

4.3.1 上传对象

上传文件到 MinIO 桶中。这里以上传一个字符串作为文件内容为例。

java

复制代码

import io.minio.PutObjectArgs;
import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
// ... (其他导入)

        String objectName = "my-object.txt";
        String content = "Hello, MinIO! This is a test file.";
        InputStream inputStream = new ByteArrayInputStream(content.getBytes(StandardCharsets.UTF_8));
        long contentLength = content.length();

        minioClient.putObject(
                PutObjectArgs.builder()
                        .bucket(bucketName)
                        .object(objectName)
                        .stream(inputStream, contentLength, -1) // -1 表示文件大小未知，SDK 会自动处理
                        .contentType("text/plain") // 设置文件类型
                        .build());
        System.out.println("对象 '" + objectName + "' 上传成功到桶 '" + bucketName + "'。");

4.3.2 下载对象

从 MinIO 桶中下载对象。

java

复制代码

import io.minio.GetObjectArgs;
import java.io.FileOutputStream;
// ... (其他导入)

        String downloadedObjectName = "downloaded-object.txt";
        try (InputStream stream = minioClient.getObject(
                GetObjectArgs.builder()
                        .bucket(bucketName)
                        .object(objectName)
                        .build());
             FileOutputStream fos = new FileOutputStream(downloadedObjectName)) {

            byte[] buffer = new byte[1024];
            int bytesRead;
            while ((bytesRead = stream.read(buffer)) != -1) {
                fos.write(buffer, 0, bytesRead);
            }
            System.out.println("对象 '" + objectName + "' 从桶 '" + bucketName + "' 下载成功，保存为 '" + downloadedObjectName + "'。");
        } catch (IOException e) {
            System.err.println("下载对象失败: " + e.getMessage());
        }

4.3.3 删除对象

从 MinIO 桶中删除对象。

java

复制代码

import io.minio.RemoveObjectArgs;
// ... (其他导入)

        minioClient.removeObject(
                RemoveObjectArgs.builder()
                        .bucket(bucketName)
                        .object(objectName)
                        .build());
        System.out.println("对象 '" + objectName + "' 从桶 '" + bucketName + "' 删除成功。");

5. 完整示例代码

以下是一个完整的 Java 示例，演示了 MinIO 客户端的初始化、桶的创建、对象的上传、下载和删除。

java

复制代码

import io.minio.BucketExistsArgs;
import io.minio.GetObjectArgs;
import io.minio.ListBucketsArgs;
import io.minio.MakeBucketArgs;
import io.minio.MinioClient;
import io.minio.PutObjectArgs;
import io.minio.RemoveBucketArgs;
import io.minio.RemoveObjectArgs;
import io.minio.errors.MinioException;
import io.minio.messages.Bucket;

import java.io.ByteArrayInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.List;

public class MinioJavaExample {

    private static final String MINIO_ENDPOINT = "http://127.0.0.1:9000";
    private static final String MINIO_ACCESS_KEY = "minioadmin";
    private static final String MINIO_SECRET_KEY = "minioadmin";
    private static final String BUCKET_NAME = "my-java-bucket";
    private static final String OBJECT_NAME = "my-first-object.txt";
    private static final String LOCAL_DOWNLOAD_PATH = "downloaded-my-first-object.txt";

    public static void main(String[] args) {
        try {
            // 1. 初始化 MinioClient
            MinioClient minioClient = MinioClient.builder()
                    .endpoint(MINIO_ENDPOINT)
                    .credentials(MINIO_ACCESS_KEY, MINIO_SECRET_KEY)
                    .build();
            System.out.println("MinioClient 初始化成功！");

            // 2. 检查并创建桶
            boolean found = minioClient.bucketExists(BucketExistsArgs.builder().bucket(BUCKET_NAME).build());
            if (!found) {
                minioClient.makeBucket(MakeBucketArgs.builder().bucket(BUCKET_NAME).build());
                System.out.println("桶 '" + BUCKET_NAME + "' 创建成功。");
            } else {
                System.out.println("桶 '" + BUCKET_NAME + "' 已经存在。");
            }

            // 3. 列出所有桶
            System.out.println("\n所有桶列表：");
            List<Bucket> bucketList = minioClient.listBuckets(ListBucketsArgs.builder().build());
            for (Bucket bucket : bucketList) {
                System.out.println("  " + bucket.name() + " (创建日期: " + bucket.creationDate() + ")");
            }

            // 4. 上传对象
            String content = "Hello from Java MinIO SDK! This is my first object content.";
            InputStream inputStream = new ByteArrayInputStream(content.getBytes(StandardCharsets.UTF_8));
            long contentLength = content.length();

            minioClient.putObject(
                    PutObjectArgs.builder()
                            .bucket(BUCKET_NAME)
                            .object(OBJECT_NAME)
                            .stream(inputStream, contentLength, -1)
                            .contentType("text/plain")
                            .build());
            System.out.println("\n对象 '" + OBJECT_NAME + "' 上传成功到桶 '" + BUCKET_NAME + "'。");

            // 5. 下载对象
            System.out.println("\n开始下载对象 '" + OBJECT_NAME + "'...");
            try (InputStream stream = minioClient.getObject(
                    GetObjectArgs.builder()
                            .bucket(BUCKET_NAME)
                            .object(OBJECT_NAME)
                            .build());
                 FileOutputStream fos = new FileOutputStream(LOCAL_DOWNLOAD_PATH)) {

                byte[] buffer = new byte[1024];
                int bytesRead;
                while ((bytesRead = stream.read(buffer)) != -1) {
                    fos.write(buffer, 0, bytesRead);
                }
                System.out.println("对象 '" + OBJECT_NAME + "' 下载成功，保存为 '" + LOCAL_DOWNLOAD_PATH + "'。");
            } catch (IOException e) {
                System.err.println("下载对象失败: " + e.getMessage());
            }

            // 6. 删除对象
            minioClient.removeObject(
                    RemoveObjectArgs.builder()
                            .bucket(BUCKET_NAME)
                            .object(OBJECT_NAME)
                            .build());
            System.out.println("\n对象 '" + OBJECT_NAME + "' 从桶 '" + BUCKET_NAME + "' 删除成功。");

            // 7. (可选) 删除桶 - 确保桶内无对象
            // 如果需要删除桶，请确保桶内所有对象都已删除
            // minioClient.removeBucket(RemoveBucketArgs.builder().bucket(BUCKET_NAME).build());
            // System.out.println("桶 '" + BUCKET_NAME + "' 删除成功。");

        } catch (MinioException e) {
            System.err.println("MinIO 操作异常: " + e.getMessage());
            System.err.println("HTTP Status Code: " + e.response().code());
            System.err.println("Error Response: " + e.response().body().string());
        } catch (IOException e) {
            System.err.println("I/O 异常: " + e.getMessage());
        } catch (NoSuchAlgorithmException e) {
            System.err.println("加密算法异常: " + e.getMessage());
        } catch (InvalidKeyException e) {
            System.err.println("无效密钥异常: " + e.getMessage());
        }
    }
}