MinIO Docker：S3 兼容对象存储的搭建指南

您是否需要用于开发的对象存储，但又不想配置并为 AWS S3 付费？

MinIO 为您提供可在任意环境运行的 S3 兼容存储——无论是笔记本电脑、虚拟机，还是 Kubernetes 集群。它是开源的，意味着与厂商无关，月底也不会有意外账单。结合 Docker，运行 MinIO 更加轻松，您无需在本机直接安装任何东西，就能在几秒钟内启动一个存储服务。

Docker 容器让 MinIO 与系统隔离的同时，仍为您提供对配置与数据持久化的完全控制。您可以在本地测试 S3 API、模拟生产存储环境，或为小型项目运行轻量级对象存储。

本文将演示如何通过 Docker 运行 MinIO，验证其是否正常工作，并配置最常见的设置选项。

如果您完全不熟悉 Docker，周末抽个下午掌握基础知识即可——DataCamp 的 Introduction to Docker 课程可以帮助您入门。

前置条件

使用 Docker 运行 MinIO 您需要准备三样东西。

已安装并正在运行的 Docker。您可以在终端中运行 docker --version 进行验证。如果返回了版本号，就没问题。

对 Docker 命令的基本了解。您应当知道如何启动与停止容器、查看日志以及管理镜像。如果您用过 docker run 或 Docker Compose，就足够了。

用于持久化存储的本地目录。MinIO 需要将数据存放在容器之外。请在主机上创建一个空目录——~/minio/data 这样的路径很合适。

就这些。清单很短也很简单，但在继续之前请确保全部满足。

如何使用 Docker 运行 MinIO（单节点部署）

单节点 MinIO 会在一个 Docker 容器中运行一个 MinIO 实例，并将所有数据存储在同一位置。

该方式适用于开发、测试以及无需高可用或分布式存储的小规模生产工作负载。您可以获得完整的 S3 API 兼容性，而无需运行多节点的复杂性。

使用 Docker Run 运行 MinIO

docker run 命令可以在一行中启动已配置好的 MinIO 新容器。

基本命令如下：

docker run -p 9000:9000 -p 9001:9001 \
  --name minio \
  -v ~/minio/data:/data \
  -e "MINIO_ROOT_USER=admin" \
  -e "MINIO_ROOT_PASSWORD=password123" \
  quay.io/minio/minio server /data --console-address ":9001"技术支持

使用 docker run 运行 MinIO

下面逐一解释每个部分的作用。

• 9000 端口是 API 端点，您的应用会连接此端口以上传与下载文件。S3 兼容客户端会向该端口发送请求。

• 9001 端口提供用于管理桶、设置权限和监控存储的 Web 控制台。您将用它来验证 MinIO 是否正确运行。

• -v ~/minio/data:/data 标志将本地目录映射到容器的存储位置。MinIO 存储的一切都会写入主机的 ~/minio/data。即使您停止或删除容器，数据也会安全地保存在该目录中。

• 环境变量 用于设置访问凭据。MINIO_ROOT_USER 是管理员用户名，MINIO_ROOT_PASSWORD 是密码。您将使用这些凭据登录 Web 控制台并配置 API 访问。

• server /data 参数告诉 MinIO 以服务器模式运行并使用 /data 作为存储目录。--console-address ":9001" 指定 Web 控制台监听的端口。

还有另一种运行 MinIO 的方式，非常适合不喜欢冗长多行终端命令的您。

注意：自 2025 年 10 月起，MinIO 不再更新其 Docker Hub 和 Quay 镜像。本文代码仍适用于本地开发，但在生产环境中，请考虑使用仍在维护的替代方案，例如 Chainguard 的 MinIO 镜像（cgr.dev/chainguard/minio:latest）。

使用 Docker Compose 运行 MinIO

Docker Compose 允许您在一个 YAML 文件中定义 MinIO 的配置，而无需敲长命令。

这样配置具有可重复性并可纳入版本控制。您可以与团队分享该文件、提交到 git，并在每次重启时以完全相同的设置运行 MinIO。

创建一个 docker-compose.yml 文件：

services:
  minio:
    image: quay.io/minio/minio
    container_name: minio
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: password123
    volumes:
      - ./minio/data:/data
    command: server /data --console-address ":9001"技术支持

该结构与 docker run 命令相对应，但将所有内容组织到命名的分区中。端口、环境变量和卷各有自己的区块。

卷映射的工作方式相同——./minio/data:/data 会在当前文件夹下创建一个目录，并将其挂载到容器中。./ 表示相对于该 docker-compose.yml 文件所在位置。

现在您可以通过以下命令启动 MinIO：

docker-compose up -d技术支持

使用 docker compose 运行 MinIO

-d 标志会让容器在后台运行。您的终端不会被 MinIO 日志占用，关闭终端后容器也会继续运行。

使用以下命令停止：

docker-compose down技术支持

对于开发而言，Compose 更好，因为您可以在同一文件中添加健康检查、重启策略以及多个服务。如果稍后需要在 MinIO 旁边添加数据库或其他服务，只需在 services: 下再添加条目即可。

如何访问并验证 MinIO 正在运行

既然 MinIO 已经启动，您需要在使用其作为存储之前确认其是否正确运行。

有两种方式验证：通过 Web 控制台进行可视化确认，或使用 MinIO 客户端在命令行中验证。

使用 MinIO Web 控制台

打开浏览器并访问 http://localhost:9001。

您会看到一个要求输入凭据的登录页面：

MinIO Web 界面

您可以使用作为环境变量提供的凭据登录——在我的示例中是 admin/password123。

登录后，您将进入 MinIO 仪表盘。首页显示存储用量、桶数量和系统健康状况。左侧边栏提供创建桶、管理用户及查看指标的选项。

通过 MinIO Web 界面创建桶

创建一个测试桶来验证一切是否正常。在侧边栏点击 "Buckets"，然后点击 "Create Bucket"。给它起个名字，例如 test-bucket，再点击创建。如果该桶出现在列表中，说明 MinIO 正常运行且能够存储数据。

通过 MinIO Web 界面创建桶

使用 MinIO 客户端（mc）

MinIO 客户端是一个命令行工具，使用体验类似 AWS CLI，可与 MinIO 交互。

通过以下命令之一进行安装：

# macOS
brew install minio/stable/mc

# Linux
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/技术支持

现在运行下述命令，将客户端连接到本地 MinIO 实例：

mc alias set local http://localhost:9000 admin password123技术支持

这将创建一个名为 local 的别名，指向您的 MinIO 服务器。您现在可以针对它执行命令。

列出您的桶：

mc ls local技术支持

列出桶

如果您之前创建了测试桶，它会显示在输出中。无论输出为空还是显示了您的桶，说明 MinIO 正常工作。

现在可以将测试文件上传到该桶：

echo "test" > test.txt
mc cp test.txt local/test-bucket/技术支持

然后验证它是否存在：

mc ls local/test-bucket技术支持

如果您在输出中看到 test.txt，说明所有配置均已正确完成。

列出桶中的文件

如果出现问题，下面是一些快速排障建议：

• 使用 docker ps 检查容器是否正在运行。如果没有看到名为 minio 的容器，说明它没有启动或已崩溃。

• 通过 docker logs minio 查看日志。留意端口已被占用或数据目录权限问题等错误。

• 如果无法访问 Web 控制台，使用 docker port minio 检查端口是否被正确映射。应当看到 9000 和 9001 都已映射。

• 如果遇到数据目录的权限错误，运行 chmod -R 755 ~/minio/data 以修复访问问题。

持久化存储与数据卷

容器默认是易失性的——删除容器时，内部的一切都会消失。

MinIO 会存储对象、元数据和配置文件。如果您未正确设置持久化存储，那么在重启或删除容器的那一刻，所有数据都会丢失。

在 Docker 中使用本地卷

Docker 卷与绑定挂载可让您的数据安全保存在容器之外。

当您使用 -v ~/minio/data:/data 或在 Docker Compose 中映射卷时，MinIO 会将一切写入主机。容器读写的是 /data，但这些文件实际存放在主机的 ~/minio/data。

当您停止容器、删除容器，甚至删除镜像时——数据仍保存在 ~/minio/data。只需启动一个新的 MinIO 容器并指向同一目录，您所有的桶、对象和设置都会原样返回。

如果您不映射卷，MinIO 会使用容器的内部文件系统。一切在您停止容器之前看似正常，但当您重启时，MinIO 会从头开始——没有桶、没有对象、也没有配置。

我之前展示的 compose 示例会在 compose 文件所在位置创建一个 minio/data 文件夹：

MinIO 数据文件夹

常见存储错误

未使用卷运行 是最常见的错误。

您启动 MinIO、上传文件、创建桶，一切都很顺利。随后为更新或修改配置重启容器。结果所有数据都丢了，因为它们存储在容器内，而非主机上。

在向 MinIO 存入任何真实数据之前，务必检查您的 Docker 命令或 Compose 文件是否包含卷映射。

权限问题 发生在 Docker 无法写入您挂载的目录时。

容器内的 MinIO 进程以特定用户运行。如果该用户对主机目录没有写权限，MinIO 会在启动时崩溃，或在尝试写入对象时静默失败。

您可以通过确保数据目录可写来修复：

chmod -R 755 ~/minio/data技术支持

或者以与主机用户匹配的用户身份运行容器：

docker run --user $(id -u):$(id -g) ...技术支持

总之，一次性正确设置好卷，便无需担心数据丢失。

环境变量与基础配置

MinIO 在启动时从环境变量读取配置。

这意味着您无需编辑配置文件或重建容器即可更改 MinIO 行为。您可在 docker run 命令或 Docker Compose 文件中设置这些变量。

访问密钥与凭据

MinIO 需要两个用于认证的环境变量：MINIO_ROOT_USER 和 MINIO_ROOT_PASSWORD。

它们用于创建对 MinIO 拥有完全控制权的 root 管理员账户。root 用户可以创建桶、管理其他用户、设置策略，并访问所有已存储对象。

在 docker run 中这样设置：

-e "MINIO_ROOT_USER=admin" \
-e "MINIO_ROOT_PASSWORD=your-secure-password"技术支持

或在 Docker Compose 中：

environment:
  MINIO_ROOT_USER: admin
  MINIO_ROOT_PASSWORD: your-secure-password技术支持

不要在生产环境中使用默认凭据。本文示例为简化使用了 admin 与 password123，但在真实部署中这是极差的选择。

请选择至少 8 个字符的强密码。更好的是使用随机生成的凭据，并将其存放在密码管理器或机密管理系统中。

不要将凭据硬编码在被提交到版本控制的 Docker Compose 文件中。请改用环境文件：

environment:
  MINIO_ROOT_USER: ${MINIO_ROOT_USER}
  MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}技术支持

然后创建一个包含实际凭据的 .env 文件，并将其加入 .gitignore。

端口配置与网络

MinIO 需要两个端口才能正常工作。

• 9000 端口 处理 S3 API。应用会向此端口发送存取对象的请求。所有 S3 兼容客户端都连接该端口。
• 9001 端口 提供 Web 控制台。这是通过浏览器以 GUI 管理 MinIO 的界面。

在 Docker 命令中映射这些端口：

-p 9000:9000 -p 9001:9001技术支持

当主机上有其他服务已使用 9000 或 9001 端口时，会发生端口冲突。

启动容器时您会看到类似 "bind: address already in use" 的错误。可通过映射到其他主机端口来解决：

-p 9090:9000 -p 9091:9001技术支持

现在 MinIO 的 API 位于 http://localhost:9090，控制台位于 http://localhost:9091。容器内部仍使用 9000 和 9001，但外部访问通过不同的主机端口。

在启动 MinIO 前，可用以下命令检查哪些进程占用了端口：

# Linux/macOS
lsof -i :9000
lsof -i :9001

# Windows
netstat -ano | findstr :9000
netstat -ano | findstr :9001技术支持

检查端口占用

如果在同一台机器上运行多个 MinIO 实例，请为每个实例分配唯一的端口映射，避免冲突。

使用 Docker 运行分布式模式的 MinIO

分布式模式会在多台服务器和多块磁盘上运行 MinIO，以实现高可用与数据冗余。

开发或测试并不需要这样做。单节点模式几乎能满足大多数用例。除非您计划在生产环境部署、且需要在服务器故障时保持在线，否则可跳过本节。

何时需要分布式 MinIO

当您需要容错能力时，请使用分布式模式。

在分布式部署中，即使某台服务器宕机，MinIO 仍能继续运行，且您的数据可访问。系统通过纠删码将对象拆分到多块磁盘和多台服务器上，即使丢失磁盘或节点，数据也不会丢失。

对于大规模存储也需要分布式模式。如果您需要存储 TB 级或 PB 级的数据，将其分散到多台机器上可获得更好的性能与容量，超出单台服务器所能提供的上限。

本地开发不需要这些。分布式模式会带来复杂性——您需要多台机器或虚拟机、协调网络以及谨慎的磁盘配置。若只是测试 S3 API 或在笔记本上运行对象存储，单节点模式已足够。

在生产环境中，当无法接受停机且数据丢失将造成严重后果时（如备份系统、数据湖或需要持续存储可用性的应用），才会使用分布式模式。

高层次搭建概览

分布式 MinIO 至少需要跨多个节点的四块磁盘。

每个节点都运行一个 MinIO 容器，且所有节点必须具有相同的磁盘配置。您不能将单盘节点与多盘节点混用，或在搭建后更改磁盘数量。

一个基础的分布式部署如下：

• 四台服务器（或虚拟机），均已安装 MinIO
• 每台服务器上有多块专用于 MinIO 的磁盘
• 各节点之间的网络互通
• 每个节点上的磁盘路径一致

您可以在一个 Compose 文件中处理所有协调工作，但我要提醒您——这会非常长。您需要定义所有节点、设置磁盘路径，并同时启动它们。

以下是一个包含四个节点、每个节点有两块磁盘的完整示例：

version: "3.9"

services:
  minio1:
    image: quay.io/minio/minio:latest
    hostname: minio1
    container_name: minio1
    command: server http://minio{1...4}/data{1...2} --console-address ":9001"
    ports:
      - "9001:9000"
      - "9091:9001"
    environment:
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: password123
    volumes:
      - ./data/minio1/data1:/data1
      - ./data/minio1/data2:/data2
    networks:
      - minio

  minio2:
    image: quay.io/minio/minio:latest
    hostname: minio2
    container_name: minio2
    command: server http://minio{1...4}/data{1...2} --console-address ":9001"
    ports:
      - "9002:9000"
      - "9092:9001"
    environment:
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: password123
    volumes:
      - ./data/minio2/data1:/data1
      - ./data/minio2/data2:/data2
    networks:
      - minio

  minio3:
    image: quay.io/minio/minio:latest
    hostname: minio3
    container_name: minio3
    command: server http://minio{1...4}/data{1...2} --console-address ":9001"
    ports:
      - "9003:9000"
      - "9093:9001"
    environment:
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: password123
    volumes:
      - ./data/minio3/data1:/data1
      - ./data/minio3/data2:/data2
    networks:
      - minio

  minio4:
    image: quay.io/minio/minio:latest
    hostname: minio4
    container_name: minio4
    command: server http://minio{1...4}/data{1...2} --console-address ":9001"
    ports:
      - "9004:9000"
      - "9094:9001"
    environment:
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: password123
    volumes:
      - ./data/minio4/data1:/data1
      - ./data/minio4/data2:/data2
    networks:
      - minio

networks:
  minio:
    driver: bridge技术支持

{1...4} 语法告诉 MinIO 连接四个节点（minio1 到 minio4），每个节点有两块磁盘（data1 与 data2）。每个节点都有唯一的端口映射，方便单独访问——节点 1 使用 9001/9091，节点 2 使用 9002/9092，依此类推。

minio-distributed 网络让容器可以通过主机名互相访问。所有节点必须使用相同的凭据并看到一致的磁盘布局。

启动集群前，先创建数据目录，然后运行 compose 文件：

mkdir -p data/minio{1..4}/data{1..2}
docker compose up -d技术支持

以分布式模式运行 MinIO

就是这样！现在您可以访问以下任一 URL 打开 Web 界面：

• http://localhost:9091
• http://localhost:9092
• http://localhost:9093
• http://localhost:9094

但再次强调，除非确有需要，否则不要构建这种架构——分布式模式用于对在线率和冗余有严格要求的生产工作负载，才值得其额外复杂性。

此外，在完整的生产环境中，您可能还需要 TLS、单一控制台端点、外部卷/磁盘等配置。

在 Docker 中运行 MinIO 的常见问题

大多数 MinIO 与 Docker 相关的问题都来自卷、端口或凭据配置不当。

以下是您实际会遇到的问题及快速解决方法。

容器已启动但无法访问 Web 界面

您运行 docker ps 看到容器在运行，但 http://localhost:9001 无响应或超时。

要解决此问题，先检查控制台端口是否正确映射：

docker port minio技术支持

您应当看到 9001/tcp -> 0.0.0.0:9001。如果没有 9001 端口，说明您在 docker run 命令或 Compose 文件中忘记映射该端口。

同时查看 MinIO 日志：

docker logs minio技术支持

查找包含 "Console: http://..." 的日志行——这会告诉您 MinIO 实际监听的地址。如果看到不同于预期的端口，可能是 --console-address 参数设置有误。

挂载卷的权限错误

MinIO 在启动时崩溃，或日志中出现尝试写入 /data 时的 "permission denied" 错误。

容器内的 MinIO 进程以特定用户身份运行，该用户需要对挂载目录具有写入权限。可通过以下方式修复：

chmod -R 755 ~/minio/data技术支持

或者在 Linux 上，以您的用户 ID 运行容器：

docker run --user $(id -u):$(id -g) ...技术支持

与其他服务的端口冲突

启动容器时收到 "bind: address already in use"。

这意味着主机上已有服务在使用 9000 或 9001 端口。找出是谁在使用：

# Linux/macOS
lsof -i :9000
lsof -i :9001

# Windows
netstat -ano | findstr :9000技术支持

然后将 MinIO 映射到不同的主机端口：

docker run -p 9090:9000 -p 9091:9001 ...技术支持

现在通过 localhost:9090 访问 API，通过 localhost:9091 访问控制台。

凭据无法按预期工作

您设置了 MINIO_ROOT_USER 与 MINIO_ROOT_PASSWORD，但无法登录或容器无法启动。

请检查是否确实传递了环境变量：

docker inspect minio | grep -A 5 Env技术支持

在输出中查找 MINIO_ROOT_USER 与 MINIO_ROOT_PASSWORD。如果缺失，说明您忘记了 -e 标志或 Compose 文件中的 environment: 部分。

MinIO 要求密码至少 8 个字符。如果您的密码更短，容器可能会拒绝它或改用默认值。

如果您在现有设置上更改了凭据，请完全停止并删除容器，然后重新启动：

docker stop minio
docker rm minio
docker run ...  # with new credentials技术支持

旧的凭据文件可能保留在数据目录中并引发冲突。

使用 Docker 运行 MinIO 的最佳实践

遵循以下实践，可避免常见错误并保持您的 MinIO 配置易于维护。

• 使用 Docker Compose 以保证可重复性。Compose 文件记录您的精确配置——端口、卷、环境变量与命令。您可以将其纳入版本控制、与团队共享，并在不同机器上复现一致的环境。从 shell 历史中运行冗长的 docker run 命令会导致配置漂移与错误。

• 始终配置持久化存储。 在存入任何真实数据前映射卷或绑定挂载。容器是易失性的——若跳过此步骤，容器重启时您会丢失一切。使用 docker inspect minio 检查并确认卷映射是否正确。

• 避免将凭据留在命令历史中。 不要将密码直接放在 docker run 命令中，或在 Compose 文件中提交到 git。请使用 Docker Compose 的环境文件（.env），或在运行时通过环境变量传递凭据。务必将 .env 加入 .gitignore。

• 仅在开发中使用单节点模式。 分布式模式搭建复杂且耗时。您不需要在笔记本上实现高可用或纠删码。将分布式部署留给真正关乎停机成本的生产环境。

• 启动时监控日志。 首次启动 MinIO 时运行 docker logs -f minio。日志会显示 API 端点、控制台 URL 以及任何配置错误。如果有问题，您会第一时间看到，而不是盲目排查为何无法工作。

遵循这些实践，您的 MinIO 环境从第一天起就会稳健可靠。

结语

使用 Docker 运行 MinIO，意味着您可以在不到一分钟的时间内在本机上拥有 S3 兼容的对象存储。

对于开发、测试与小型项目而言，Docker 中的单节点 MinIO 已提供您所需的一切。您可以完全兼容 S3 API，使用 Web 控制台进行管理，并对数据拥有完全控制，而无需依赖云服务或为未使用的存储付费。

从基础开始：一个简单的 docker run 命令或带有持久化卷与安全凭据的 Docker Compose 文件（更推荐后者）。测试并验证您的环境，仅在确有需要时再增加复杂度。

分布式模式、高可用与生产级配置的确有其存在价值——但这并不针对本地开发。等到您部署到生产、停机会带来成本、或存储的数据不容丢失时，再迁移到这些架构。在此之前，保持简单，把精力放在构建应用上，而非管理基础设施。

当您准备深入学习更复杂的 Docker 主题时，欢迎查看我们的 Containerization and Virtualization with Docker and Kubernetes 课程。