[!info] related notes

• 所属 MOC：Backend 常用中间件与基础设施 MOC
• 前置：分布式系统、数据复制
• 数据边界：数据库 MOC、事件驱动架构
• 流量入口：Nginx MOC

MinIO

[!abstract] 一句话定位 MinIO 是提供 S3-compatible API 的对象存储系统，适合保存图片、视频、附件、备份和模型文件等大对象。业务数据库保存对象的 ID、Owner、状态和元数据；MinIO 保存实际字节，两者的生命周期需要显式协调。

对象存储的核心模型

Bucket
└─ Object Key
   ├─ bytes
   ├─ metadata
   ├─ version
   └─ tags / retention

Object Key 可以长得像路径：

users/42/avatar.webp

但对象存储不是 POSIX 文件系统：没有相同的目录、inode、随机写和文件锁语义。

为什么大文件不应默认塞进业务数据库

把大量二进制数据直接放入关系型数据库，会放大：

• Backup / Restore；
• Replication；
• Connection 与 Query I/O；
• WAL / Binlog；
• 存储扩容和冷热分层成本。

常见分工：

Database
  object_id
  owner_id
  object_key
  status
  checksum
  size / content_type

MinIO
  actual object bytes

S3-compatible API

应用通常使用 S3 SDK 调用：

• PutObject / GetObject；
• HeadObject；
• DeleteObject；
• ListObjects；
• Multipart Upload；
• Presigned URL。

S3-compatible 的价值在于应用可以在自托管 MinIO 和其他 S3 API 存储之间复用相似访问模型，但兼容性细节仍应以实际 SDK / 功能测试为准。

推荐上传架构

Client
→ Backend: request upload intent
→ Backend: authenticate + authorize + create object record
→ Backend: return short-lived Presigned URL
→ Client: upload directly to MinIO
→ Client / event: confirm completion
→ Backend: verify object metadata / checksum
→ mark object ready

优点：大文件不经过应用服务器内存和带宽，同时权限决策仍由 Backend 掌握。

Presigned URL 的安全边界

Presigned URL 是短期签名授权，不代表对象永久公开。生成前应限制：

• HTTP Method；
• Bucket / Object Key；
• TTL；
• Owner / Tenant；
• Content Type；
• Size / Checksum；
• 后续确认流程。

不要让客户端任意指定 Bucket 或可覆盖其他用户对象的 Key。

Multipart Upload

Create Upload
→ Upload Part 1..N
→ Verify Part ETags / Checksums
→ Complete Multipart Upload

适合大文件和不稳定网络，失败时只重传部分数据。还要治理：

• 未完成 Upload 的过期清理；
• Part 数量和大小；
• 并发与带宽限制；
• Complete 的幂等和状态机；
• 客户端声称完成但对象实际缺失。

Erasure Coding

MinIO 将 Object 分成 Data Shards 与 Parity Shards，分布到 Erasure Set 的多个 Drive：

N = K data + M parity

只要保留足够 Shards，就能读取并重建损坏数据。与保存多个完整副本相比，Erasure Coding 常以更低存储冗余获得磁盘/节点容错。

Read / Write Quorum

读写都需要足够健康 Drive：

healthy shards >= read quorum  → can read / reconstruct
healthy drives >= write quorum → can accept writes

当 Parity 恰好是 Erasure Set 的一半时，Write Quorum 需要额外多数约束，避免两个隔离的半区同时写入。

[!warning] 原始磁盘不能手工改 MinIO 需要独占管理提供给它的 Drive / Volume。绕过 MinIO 直接移动、删除或修改内部 Shard 和 Metadata 可能导致无法恢复的损坏。

Erasure Coding、Replication 与 Backup

机制	主要解决
Erasure Coding	同一部署内 Drive / Node 故障与 Bit Rot
Replication	跨 Bucket / Site 复制和灾难隔离
Versioning	同一 Key 的历史版本与误覆盖恢复
Backup	独立恢复点，防逻辑误删、系统性故障或凭证事故

高可用不是备份。删除操作或错误数据也可能被复制到其他节点/站点。

Versioning、Lifecycle 与 Object Lock

Versioning

保留同一 Key 的多个版本，支持恢复误覆盖和历史对象。代价是旧版本持续占用空间。

Lifecycle

按 Age、Prefix、Tag 等规则自动过期或转换对象/旧版本，避免依赖应用定时扫描整个 Bucket。

Object Lock / Retention

用于 WORM、合规和不可篡改保留。它比普通 ACL 更强，启用前必须确认治理、恢复和成本要求。

数据库与对象存储的一致性

两个系统没有天然共同事务。典型失败窗口：

1. DB 记录已创建，Upload 从未完成；
2. Object 已上传，DB 确认失败；
3. DB 删除成功，对象删除失败；
4. Object 已删除，但旧 Presigned URL / 缓存仍存在；
5. 重试造成重复 Object 或覆盖错误版本。

常见方案：

state machine: pending → uploaded → verified → ready
idempotent object key / request id
outbox / async cleanup
periodic reconciliation
orphan object and broken reference scan

与 Nginx / CDN 的关系

• MinIO 负责对象存储和 S3 API；
• Nginx / Gateway 可负责 TLS、域名、访问入口和部分代理策略；
• CDN 负责边缘缓存和分发。

大文件代理可能增加应用或 Nginx 的带宽、Buffering 和 Timeout 压力，能直传时通常优先 Presigned URL。

适用与不适用

适合：用户上传、图片/视频、文档附件、模型 Artifact、备份、静态资源源站、数据湖对象。

不适合：高频小 Key Cache、全文搜索、关系查询和事务、Event Stream、POSIX 强语义共享文件系统。

高频生产问题

问题	排查方向
容量快速增长	Versioning、Multipart、Lifecycle、Replication、日志/备份策略
Orphan Object	上传/删除状态机、补偿与 Reconciliation
Broken DB Reference	对象存在性、版本、Key 和权限
Slow Upload	Client、Proxy、Network、Part Size、Disk、Erasure Write
Quorum Lost	Drive / Node / Network failure domain
Healing 长时间运行	故障规模、磁盘吞吐、容量余量

观测重点

request rate / latency / errors
bucket and object growth
raw vs usable capacity
node / drive health
read / write quorum
healing / replication backlog
multipart uploads
version and lifecycle growth
network and disk throughput

面试掌握标准

• Bucket、Object Key 与 S3 API；
• Presigned URL 与直传架构；
• Multipart Upload；
• Erasure Coding、Read/Write Quorum；
• Versioning、Lifecycle、Object Lock；
• Object Storage 与 DB / File System 的边界；
• 两系统一致性和 Orphan Reconciliation；
• 高可用为什么不等于 Backup。

官方资料

• MinIO documentation: https://min.io/docs/minio/linux/index.html
• Erasure Coding: https://min.io/docs/minio/linux/operations/concepts/erasure-coding.html
• S3 API compatibility: https://min.io/docs/minio/linux/reference/s3-api-compatibility.html

Related notes

• 数据库 MOC
• Nginx MOC
• Backend 常用中间件与基础设施 MOC