Docker 安装 MinIO 完整教程(新手友好版)

✅ 亲测可用 | 官方渠道 | 从零开始 | 部署即能用

一、MinIO 是什么？

MinIO 是一款高性能、分布式的对象存储系统，完全兼容 Amazon S3 API。简单来说，它就是你自己私有的"云盘"，可以存图片、视频、文档、备份等任何文件，通过 API 或网页界面管理。

核心特点

典型应用场景

• 📦 文件存储服务（替代 FTP / 本地文件服务器）

• 🖼️ 图片/视频等多媒体存储

• 💽 数据备份与归档

• 🧠 智能知识库系统（存原始文档）

• 🌐 私有云替代公有云 S3

二、环境准备

1. 系统要求

• Windows / macOS / Linux 均可

• 已安装 Docker 和 Docker Compose

• 至少 1GB 可用内存

• 至少 1GB 可用磁盘空间

2. 确认 Docker 已安装

打开终端（CMD / PowerShell / Terminal），输入：

docker --versiondocker-compose --version

如果能看到版本号，说明 Docker 已经装好。

💡 还没装 Docker？Windows/Mac：直接下载 Docker Desktop 安装即可Linux：参考官方文档安装 Docker Engine

三、方式一：docker run 一键安装（最快）

适合快速体验、开发测试用。

执行命令

复制下面的命令，直接粘贴到终端执行：

docker run -d \--name minio \-p9000:9000 \-p9001:9001 \-e"MINIO_ROOT_USER=minioadmin" \-e"MINIO_ROOT_PASSWORD=minioadmin123" \-v minio_data:/data \--restart=always \  minio/minio:latest \  server /data --console-address":9001"

⚠️ 注意：命令中的 \ 是换行符，Windows 的 CMD 里要换成 ^，PowerShell 里用 `（反引号）。

Windows PowerShell 版本：

dockerrun-d`--nameminio`-p9000:9000`-p9001:9001`-e"MINIO_ROOT_USER=minioadmin"`-e"MINIO_ROOT_PASSWORD=minioadmin123"`-vminio_data:/data`--restart=always`minio/minio:latest`server/data--console-address":9001"

参数说明

四、方式二：docker-compose 安装（推荐）

适合长期使用、和其他服务统一管理。

第 1 步：创建 docker-compose.yml

新建一个文件夹，比如 minio，在里面创建文件 docker-compose.yml，内容如下：

version: '3.8'services:  minio:    image: minio/minio:latest    container_name: minio    restart: always    ports:      - "9000:9000"# API 端口      - "9001:9001"# 控制台端口    environment:      MINIO_ROOT_USER: minioadmin      MINIO_ROOT_PASSWORD: minioadmin123      MINIO_REGION_NAME: cn-north-1    command: server /data --console-address ":9001"    volumes:      - minio_data:/data    healthcheck:      test: ["CMD","curl","-f","http://localhost:9000/minio/health/live"]      interval: 30s      timeout: 20s      retries: 3volumes:  minio_data:

第 2 步：启动

在 docker-compose.yml 所在目录打开终端，执行：

docker-compose up -d

第 3 步：查看状态

docker-compose ps

看到 State 是 Up 就说明启动成功了。

五、验证安装

1. 查看容器状态

docker ps | grep minio

正常输出类似：

CONTAINER ID   IMAGE            STATUS         PORTS7c75dbdf0107   minio/minio:latest  Up 2 minutes  0.0.0.0:9000-9001->9000-9001/tcp

2. 查看启动日志

docker logs minio

看到类似下面的输出，说明启动成功：

Status:         1 Online, 0 Offline.API: http://172.17.0.2:9000  http://127.0.0.1:9000Console: http://172.17.0.2:9001 http://127.0.0.1:9001

3. 浏览器访问控制台

打开浏览器，访问：

http://localhost:9001

如果是远程服务器，把 localhost 换成服务器 IP 地址。

登录页面，输入：

• 用户名：minioadmin

• 密码：minioadmin123

登录成功后，你会看到 MinIO 的管理控制台！

六、控制台基础操作

1. 创建存储桶（Bucket）

Bucket 就相当于"文件夹"，用来分类存放文件。

1. 左侧菜单点击 Buckets

2. 点击右上角 Create Bucket

3. 输入 Bucket 名称，比如 my-files

4. 点击 Create Bucket

💡 Bucket 命名规则：只能用小写字母、数字、横线（-）和点（.），不能有大写字母和空格。

2. 上传文件

1. 左侧菜单点击 Object Browser

2. 点击你刚创建的 bucket

3. 点击右上角 Upload

4. 选择文件上传

5. 上传完成后，文件列表里就能看到了

3. 下载/预览/删除文件

1. 点击文件列表里的文件

2. 右侧会出现操作菜单：

• Download：下载文件

• Share：生成分享链接（可设置过期时间）

• Preview：预览文件（图片、PDF 等支持预览）

• Delete：删除文件

4. 创建子目录

1. 进入 bucket

2. 点击 Create new path

3. 输入目录名，确认

七、常用配置说明

修改管理员账号密码

修改 docker-compose.yml 里的环境变量：

environment:  MINIO_ROOT_USER: your_username    # 改成你的账号  MINIO_ROOT_PASSWORD: your_password # 改成你的密码（至少8位）

然后重启：

docker-compose restart

修改端口

如果 9000 或 9001 端口被占用了，可以改：

ports:  - "9002:9000"   # 左边是宿主机端口，可以改  - "9003:9001"   # 左边是宿主机端口，可以改

左边是你电脑上的端口，右边是容器内部的端口（不要改右边）。

限制内存使用

deploy:  resources:    limits:      memory: 2G

开启 HTTPS（生产环境建议）

1. 准备好 SSL 证书（public.crt 和 private.key）

2. 把证书放到宿主机某个目录，比如 ./certs

3. 修改 docker-compose.yml：

volumes:  - minio_data:/data  - ./certs:/root/.minio/certs

八、数据持久化说明

数据存在哪？

你用的是 -v minio_data:/data，这是 Docker 的命名卷（Named Volume），数据由 Docker 管理，安全可靠。

特点：

• ✅ 重启电脑 → 数据不丢

• ✅ 删除容器 → 数据不丢

• ✅ 升级 MinIO → 数据不丢

• ✅ 容器崩溃 → 数据不丢

查看数据卷

docker volume ls | grep minio

查看数据实际位置

docker volume inspect minio_data

输出里的 Mountpoint 就是数据实际存放路径。

备份数据

方法一：整卷备份（推荐）

# 备份docker run --rm -v minio_data:/data -v $(pwd):/backup alpine tar czf /backup/minio_backup.tar.gz -C /data .# 恢复docker run --rm -v minio_data:/data -v $(pwd):/backup alpine tar xzf /backup/minio_backup.tar.gz -C /data

方法二：用 mc 客户端同步

mc mirror myminio/my-bucket ./backup/

九、常见问题 FAQ

Q1：启动报错 invalid reference format？

原因：命令格式有问题，比如注释写在了续行符 \ 后面。

解决：用上面给的干净命令，不要在中间加注释。

Q2：浏览器访问不了控制台？

排查步骤：

1. 确认容器在运行：docker ps | grep minio

2. 确认端口映射：看 PORTS 列有没有 9001

3. 确认防火墙有没有开放 9001 端口

4. 试试 http://127.0.0.1:9001

Q3：重启电脑后 MinIO 不见了？

原因：没加 --restart=always

解决：重新创建容器时加上 --restart=always 参数，或者 docker-compose 里加 restart: always。

Q4：数据会丢吗？

不会！ 只要你用了 -v minio_data:/data 数据卷，数据就存在宿主机上，容器删了都不丢。

Q5：怎么升级 MinIO？

# 1. 拉取最新镜像docker pull minio/minio:latest# 2. 停止并删除旧容器docker stop miniodocker rm minio# 3. 用新镜像重新启动（用同样的命令）docker run -d ... minio/minio:latest ...

💡 数据存在卷里，删除容器不影响数据，放心升级。

Q6：Windows 上 Docker 数据存在哪？

Windows 上 Docker Desktop 用的是 WSL2 后端，数据存在 WSL 虚拟磁盘里。

在文件资源管理器地址栏输入：

\\wsl$\docker-desktop-data\data\docker\volumes\minio_data\_data

就能看到 MinIO 的数据文件了。

十、mc 命令行工具（可选）

如果你喜欢用命令行操作，可以用 MinIO 官方客户端 mc。

安装

# Docker 方式运行（不用安装）docker run --rm --entrypoint="" minio/mc --version

配置连接

docker run --rm --entrypoint="" minio/mc \  mc alias set myminio http://host.docker.internal:9000 minioadmin minioadmin123

常用命令

# 列出所有 bucketdocker run --rm --entrypoint="" minio/mc mc ls myminio# 创建 bucketdocker run --rm --entrypoint="" minio/mc mc mb myminio/my-bucket# 上传文件docker run --rm --entrypoint="" -v /本地路径:/data minio/mc mc cp /data/test.txt myminio/my-bucket/# 下载文件docker run --rm --entrypoint="" -v /本地路径:/data minio/mc mc cp myminio/my-bucket/test.txt /data/# 删除文件docker run --rm --entrypoint="" minio/mc mc rm myminio/my-bucket/test.txt

十一、下一步

MinIO 已经装好了，你可以：

1. 当私有云盘用：直接在控制台上传下载文件

2. 集成到项目里：用 Java/Python/Go 等 SDK 调用 API

3. 搭建智能知识库：配合 pgvector + 大模型做 RAG 系统

4. 做数据备份：把重要文件同步到 MinIO 备份

附录：完整命令速查

# 启动docker-compose up -d# 停止docker-compose stop# 重启docker-compose restart# 查看状态docker-compose ps# 查看日志docker-compose logs -f# 删除容器（数据不丢）docker-compose down# 删除容器和数据（⚠️ 慎用！数据会全没）docker-compose down -v

🎉 恭喜你！ 看到这里，你已经成功部署了自己的 MinIO 对象存储服务！

如果有问题，随时查阅上面的 FAQ，或者去 MinIO 官方文档 查找更多信息。