MinIO 本地安装配置

MinIO 本地部署最容易混淆的是两个端口：9000 是 S3 兼容 API，9001 是管理控制台。应用程序要连接 9000，浏览器管理界面则打开 9001。两者写反时，SDK 往往只会给出一个不直观的 HTTP 错误。

下面搭一套面向本地开发的单节点、单磁盘环境。它适合测试 S3 SDK、预签名 URL 和上传流程，不等于生产高可用架构。

用 Compose 保留配置和数据

新建一个独立目录，放入 compose.yaml：

services:
  minio:
    image: quay.io/minio/minio:latest
    command: server /data --console-address ":9001"
    restart: unless-stopped
    ports:
      - "127.0.0.1:9000:9000"
      - "127.0.0.1:9001:9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    volumes:
      - minio-data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 10s
      timeout: 3s
      retries: 5

volumes:
  minio-data:

127.0.0.1:9000:9000 表示只把端口绑定到本机回环地址，局域网其他设备不能直接访问。如果你确实需要跨设备调试，再明确调整绑定地址和防火墙，不要在不知情的情况下把管理端口暴露到公网。

凭证放入 .env：

MINIO_ROOT_USER=localadmin
MINIO_ROOT_PASSWORD=replace-with-at-least-16-random-characters

.env 应加入 .gitignore。示例密码不应原样用于共享环境。

启动并检查状态：

docker compose up -d
docker compose ps
curl -f http://127.0.0.1:9000/minio/health/live

curl 退出码为 0 时，只说明服务活着。还要实际创建 bucket 并完成一次上传、下载，才能证明凭证、权限和持久化路径正常。

用 mc 做一次完整验证

mc 是 MinIO 官方客户端，它可以管理 MinIO 和其他 S3 兼容服务。macOS 可用以下命令安装：

brew install minio/stable/mc
mc --help

不把真实凭证直接写进 Shell 历史。下面的命令会交互式读取凭证，然后创建别名、bucket 和测试对象：

read -r -p "MinIO user: " MINIO_USER_INPUT
read -r -s -p "MinIO password: " MINIO_PASSWORD_INPUT
echo

mc alias set local http://127.0.0.1:9000 \
  "$MINIO_USER_INPUT" "$MINIO_PASSWORD_INPUT"
mc mb --ignore-existing local/app-data

printf 'minio-check\n' > /tmp/minio-check.txt
mc cp /tmp/minio-check.txt local/app-data/minio-check.txt
mc cat local/app-data/minio-check.txt

典型输出的最后一行是：

minio-check

再停止和重启容器，检查对象是否还在：

docker compose down
docker compose up -d
mc stat local/app-data/minio-check.txt

docker compose down 不会默认删除命名卷，所以数据应当保留。带 --volumes 参数则会删除该 Compose 项目的卷，不要在保留数据的场景中使用。

应用程序连接的是 API 端口

以 Python boto3 为例，endpoint_url 填写 9000：

import os

import boto3


client = boto3.client(
    "s3",
    endpoint_url="http://127.0.0.1:9000",
    aws_access_key_id=os.environ["MINIO_ROOT_USER"],
    aws_secret_access_key=os.environ["MINIO_ROOT_PASSWORD"],
    region_name="us-east-1",
)

bucket_names = [item["Name"] for item in client.list_buckets()["Buckets"]]
print(bucket_names)

这段代码使用 root 凭证是为了验证本地环境。真实应用应创建独立用户，只授予指定 bucket 的必要动作。应用不需要创建用户或修改全局策略时，就不应持有 root 凭证。

本地环境与生产环境的边界

单节点、单卷可以验证 API，却无法提供节点或磁盘故障容错。上线前还要单独考虑 TLS、用户策略、容量规划、监控、备份和恢复演练。把 Compose 文件复制到服务器上，不会自动获得这些能力。

参考资料

• MinIO 单节点容器部署
• MinIO Client 参考