搜索「MinIO 教程」,出来的几乎全是 docker run minio/minio 那一套。但如果你在 2026 年照着做,第一步就会卡住:Docker Hub 上的 minio/minio 已经拉不到了,dl.min.io 的社区版下载地址返回 410。

这篇先把「现在到底还能用什么」讲清楚,再给五种部署方式和四类接入方法。命令都能直接复制,但不照搬——每一步标明了适用场景和坑。

零、先看现状:2026 年的 MinIO 到底怎么了

这是写在任何部署步骤之前的必读节。MinIO 的社区版(Community Edition)没有换许可证,代码仍是 AGPLv3、仍可阅读和自行构建;变的是维护和分发:官方不再发布二进制、不再发镜像,仓库归档只读。

时间 事件
2021-04/05 服务端与客户端从 Apache 2.0 改为 AGPLv3(SDK 仍 Apache 2.0)
2025-05-24 RELEASE.2025-05-24... 弃用内置管理控制台,改为独立的 object-browser;UI 的 LDAP/OIDC 登录从社区版移除
2025-09-07 RELEASE.2025-09-07... 最后一个带预编译二进制/包的版本
2025-10-15 RELEASE.2025-10-15... 源码版安全更新(修 CVE-2025-62506 权限提升),无二进制产物
2025-12-03 README 加入「维护模式」说明
2025-12-23 推出商业产品 AIStor Free / Enterprise Lite
2026-02-12 README 改为「THIS REPOSITORY IS NO LONGER MAINTAINED」
2026-04-25 minio/minio GitHub 仓库归档只读
2026-07-14 minio/mc 客户端仓库也归档
2026 下半年 dl.min.io 社区版地址返回 410 Gone;Docker Hub 上 minio/minio、minio/mc 显示 object not found

MinIO 社区版关键时间线

说明:本文写作时(2026-11)社区版已归档。若你在更早或更晚的时间点阅读,请以 MinIO 官方仓库 README 与实际可拉取的镜像为准。

安全现实(这条最要紧):自 2026 年 1 月起,归档仓库陆续发布了多个安全公告,包括签名绕过导致的未认证写入(CVE-2026-41145)、Snowball 自动解压缺少签名校验(CVE-2026-40344)、SSE 元数据注入(CVE-2026-34204)、S3 Select 内存耗尽 DoS(CVE-2026-39414)、多节点路径穿越(CVE-2026-42600,以 root 运行时可读取宿主机文件)。这些修复只进入商业版 AIStor,开源仓库自 2025 年 11 月起没有任何代码变更。

一句话结论:

  • 已有集群还能继续跑,但它是一个冻结且带已知漏洞的组件,风险由你自己承担;
  • 新项目不要再基于社区版做生产,先看本文最后一节的替代方案;
  • 如果只是本地开发、CI、临时对象存储,用固定 tag 的旧镜像仍可应付,但要绑 localhost、不暴露公网。

一、部署前的统一准备

不管选哪种方式,下面这些先定好,后面少返工。

1.1 两个端口别搞混

端口 作用 谁访问
9000 S3 API 应用程序、mc 客户端、SDK
9001 Web 控制台 人,浏览器管理

把 S3 客户端指向 9001 会得到一堆看不懂的报错,这是新手第一大坑。

1.2 凭据规则

1
2
MINIO_ROOT_USER=admin          # 至少 3 字符
MINIO_ROOT_PASSWORD=... # 至少 8 字符,生产用 32 位以上随机串

生成强密码:

1
openssl rand -base64 32

永远不要把 minioadmin/minioadmin 带进任何非实验环境。写进 .env 文件并 chmod 600。

1.3 镜像怎么选(关键)

来源 状态 适用
minio/minio(Docker Hub) 已失效,拉不到 不用再试
quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z 历史镜像仍可拉取 本地开发、测试;固定 tag,别用 latest
quay.io/minio/minio:latest 仍可拉取,但指向冻结快照 同上,但不如固定 tag 明确
源码自构建 go install github.com/minio/minio@latest 或从归档仓库构建 需要自己跟进 CVE
pgsty/minio(Silo fork) 社区维护分支,重建二进制与镜像、恢复控制台、跟进安全修复 想低成本留在 MinIO 生态
AIStor Free / Enterprise 商业产品,免费版仅单节点 生产、需要支持

本文示例统一用 quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z 这个已知可拉取的冻结版本,并明确标注:生产请换成本节表格里更适合你的选项。

1.4 数据目录与文件系统

1
mkdir -p /opt/minio/data /opt/minio/config

生产建议:

  • 用 XFS 格式的本地盘,JBOD 直挂,不要在下面垫 RAID / LVM;MinIO 自己做纠删码,RAID 只会增加复杂度并放大重建时间。
  • 单机多盘用 /data1 /data2 ... 这样分开挂载,别把一个分区的子目录当多盘。
  • 所有盘容量尽量一致——MinIO 会把每块盘的可用容量拉平到最小盘。

1.5 纠删码:决定你能坏几块盘

MinIO 把一个对象切成 数据分片 K 和 奇偶分片 M,写进一个纠删集(N = K + M)。读写仲裁:

  • 读取:至少 K 块健康盘;
  • 写入:至少 K 块在线盘(不同版本策略略有差异,按 N/2 + 1 估算更保守);
  • 最多可容忍 M 块盘故障而不丢数据。

以 4 节点 × 4 盘 = 16 盘、默认 EC:8(8 数据 + 8 奇偶)为例:原始 160 TB(16×10TB),可用约 80 TB,利用率 50%,最多坏 8 块盘仍可读。

纠删码分片与读写仲裁

单盘单节点(本文部署方式 1/2/3)没有纠删码、没有冗余,删盘即丢数据。只适合开发和测试。


二、部署方式 1:源码二进制 + systemd

适合:想跑原生进程、不用 Docker、愿意自己构建。因为官方已停发二进制,必须自行构建。

1
2
3
4
5
# Go 1.21+ 环境
go install github.com/minio/minio@latest
# 产物通常在 ~/go/bin/minio
install -m 0755 ~/go/bin/minio /usr/local/bin/minio
minio --version

配置 systemd:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# /etc/systemd/system/minio.service
[Unit]
Description=MinIO Object Storage
After=network-online.target
Wants=network-online.target

[Service]
User=minio
Group=minio
EnvironmentFile=/etc/default/minio
ExecStart=/usr/local/bin/minio server /opt/minio/data --console-address ":9001"
Restart=always
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
1
2
3
4
5
6
7
8
9
10
useradd -r -s /sbin/nologin minio
chown -R minio:minio /opt/minio
cat > /etc/default/minio <<'EOF'
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=换成你生成的强密码
EOF
chmod 600 /etc/default/minio
systemctl daemon-reload
systemctl enable --now minio
journalctl -u minio -f

注意 go install ...@latest 拉的是归档仓库的最后一个提交,不会有任何新修复——把它当作「冻结核」,CVE 要自己盯。


三、部署方式 2:Docker run 单机(最快)

适合:本机开发、临时验证。

1
2
3
4
5
6
7
8
9
docker run -d \
--name minio \
-p 127.0.0.1:9000:9000 \
-p 127.0.0.1:9001:9001 \
-e MINIO_ROOT_USER=admin \
-e MINIO_ROOT_PASSWORD='换成强密码' \
-v /opt/minio/data:/data \
quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z \
server /data --console-address ":9001"

为什么绑定 127.0.0.1:Docker 会自己写 iptables 规则,-p 9000:9000 会把端口发布到所有网卡,绕过 ufw/firewalld。你在防火墙里关了 9000,容器端口照样能从外网访问——这和你上一篇 firewalld 里 DOCKER-USER 链是同一个问题。要公网访问,正确做法是绑本地 + 反向代理,而不是直接 -p 9000:9000。

1
2
docker logs -f minio
curl -s http://127.0.0.1:9000/minio/health/live -w '%{http_code}\n'

四、部署方式 3:Docker Compose 单机(推荐用于本地/内网)

这是最省心的单机形态:配置集中、健康检查、重启策略齐全。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# /opt/minio/compose.yaml
services:
minio:
image: quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z
container_name: minio
restart: unless-stopped
env_file: .env
command: server /data --console-address ":9001"
ports:
- "127.0.0.1:9000:9000"
- "127.0.0.1:9001:9001"
volumes:
- ./data:/data
- ./config:/root/.minio
healthcheck:
test: ["CMD", "curl", "-f", "http://127.0.0.1:9000/minio/health/live"]
interval: 30s
timeout: 10s
retries: 3
1
2
3
# /opt/minio/.env
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=换成32位以上随机密码
1
2
3
4
chmod 600 .env
docker compose up -d
docker compose ps
docker compose logs --tail=100 minio

几个细节:

  • config 目录挂载出来,证书和部分配置才能跨容器重建保留;
  • 健康检查用 curl(镜像内置),mc ready local 在部分版本里不可用;
  • 端口仍绑 localhost,公网入口交给 Nginx/Caddy,见第八节;
  • 想加入你已有的 Docker 网络(比如 app-net),加一段 networks:,让同网容器用服务名 minio:9000 互访。

五、部署方式 4:分布式 4 节点(生产形态)

适合:需要真正冗余的生产集群。最少 4 个驱动器,官方生产建议 4 个节点起步、同构配置。

拓扑:4 节点 × 每节点 4 盘 = 16 盘,组成一个纠删集,默认 EC:8。

五种方式一览——本地形态(1/2/3)与生产形态(4/5)的差别主要在冗余和暴露面:

五种部署方式对比

前置条件:

  • 4 台机器时间同步(chrony/NTP),时钟漂移会导致签名校验失败;
  • 节点间 9000 端口互通,主机名能解析(写 hosts 或用 DNS);
  • 每节点 4 块 XFS 盘,挂载为 /data1 ~ /data4;
  • 凭据四节点完全一致。

每个节点上写同样的 Compose(以 minio1 为例,其余节点把 hostname 与 IP 对应改好):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
services:
minio:
image: quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z
container_name: minio
hostname: minio1
restart: unless-stopped
env_file: .env
command: server http://minio{1...4}/data{1...4} --console-address ":9001"
extra_hosts:
- "minio1:10.0.0.11"
- "minio2:10.0.0.12"
- "minio3:10.0.0.13"
- "minio4:10.0.0.14"
ports:
- "9000:9000"
- "9001:9001"
volumes:
- /data1:/data1
- /data2:/data2
- /data3:/data3
- /data4:/data4

{1...4} 是 MinIO 的椭圆展开语法(三个点),必须写全,不能用 {1..4}。四台都启动后:

1
2
mc alias set myminio http://10.0.0.11:9000 admin '你的密码'
mc admin info myminio # 应看到 4 在线、16 块盘

生产注意:

  • 节点增减要按官方扩容流程做,不要直接改 {1...4} 范围;
  • 混用不同容量盘会按最小盘计算,别拿 1TB 和 10TB 混布;
  • 控制台和 API 前面都要挂 TLS 终止,SDK 用 HTTPS 端点;
  • 分布式 + 冻结镜像 = 已知 CVE 无修复,生产务必评估 Silo fork / AIStor / 其他引擎(见第十一节)。

六、部署方式 5:Kubernetes(Helm / Operator)

适合:已在 K8s 上运行、有存储运维经验。

需要提醒:minio/operator 仓库同样在 2026 年归档,Helm Chart 也不再有新版本。以下流程仍可跑,但你要接受「无人维护」这个前提。

1
2
3
4
5
6
7
8
# Helm 方式(社区 chart,单节点示例)
helm repo add minio https://charts.min.io/
helm install minio minio/minio \
--namespace minio --create-namespace \
--set mode=standalone \
--set rootUser=admin \
--set rootPassword='换成强密码' \
--set persistence.size=50Gi

分布式模式用 --set mode=distributed --set replicas=4,并配置每个 Pod 的 PVC。生产建议:

  • 用 StatefulSet + 本地 PV 或专门的 CSI 驱动,避免网络存储的额外延迟;
  • 资源限制要留足(MinIO 对内存和网络敏感);
  • Ingress 暴露时同样区分 API 与 Console 两个域名;
  • 更稳妥的路线是改用仍在维护的 S3 引擎的官方 Operator。

七、接入方式一:mc 命令行客户端

mc 是管理 MinIO 的核心工具(2025-05 之后,用户/策略/生命周期管理都靠它,控制台只剩对象浏览)。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 下载(社区版历史地址若 410,可从 AIStor 地址或 Silo fork 获取)
curl -L https://dl.min.io/aistor/mc/release/linux-amd64/mc -o /usr/local/bin/mc
chmod +x /usr/local/bin/mc

# 配别名:注意用 API 端口 9000,不是 9001
mc alias set myminio http://127.0.0.1:9000 admin '你的密码'
mc admin info myminio

# 日常操作
mc mb myminio/uploads # 建桶
mc ls myminio # 列桶
mc cp ./a.jpg myminio/uploads/ # 上传
mc cp --recursive ./photos/ myminio/uploads/ # 传目录
mc cp myminio/uploads/a.jpg ./ # 下载
mc rm myminio/uploads/a.jpg # 删除

# 权限:设为公共读(注意新版命令是 anonymous,不是 policy)
mc anonymous set download myminio/uploads
mc anonymous set none myminio/uploads

# 限时分享链接
mc share download --expire 24h myminio/uploads/a.jpg

# 版本控制与生命周期
mc version enable myminio/uploads
mc ilm add --expiry-days 30 myminio/uploads

# 镜像备份
mc mirror myminio/uploads ./backup/uploads

常见报错:

  • AccessDenied:检查 alias 用的 key 权限、桶策略;
  • The specified bucket does not exist:桶名拼写或 alias 指错端点;
  • 设置了公共读但访问 403:如果前面有 Nginx,检查 proxy_set_header Host 是否被改写,签名校验依赖 Host。

八、接入方式二:S3 SDK(Python / Java)

MinIO 兼容 S3 API,SDK 几乎不用改逻辑,只要换 endpoint 并打开 path-style。

8.1 Python boto3

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import boto3
from botocore.client import Config

s3 = boto3.client(
"s3",
endpoint_url="https://s3.example.com", # API 域名,指向 9000
aws_access_key_id="admin",
aws_secret_access_key="你的密码",
region_name="us-east-1", # MinIO 忽略,但必填
config=Config(
signature_version="s3v4",
s3={"addressing_style": "path"}, # 关键:MinIO 默认不支持虚拟主机桶名
),
)

s3.create_bucket(Bucket="uploads")
s3.upload_file("./a.jpg", "uploads", "a.jpg")

# 预签名下载链接(1 小时有效,不暴露密钥)
url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "uploads", "Key": "a.jpg"},
ExpiresIn=3600,
)

8.2 Java Spring Boot

1
2
3
4
5
6
<!-- pom.xml -->
<dependency>
<groupId>io.minio</groupId>
<artifactId>minio</artifactId>
<version>8.5.7</version>
</dependency>
1
2
3
4
5
6
# application.yml
minio:
endpoint: https://s3.example.com
access-key: admin
secret-key: 你的密码
bucket: uploads
1
2
3
4
5
6
7
8
9
10
11
12
13
14
@Configuration
public class MinioConfig {
@Value("${minio.endpoint}") String endpoint;
@Value("${minio.access-key}") String accessKey;
@Value("${minio.secret-key}") String secretKey;

@Bean
public MinioClient minioClient() {
return MinioClient.builder()
.endpoint(endpoint)
.credentials(accessKey, secretKey)
.build();
}
}

上传示例:

1
2
3
4
5
6
minioClient.putObject(PutObjectArgs.builder()
.bucket("uploads")
.object("2026/a.jpg")
.stream(inputStream, inputStream.available(), -1)
.contentType("image/jpeg")
.build());

要点:

  • endpoint 填 API 地址,不要带 bucket 名;
  • 老版本 SDK 需要 secure(false) / HTTP 明确指定,HTTPS 反代后改成 true;
  • 分片上传大文件用 uploadObject + 大文件参数,单对象上限 5TB、单次 PUT 上限 5GB。

8.3 接入方式对照

四类接入方式与端点关系

方式 适合 注意
mc 管理、运维、批处理 用 9000,命令已改为 mc anonymous
boto3 / AWS SDK 应用上传下载 path-style 必开
Spring Boot Minio SDK Java 业务集成 版本 8.5.x,注意流式上传
rclone 备份、挂载为本地盘 provider=MinIO,填 endpoint 与 key

九、接入方式三:Nginx 反代 + HTTPS

公网访问不要直接暴露 9000/9001,用反代做 TLS 终止和域名分离。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# S3 API:s3.example.com → 9000
server {
listen 443 ssl http2;
server_name s3.example.com;
ssl_certificate /etc/ssl/wildcard.crt;
ssl_certificate_key /etc/ssl/wildcard.key;

client_max_body_size 0; # 关键:Nginx 默认 1MB,大文件会 413
proxy_request_buffering off; # 大对象流式上传,不落磁盘
proxy_buffering off;

location / {
proxy_pass http://127.0.0.1:9000;
proxy_set_header Host $http_host; # 签名校验依赖原始 Host
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_connect_timeout 300s;
proxy_read_timeout 300s;
}
}

# Console:minio.example.com → 9001
server {
listen 443 ssl http2;
server_name minio.example.com;
ssl_certificate /etc/ssl/wildcard.crt;
ssl_certificate_key /etc/ssl/wildcard.key;
client_max_body_size 0;
location / {
proxy_pass http://127.0.0.1:9001;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}

三个必踩的坑:

  1. client_max_body_size 不调大,上传超过 1MB 就 413;
  2. Host 头必须透传原始值,改成 $host 都可能破坏签名(带端口时尤其);
  3. API 和 Console 用两个域名,不要靠路径区分——MinIO 的签名和重定向都基于完整 URL。

改完验证:

1
2
nginx -t && systemctl reload nginx
curl -I https://s3.example.com/minio/health/live

9.1 接入方式四:rclone 挂载与备份

1
2
3
4
5
6
# 配置 remote,provider 选 MinIO / S3 Compatible
rclone config
# 常用参数
rclone ls minio:uploads
rclone copy ./local minio:uploads --progress
rclone mount minio:uploads /mnt/minio --vfs-cache-mode writes

备份脚本里更稳的做法是 rclone sync + --backup-dir 保留删除历史,避免误删不可逆。


十、排障清单

现象 优先怀疑 验证命令
docker pull minio/minio 失败 镜像已从 Docker Hub 下架 换 quay.io/minio/minio:<固定tag>
下载 mc 返回 410 社区版下载地址失效 换 AIStor 地址或 Silo fork
客户端报奇怪 XML 错误 指到了 9001 控制台端口 改成 9000
SDK 报 NoSuchBucket 但桶存在 缺 path-style addressing_style="path"
上传大文件 413 Nginx client_max_body_size 默认 1MB 设为 0 或足够大
签名不一致 SignatureDoesNotMatch Host 头被改写 / 时钟漂移 检查反代 Host、同步 NTP
防火墙关了端口仍可访问 Docker 发布端口绕过防火墙 绑 127.0.0.1 或写 DOCKER-USER 链
分布式节点起不来 {1...4} 写成 {1..4} 三个点,且主机解析要通
写入报仲裁不足 在线盘少于 K mc admin info 看在线盘数
混盘后容量变小 按最小盘拉平 换同容量盘
控制台空白 / 功能少 2025-05 后社区版控制台缩减 用 mc 管理用户与策略

健康检查探针:

1
2
curl -s http://127.0.0.1:9000/minio/health/live -w '%{http_code}\n'   # 存活
curl -s http://127.0.0.1:9000/minio/health/ready -w '%{http_code}\n' # 就绪(分布式依赖仲裁)

十一、社区版归档后的替代方案

这是新项目必须做的选择题。没有一个是完全 drop-in 的替代,选型前务必用你应用实际用到的 S3 特性(分段上传、预签名 URL、版本控制、批量删除)做验证。

方案 许可 状态 适合
Silo(原 pgsty/minio) AGPLv3 社区 fork,重建二进制与镜像、恢复控制台、跟进安全修复 想最小改动留在 MinIO 生态
AIStor Free 专有(免费) 官方当前产品,仅单节点、禁止再分发 开发、测试、单机备份
AIStor Enterprise 商业订阅 分布式、有支持与修复 生产、要厂商兜底
RustFS Apache 2.0 2026-09 发布 1.0,类 MinIO 分布式模型 多节点,先测 S3 兼容性
Garage AGPLv3 活跃维护,轻量 小规模、异地多站点
SeaweedFS Apache 2.0 成熟(2015 起) 海量小对象、多协议
Ceph RGW LGPL 企业级参考实现 大规模、严格 S3 语义

迁移路径(无论选哪个):

  1. 盘点桶、策略、用户、生命周期、版本控制规则——目标端不一定都有对应物;
  2. 用 rclone sync 或 mc mirror 搬数据;
  3. 用应用的真实 S3 调用跑一遍兼容性测试;
  4. 新旧端点并存一段时间,旧集群先只读、别急着下线;
  5. 确认新集群稳定运行一个维护周期后再切流量。

替代方案决策路径


十二、一页速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 镜像(固定 tag,别用 latest)
quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z

# 单机 Compose 关键片段
command: server /data --console-address ":9001"
ports:
- "127.0.0.1:9000:9000" # API
- "127.0.0.1:9001:9001" # Console

# 分布式(4 节点 × 4 盘,三个点!)
command: server http://minio{1...4}/data{1...4} --console-address ":9001"

# mc
mc alias set myminio http://IP:9000 admin '密码'
mc mb myminio/uploads
mc cp ./a.jpg myminio/uploads/
mc anonymous set download myminio/uploads
mc admin info myminio
mc mirror myminio/uploads ./backup/

# 健康检查
curl -s http://127.0.0.1:9000/minio/health/live -w '%{http_code}\n'

# boto3 必开
s3={"addressing_style": "path"} # 或 s3ForcePathStyle=true

# Nginx 必改
client_max_body_size 0;
proxy_set_header Host $http_host;

小结

  1. 先认清现状:社区版归档、无官方二进制与镜像、已知 CVE 无修复;新生产项目优先评估替代方案。
  2. 五种部署:二进制/systemd(自构建)、Docker run、Compose(本地推荐)、4 节点分布式(生产形态)、K8s Helm/Operator;本地一律绑 localhost + 反代。
  3. 端口记牢:9000 给程序和 mc,9001 给人看控制台。
  4. 四类接入:mc 管运维、SDK 做业务、Nginx 做 TLS 与域名、rclone 做备份;SDK 记住 path-style,Nginx 记住 body 大小和 Host 头。
  5. 纠删码算清账:N=K+M,能坏 M 块盘,混盘按最小盘算——容量和冗余都要提前算好,不是「加上盘就变多」。

最后一句实在话:对象存储是那种「平时最不想被想起、出事最要命」的基础设施。2026 年这个时间点,选一个上游还活着的引擎,比省下那点迁移成本更重要。