自建对象存储不求人：MinIO Docker 部署完整教程（附踩坑记录）

Apache王也道长
0 阅读3分钟

MinIO 是一款高性能的开源对象存储服务，API 完全兼容 AWS S3，可以理解为自建版的阿里云 OSS。本文带你用 Docker Compose 快速搭建，10 分钟跑起来。

为什么选 MinIO？

做项目经常需要存储图片、文件、视频，常见方案对比：

方案费用数据控制适合场景
阿里云 OSS按量付费，~0.12元/GB/月数据在云上生产环境，流量大
腾讯云 COS按量付费，~0.099元/GB/月数据在云上生产环境
MinIO 自建服务器成本，存储近乎免费数据完全自控自建、开发测试、私有化部署

MinIO 最大的优势是 S3 兼容——只要代码里用的是 AWS S3 SDK，切换到 MinIO 几乎不需要改代码，直接换个 endpoint 就行。

环境准备

服务器需要安装：

# 检查 docker
docker --version

# 检查 docker compose
docker compose version

推荐系统：Ubuntu 20.04 / 22.04，内存 2G 以上。

编写 docker-compose.yaml

新建工作目录：

mkdir minio && cd minio
vim docker-compose.yaml

写入以下内容：

services:
  minio:
    container_name: minio
    image: quay.io/minio/minio:RELEASE.2024-09-22T00-33-43Z
    command: server /data --console-address ":9001"
    environment:
      # 管理员账号，生产环境务必修改
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      # 数据持久化目录
      - "./data:/data"
    ports:
      # API 端口（SDK 访问用）
      - "9000:9000"
      # Web 控制台端口
      - "9001:9001"
    restart: always
    extra_hosts:
      - "svc175:192.168.0.175"

端口说明

MinIO 启动后会监听两个端口，容易混淆：

  • 9000：S3 API 端口，Java/Python 等 SDK 上传下载文件走这个端口
  • 9001：Web 控制台端口，浏览器访问管理界面走这个端口

启动服务

docker compose up -d

查看启动日志确认是否正常：

docker compose logs -f minio

正常启动会看到：

minio  | MinIO Object Storage Server
minio  | Copyright: 2015-2024 MinIO, Inc.
minio  | API: http://0.0.0.0:9000
minio  | WebUI: http://0.0.0.0:9001
minio  | Documentation: https://min.io/docs/minio/linux/index.html

访问 Web 控制台

浏览器打开：

http://你的服务器IP:9001

使用配置的账号密码登录（默认 minioadmin / minioadmin）。

登录后可以：

  • 创建 Bucket（存储桶）
  • 上传、下载、删除文件
  • 生成文件访问链接
  • 管理访问权限和策略

Java SDK 接入示例

MinIO 完全兼容 S3 API，Java 项目引入 MinIO SDK：

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

初始化客户端：

MinioClient minioClient = MinioClient.builder()
    .endpoint("http://192.168.0.175:9000")  // API 端口
    .credentials("minioadmin", "minioadmin")
    .build();

上传文件：

minioClient.uploadObject(
    UploadObjectArgs.builder()
        .bucket("my-bucket")
        .object("test.jpg")
        .filename("/tmp/test.jpg")
        .build()
);

获取文件访问链接（有效期 1 小时）：

String url = minioClient.getPresignedObjectUrl(
    GetPresignedObjectUrlArgs.builder()
        .method(Method.GET)
        .bucket("my-bucket")
        .object("test.jpg")
        .expiry(1, TimeUnit.HOURS)
        .build()
);

常见问题

Q：上传文件报错 InvalidEndpointException？

检查 endpoint 是否用的 9000 端口（API 端口），不是 9001（控制台端口）。

Q：文件上传成功但外网无法访问？

默认 Bucket 是私有的，需要在控制台把 Bucket 的访问策略改为 public，或者用 SDK 生成预签名 URL。

Q：重启容器后数据丢失？

检查 ./data 目录是否存在，以及 docker-compose.yaml 中的 volumes 挂载是否正确。

Q：生产环境怎么配置？

生产环境建议：

  1. 修改 MINIO_ROOT_USER 和 MINIO_ROOT_PASSWORD 为强密码
  2. 配置 Nginx 反向代理，加上 HTTPS
  3. 把数据目录挂载到单独的磁盘分区

与阿里云 OSS 无缝切换

如果你的代码原来用的是阿里云 OSS SDK，迁移到 MinIO 需要改动的地方很少。

以 Spring Boot 为例，只需要修改配置：

# 原来的 OSS 配置
cloud:
  oss:
    endpoint: https://oss-cn-hangzhou.aliyuncs.com
    access-key-id: your-access-key
    access-key-secret: your-secret

# 改成 MinIO
minio:
  endpoint: http://192.168.0.175:9000
  access-key: minioadmin
  secret-key: minioadmin

代码逻辑几乎不用动，因为操作 API 完全一致。

总结

项目说明
镜像quay.io/minio/minio
API 端口9000
控制台端口9001
默认账号minioadmin / minioadmin
数据目录./data
S3 兼容完全兼容，SDK 无缝切换

MinIO 非常适合在内网或开发环境替代云存储，配合 Docker 部署维护成本极低。如果你的项目有文件存储需求，值得一试。

后续我会出 MinIO 数据迁移教程，把老服务器的数据迁移到新服务器，感兴趣的可以关注。

本文同步发布于个人博客，持续更新 Java / 后端 / Docker 实战内容：

👉 blog.123571.xyz

avatar
文章
阅读
粉丝