在 Ubuntu 上安装并 Java 调用 MinIO 的完整踩坑记录

环境：Ubuntu 22.04 LTS + JDK 8 + Maven 3.9 + MinIO RELEASE.2024-xx

1. 背景

本文记录从零开始在 Ubuntu 上安装 MinIO，并用纯 Java 8（无 Spring）完成文件上传、下载、删除的完整流程，同时给出端口、凭据脱敏的最佳实践。

2. 安装与启动 MinIO

# 下载并赋权
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio

# 启动（关键参数已脱敏）
./minio server /data \
  --address    ":<API_PORT>" \
  --console-address ":<CONSOLE_PORT>"

把 <API_PORT> 与 <CONSOLE_PORT> 换成真实端口，例如 9000、9001。

3. 防火墙 & 安全组

sudo ufw allow <API_PORT>/tcp
sudo ufw allow <CONSOLE_PORT>/tcp

云主机还需在安全组入方向放行同样端口。

4. 创建 Bucket

浏览器访问

http://<服务器IP>:<CONSOLE_PORT>

使用脱敏后的凭据登录：

• Access Key = <ACCESS_KEY>
• Secret Key = <SECRET_KEY>

手动创建 bucket，命名为 files（可自定义）。

5. Java 最小可运行示例

5.1 依赖（已脱敏）

<dependencies>
  <!-- MinIO SDK -->
  <dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.7</version>
  </dependency>
  <!-- 强制升级 OkHttp，避免低版本冲突 -->
  <dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
  </dependency>
</dependencies>

5.2 单文件示例 MinioQuickStart.java

package demo;

import io.minio.*;
import java.io.*;

public class MinioQuickStart {
    // 脱敏变量，请替换为真实值
    private static final String ENDPOINT   = "http://127.0.0.1:<API_PORT>";
    private static final String ACCESS_KEY = "<ACCESS_KEY>";
    private static final String SECRET_KEY = "<SECRET_KEY>";
    private static final String BUCKET     = "files";

    private static final MinioClient client = MinioClient.builder()
            .endpoint(ENDPOINT)
            .credentials(ACCESS_KEY, SECRET_KEY)
            .build();

    public static void main(String[] args) throws Exception {
        ensureBucket();
        upload("demo.txt", "Hello MinIO".getBytes("UTF-8"));
        download("demo.txt");
        remove("demo.txt");
    }

    private static void ensureBucket() throws Exception {
        boolean exists = client.bucketExists(
                BucketExistsArgs.builder().bucket(BUCKET).build());
        if (!exists) {
            client.makeBucket(MakeBucketArgs.builder().bucket(BUCKET).build());
            System.out.println("Bucket created: " + BUCKET);
        }
    }

    private static void upload(String objectName, byte[] data) throws Exception {
        client.putObject(
            PutObjectArgs.builder()
                .bucket(BUCKET)
                .object(objectName)
                .stream(new ByteArrayInputStream(data), data.length, -1)
                .contentType("text/plain")
                .build());
        System.out.println("Uploaded: " + objectName);
    }

    private static void download(String objectName) throws Exception {
        try (InputStream in = client.getObject(
                GetObjectArgs.builder().bucket(BUCKET).object(objectName).build());
             ByteArrayOutputStream out = new ByteArrayOutputStream()) {

            byte[] buf = new byte[8192];
            int len;
            while ((len = in.read(buf)) != -1) out.write(buf, 0, len);
            System.out.println("Downloaded content: " + out.toString("UTF-8"));
        }
    }

    private static void remove(String objectName) throws Exception {
        client.removeObject(
            RemoveObjectArgs.builder().bucket(BUCKET).object(objectName).build());
        System.out.println("Deleted: " + objectName);
    }
}

5.3 编译 & 运行

mvn package
java -cp target/<your-jar>.jar demo.MinioQuickStart

输出示例：

Bucket created: files
Uploaded: demo.txt
Downloaded content: Hello MinIO
Deleted: demo.txt

6. 常见错误速查表

7. 总结

1. 替换占位符即可零配置迁移到生产。
2. 纯 Java 8 项目也能愉快使用 MinIO，无需 Spring。
3. 端口 & 密码脱敏让示例可公开分享，避免泄漏真实凭证。

祝你编码顺利，存储安心！