MinIO 对象存储集群搭建与 S3 兼容性配置【转】
MinIO 对象存储集群搭建与 S3 兼容性配置
一、问题背景:从一台单机到一套能扛事的对象存储
事情通常是这样开始的。业务侧要做文件上传、模型权重存放、日志冷备、数据库备份落盘,一开始在应用服务器上装了个单机 MinIO,挂了一块 4TB 的盘,跑得挺好。半年后盘满了,加一块盘,发现单机 MinIO 不能"把两块盘并成一个更大的空间"——你只能在启动命令里追加一个目录,但那只是多了一个存储位置,不是扩容。再往后,机器一重启,或者磁盘坏一块,数据就少一截。这时候才意识到:对象存储这东西,单机只能算"能存",集群才算"敢存"。
第二类常见场景是 S3 兼容性的坑。业务代码在 AWS 上测通了,换到自建 MinIO 上跑不通:有的是分片上传(Multipart Upload)的 ETag 对不上,有的是预签名 URL(Presigned URL)的 Host 不对导致签名校验失败,有的是 SDK 用了 MinIO 没实现或行为不同的接口,比如某些批量删除的响应结构、ListObjectsV2 的分页参数、对象锁(Object Lock)的保留策略。还有一类问题更隐蔽:MinIO 的 s3:GetObject 策略配得"看起来没问题",但用子账号访问对象时 403,原因是桶策略(Bucket Policy)与用户策略(User Policy)的并集逻辑没搞清楚。
第三类是集群运维。四个节点、每节点四块盘建好集群之后,半年内会陆续遇到:怎么加机器扩容(不能往已有池子里塞盘)、加了新池子之后旧数据没有自动迁移(要手动 rebalance)、某块盘坏了怎么判断是"降级"还是"丢数据"、mc admin info 里那个 Drives: 15/16 OK 到底意味着还能扛几块、升级版本时能不能滚动升、监控该看哪些指标。
这篇文章就围绕这三条线展开:先把集群搭对,再把 S3 兼容性配好,最后把日常运维的判断依据讲清楚。中间会涉及大量 MinIO 特有的行为约束,这些约束不讲清楚,搭出来的集群一定会在某个时间点出事。
二、适用场景与不适用场景
适用:
- 自建私有云对象存储,承载图片/视频/附件、备份归档、日志冷数据、AI 训练数据与模型权重;
- 需要 S3 协议兼容,但不想付公有云出口流量费用的场景;
- 已有 3~16 台物理机或虚拟机,每台可挂 4~16 块独立数据盘,且对数据可靠性有要求(能接受降级,不能接受丢数据);
- 需要把对象存储接入现有监控体系(Prometheus)与现有备份链路(mysqldump、pg_basebackup、Velero 等)。
不适用:
- 单机小容量(小于 1TB)且无可靠性要求——单机模式足够,本文的集群部分对你是负担;
- 需要 POSIX 语义(随机写、文件锁、目录操作)——对象存储不是文件系统,不要用 s3fs/FUSE 硬凑,性能与一致性都会出问题;
- 需要块存储(给数据库挂盘)——那是 Rook/Ceph RBD 或云盘的事;
- 需要跨地域强一致的全局命名空间、需要 POSIX 兼容的多挂载点——Ceph 更合适;
- 需要商业支持合同、需要 LDAP/OIDC 单点登录(社区版自 2025-05-24 版本起移除了内嵌控制台的外部 IDP 登录,见下节)——要么走 AIStor 商业版,要么自己在前面套一层认证网关。
三、版本基线与关键事实(先讲清楚,否则后面全错)
MinIO 从 2025 年开始的产品与版本变化比较剧烈,写方案前必须把这几件事理清。
| 项目 | 现状 | 影响 |
|---|---|---|
社区版(minio/minio,AGPLv3) |
GitHub 上仍在发版,采用 RELEASE.YYYY-MM-DDTHH-MM-SSZ 时间戳版本号 |
社区版没有"1.x/2.x"这种语义化版本,也没有 LTS 概念,升级策略必须按时间戳版本管理 |
| 商业版 | 更名为 MinIO AIStor,独立文档站与许可证(MinIO Software License) | AIStor 才包含 Iceberg Catalog、SFTP、S3 over RDMA、MemKV 等能力,社区版没有 |
| 内嵌 Web 控制台 | RELEASE.2025-05-24T17-08-30Z 起标记为 Breaking Release:内嵌 Console 弃用,迁到独立的 object-browser 项目;通过 LDAP/OIDC 的外部 IDP 登录被移除(该能力转入 AIStor) |
升级到这个版本以后,http://ip:9001 上的控制台不再具备完整的用户/组/策略管理能力,外部 IDP 登录直接不可用;STS API 仍然可用 |
| 许可证 | AGPLv3 | 如果你把 MinIO 改造成对外提供服务的 SaaS,AGPL 的传染性需要法务确认;内部自用不受影响 |
这意味着什么:如果你现在规划一套新集群,且计划长期用社区版,就要接受"控制台功能被削减"这一现实,把用户/策略管理全部脚本化(mc admin user / mc admin policy / mc admin accesskey),不要依赖网页点点点。如果确实需要内嵌控制台做运维,就要把版本锁定在 2025-05-24 之前的某个版本,但这意味着后续安全修复你拿不到——这是个真实的取舍,需要写进方案里让领导确认。
本文示例以社区版 RELEASE.2025-10-15T17-29-55Z(截至目前 GitHub 上的最新安全修复版)为基础。所有命令在该版本上有效;早期(2023 年以前)的版本在 mc 子命令名称上有差异,会单独标注。
另一个必须先讲的事实:社区版文档站已从 min.io/docs/minio/linux/ 逐步迁到 AIStor 文档,社区版文档入口在 min.io/docs/minio/community/(部分镜像站也在同步)。查文档时注意 URL 里的 aistor 与 community,两边指令不通用,AIStor 的很多 mc admin 子命令(如 mc admin pool、mc admin set、mc admin cordon、mc admin cluster stats)在社区版里不可用。
四、环境假设
本文的集群规模按"最小可用生产规格"设计——4 节点 × 4 块盘 = 16 块盘,纠删码 EC:4。
| 项目 | 规格 | 说明 |
|---|---|---|
| 节点数 | 4 台 | 最少 4 台才有实用价值;2 台也能起,但容错空间太小 |
| 每节点数据盘 | 4 块 NVMe/SATA SSD 或 HDD | 每块盘独立挂载点,不要 RAID 后再给 MinIO |
| 单盘容量 | 4TB | 示例用;按容量规划,见第五节末尾 |
| 文件系统 | XFS | 官方明确不建议 ext4(不严格遵循 O_DIRECT/fdatasync 语义),ZFS/btrfs 可用但运维复杂度高 |
| 操作系统 | Rocky Linux 9 / Ubuntu 24.04 | 命令以 Rocky 9 为主,Debian 系差异标注 |
| 内存 | 每节点 ≥ 32GB | 对象存储对内存要求不高,但元数据扫描与并发连接需要内存兜底 |
| 网络 | 万兆起步,建议双口 bond | 纠删码的写放大让网络成为瓶颈,千兆下吞吐非常难看 |
| 时间同步 | chrony 强制开启 | 节点间时间差必须小于 15 分钟,否则互相拒绝加入 |
五、前置检查:系统层与容量规划
上一节给出的环境假设是否成立,取决于下面这些检查项。任何一项不通过,就不要往下走。
部署前逐项确认,任何一项不满足就不要往下走。
bash# 内核版本(MinIO 依赖较新的 epoll 与 sendfile 实现,3.10 内核上性能明显差)
uname -r
cat /etc/os-release | grep -E "^(NAME|VERSION_ID)"
# 文件句柄上限(MinIO 并发连接多,默认 1024 不够)
ulimit -n
grep -E "^(root|minio-user|nofile)" /etc/security/limits.conf /etc/security/limits.d/*.conf 2>/dev/null
预期 uname -r 为 5.14.x(Rocky 9)或 6.8.x(Ubuntu 24.04)。如果看到 3.10.0-1160,说明是 CentOS 7,MinIO 最新版对 glibc 有最低要求,先确认能否运行:ldd --version | head -1,glibc 需 2.28 以上。CentOS 7 的 glibc 是 2.17,直接跑不起来,会报 GLIBC_2.28 not found——这不是"缺个包",是内核与基础库整体落后,换系统比打补丁划算。
bash# 时间同步状态(偏移必须很小)
chronyc tracking | grep -E "System time|Leap status|Stratum"
# 期望:System time 偏移在毫秒级,Leap status : Normal,Stratum 小于 5
如果 chronyc tracking 报 506 Cannot talk to daemon,说明 chrony 没跑;如果 System time 显示偏移上百毫秒,说明同步链路有问题。节点间时间差超过 15 分钟会导致节点互相拒绝加入集群,日志里是 Specified time is not within the allowed range。这是最容易被忽略、又最容易在虚拟化环境里踩到的一条——VM 快照恢复、宿主机休眠都会导致时间跳变。
bash# 数据盘已独立挂载且文件系统为 XFS
lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT
df -hT | grep -E "xfs|data"
预期看到 4 块独立的盘,每块一个挂载点,FSTYPE 全是 xfs。如果看到的是 LVM 卷或者 /dev/md0,说明有人已经做了 LVM/RAID——必须先拆掉再给 MinIO,理由见第五节 5.1。
bash# 节点间网络连通性与 MTU 一致(不一致会导致大包丢,表现为"上传卡住")
for h in 10.0.10.11 10.0.10.12 10.0.10.13 10.0.10.14; do
if ping -c 2 -M do -s 8972 "$h" >/dev/null 2>&1; then
echo "$h MTU9000 OK"
else
echo "$h MTU9000 FAIL"
fi
done
ip -o link show | awk '{print $2, $NF}'
-M do 是禁止分片,-s 8972 是 9000 MTU 下 ICMP 能承载的最大负载(9000 - 20 IP 头 - 8 ICMP 头)。四台都 OK 才说明 MTU 端到端一致。
第 4 步的 MTU 检查特别容易被跳过,但它造成的故障极难排查:四台机器里有一台 MTU 是 1500、其余是 9000,表现是"上传小文件正常、上传大文件卡在某百分比然后超时",mc admin trace 里能看到节点间 RPC 反复重试。这类问题不看 MTU 根本想不到——你会先去查磁盘 IO,再去查网络丢包,最后才有人想起来看 MTU。虚拟化环境里尤其常见:宿主机开了巨帧,某个新起来的 VM 没继承。
bash# 端口未被占用(9000 API,9001 Console)
ss -lntp | grep -E ":(9000|9001)\b"
# SELinux 状态(开启时需额外放行目录与端口)
getenforce
# 防火墙状态
systemctl is-active firewalld
firewall-cmd --list-ports 2>/dev/null
端口检查如果发现 9000 被占用,不要急着重启机器——先确认占用进程是谁:
bashss -lntp | grep ':9000' # 看 pid/程序名
ps -fp <pid>
曾经有人在容器里跑了别的服务占了 9000,MinIO 起不来,报 Specified port is already in use,查了半天以为是 MinIO 的问题,实际是自己三个月前起的测试容器。
防火墙:四节点之间要放行 9000(节点间 RPC 走同一端口);对客户端只放行反代 IP;9001 只放行内网管理网段。
bash# 内网节点互访(在所有节点执行,zone 按实际网卡所在区域调整)
firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.0.10.0/24" port protocol="tcp" port="9000" accept'
firewall-cmd --reload
firewall-cmd --list-rich-rules
风险:firewall-cmd --reload 会重建规则表,正在建立的连接可能被重置。生产上改防火墙要在维护窗口,并准备好"另一条 SSH 通道"(比如带外管理口),避免规则写错把自己关在门外。改之前先 firewall-cmd --list-all > /root/fw-backup-$(date +%F).txt 存证。
前置检查:容量规划
把容量算清楚再买盘,比买回来再想办法实在。
text需求:业务需要 30TB 可用容量,保留 20% 水位
计算:需要可用 30TB / 0.8 = 37.5TB
EC:4 下可用率 50%:裸容量 = 37.5TB / 0.5 = 75TB
每盘 4TB(实际可用约 3.6TB,格式化和保留区损耗):
75TB / 3.6TB ≈ 21 块盘 → 取整到 24 块盘(6 节点 × 4 盘)
这个算式里有两个坑:
- 单盘标称容量不等于可用容量。4TB 的盘格式化后 XFS 可用约 3.6~3.7TB,因为厂商按 10 进制算而系统按 2 进制算,再加上 XFS 的元数据区。按 90% 折算比较稳。
- 保留水位不是为了"留余量",是因为 MinIO 满盘会拒绝写入并且无法自动腾挪。到 100% 时所有写入失败,连删除操作都可能因元数据无法更新而卡住。20% 是底线,不是建议值。
另外要预留 一个节点的空间用于 heal:某节点整机故障恢复时,重建的数据要写到其他节点上,如果集群已经 95% 满,重建会失败。所以真实可用率要再打个折,规划时按 70% 算更安全。
六、核心知识:纠删码、纠删集与"盘够不够"
不把纠删码(Erasure Coding,EC)讲透,后面所有的容量计算、故障判断、扩容决策都是瞎猜。
6.1 纠删码在做什么
MinIO 不用 RAID,也不用三副本。它把每个对象切成数据块,配上校验块,分散写到一组盘上——这一组盘叫纠删集(Erasure Set)。
MinIO 的纠删码参数写成 EC:N,表示 N 个数据块 + N 个校验块,总共 2N 块,能容忍 N 块盘同时故障。默认 EC:4,即 4 数据 + 4 校验,一共 8 块。
必须记住的规则:
- 纠删集大小只能是 2 的幂,从 2 到 16(2、4、8、16)。MinIO 会选"能整除总盘数、且让每个节点参与相同数量盘"的最大值。总盘数必须是这些数字之一的整数倍。
- 每个对象只写入一个纠删集,最多分散在 16 块盘上。所以单对象的读写性能上限由单纠删集的盘数与网络决定,加机器不会让单个大文件的下载变快——这是很多人扩容后的第一个困惑。
- 纠删集在启动时确定,运行中不可变。加盘、换盘都不能改变已有纠删集的成员;加机器只能通过"新增池(server pool)"实现。
EC:4的冗余度是 50%:16 块盘 × 4TB = 64TB 裸容量,可用约 32TB。- 纠删码之下不要再叠 RAID。RAID 会让你"单盘故障"变成"整组故障":一块盘坏了,RAID 卡的降级重建要几个小时,期间一旦再坏一块,整组数据全丢——而 MinIO 本来只需要那块盘的 1/N。叠 RAID 还会让 MinIO 看到的"一块盘"实际是"一组盘",纠删集分布计算全乱。
6.2 盘数怎么选:16 块盘的几种组合
| 总盘数 | 可能的纠删集大小 | 纠删集数量 | 每对象落在几块盘 | 容错 | 可用率 |
|---|---|---|---|---|---|
| 4 | 4 | 1 | 4 | 2 块(EC:2) | 50% |
| 8 | 8 或 4×2 | 1 或 2 | 8 或 4 | 4 块 或 2 块×2 组 | 50% |
| 12 | 4×3(12 不能被 8/16 整除) | 3 | 4 | 每组 N/2 | 50% |
| 16 | 16 或 8×2 | 1 或 2 | 16 或 8 | 8 块 或 4 块×2 组 | 50% |
| 20 | 4×5 | 5 | 4 | 每组容错低 | 50% |
| 24 | 8×3 或 4×6 | 3 或 6 | 8 或 4 | 4 块×3 组 | 50% |
一个反直觉的结论:盘数越"整齐"(8、16、24 都能被 8 整除),纠删集越大,单对象并行度越高、读写越快;盘数越零碎(12、20),纠删集被迫变小(4),单对象只能并行 4 路,大文件吞吐明显下降。
条件允许的话,16 块盘就让 MinIO 自己选最大的纠删集,不要人为拆成 8×2。原因:16 块盘的纠删集,读一个对象需要 16 块盘同时响应,带宽被摊薄到每块盘 1/16,单盘队列深度压力小;4+4 的小纠删集只需要 8 块盘,单盘压力集中,在 HDD 上尤其明显(寻道次数多)。
但大纠删集有代价:16 块盘的 set 里坏 9 块才不可读,但坏 5~8 块时虽然可读却不可写;同时 16 块盘任一慢都会拖累整个 set(短板效应)。所以在盘本身不稳定的环境(比如二手盘、老 HDD),小纠删集反而容错边界更清晰。
6.3 降级(Degraded)与"还能扛几块"
mc admin info 里的这两行是关键证据:
textDrives: 15/16 OK
Nodes: 4/4 OK
15/16 OK表示 16 块盘里有 1 块不可用。集群仍在读仲裁与写仲裁之上,读写正常。- EC:4 下每个纠删集 8 块:坏 1~4 块可读写;坏 5 块(只剩 4 块)进入只读;坏 6 块以上数据不可恢复。
但"看总数"是错的,必须看每个纠删集坏了几块:
bash# 看每个 set 的盘数与状态
mc admin info myminio | grep -iE "pool|set|drives per set"
# 逐盘列出状态(state 为 ok / offline / unformatted)
mc admin info myminio --json | jq -r '
.info.servers[] | .endpoint as $e | .drives[] |
"\($e)\t\(.path)\t\(.state)"' | sort -k3
15/16 会骗人:16 块盘分两个 set,如果 3 块坏在同一个 set 里、另一个 set 完好,整体显示 13/16 OK 看起来还好,但那个 set 只剩 5 块,已经离只读只差一步。反过来,如果 1 块坏在 set A、1 块坏在 set B,整体 14/16 看起来更差,实际两边各剩 7 块,还能各扛 3 块。
这就是为什么要把每个 set 的 offline 数量单独盯住。告警规则应该是"任一 set 的可用盘数 < 6"(EC:4 下),而不是"集群总离线盘数 > 1"。
6.4 存储类(Storage Class):让不同数据用不同冗余
MINIO_STORAGE_CLASS_STANDARD 控制标准存储层的纠删码配置,MINIO_STORAGE_CLASS_RRS 控制低冗余层。
bash# 标准层用 EC:4(4 数据 + 4 校验)
export MINIO_STORAGE_CLASS_STANDARD="EC:4"
# 低冗余层用 EC:2(2 数据 + 2 校验)
export MINIO_STORAGE_CLASS_RRS="EC:2"
EC:N 的语义容易搞错:EC:4 表示 4 个数据块 + 4 个校验块(总共 8 块),不是 RAID6 式的"4 数据 + 2 校验"。很多人按 RAID6 习惯算成可用率 66%,实际是 50%,容量规划直接错 16 个百分点。这一点必须在方案评审时说清楚,不然后面扩容时会发现"按算出来的容量买盘,装不下"。
低冗余层不是"更省空间"的层,而是"校验块更少、能容忍故障更少"的层。除非有明确的冷数据场景且能接受更低可靠性,否则不要动 RRS。
6.5 S3 兼容性的边界:MinIO 实现了什么,没实现什么
这是"配置"的核心依据。MinIO 的 S3 兼容性分三层。
第一层,核心对象操作,完整实现:PutObject、GetObject、HeadObject、DeleteObject、CopyObject、Multipart 全流程(CreateMultipartUpload / UploadPart / UploadPartCopy / CompleteMultipartUpload / AbortMultipartUpload / ListParts / ListMultipartUploads)、ListObjectsV2、DeleteObjects(批量删除)。
第二层,行为有差异,必须校准:
| 能力 | MinIO 行为 | 与 AWS 的差异 | 应对 |
|---|---|---|---|
| ETag | 单次 PUT 且未加密时是 MD5;分片上传是 MD5(各分片MD5拼接)-分片数 |
与 AWS 规则一致,但业务常假设 ETag 就是整体 MD5 | 不要用 ETag 判断内容一致性;秒传用 x-amz-checksum-* 或业务自存哈希 |
| 校验和 | 支持 CRC32C / CRC32 / SHA1 / SHA256(x-amz-checksum-*) |
与 AWS 新校验和机制的对齐程度因版本而异 | 先 HeadObject 看是否有 x-amz-checksum-crc32c,再决定客户端是否强制校验 |
ListObjectsV2 分页 |
continuation-token、start-after、delimiter、max-keys(上限 1000) |
一致 | 分页必须用 continuation-token,不要手工翻 marker |
| 强一致 | 读后写一致、列表后写一致(XFS/ZFS/btrfs 上);NFS 后端不保证 | AWS 也强一致,但 MinIO 的保证依赖底层文件系统 | 不用 ext4,不用 NFSv3 挂数据盘 |
| Object Lock | 支持,但必须建桶时开启 | 一致 | 事后 mc version enable 不等于开了 Object Lock |
| 版本控制 | 支持 Enabled/Suspended | 大体一致 | 想清楚删除语义:删对象只是加删除标记,空间不释放 |
| 事件通知 | webhook、amqp、kafka、nats、postgres、redis、elasticsearch |
不支持 AWS Lambda/SQS/SNS 原生协议 | 用 Kafka 或 webhook 中间层对接 |
| 桶名 | 3~63 字符,小写字母/数字/连字符/点,不能是 IP 形式,不能以点或连字符开头结尾 | 一致 | 带点的桶名在 HTTPS 下会触发证书通配符不匹配 |
| Region | 默认 us-east-1,可改 |
客户端签名时必须与之一致 | SDK 的 region 写错会报 SignatureDoesNotMatch |
第三层,不实现或只做最小实现:S3 Select(部分版本有,行为受限)、S3 Object Lambda、S3 Access Points、S3 Transfer Acceleration、跨账号 ACL(MinIO 用桶策略替代 ACL,ACL 接口只做兼容性响应)。
这条边界很重要:如果业务代码用了 S3 Access Points 或 S3 Object Lambda,换到 MinIO 上一定跑不通,且报错信息往往很模糊(NotImplemented 或直接 MalformedXML)。选型阶段就要把业务用到的 S3 API 拉一个清单逐个验证,不要等上线才发现。
怎么快速出一个"用了哪些 API"的清单:在测试环境开 mc admin trace,跑一轮业务的完整流程(上传、下载、列表、删除、分片),把 trace 里的 Call 与 Method 去重,就是真实的依赖清单:
bashmc admin trace --verbose --duration 300s myminio 2>&1 \
| grep -oE '(S3\.)?[A-Z][A-Za-z]+\(' | sort | uniq -c | sort -rn
七、整体实施思路
按下面六步走,每一步都有独立验证点,不通过不进入下一步:
text[1] 单节点准备(磁盘、文件系统、系统参数、用户)
↓ 验证:单节点 minio server 能起来,写入能落盘
[2] 单节点伪集群(同一节点 4 个目录模拟 4 块盘)
↓ 验证:mc 能连上,能建桶,能上传下载,纠删集大小符合预期
[3] 4 节点集群搭建(systemd 管理,统一 root 凭据)
↓ 验证:mc admin info 显示 4/4 节点、16/16 盘 OK
[4] 负载均衡与 TLS(Nginx 反向代理 + 证书)
↓ 验证:通过域名上传下载,证书链完整,签名正确
[5] S3 兼容性配置(用户、策略、桶策略、预签名、跨域、事件)
↓ 验证:aws-cli / SDK 走一遍核心流程
[6] 监控与配置备份
↓ 验证:Prometheus 抓到指标,IAM/桶配置已导出
为什么第 2 步要单独做"单节点伪集群":4 节点集群的问题九成出在"配置不一致"——root 凭据不一致、盘路径不一致、时间不同步、MTU 不一致、版本不一致。先用单节点的 4 个目录把 mc 客户端、systemd 单元、环境变量文件这一套跑通,再复制到 4 台机器,能省掉大量"四台机器逐个登录看日志"的时间。这个步骤大约 20 分钟,但能省掉半天。
为什么不做"直接上四台":四台机器同时起不来时,你面对的是"四个日志、四种可能",定位成本是单节点的四倍。分步走的价值在于"每一步只有一个变量"。
目录与用户规划
text/data/minio/disk1 ← /dev/nvme0n1
/data/minio/disk2 ← /dev/nvme1n1
/data/minio/disk3 ← /dev/nvme2n1
/data/minio/disk4 ← /dev/nvme3n1
要点:
- 每块盘独立挂载,不要 LVM 跨盘、不要 RAID。MinIO 自己管冗余,下面再做一层 RAID 是重复冗余,还会让"单盘故障"变成"整组故障"。
- 挂载点放进
/etc/fstab时用UUID,加nofail,避免某块盘挂不上导致整机进入紧急模式。但要注意:nofail会让 MinIO 在盘缺失时静默启动,表现是mc admin info显示少一块盘。所以要在 systemd 单元里加RequiresMountsFor=强制依赖挂载点,让启动失败而不是降级启动。 - 目录属主设为专用用户
minio-user,不要用 root 跑服务。 - 每个挂载点单独一个文件系统,不要在一个大盘上 mkdir 出 4 个目录充当 4 块盘(除了测试)。伪盘会让"盘故障"和"节点故障"变成同一件事,纠删码的容错完全失效。
bash# 创建专用用户(无登录权限)
useradd -r -s /sbin/nologin -M minio-user
# 格式化并挂载(以第一块盘为例,其余三块同理)
mkfs.xfs -f -L minio1 /dev/nvme0n1
mkdir -p /data/minio/disk1
blkid /dev/nvme0n1 # 取 UUID,形如 UUID="0a1b2c3d-..."
# 写入 /etc/fstab:
# UUID=0a1b2c3d-... /data/minio/disk1 xfs defaults,noatime,nofail 0 0
mount -a
chown -R minio-user:minio-user /data/minio
mkfs.xfs -f 的 -f 是强制格式化,会抹掉盘上原有数据。执行前务必 lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT 确认盘符,别把系统盘格式化了。这是最典型的手滑事故,且不可恢复。稳妥做法是把盘符先记到表格里,插盘时按物理位置逐个确认,且确认 df -h 里看不到该盘已挂载业务数据。
noatime 是必须的:对象存储每秒大量读写,atime 更新会带来额外元数据写入。nobarrier 不要加,XFS 的 barrier 对掉电后的数据一致性有意义。
XFS 参数是否需要调优:默认 mkfs.xfs 在较新版本(5.10+ 内核)会做恰当的对齐。如果你想显式指定,MinIO 场景下常用的设置是:
bash# 仅在有明确理由时使用,默认值通常够
mkfs.xfs -f -L minio1 -d su=256k,sw=4 -n ftype=1 /dev/nvme0n1
ftype=1 是必须的(XFS 默认已经是 1),否则不支持 d_type,MinIO 会拒绝启动。su/sw 的条带参数在 SSD 上意义不大,HDD 阵列上才需要按 RAID 条带宽度对齐——但既然不建议叠 RAID,这两个参数通常会用到的人不多。不确定就用默认值,不要抄网上的"最优参数"。
八、实战步骤一:系统层准备
目标:四台机器在系统层面完全一致,为 MinIO 提供稳定底座。
8.1 系统参数
bashcat > /etc/sysctl.d/99-minio.conf <<'EOF'
# 并发连接数大,backlog 与端口范围要放大
net.core.somaxconn = 4096
net.ipv4.tcp_max_syn_backlog = 8192
net.ipv4.ip_local_port_range = 10000 65000
# TCP 缓冲区:万兆网络下默认值偏小,影响大对象吞吐
net.core.rmem_max = 33554432
net.core.wmem_max = 33554432
net.ipv4.tcp_rmem = 4096 87380 33554432
net.ipv4.tcp_wmem = 4096 65536 33554432
# 短连接多(客户端不断新建连接),开启 TIME_WAIT 复用
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 15
# 文件句柄上限
fs.file-max = 2000000
fs.inotify.max_user_watches = 524288
EOF
sysctl --system >/dev/null
sysctl net.core.somaxconn net.ipv4.tcp_tw_reuse fs.file-max
预期输出:
textnet.core.somaxconn = 4096
net.ipv4.tcp_tw_reuse = 1
fs.file-max = 2000000
如果仍是旧值,说明有更高优先级的配置文件覆盖(通常是 /etc/sysctl.conf,其加载顺序可能在后):
bashgrep -rn "somaxconn" /etc/sysctl.conf /etc/sysctl.d/ | grep -v 99-minio
sysctl -a 2>/dev/null | grep somaxconn
参数逐条说明与风险:
| 参数 | 作用 | 风险 |
|---|---|---|
somaxconn |
accept 队列长度 | 太小会导致高并发时连接被拒绝(SYN 丢),日志表现是客户端 connection reset |
tcp_tw_reuse |
复用 TIME_WAIT 状态的连接 | NAT 环境下可能导致 TCP 时间戳误判,跨 NAT 集群先评估 |
rmem_max/wmem_max |
单 socket 缓冲区上限 | 调大后内存占用上限提高,32GB 机器安全,8GB 机器不要照抄 |
fs.file-max |
全局句柄上限 | 与 ulimit -n 是两个层面,都要配 |
8.2 进程级限制
bashcat > /etc/security/limits.d/99-minio.conf <<'EOF'
minio-user soft nofile 1048576
minio-user hard nofile 1048576
minio-user soft nproc 65535
minio-user hard nproc 65535
EOF
重要:这些限制对 systemd 启动的服务不生效。systemd 服务的限制由单元文件里的 LimitNOFILE= 控制,两处都要配。这一点踩坑的人极多:改完 limits.conf 重启服务,cat /proc/<pid>/limits 还是 1024,以为是配置没生效,其实是 systemd 根本不读这个文件。
验证方式:
bashpid=$(systemctl show -p MainPID --value minio)
cat /proc/"$pid"/limits | grep -E "open files|processes"
# 期望:Max open files 1048576 1048576
8.3 SELinux 与防火墙
Rocky/Alma 默认 SELinux=enforcing,MinIO 会因上下文不符而无法写入数据目录:
bashgetenforce
# 若为 Enforcing:
semanage fcontext -a -t container_file_t "/data/minio(/.*)?"
restorecon -Rv /data/minio
setsebool -P httpd_can_network_connect 1 # 仅在使用 Nginx 反代时需要
semanage port -a -t http_port_t -p tcp 9000 || sestatus -b | grep 9000
restorecon 的输出会逐条列出"重新标记"的文件,看到 /data/minio/disk1 等路径就说明生效。如果 semanage: command not found,先装 policycoreutils-python-utils。
如果不想处理 SELinux,务实的选择是 setenforce 0 + /etc/selinux/config 里设 SELINUX=permissive,但要记录为"合规豁免项"。不要既不配策略又强行 Enforcing,然后反复 chcon -t unconfined_t 打补丁——那不是方案,是掩盖。
8.4 安装 MinIO 服务端与客户端
bash# 服务端
curl -fSLo /usr/local/bin/minio \
https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x /usr/local/bin/minio
minio --version
预期输出:
textminio version RELEASE.2025-10-15T17-29-55Z (commit-id=...)
Runtime: go1.24.x linux/amd64
License: GNU AGPLv3 <https://www.gnu.org/licenses/agpl-3.0.html>
Copyright: 2015-2025 MinIO, Inc.
bash# 客户端
curl -fSLo /usr/local/bin/mc \
https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x /usr/local/bin/mc
mc --version
务必记录输出的完整版本号,后续所有节点必须一致。MinIO 的服务端版本不一致会导致节点无法加入集群(mc admin info 里显示某节点 offline,日志报版本不匹配)。
平台与离线环境:
- ARM 平台把 URL 里的
amd64换成arm64; - 离线环境在有网机器下载后
scp分发,并在内网自建更新源:mc admin update --update-url https://mirror.example.internal/minio/,不要把"每次升级都去公网下"当成长期方案; - 不要用
apt install minio或社区源里的包。发行版仓库里的 MinIO 往往落后一两年,且可能被改过默认行为。只用官方二进制。
校验完整性(下载链路被劫持或中断都会导致二进制损坏,损坏的二进制可能能启动但行为异常):
bashcurl -fSLo /tmp/minio.sha256sum \
https://dl.min.io/server/minio/release/linux-amd64/minio.sha256sum
cd /usr/local/bin && sha256sum -c /tmp/minio.sha256sum
# 预期:minio: OK
sha256sum -c 要求清单文件里的路径与当前目录对应。如果不在同目录,用 sha256sum -c /tmp/minio.sha256sum 会报 No such file or directory,此时先 cd 到二进制所在目录。
8.5 环境变量文件
社区版推荐的部署方式是"环境变量文件 + systemd 单元"。root 凭据只放在环境变量文件里,权限 640、属主 root:minio-user。
bashcat > /etc/default/minio <<'EOF'
# 四个节点必须完全一致
MINIO_VOLUMES="http://minio{1...4}.example.internal:9000/data/minio/disk{1...4}"
# API 与 Console 监听地址(Console 只绑本机,禁止公网暴露)
MINIO_OPTS="--address :9000 --console-address 127.0.0.1:9001"
# 根凭据:access key ≥ 3 字符,secret key ≥ 8 字符,实际请用 20+ 位随机串
MINIO_ROOT_USER="opsadmin"
MINIO_ROOT_PASSWORD="请替换为 openssl rand -base64 24 生成的强口令"
# 存储类
MINIO_STORAGE_CLASS_STANDARD="EC:4"
# 控制台对外地址(反代 + 自定义域名时必须配,否则跳转到 ip:9000)
MINIO_BROWSER_REDIRECT_URL="https://console.example.com"
# 生成预签名 URL 的基准地址(详见 10.4)
MINIO_SERVER_URL="https://s3.example.com"
# 关闭升级检查(内网环境避免外联)
MINIO_UPDATE="off"
EOF
chown root:minio-user /etc/default/minio
chmod 640 /etc/default/minio
ls -l /etc/default/minio
生成强口令:
bashopenssl rand -base64 24 | tr -d '/+=' | cut -c1-24
# 输出 24 位随机串,直接粘进上面文件;不要用 && 拼接,避免特殊字符进 shell 历史
MINIO_VOLUMES 的写法是整套方案最容易错的地方,逐条解释:
- 使用
{1...4}序号展开(三个点,不是两个点)。两个点{1..4}会被 shell 展开,MinIO 收到 4 个独立字符串,纠删集分布会变。因为写在环境变量文件里由 systemd 解析、不经过 shell,这一点在 systemd 模式下相对安全;但命令行调试时务必用三点:
bash# 正确:三个点,由 MinIO 自己展开
minio server http://host{1...4}/data/disk{1...4}
# 错误:两个点,被 bash 展开成 4 个独立 URL,纠删集顺序可能错乱
minio server http://host{1..4}/data/disk{1..4}
- 每个节点执行时,这一行完全相同。MinIO 会识别本机 IP 并把对应目录挂到本节点——不需要(也不能)为每台机器写不同的 volumes。
- 主机名解析必须可靠。
minio1.example.internal的解析要么走/etc/hosts,要么走内网 DNS。不要用会变的动态 IP,也不要用环回地址,否则节点重启后 IP 变化会导致集群错乱。如果必须用 IP,四个节点的顺序要严格一致。 - 路径必须已存在且为空。MinIO 要求初始化时目录为空;有残留文件(比如上次测试留下的)会启动失败并报
Unable to initialize backend。
一个不明显的约束:MINIO_VOLUMES 里的主机名必须在所有四个节点上都能解析到同一个 IP。如果某台机器的 /etc/hosts 写错了,那台机器会认为自己在跟一个不存在的节点通信,表现是集群能起但只有一个节点 offline,且日志里没有明显错误。
8.6 systemd 单元
bashcat > /etc/systemd/system/minio.service <<'EOF'
[Unit]
Description=MinIO Object Storage
Documentation=https://min.io/docs/minio/linux/index.html
Wants=network-online.target
After=network-online.target
# 数据盘挂载失败时不启动,避免"少一块盘的降级集群"
RequiresMountsFor=/data/minio/disk1 /data/minio/disk2 /data/minio/disk3 /data/minio/disk4
AssertFileIsExecutable=/usr/local/bin/minio
[Service]
Type=notify
NotifyAccess=main
User=minio-user
Group=minio-user
EnvironmentFile=/etc/default/minio
ExecStartPre=/bin/bash -c 'if [ -z "${MINIO_VOLUMES}" ]; then echo "MINIO_VOLUMES not set"; exit 1; fi'
ExecStart=/usr/local/bin/minio server $MINIO_OPTS $MINIO_VOLUMES
# 优雅退出:给在途请求 30 秒
TimeoutStopSec=30
# 启动等待:4 节点集群首次握手可能较慢
TimeoutStartSec=300
Restart=always
RestartSec=5
LimitNOFILE=1048576
LimitNPROC=65535
# 内存保护:避免 OOM 时被系统优先杀
OOMScoreAdjust=-500
# 安全加固
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
ReadWritePaths=/data/minio
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable minio
systemctl start minio
systemctl status minio --no-pager
逐项说明为什么这样配:
| 配置 | 作用 | 不这么配的后果 |
|---|---|---|
Type=notify |
服务通过 sd_notify 上报就绪状态 | 用 simple 时,进程一起来就算 running,实际还在等其它节点,监控误判为"已就绪" |
RequiresMountsFor |
挂载点不存在则不启动 | 某块盘掉了,MinIO 带着 12 块盘起来,集群静默降级,而 systemctl status 显示正常 |
ExecStartPre |
校验 MINIO_VOLUMES 非空 |
变量为空时 MinIO 会以单机模式启动,误把一块盘当成独立集群,后续接入会数据错乱 |
TimeoutStartSec=300 |
首次握手给足时间 | 默认 90 秒,大集群首次启动可能超时被 systemd 杀掉 |
ProtectSystem=full + ReadWritePaths |
系统目录只读,仅放行数据目录 | 只写 ProtectSystem=full 会导致 MinIO 无法写 /data/minio,报 Permission denied |
OOMScoreAdjust=-500 |
降低被 OOM killer 杀的概率 | 内存紧张时 MinIO 被优先杀掉,集群反复抖动 |
ProtectHome=true 的副作用:如果证书放在 /home/minio-user/.minio/certs/,ProtectHome 会让该目录不可访问,MinIO 读不到证书。所以证书一律放 /data/minio/certs(见 10.2),不要用 ~/.minio 默认路径。
8.7 单节点伪集群验证
在正式上四台之前,先在 minio1 这一台上用 4 个目录起伪集群,把客户端、策略、TLS、监控这一整套流程验证一遍。
bashmkdir -p /tmp/minio-test/disk{1..4}
chown -R minio-user:minio-user /tmp/minio-test
sudo -u minio-user /usr/local/bin/minio server \
/tmp/minio-test/disk{1..4} \
--address :9100 --console-address 127.0.0.1:9101 &
# 说明:这里是 4 个本地目录,用 shell 的 {1..4}(两个点)即可,
# 不是分布式,不存在纠删集顺序问题
预期日志:
textMinIO Object Storage Server
Copyright: 2015-2025 MinIO, Inc.
License: GNU AGPLv3 <https://www.gnu.org/licenses/agpl-3.0.html>
Version: RELEASE.2025-10-15T17-29-55Z (go1.24.x linux/amd64)
API: http://10.0.10.11:9100 http://127.0.0.1:9100
WebUI: http://127.0.0.1:9101
Status: 4 Online, 0 Offline.
看到 4 Online, 0 Offline 说明底层 OK。接着验证 mc:
bashmc alias set test http://127.0.0.1:9100 opsadmin "$MINIO_ROOT_PASSWORD"
# 预期:Added `test` successfully.
mc admin info test
mc mb test/demo
printf 'hello minio\n' > /tmp/hello.txt
mc cp /tmp/hello.txt test/demo/
mc ls test/demo
mc cat test/demo/hello.txt
mc stat test/demo/hello.txt
这一步要验证的隐藏点:
mc admin info里Set: 1, Drives per set: 4。如果显示Drives per set: 2或Set: 2,说明 MinIO 选了你没预期的纠删集大小,容量与容错都要重算。mc stat的ETag是 32 位十六进制(单次 PUT 的 MD5)。如果不是,说明走了分片上传,会影响业务的"按 ETag 秒传"逻辑。mc ls的时间戳与本地时区一致。不一致说明服务端 TZ 与客户端不同,排查日志时会错位。
测试完清理:
bashjobs -p | xargs -r kill
rm -rf /tmp/minio-test
风险提示:rm -rf /tmp/minio-test 在测试环境无害,但如果你把它误用在 /data/minio 上就是灾难。给清理脚本加绝对路径白名单校验:
bashtarget=/tmp/minio-test
case "$target" in
/tmp/minio-test*) rm -rf -- "$target" ;;
*) echo "refuse to delete $target" >&2; exit 1 ;;
esac
九、实战步骤三:四节点集群正式搭建
9.1 一致性检查脚本
在四台机器上分别执行以下脚本,把输出贴到一起对比,任何一行不一致都不要继续。
bash#!/usr/bin/env bash
# check-consistency.sh —— 在四个节点分别执行,对比输出
set -euo pipefail
echo "=== hostname / ip ==="
hostname; hostname -I
echo "=== minio version ==="
/usr/local/bin/minio --version | head -1
echo "=== volume string ==="
grep '^MINIO_VOLUMES' /etc/default/minio
echo "=== root user ==="
grep '^MINIO_ROOT_USER' /etc/default/minio
echo "=== password sha256 (只比哈希,不泄露明文) ==="
grep '^MINIO_ROOT_PASSWORD' /etc/default/minio | sed 's/.*="\(.*\)"/\1/' | sha256sum
echo "=== storage class ==="
grep -E '^MINIO_STORAGE_CLASS' /etc/default/minio || echo "unset"
echo "=== disks ==="
df -hT | awk '$2=="xfs" || $2=="ext4" {print $1, $2, $7}'
echo "=== mtu ==="
ip -o link show | awk '{print $2, $NF}' | grep -E 'mtu'
echo "=== ntp offset ==="
chronyc tracking 2>/dev/null | grep "System time" || echo "chrony not running"
echo "=== kernel max files ==="
cat /proc/sys/fs/file-max
echo "=== selinux ==="
getenforce 2>/dev/null || echo "not installed"
这个脚本的重点是密码哈希对比:直接 grep 明文密码在屏幕上是泄露,用 sha256sum 只比哈希。四台机器哈希一致即密码一致,不一致就报 Specified credentials are not valid。
9.2 启动与验证
四台机器同时(或在 1 分钟内)启动:
bash# 依次执行(间隔不要太长,MinIO 集群启动时节点会互相等待)
for h in minio1 minio2 minio3 minio4; do
ssh "$h" 'systemctl restart minio'
done
# 等 10 秒后检查
systemctl status minio --no-pager | head -12
预期日志(节选):
textStatus: 16 Online, 0 Offline.
API: http://10.0.10.11:9000 http://10.0.10.12:9000 http://10.0.10.13:9000 http://10.0.10.14:9000
WebUI: http://10.0.10.11:9001 ...
16 Online, 0 Offline 是关键。如果显示 15 Online, 1 Offline:
bash# 第一步:在任一节点看日志,找 offline 的节点 IP
journalctl -u minio -n 200 --no-pager | grep -iE "offline|error|unreachable|not reachable"
# 第二步:从故障节点上反向测试连通性
# 在 minio2 上执行
for h in minio1 minio3 minio4; do
nc -zv -w 3 "$h" 9000 && echo "$h:9000 OK" || echo "$h:9000 FAIL"
done
# 第三步:如果连通正常但节点仍 offline,检查时钟
chronyc tracking
| 异常表现 | 判断依据 | 下一步 |
|---|---|---|
Unable to initialize backend: Unsupported backend format |
目录里有残留数据(非空) | 确认该目录可清空后重建;先确认这是新盘 |
Specified credentials are not valid |
四节点 root 凭据不一致 | 用 9.1 脚本对比密码哈希 |
节点 offline 且 nc 通但报 TLS/协议错误 |
版本不一致 | 统一版本后逐个重启 |
某节点反复重启,日志有 drive is not mounted |
盘未挂载或挂载点权限错 | df -h 确认,mount -a 重试 |
集群起得来但 mc admin info 超时 |
反代/防火墙问题,或 mc 版本过旧 |
直连 9000 测试排除反代 |
9.3 建桶与基础策略
bashmc alias set myminio http://10.0.10.11:9000 opsadmin "$MINIO_ROOT_PASSWORD"
mc admin info myminio
# 建桶:生产桶一律带版本控制,备份桶额外带 Object Lock
mc mb myminio/app-assets
mc mb myminio/backup-db
mc version enable myminio/app-assets
# Object Lock 必须在建桶时开启,事后无法追加
mc mb --with-lock myminio/audit-log
mc mb --with-lock --with-versioning myminio/backup-db-immutable
--with-lock 的语义:建一个带对象锁能力的桶,默认会自动启用版本控制。开启后桶内对象可以设置保留期(Retention)与合规模式(Compliance),在保留期内包括 root 用户在内都无法删除。这是勒索病毒防护的核心手段,但用错了也麻烦:测试桶不要开,否则测试数据删不掉,只能用 mc admin 强行解除保留(合规模式下连 root 也解不了,只能等过期)。
bash# 查看桶的锁配置
mc stat myminio/audit-log
# 预期输出含 Governance/Compliance 模式的 Object Lock 信息
9.5 建桶与对象锁
bashmc alias set myminio http://10.0.10.11:9000 opsadmin "$MINIO_ROOT_PASSWORD"
mc admin info myminio
# 业务桶:开启版本控制(便于误删恢复)
mc mb myminio/app-assets
mc version enable myminio/app-assets
# 审计桶:建桶时开启 Object Lock,事后无法补开
mc mb --with-lock myminio/audit-log
# 备份桶:Object Lock + 版本控制
mc mb --with-lock myminio/backup-db-immutable
# 确认
mc version info myminio/app-assets
mc stat myminio/audit-log
预期 mc version info 输出形如:
textmyminio/app-assets versioning is enabled
--with-lock 的准确语义:建一个具备对象锁能力的桶,同时自动启用版本控制。开启后桶内对象可设置保留期(Retention),分治理模式(Governance)与合规模式(Compliance)。合规模式下包括 root 用户在内都无法提前删除,只能等保留期结束。这是应对勒索病毒的关键手段,但用错了也麻烦:测试桶不要开,否则测试数据删不掉。
Object Lock 是桶级不可逆的开关:建桶时没开,事后无法补开。这对"上线三个月后发现需要防删除"的场景是硬约束,所以备份桶、审计桶在规划阶段就要决定。费用上也没有额外成本,早开不亏。
版本控制开与不开的取舍:
| 维度 | 开启 | 不开启 |
|---|---|---|
| 误删恢复 | 可以恢复(删的是当前版本,历史还在) | 无 |
| 覆盖恢复 | 可以回滚到旧版本 | 无 |
| 存储开销 | 每次覆盖都留一份 | 只保留最新 |
| 容量治理 | 必须配 NoncurrentVersionExpiration,否则空间无限涨 |
简单 |
| 删除语义 | mc rm 只是加删除标记,mc ls 看不到但空间不释放 |
真删 |
建议:业务桶开版本控制 + 30 天非当前版本过期;纯临时中转桶不开。开了不管,是最常见的"存储悄悄涨满"原因,见第十三节场景四。
9.6 纠删集分配确认
建好集群后第一件事是确认纠删集的实际分配,因为这是后续所有容量与容错判断的基准。
bashmc admin info myminio | grep -iE "pool|set|drive"
预期看到类似:
textPool: 1
Set: 1, Drives per set: 8
Set: 2, Drives per set: 8
16 块盘,MinIO 可能选 8 而不是 16。原因是"每个节点参与相同数量盘"的约束:16 块盘分 4 节点,每节点 4 块。若纠删集为 16,则每节点贡献 4 块,可行;若为 8,则每个 set 每节点贡献 2 块,也可行。MinIO 的具体选择取决于版本实现与参数,以实际输出为准,不要按理论推导。
判断是否合理的实用规则:
text纠删集大小 S ∈ {2,4,8,16},需同时满足:
1. 总盘数 % S == 0
2. S % 节点数 == 0(每个节点在 set 中贡献相同盘数)
3. S / 节点数 ≥ 1
在满足条件的 S 中取实际输出值,若与预期不符,重算容量与容错。
关键动作:把实际输出记进运维文档。以后有人问"我们坏两块盘会不会丢数据",答案取决于这个数字:8 块 set + EC:4,坏 2 块可读写;16 块 set + EC:4,坏 2 块可读写,坏 5 块只读,坏 9 块不可恢复。
bashmkdir -p /var/log/minio
{
echo "### $(date +%F) 集群拓扑快照"
mc admin info myminio | sed -n '/^Pool/,/^$/p'
} >> /var/log/minio/topology-history.log
tail -20 /var/log/minio/topology-history.log
这个快照的价值:出故障时,你需要知道"故障发生前的拓扑"。事后才去查,可能集群已经变了(比如 heal 完成、盘状态变化)。建议加进 crontab 每周一次,并保留一年。
十、实战步骤四:TLS 与负载均衡
10.1 为什么需要反代
MinIO 集群本身可以直连任一节点的 9000 端口(节点间会自动转发请求),但生产环境仍需反向代理,原因有三:
- 统一入口与证书:客户端只认一个域名,不用在四台机器的配置文件里不断增减 IP;
- TLS 卸载或透传:证书只在反代上维护一份;
- 访问控制:可以在反代层做 IP 白名单、限速、请求体大小限制。
MinIO 官方建议:如果用反代,反代必须正确设置 X-Forwarded-* 头、必须支持 HTTP/1.1 的 Transfer-Encoding: chunked 透传、并且不能改写 Host 头——S3 的签名(SigV4)对 Host/URI/Headers 做哈希,任何一处被改写都会导致 SignatureDoesNotMatch。
10.2 MinIO 自身的 TLS 配置
MinIO 支持直接从目录加载证书,无需配置文件:
bash# 证书路径必须严格为:
# ~/.minio/certs/public.crt (服务端证书,含完整链)
# ~/.minio/certs/private.key (私钥)
# 当以 minio-user 运行时,实际路径是:
# /home/minio-user/.minio/certs/
# 也可以在 MINIO_CONFIG_DIR 指定根目录
mkdir -p /data/minio/certs
# 把 证书链(server + 中间证书)和私钥放进去
cp fullchain.pem /data/minio/certs/public.crt
cp privkey.pem /data/minio/certs/private.key
# 仅为内部 CAs / mTLS 时需要
# cp ca.pem /data/minio/certs/CAs/example-ca.crt
chown -R minio-user:minio-user /data/minio/certs
chmod 600 /data/minio/certs/private.key
# 环境变量文件里指定证书目录(推荐显式声明,避免依赖 ~ 展开)
echo 'MINIO_CERTS_DIR=/data/minio/certs' >> /etc/default/minio
然后在 MINIO_OPTS 里把监听改为 https:
bashMINIO_OPTS="--address :9000 --console-address 127.0.0.1:9001"
# MinIO 检测到证书后自动以 HTTPS 提供,无需改 --address
重启后 curl -k https://10.0.10.11:9000/minio/health/live 应返回 200。
风险:证书热更新。MinIO 支持检测到证书文件变化后自动重载,但四个节点必须同时更换,否则节点间 TLS 握手会因证书不互信而失败。正确做法是滚动更换:先在所有节点同时放好新旧两张证书(旧的继续被信任),再逐个替换域名证书。
10.3 Nginx 反代配置
nginx# /etc/nginx/conf.d/minio.conf
upstream minio_api {
# 1.29.7 起 keepalive 默认启用(每 worker 32 条),显式声明更清晰
keepalive 64;
least_conn;
server 10.0.10.11:9000 max_fails=3 fail_timeout=10s;
server 10.0.10.12:9000 max_fails=3 fail_timeout=10s;
server 10.0.10.13:9000 max_fails=3 fail_timeout=10s;
server 10.0.10.14:9000 max_fails=3 fail_timeout=10s;
}
upstream minio_console {
server 127.0.0.1:9001;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name s3.example.com;
ssl_certificate /etc/nginx/ssl/s3.example.com/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/s3.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_session_cache shared:SSL:20m;
ssl_session_timeout 10m;
# 大对象上传:0 表示不限制,由桶配额与应用层控制
client_max_body_size 0;
# 关掉请求缓冲,避免大文件落到 nginx 临时目录(双写磁盘)
proxy_request_buffering off;
# 分片上传/长传输需要较长超时,但不要把读超时设成 0(无限等)
proxy_connect_timeout 5s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
ignore_invalid_headers off;
proxy_buffering off;
location / {
proxy_pass http://minio_api;
proxy_http_version 1.1; # 1.29.7 起为默认值,保留以兼容旧版本
proxy_set_header Host $http_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_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-Port $server_port;
# 关键:清空 Connection 头,让 keepalive 生效
proxy_set_header Connection "";
}
}
逐条说明几个必踩的坑:
proxy_set_header Host $http_host——不能用 $host。$host 会把端口去掉,而 SigV4 签名时客户端签的是 Host: s3.example.com(不带端口)。反代如果转发 Host: s3.example.com 但客户端签的是 s3.example.com:443,签名就不过。用 $http_host 原样透传客户端的 Host 头,签名才能对上。如果反代监听非 443 端口,这个差异立刻显形。
proxy_buffering off——MinIO 的大对象下载如果被 nginx 缓冲,会先落到 proxy_temp_path 再发给客户端,磁盘 IO 翻倍且增加延迟。但注意:关掉缓冲后,nginx 无法在响应头到达后判断"是否该重试下一个上游",proxy_next_upstream 对响应体阶段失效。对对象存储来说这没关系——对象存储的重试由客户端 SDK 做(S3 SDK 都有重试策略),nginx 层的重试反而可能把大文件重复拉一遍。
client_max_body_size 0——对象存储要传几十 GB 的单对象(虽然更推荐分片),nginx 默认 1MB 的限制必须解除。同时建议在应用层限制单对象大小(大量小对象也伤元数据,见第十四节)。
proxy_request_buffering off——大文件上传时 nginx 不缓存请求体,边收边转。副作用是:一旦开始转发,请求就不能再换上游重试。对对象存储可接受。
HTTP/2 的方向:http2 on 作用于客户端到 nginx 这一段。nginx 到 MinIO 这一段仍是 HTTP/1.1(proxy_http_version 1.1)。nginx 1.29.4 起支持 proxy_http_version 2 连后端,但 MinIO 对 h2 的代理支持要看版本,不要贸然开启——先在小流量环境验证 mc cp 与分片上传是否正常。
验证配置:
bashnginx -t
# 预期:nginx: configuration file /etc/nginx/nginx.conf test is successful
nginx -s reload
生效验证:
bash# 1. 健康检查走反代
curl -sS -o /dev/null -w "%{http_code}\n" https://s3.example.com/minio/health/live
# 预期:200
# 2. 用 mc 走域名测试签名
mc alias set s3 https://s3.example.com opsadmin "$MINIO_ROOT_PASSWORD"
mc ls s3
# 若报 SignatureDoesNotMatch,先查 Host 头与时钟:
date -u; chronyc tracking
# 3. 大对象上传测试(1GB,验证 chunked 与超时)
dd if=/dev/urandom of=/tmp/test1g.bin bs=1M count=1024 status=none
time mc cp /tmp/test1g.bin s3/app-assets/
# 预期:速度接近网络带宽,不出现 400/408/504
10.4 预签名 URL 的 Host 问题
这是 S3 兼容性里最高频的线上故障。预签名 URL(Presigned URL)在生成时把 Host 头算进签名,客户端访问时的 Host 必须与签名时一致。
text场景:应用通过 http://10.0.10.11:9000 生成预签名 URL,但把 https://s3.example.com/... 返回给浏览器
结果:SignatureDoesNotMatch
原因:签名时 Host=10.0.10.11:9000,访问时 Host=s3.example.com
解决方式(按推荐顺序):
- 应用侧只用对外域名生成预签名:SDK 初始化时
endpoint写https://s3.example.com,让 SDK 走域名而不是内网 IP。这要求应用服务器能解析并访问该域名(内网 DNS 指到反代即可)。 - 使用
MINIO_SERVER_URL:MinIO 会用它作为生成预签名 URL 的基准地址:
bash# /etc/default/minio 追加(必须是 HTTPS 公网可达地址)
MINIO_SERVER_URL="https://s3.example.com"
配置后,即使客户端用内网 IP 建连,MinIO 生成的预签名 URL 也会用 s3.example.com 作为 Host。注意:同时配了 MINIO_SERVER_URL 与反向代理时,要确保该域名确实能访问到本集群,否则返回的 URL 打不开。
- 反向代理改写:不推荐。改写 URL 会让签名失效,只有在你同时能改签名的情况下可行,实际等于自己实现一套签名逻辑。
验证:
bash# 用 mc 生成一个 7 天有效的下载链接
mc share download --expire 168h myminio/app-assets/demo.png
# 预期输出形如:Share: https://s3.example.com/app-assets/demo.png?X-Amz-Algorithm=...
# 用 curl 验证(不要带额外头,模拟浏览器)
curl -sS -o /dev/null -w "%{http_code} %{size_download}\n" "粘贴上面的URL"
# 预期:200 与文件大小
如果返回 403 且 XML 里是 SignatureDoesNotMatch,用 mc admin trace --verbose myminio 同时观察服务端收到的请求,对比 Host 与 X-Amz-Credential 的 region 字段。
十一、实战步骤五:S3 兼容性配置(用户、策略、CORS、事件)
11.1 用户与访问密钥的分层
生产环境不要用 root 凭据跑业务。分层原则:
textroot(opsadmin) → 只用于集群管理,不签发 AccessKey,不做业务调用
service account(服务账号)→ 每个应用一个,绑定限定策略
user(人类账号) → 每个运维一个,便于审计
bash# 1. 创建应用用户(不带策略时默认无任何权限)
mc admin user add myminio app-uploader '强随机口令'
# 2. 写策略文件:只允许对 app-assets 桶的 Put/Get/List
cat > /tmp/policy-app-uploader.json <<'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject",
"s3:AbortMultipartUpload",
"s3:ListMultipartUploadParts"
],
"Resource": ["arn:aws:s3:::app-assets/*"]
},
{
"Effect": "Allow",
"Action": ["s3:ListBucket", "s3:GetBucketLocation"],
"Resource": ["arn:aws:s3:::app-assets"]
}
]
}
EOF
# 3. 创建策略并绑定
mc admin policy create myminio app-uploader-policy /tmp/policy-app-uploader.json
mc admin policy attach myminio app-uploader-policy --user app-uploader
# 4. 验证:用该用户只能访问指定桶
mc alias set up http://10.0.10.11:9000 app-uploader '强随机口令'
mc ls up # 预期:列出 app-assets
mc ls up/backup-db # 预期:Access Denied
mc cp /tmp/hello.txt up/app-assets/ # 预期:成功
几个策略细节,写错了就是权限漏洞:
s3:ListBucket的 Resource 是桶本身(arn:aws:s3:::bucket),不是bucket/*。写成bucket/*的话,mc ls会报 Access Denied,而mc cat正常——这种"一半能用"最容易让人误判成权限没问题。s3:GetObject的 Resource 是对象(bucket/*)。写反了导致列表能看、下载不能下。- 需要分片上传就必须给
s3:AbortMultipartUpload和s3:ListMultipartUploadParts。只给PutObject时,小文件能传、大文件报AccessDenied——因为大文件走的是CreateMultipartUpload。 - 不要用
"Resource": "*"图省事。MinIO 的策略是"显式允许"模型,*在多层桶共用集群时等于把整个集群的读写权交出去。
11.2 服务账号(Service Account)替代明文密钥
对于应用,比"用户 + 密码换 AccessKey"更合适的是服务账号——它继承父用户的策略,可以进一步限制到更小的范围,并且可以设置过期时间。
bash# 给 app-uploader 创建一个服务账号,限制到期时间与更窄的策略
mc admin accesskey create myminio app-uploader \
--name ci-uploader \
--expiry 90d \
--policy /tmp/policy-ci-narrow.json
# 输出里会给出 accessKey 与 secretKey,只能看到一次,立即存入密钥管理系统
这条纪律要写进流程:AccessKey 只能在创建时看到,丢了只能重新创建。不要把 secretKey 贴进 Git、写进 Dockerfile、打进镜像层、写进前端 JS。CI 里用 Secret 变量注入,运行时用环境变量或 Vault/KMS 拉取。
11.3 桶策略 vs 用户策略:并集逻辑
MinIO 的鉴权是用户策略与桶策略的并集:
text最终权限 = 用户附加的策略(policy attach)∪ 桶上配置的策略(bucket policy)
这意味着桶策略可以给"任何匿名用户"开权限,也可以给特定账号开权限,是绕不过去的第二道门。 一个典型的误配置:运维为了让某个外部系统能下载文件,在桶策略里写了 Principal: {"AWS": ["*"]} + s3:GetObject,结果桶里所有对象都对公网可读。这个操作在控制台上只是一次点击,不会有人提醒你风险。
bash# 查看桶策略
mc anonymous get myminio/app-assets
# 预期:若未配置,返回 "Access permission for `myminio/app-assets` is `private`"
# 只开"下载"给匿名(常见的 CDN 回源场景,务必确认桶内无敏感数据)
mc anonymous set download myminio/cdn-public-assets
# 立即收回
mc anonymous set none myminio/app-assets
规则:允许匿名读的桶,命名里必须带 public,且在桶策略评审时单独列出。永远不要对备份桶、审计桶开匿名访问。
11.4 CORS:浏览器直传必须配
如果前端用 JS 直接上传(而不是经后端转发),必须配置 CORS,否则浏览器预检(OPTIONS)会被拒:
bashcat > /tmp/cors.json <<'EOF'
{
"CORSRules": [
{
"AllowedOrigins": ["https://www.example.com", "https://admin.example.com"],
"AllowedMethods": ["GET", "PUT", "POST", "HEAD"],
"AllowedHeaders": ["*"],
"ExposeHeaders": ["ETag", "x-amz-request-id", "x-amz-version-id", "Content-Length"],
"MaxAgeSeconds": 3600
}
]
}
EOF
mc cors set myminio/app-assets /tmp/cors.json
mc cors get myminio/app-assets
ExposeHeaders 里必须包含 ETag。浏览器默认只暴露少数几个响应头,前端拿不到 ETag 就无法在分片上传时组装 CompleteMultipartUpload,表现为"上传成功但文件不完整"或"合并时报错"。
AllowedOrigins 不要写 *,尤其当同时允许 PUT 时——等于允许任何站点向你的桶写数据(配合匿名写策略就是灾难)。
11.5 事件通知
MinIO 支持把对象事件推送到 Kafka/AMQP/Webhook/PG/Redis/ES。以 Kafka 为例(用于"上传后触发转码/入库"):
bash# 配置 Kafka 目标(target id 自取,如 kafka-main)
mc admin config set myminio notify_kafka:kafka-main \
brokers="kafka1:9092,kafka2:9092,kafka3:9092" \
topic="" \
sasl_plain="off" \
tls="off" \
queue_limit="100000"
mc admin service restart myminio
mc admin service restart 会重启整个集群,这是高风险操作,必须在维护窗口执行,并提前确认没有大文件正在上传(中断的上传需要客户端重新开始)。
bash# 给桶绑定事件
mc event add myminio/app-assets arn:minio:sqs::kafka-main:kafka \
--event put,delete --ignore-existing
mc event list myminio/app-assets
注意事项:
--ignore-existing只对绑定前的对象生效(不补发历史事件),绑定后新增的才推送。- 事件是至少一次语义,消费端必须幂等。
- 目标不可用时会本地排队(受
queue_limit限制),队列满了丢事件。不要把queue_limit设太大,那会吃内存;宁可丢事件也不要 OOM,丢的事件可以通过"定期全量扫描 + 对比"补。
11.6 用 aws-cli 做交叉验证
S3 兼容性最可靠的验证不是看文档,而是用标准 S3 客户端跑一遍。aws-cli 是最接近中立的测试工具:
bash# 安装后配置(注意 --endpoint-url 与 region)
aws configure set aws_access_key_id app-uploader
aws configure set aws_secret_access_key '强随机口令'
aws configure set default.region us-east-1
# 1. 列表
aws --endpoint-url https://s3.example.com s3api list-buckets
# 2. 简单上传/下载
aws --endpoint-url https://s3.example.com s3 cp /tmp/hello.txt s3://app-assets/hello.txt
# 3. 分片上传(阈值 8MB,强制走 multipart)
aws --endpoint-url https://s3.example.com s3 cp /tmp/test1g.bin s3://app-assets/test1g.bin \
--cli-write-timeout 0 --cli-read-timeout 0
# 4. 校验 ETag 与校验和
aws --endpoint-url https://s3.example.com s3api head-object \
--bucket app-assets --key test1g.bin
# 5. 批量删除
aws --endpoint-url https://s3.example.com s3api delete-objects --bucket app-assets \
--delete '{"Objects":[{"Key":"hello.txt"}],"Quiet":false}'
# 6. 预签名(生成后用 curl 验证)
aws --endpoint-url https://s3.example.com s3 presign s3://app-assets/test1g.bin --expires-in 3600
预期输出对照:
| 命令 | 预期 | 异常时看什么 |
|---|---|---|
list-buckets |
返回 JSON,Buckets 数组 |
SignatureDoesNotMatch → region/Host;AccessDenied → 策略 |
s3 cp 小文件 |
upload: ... to s3://... |
403 → 缺 PutObject |
s3 cp 大文件 |
同上,但走 multipart | AccessDenied → 缺 AbortMultipartUpload |
head-object |
含 ETag、ContentLength、Metadata |
ETag 带 -N 后缀说明是分片上传 |
delete-objects |
"Deleted": [...] |
MalformedXML → JSON 格式错 |
presign |
输出 URL | 返回 403 → Host 不一致 |
如果 aws-cli 能过但业务 SDK 不过,问题基本在 SDK 层:要么 SDK 版本太老不支持新接口,要么 SDK 默认开启了 MinIO 不支持的特性(例如新版 Java SDK 默认启用 checksum 相关的新行为,某些 MinIO 版本会报错)。此时用 mc admin trace 抓服务端实际收到的请求头,与 SDK 文档对照。mc admin trace 的用法:
bashmc admin trace --verbose --errors-only myminio
# 只显示错误请求;去掉 --errors-only 看全部
# 输出里有完整的 method、path、header、response code 与耗时
mc admin trace 会打印请求头,包含 Authorization 签名,不要在公网环境或录屏时开着它。生产排查建议限制时间(--duration 30s)并只开 --errors-only。
十二、常用命令速查与判断依据
12.1 集群状态类
bash# 集群概览(节点、盘、容量、纠删集)
mc admin info myminio
# 只看盘的健康与剩余空间(含每块盘的 UUID、pool、set 归属)
mc admin info myminio --json | jq -r '
.info.servers[] | .endpoint as $e | .drives[] |
[$e, .path, .state, (.totalspace|tostring), (.usedspace|tostring)] | @tsv'
# 服务端日志(相当于看 journalctl,但走 HTTP,不用登服务器)
mc admin logs myminio --type error --limit 200
# 实时 API 追踪(排查兼容性/延迟问题)
mc admin trace --verbose --errors-only --duration 30s myminio
# 慢请求筛查(按耗时过滤,字段位置以实际输出为准)
mc admin trace --verbose --duration 30s myminio | awk '$NF>200'
mc admin info 的输出怎么读,把每一行都对应上判断依据:
text● 10.0.10.11:9000
Uptime: 21 days
Version: RELEASE.2025-10-15T17-29-55Z
Network: 4/4 OK
Drives: 4/4 OK
16 drives online, 0 drives offline, 0 drives healing
| 字段 | 含义 | 异常判断 |
|---|---|---|
Uptime |
该节点连续运行时长 | 与其他节点差异大 → 该节点重启过,查 journalctl -u minio 找重启原因 |
Version |
二进制版本 | 与其他节点不同 → 必须立刻统一 |
Network: n/n OK |
到其他节点的连通性 | 小于总数 → 节点间网络问题,nc -zv 逐对测 |
Drives: n/m OK |
本节点盘状态 | 小于总数 → 换盘或查挂载 |
drives healing |
正在修复的盘数 | 长时间不为 0 → heal 卡住,查 mc admin heal 进度 |
drives offline |
离线盘数 | > 0 立刻处理,别等 |
12.2 容量类
bash# 集群容量(显示的是裸容量与已用,不是可用容量)
mc admin info myminio | grep -E "Used|Capacity"
# 单桶容量与对象数(会遍历,大桶慎用)
mc du myminio/app-assets
mc du --depth 2 myminio/app-assets # 按前缀汇总
# 顶层前缀的对象数与大小分布
mc ls -r --json myminio/app-assets | jq -s '
group_by(.key|split("/")[0]) |
map({prefix: (.[0].key|split("/")[0]), count: length, bytes: (map(.size)|add)})'
mc du 在大桶上是重操作:它要 ListObjectsV2 递归遍历,千万对象级别的桶可能跑十几分钟并占用服务端 CPU。生产上建议:
- 用 Prometheus 指标
minio_bucket_usage_total_bytes/minio_bucket_objects_count(需开启 bucket metrics 采集)替代实时遍历; - 或者按前缀分段跑,避免一次性扫全桶;
- 不要在业务高峰跑,
mc du的遍历会与业务 List 请求争抢资源。
12.3 对象操作与排查
bash# 对象的完整元数据(ETag、版本、校验和、标签)
mc stat myminio/app-assets/demo.png
# 列出未完成的分片上传(清理僵尸分片的前提)
mc ls --incomplete myminio/app-assets
# 对象版本列表
mc ls --versions myminio/app-assets/demo.png
# 删除指定版本(版本 ID 从上一命令取)
mc rm --version-id "3HL4kqtJlcpXroDTDmJrmSpXd3dIbrHYMTRCxf3vjVBH40Nr8X8gdRQBpUMLUo" \
myminio/app-assets/demo.png
# 带校验和上传,并让服务端计算 CRC32C
mc cp /tmp/hello.txt myminio/app-assets/ --checksum CRC32C
清理残留分片的两种方式,先说风险小的:
bash# 方式一(推荐):生命周期规则自动清理,安全、可审计
cat > /tmp/ilm.json <<'EOF'
{
"Rules": [
{
"ID": "abort-stale-multipart",
"Status": "Enabled",
"Filter": {"Prefix": ""},
"AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 3}
},
{
"ID": "expire-tmp-prefix",
"Status": "Enabled",
"Filter": {"Prefix": "tmp/"},
"Expiration": {"Days": 7}
}
]
}
EOF
mc ilm import myminio/app-assets < /tmp/ilm.json
mc ilm rule ls myminio/app-assets
# 方式二(手工):先看再删,必须带 --older-than
mc ls --incomplete --recursive myminio/app-assets | head -20
mc rm --incomplete --recursive --force --older-than 7d myminio/app-assets
手工清理的影响范围:删除的是"上传中断但未 Abort"的分片数据,这些分片占着实际存储空间但不可访问。删除后,仍在上传中的客户端(超过 7 天还没传完的)会失败。所以:
- 前置检查:
mc ls --incomplete确认哪些是多天前的残留,不要一键全删; - 替代方案:客户端侧确保异常时调
AbortMultipartUpload,服务端配生命周期兜底; - 回滚:不可回滚,分片数据删除后上传必须重来。但残留分片本身没有业务价值,风险主要在"误删正在进行的上传"。
验证生命周期是否真的在跑:看 mc admin logs 里 scanner 的相关日志,或查 Prometheus 的 ILM 过期任务指标(具体名称以你的版本 curl /minio/v2/metrics/cluster 输出为准)。生命周期是异步、按 scanner 周期执行的,不是到点立刻删,别按小时级精度要求它。
12.4 配置管理
bash# 查看全部动态配置
mc admin config get myminio
# 逐项查看(如 API 限流、scanner 速度、region)
mc admin config get myminio api
mc admin config get myminio scanner
mc admin config get myminio region
# 修改(示例:限制单节点 API 并发请求数,防止单个客户端打爆)
mc admin config set myminio api requests_max=3200
mc admin config set myminio region name="cn-north-1"
# 让配置生效
mc admin service restart myminio
mc admin service restart 是集群级重启,等同于四台机器同时重启。影响:正在进行的上传/下载全部中断;客户端需要重试。不要在业务高峰执行。如果只想让某个配置生效,先看 mc admin config get 输出里该项是否标注需要重启——大部分 api、scanner 类配置热生效,region、MINIO_VOLUMES 类必须重启。
12.5 修复(heal)
bash# 全量扫描并修复(后台运行,输出实时进度)
mc admin heal -r myminio
# 只扫某个桶/前缀
mc admin heal -r myminio/app-assets
# 只报告不修复(先看规模)
mc admin heal -r --dry-run myminio/app-assets
# 只修复元数据(不重传数据块,速度快)
mc admin heal -r --mode metadata myminio/app-assets
heal 的触发时机:
- 换盘之后(新盘加入,需要把缺失的分片重建回来);
- 节点长时间离线后重新加入;
mc admin info显示drives healing长时间不为 0;- 读对象报
XMinioReadQuorum(读仲裁不足)。
heal 的代价:它遍历全部对象并比对每块盘的分片,是重 I/O 操作。100TB 级别的集群全量 heal 可能持续数小时到数天,期间集群吞吐下降。所以:
- 优先 heal 受影响的前缀,不要无脑全量;
- 在低峰期跑,或先用
--dry-run评估规模; - 观察日志里的 heal 计数增长,确认在推进而不是卡死。
判断 heal 是否真在推进:mc admin heal 的进度条是估算值,不可靠。看 mc admin logs --type info 里 healed 相关日志的递增,或前后两次 mc du 的差值。
十三、故障排查:五类典型场景的闭环
场景一:上传大文件报 XMinioWriteQuorum 或 5xx
现象:小于 5MB 的文件正常,大文件传到 30%~80% 时失败,客户端报 500 或 XMinioWriteQuorum。
初判:写入时某纠删集的可用分片数低于写仲裁,通常是节点/盘掉线,或网络抖动导致分片写入超时。
检查:
bash# 1. 确认集群状态(是否有盘 offline)
mc admin info myminio | grep -E "drives|Drives"
# 2. 确认没有正在进行的 heal 占满 IO
mc admin info myminio | grep -i heal
iotop -o -b -n 1 | head -20
# 3. 抓出错请求的具体信息
mc admin trace --verbose --errors-only --duration 60s myminio
# 关注返回码与 <Error><Code>,以及涉及的 disk path
指标:minio_cluster_drive_offline_total、minio_cluster_capacity_usable_free_bytes、minio_cluster_nodes_offline_total。
根因(按概率排序):
- 某块盘 offline 但未达读仲裁阈值,小对象落在健康的 set 上能成功,大对象落到有病 set 上失败;
- 节点间网络抖动,分片 PUT 超时;
- 磁盘 IO 饱和(正在 heal 或备份任务抢 IO),写入超时被判失败。
修复:
bash# 若盘 offline:先在节点上确认为硬件/挂载问题
lsblk
dmesg -T | tail -50 | grep -iE "nvme|sd[a-z]|i/o error"
mountpoint /data/minio/disk3 || mount -a
systemctl restart minio # 单节点重启,四节点集群允许逐节点重启
验证:mc admin info 回到 16/16 OK,再次上传同一个大文件成功,耗时符合带宽预期。
回滚预案:如果重启后节点无法加入(版本或配置不一致),先停该节点的 minio,让集群以 15/16 运行,再排查节点本身。不要为了让它加入去改其他三个节点的版本。
复盘要点:写清楚"哪块盘、什么时间、为什么没在第一时间告警"。Drives: 15/16 这种状态如果持续超过 10 分钟没有告警,就是监控缺失,不是运维疏忽。
场景二:SignatureDoesNotMatch
现象:mc 直连 IP 正常,走域名/反代失败;或预签名 URL 在浏览器打开 403。
初判:签名要素之一不一致——Host、Region、被签名的 header、时间戳、密钥。
检查:
bash# 1. 核对 Host:客户端签的 Host 与反代转发的 Host 是否一致
mc admin trace --verbose --errors-only --duration 30s myminio | grep -i host
# 2. 核对 Region
mc admin config get myminio region
# 3. 核对时间偏移(签名有效期默认 15 分钟)
date -u
chronyc tracking
# 4. 核对客户端侧配置的 region 与 endpoint
aws configure list
证据链:mc admin trace 里会看到 Authorization: AWS4-HMAC-SHA256 Credential=xxx/20251107/us-east-1/s3/aws4_request,其中 20251107 是日期、us-east-1 是 region。服务端错误日志会明确指出签名不匹配。
根因:
| 证据 | 根因 | 修复 |
|---|---|---|
| Host 头被改写(少了端口或多了一层域名) | 反代用 $host 而非 $http_host,或多级反代未透传 |
改 nginx 配置,nginx -s reload |
| region 不一致 | SDK 配了 cn-north-1,服务端是 us-east-1 |
统一 region,或服务端 mc admin config set myminio region name=cn-north-1 |
| 时间差 > 15 分钟 | 节点未同步时间 | chronyc makestep,并确认 chrony 服务自启 |
| 预签名 URL 的 Host 与访问 Host 不同 | 用内网 IP 生成 URL 给外网用 | 配 MINIO_SERVER_URL 或统一用对外域名 |
验证:用 aws-cli 与 mc 各跑一次 ls,再用预签名 URL curl 一次。
回滚:反代配置改动先备份原文件(cp minio.conf minio.conf.bak.$(date +%F)),验证失败时 mv 回去 + nginx -s reload。
场景三:某节点反复 offline
现象:节点能在 ss -lntp 看到 9000 监听,但集群里显示 offline,重启后短暂恢复又掉。
初判:不是端口问题,而是节点间 RPC 或状态不一致。
检查:
bash# 1. 日志找具体原因(这是决定性证据)
journalctl -u minio -n 300 --no-pager | grep -iE "offline|peer|not reachable|version|time"
# 2. 四个节点的版本是否一致
for h in minio1 minio2 minio3 minio4; do
printf '%s: ' "$h"; ssh "$h" '/usr/local/bin/minio --version | head -1'
done
# 3. 时间同步
for h in minio1 minio2 minio3 minio4; do
printf '%s: ' "$h"; ssh "$h" 'chronyc tracking | grep "System time"'
done
# 4. 证书一致性(TLS 模式下证书不互信会导致 RPC 失败)
for h in minio1 minio2 minio3 minio4; do
printf '%s: ' "$h"
ssh "$h" 'openssl x509 -in /data/minio/certs/public.crt -noout -fingerprint -sha256'
done
根因表:
| 日志特征 | 根因 | 修复 |
|---|---|---|
Version mismatch found |
二进制版本不一致 | 统一版本,逐节点滚动重启 |
Unable to read the drive + 盘路径 |
盘掉了/挂载丢了 | mount -a,修 fstab |
| TLS 握手错误 | 证书不一致或过期 | 统一证书,滚动更新 |
Unable to initialize backend |
目录非空或有权限问题 | 检查目录内容与属主 |
drive is not writable |
SELinux 或文件系统只读 | getenforce,mount -o remount,rw |
修复后验证:mc admin info 显示 4/4 Nodes OK 并保持 30 分钟不掉,mc admin trace 无周期性重连。
回滚:如果统一版本后问题更严重(新版本引入 bug),按时间戳版本回退。MinIO 支持降级到较早版本,但必须先看 release notes 是否声明了不可逆的数据格式变更。跨年度版本降级有风险,需要先备份元数据(mc admin cluster iam export、mc admin cluster bucket export)。
场景四:写满后删除对象,空间不释放
现象:mc admin info 显示容量满,删了一批对象,容量没变。
初判:三个可能——版本控制留了历史版本、删的是"删除标记"、有未完成的分片。
检查:
bash# 1. 看对象是否有历史版本
mc ls --versions myminio/app-assets/demo.png
# 2. 查未完成分片占用的空间
mc ls --incomplete --recursive myminio/app-assets | head -20
# 3. 各前缀的真实用量
mc du --depth 2 myminio/app-assets | sort -k2 -h -r | head -20
# 4. 桶是否开启了版本控制
mc version info myminio/app-assets
根因与修复:
| 证据 | 根因 | 修复 |
|---|---|---|
mc ls --versions 有多版本 |
版本控制开启,历史版本占空间 | 用生命周期规则过期非当前版本 |
mc ls --incomplete 有大量条目 |
上传中断留下分片 | 配 AbortIncompleteMultipartUpload 生命周期 |
| 删除标记堆积 | 反复删同一对象 | 生命周期规则 ExpiredObjectDeleteMarker: true |
| 用量与实际不符 | 上次删除后 scanner 未跑完 | 等 scanner 周期,或 mc admin scanner info 查看 |
生命周期清理历史版本的正确写法:
bashcat > /tmp/ilm-versions.json <<'EOF'
{
"Rules": [
{
"ID": "keep-30d-noncurrent",
"Status": "Enabled",
"Filter": {"Prefix": ""},
"NoncurrentVersionExpiration": {"NoncurrentDays": 30},
"Expiration": {"ExpiredObjectDeleteMarker": true}
}
]
}
EOF
mc ilm import myminio/app-assets < /tmp/ilm-versions.json
mc ilm rule ls myminio/app-assets
风险与灰度:先用 mc ls --versions 抽样看历史版本的数量与价值,再在测试桶上跑 30 天,确认没有应用依赖旧版本,才上生产。这是真正的删除操作,没有回收站。
场景五:删除桶失败,报 BucketNotEmpty
现象:mc rb myminio/old-bucket 报 The bucket you tried to delete is not empty,但 mc ls 看起来是空的。
检查:
bash# 1. 看隐藏的删除标记与历史版本
mc ls --versions --recursive myminio/old-bucket | head -20
# 2. 看未完成的分片
mc ls --incomplete --recursive myminio/old-bucket | head -20
# 3. 显式统计对象数
mc ls --recursive myminio/old-bucket | wc -l
根因:桶里有 mc ls 默认不显示的删除标记或非当前版本;或者有分片。
修复:
bash# 先清历史版本(高危,务必确认桶可废弃)
mc rm --recursive --versions --force --dangerous myminio/old-bucket
# 再删桶
mc rb myminio/old-bucket
--dangerous 的作用:绕过"版本存在时拒绝删除"的检查。它不做任何确认,不加 --force 会逐条询问(交互式,脚本里会卡住)。批量删除必须先 dry-run:
bash# 先导出将删除的清单,人工确认
mc ls --recursive --versions myminio/old-bucket | awk '{print $NF}' > /tmp/to-delete.txt
wc -l /tmp/to-delete.txt
head -20 /tmp/to-delete.txt
# 确认后执行,并保留清单作为审计记录
mc rm --recursive --versions --force --dangerous myminio/old-bucket 2>&1 \
| tee "/var/log/minio-purge-$(date +%F).log"
生产纪律:删桶是不可逆操作。执行前必须:
- 确认桶里没有 Object Lock 保留中的对象(有的话删不掉,报
ObjectLocked); - 确认桶没有被其他集群复制或 site replication 引用;
- 在维护窗口执行,通知相关业务方;
- 保留删除清单与执行日志。
十四、生产注意事项
14.0 前车之鉴:三类"不满足规则"的扩容
在讲正确的扩容方式之前,先看三种踩过的坑,它们比正确姿势更能说明问题。
坑一:把"新增节点"当成"加盘"。有人看到 4 节点 16 块盘,想再买 4 块盘插到现有节点上空槽位,直接改 MINIO_VOLUMES 为 disk{1...5}。结果四台机器启动时报:
textERROR Unable to initialize backend: drive count mismatch
或者更隐蔽地,集群能起来但 mc admin info 显示 Pool: 1,只有原来 16 块盘被识别,新增的 4 块完全没用上。原因是 MinIO 的纠删集在首次启动时写入元数据,后续启动必须完全匹配。只有"新增池"能让卷数增加,池内无法扩盘。
坑二:只改了一台机器的 MINIO_VOLUMES。这个过程通常是:把新节点加进来,在新节点上写了新的 volumes(含第二池),然后 systemctl start minio。新节点起来了,但报:
textERROR Unable to initialize backend: Invalid arguments specified: number of erasure sets mismatch
或者新节点直接 offline。因为四台老节点仍然只认一个池,新节点自称是两个池,握手失败。
坑三:新池的纠删码配置与老池不同。老池 EC:4,新池因为盘数不同自动算出 EC:2,结果集群能起来,但新池的冗余度只有 50% 的校验块数量减半,且 MinIO 会明确要求"每个池必须有相同的纠删码配置"。日志里的措辞是 All pools must have the same parity configuration。这类问题的后果是:你以为扩容后可靠性不变,实际新池的容错能力更弱。
三个坑的共同点是:都在"改配置"这一步出的问题,而集群本身没问题。所以扩容的核心纪律是"配置一致性 + 一次性全量变更 + 先算清结果"。
14.1 扩容的正确姿势
不要往已有池子里加盘。MinIO 的纠删集在启动时固定,加盘无法改变。扩容只有一条路:新增池(server pool)。
bash# 原配置(4 节点 4 盘)
MINIO_VOLUMES="http://minio{1...4}.example.internal:9000/data/minio/disk{1...4}"
# 扩容后:追加第二组(4 节点 4 盘),两个池用空格分隔
MINIO_VOLUMES="http://minio{1...4}.example.internal:9000/data/minio/disk{1...4} http://minio{5...8}.example.internal:9000/data/minio/disk{1...4}"
扩容的操作顺序:
- 新节点按第三到第七节全套准备(系统参数、XFS、用户、证书、版本);
- **所有节点(新老)**同时修改
MINIO_VOLUMES,加上新池; - 滚动重启:先重启新节点(它们会等待),再重启老节点;
- 全部起来后
mc admin info应显示Pool: 2; - 新对象按"剩余空间比例"写入两个池,旧对象不会自动迁移。
关键风险:扩容期间如果只改了一部分节点,集群会因 volumes 不一致而拒绝启动。这是最容易出事故的一步——四台机器改三台,第四台慢了半拍,或者某台改错了路径。操作纪律:
- 用 Ansible 一次性推所有节点,不要手动逐台改;
- 改完先
grep VOLUMES /etc/default/minio四台对比; - 重启前拍一张配置校验和快照存证:
md5sum /etc/default/minio; - 选在业务低峰,并提前通知。
容量分布不均怎么办:扩容后新池空、老池满,写入会自动倾斜到新池,但已有旧数据仍在老池。如果老池已经逼近上限(超过 85%),需要 rebalance:
bash# 启动再均衡(后台任务,耗时可能数天)
mc admin rebalance start myminio
# 查看进度
mc admin rebalance status myminio
# 停止
mc admin rebalance stop myminio
rebalance 的代价:它会扫描并移动大量对象,产生巨大网络与磁盘 IO。100TB 数据可能跑几天,期间集群性能下降。所以:
- 不要在业务高峰期启动;
- 不要同时跑 heal 和 rebalance;
- 启动前确认监控告警阈值已放宽(否则告警风暴);
stop可以安全中断,已迁移的对象保持在新位置,不会回滚。
另一个方案:不 rebalance,接受容量不均。只要老池没超过安全水位(建议 < 80%),新写入会自动进新池,慢慢就均衡了。对多数团队,这比跑 rebalance 更划算。
14.2 升级与版本管理
MinIO 没有 LTS,每个 release 既可能是 bugfix 也可能是 breaking change。升级策略:
bash# 1. 查当前版本
mc admin info myminio | grep Version
# 2. 在测试集群验证目标版本(不是可选项)
# 3. 备份元数据(降级时的唯一依据)
mc admin cluster iam export myminio > /backup/minio/iam-pre-upgrade.zip
mc admin cluster bucket export myminio > /backup/minio/bucket-pre-upgrade.zip
# 4. 单节点滚动升级:先升级一个节点
systemctl stop minio
curl -fSLo /usr/local/bin/minio.new https://dl.min.io/server/minio/release/linux-amd64/minio
# 校验和必须匹配
curl -fsSLo /tmp/minio.sha256sum https://dl.min.io/server/minio/release/linux-amd64/minio.sha256sum
cd /tmp && sha256sum -c minio.sha256sum --ignore-missing 2>/dev/null || true
mv /usr/local/bin/minio.new /usr/local/bin/minio && chmod +x /usr/local/bin/minio
systemctl start minio
journalctl -u minio -n 50 --no-pager | grep -i version
# 5. 确认节点回归后再升下一个
mc admin info myminio | grep -E "Nodes|Version"
注意:MinIO 不保证"混版本运行"完全可用。滚动升级期间集群会短暂处于版本不一致状态,通常能容忍,但不要在这个状态下做其他变更,也不要在期间跑 rebalance。如果某个版本明确要求停机升级,按 release notes 执行。
回滚:保留旧二进制(cp /usr/local/bin/minio /usr/local/bin/minio.bak.$(date +%F))。回滚前提是该版本没有引入不可逆的元数据格式变更。跨年度版本回滚前务必查 release notes 的 “Upgrade Notes”。
14.3 监控指标(以 Prometheus 实际输出为准)
社区版通过 mc admin prometheus generate 生成抓取配置:
bashmc admin prometheus generate myminio
输出类似:
yaml- job_name: minio-job
bearer_token: <JWT>
metrics_path: /minio/v2/metrics/cluster
scheme: https
static_configs:
- targets: ['s3.example.com']
bearer_token 的注意点:它是 mc 用当前凭据生成的 JWT,有有效期。生产上应创建专门的长期服务账号,用该账号生成 token,并把 token 存进密钥管理/配置管理系统中,不要让 Prometheus 配置成为唯一副本。更换凭据时记得同步更新。
核心指标与告警阈值(阈值需结合业务基线调整):
| 指标 | 含义 | 建议告警 |
|---|---|---|
minio_cluster_drive_offline_total |
离线盘数 | > 0 持续 5 分钟(P2) |
minio_cluster_capacity_usable_free_bytes |
可用剩余容量 | 低于总可用 20%(P2),低于 10%(P1) |
minio_cluster_nodes_offline_total |
离线节点数 | > 0 持续 1 分钟(P1) |
minio_s3_requests_errors_total |
4xx/5xx 请求数 | 5xx 比例 > 1% 持续 5 分钟 |
minio_s3_requests_waiting_total |
排队请求数 | 持续 > 0 且上升 |
minio_s3_ttfb_seconds |
首字节时间(直方图) | P99 > 1s(按业务调整) |
minio_cluster_usage_total_bytes |
已用容量 | 增长速率突增(可能被刷) |
minio_node_disk_used_bytes |
单盘已用 | 单盘 > 90%,或节点间差异 > 20% |
指标名的坑:MinIO 的指标前缀在不同版本间有调整(minio_cluster_* / minio_node_* / minio_system_* / minio_bucket_*)。必须用你的版本实际 curl 一次确认,不要照抄网上的 dashboard JSON:
bash# 直接拉指标,确认名字存在
curl -sSk -H "Authorization: Bearer <token>" \
https://s3.example.com/minio/v2/metrics/cluster \
| grep -E "^minio_.*(drive|capacity|error)" | head -30
告警阈值怎么写才不是拍脑袋:先采集两周数据,取 P95 作为基线,告警阈值设在基线的 2~3 倍,且必须"持续 3~5 个周期"才触发。MinIO 的 IO 有天然毛刺(scanner 周期、heal),单点超阈值告警会造成大量误报。
14.4 备份策略:备份的不是"集群",是"配置"
对象存储的"备份"是个容易误解的话题。数据本身靠纠删码 + 多节点冗余,副本级别已经够;真正的风险是误删、勒索、机房级故障。所以备份分四层:
| 层级 | 内容 | 手段 | 频率 |
|---|---|---|---|
| 配置 | IAM(用户/策略/组)、桶策略、生命周期、事件、加密配置 | mc admin cluster iam export / mc admin cluster bucket export |
每次变更后 |
| 数据(同城) | 关键桶 | mc mirror 到另一套集群 |
每日 |
| 数据(异地) | 核心桶 | mc mirror 到异地集群 |
每周 |
| 防勒索 | 审计/备份桶 | Object Lock + 合规模式 | 建桶时定 |
bash# 配置备份(每天定时,存入独立备份目录或 Git)
ts=$(date +%F_%H%M)
mkdir -p /backup/minio
mc admin cluster iam export myminio > "/backup/minio/iam-${ts}.zip"
mc admin cluster bucket export myminio > "/backup/minio/bucket-${ts}.zip"
ls -lh /backup/minio/
# 数据镜像(单向,把源桶同步到目标集群)
mc mirror --overwrite --preserve myminio/app-assets backup-minio/app-assets
mc mirror 常用参数:
--overwrite:覆盖目标同名对象(默认跳过已存在);--preserve:保留元数据(Content-Type、自定义元数据);--remove:删除目标端"源端已不存在"的对象(高危,先别加)。
mc mirror 的风险:它是"遍历源 + 逐对象比对",大桶耗时很长,并占用源集群的 List 配额。--remove 会让源端误删自动传播到备份,等于把备份变成镜像——备份的意义就没了。
验证备份可用(最重要的一步,很多人备份了三年没验证过):
bashkey="app-assets/2025/11/demo.png"
mc cat myminio/"$key" | sha256sum
mc cat backup-minio/"$key" | sha256sum
# 两个哈希必须一致
14.5 安全加固清单
| 项目 | 做法 | 验证 |
|---|---|---|
| root 凭据 | 24 位随机口令,只存密钥管理系统,不用于业务 | grep MINIO_ROOT_PASSWORD /etc/default/minio 确认非默认值 |
| 业务账号 | 每应用独立服务账号,最小权限,设过期时间 | mc admin accesskey ls myminio --user app-uploader |
| 匿名访问 | 默认全关,仅 *-public 桶例外 |
mc anonymous get myminio/<bucket> 逐个确认 |
| 传输加密 | 全链路 TLS,禁用 TLS1.0/1.1 | openssl s_client -connect s3.example.com:443 -tls1_1 应失败 |
| 静态加密 | SSE-S3(KMS)或 SSE-C | mc stat 看 X-Amz-Server-Side-Encryption |
| 控制台暴露 | 只监听 127.0.0.1,或密码保护 + IP 白名单 | `ss -lntp |
| 审计日志 | 开启审计 webhook,记录所有管理操作 | mc admin config get myminio audit_webhook |
| 防删除 | 关键桶开 Object Lock + 合规模式 | mc stat 查看锁配置 |
控制台的安全提醒:--console-address 127.0.0.1:9001 是必须的。默认 :9001 监听所有网卡,若机器有公网 IP,控制台直接暴露。社区版从 2025-05 版本起控制台能力被削减,但"能登录"这点没变,凭据泄露的后果一样严重。
审计日志配置示例:
bashmc admin config set myminio audit_webhook:primary \
endpoint="https://audit-collector.example.com/minio" \
auth_token="${MINIO_AUDIT_TOKEN}" \
queue_size=100000
mc admin service restart myminio
mc admin config get myminio audit_webhook
auth_token 的纪律:虽然示例里用了变量展开,但 mc admin config set 会把最终值写入集群配置目录(.minio.sys/config/)。这属于"明文落地",只是文件权限受限。更稳妥的是:审计采集端做双向 TLS 或 IP 白名单,token 只作为附加校验;token 轮换走密钥管理系统,不在脚本里硬编码。
十五、S3 兼容性回归测试清单
集群搭好、策略配好之后,还需要一套可重复执行的回归清单。每次升级版本、改反代配置、改桶策略,都跑一遍,能挡住绝大多数"升级之后业务偶发失败"的问题。
15.1 用 aws-cli 跑通最小闭环
bash#!/usr/bin/env bash
# s3-regress.sh —— MinIO S3 兼容性回归测试
# 用法:AWS_PROFILE=app ./s3-regress.sh https://s3.example.com app-assets
set -euo pipefail
ENDPOINT="${1:?usage: $0 <endpoint> <bucket>}"
BUCKET="${2:?usage: $0 <endpoint> <bucket>}"
TMP_DIR="$(mktemp -d)"
trap 'rm -rf -- "$TMP_DIR"' EXIT
pass=0; fail=0
check() {
local name="$1"; shift
if "$@" >"$TMP_DIR/out.txt" 2>&1; then
echo "PASS $name"
pass=$((pass+1))
else
echo "FAIL $name"
sed -n '1,5p' "$TMP_DIR/out.txt" | sed 's/^/ /'
fail=$((fail+1))
fi
}
# 1. 连通性
check "list-buckets" aws --endpoint-url "$ENDPOINT" s3api list-buckets
# 2. 小对象上传下载
printf 'regress-%s\n' "$(date +%s)" > "$TMP_DIR/small.txt"
check "put-small" aws --endpoint-url "$ENDPOINT" s3 cp "$TMP_DIR/small.txt" "s3://$BUCKET/_regress/small.txt"
check "get-small" aws --endpoint-url "$ENDPOINT" s3 cp "s3://$BUCKET/_regress/small.txt" "$TMP_DIR/small.out"
# 3. 内容一致性(不要用 ETag 比,直接比内容)
check "content-equal" diff -q "$TMP_DIR/small.txt" "$TMP_DIR/small.out"
# 4. 分片上传(20MB,超过 8MB 阈值必走 multipart)
dd if=/dev/urandom of="$TMP_DIR/big.bin" bs=1M count=20 status=none
check "put-multipart" aws --endpoint-url "$ENDPOINT" s3 cp "$TMP_DIR/big.bin" "s3://$BUCKET/_regress/big.bin"
check "get-multipart" aws --endpoint-url "$ENDPOINT" s3 cp "s3://$BUCKET/_regress/big.bin" "$TMP_DIR/big.out"
check "multipart-equal" cmp -s "$TMP_DIR/big.bin" "$TMP_DIR/big.out"
# 5. HeadObject 元数据
check "head-object" aws --endpoint-url "$ENDPOINT" s3api head-object --bucket "$BUCKET" --key _regress/big.bin
# 6. 列表分页
check "list-objects-v2" aws --endpoint-url "$ENDPOINT" s3api list-objects-v2 --bucket "$BUCKET" --max-keys 10
# 7. 预签名(生成后立即用 curl 访问)
url=$(aws --endpoint-url "$ENDPOINT" s3 presign "s3://$BUCKET/_regress/small.txt" --expires-in 300)
code=$(curl -sS -o /dev/null -w '%{http_code}' "$url")
if [ "$code" = "200" ]; then echo "PASS presign-get"; pass=$((pass+1));
else echo "FAIL presign-get (http $code)"; fail=$((fail+1)); fi
# 8. 批量删除
check "delete-objects" aws --endpoint-url "$ENDPOINT" s3api delete-objects --bucket "$BUCKET" \
--delete '{"Objects":[{"Key":"_regress/small.txt"},{"Key":"_regress/big.bin"}],"Quiet":false}'
echo "------------------------------"
echo "pass=$pass fail=$fail"
[ "$fail" -eq 0 ]
## 十六、总结
MinIO 集群的坑,八成不在"装不上",而在"装上了但没按它的规则用"。
**四条必须记住的规则**:
1. **纠删码 `EC:N` = N 数据 + N 校验**,16 块盘 `EC:4` 可用率 50%,不是 66%。容量规划按这个算,别按 RAID6 算。
2. **扩容只能加池,不能加盘;旧数据不会自动迁移**。四台机器同时改配置,用配置管理工具推,别手改。
3. **S3 签名对 Host 敏感**。反代必须 `proxy_set_header Host $http_host`,预签名 URL 要么统一用对外域名生成,要么配 `MINIO_SERVER_URL`。
4. **磁盘独立挂载、XFS、不用 ext4、不叠 RAID**。`RequiresMountsFor` 防止"少一块盘的静默降级"。
**三个必须建立的运维习惯**:
- **每天看一次 `mc admin info` 的 `drives offline` 与 `healing`**。不看,就等于把可靠性交给运气。
- **每次变更后导出 IAM 与桶配置**。集群配置丢了可以重建,IAM 和桶策略丢了要一条条回忆。
- **每月做一次"恢复演练"**:从备份集群随机拉 10 个对象比对哈希,从 IAM 导出文件恢复一个测试用户。没演练过的备份不叫备份。
**最后一个判断依据**:当有人说"MinIO 数据很安全,坏了 4 块盘都没事",你要反问的是——**那 4 块盘坏在同一个纠删集里吗?** 如果是,你已经处在只读边缘了。16 块盘分两个 set,每个 set