数据库/协同工具类型

MinIO 深度指南

MinIO 的作用定位、何时该用、核心机制（bucket/object/预签名/纠删码）、常见问题排查（CORS、权限、直传格式、大文件）、难点解决方案（分片上传、权限策略、扩容、迁移 OSS）与生产要点。

2026年7月19日

MinIO
对象存储

这是 MinIO 的深度参考文档。上手实操见 Nest 课程第十九章。

一、基础入门（5 分钟上手）

这一节带你把 MinIO 跑起来、用控制台和命令行传一个文件；Nest 课程那篇讲的是在应用里封装 MinioService、做预签名直传——两篇不重复。

1. 用 Docker 起一个 MinIO

docker run -d \
  --name minio \
  -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"

9000：S3 API 端口（代码连这个）。
9001：Web 控制台端口（浏览器打开）。
浏览器访问 http://localhost:9001 ，用 minioadmin / minioadmin 登录。

2. 用控制台玩（最简单）

控制台里点点鼠标就能：

左侧 Buckets → Create Bucket，起名 demo。
进 bucket → Upload，把一张图或一个 txt 传上去。
点文件 → Share 生成一个临时可访问的链接（这就是预签名 URL）。

3. 或用 mc 命令行（批量/脚本用）

本机装了 mc（MinIO 客户端，兼容 S3）后：

# 1) 配一个连接别名 local
mc alias set local http://localhost:9000 minioadmin minioadmin
# Added `local` successfully.

# 2) 建一个 bucket（桶）
mc mb local/demo
# Bucket created successfully `local/demo`.

# 3) 列出所有 bucket
mc ls local
# demo/

echo "hello" > a.txt

# 4) 上传文件
mc cp a.txt local/demo/
# ...a.txt: 6 B / 6 B ━━━━━━━━━ 100%

# 5) 看桶里的文件
mc ls local/demo
# a.txt

# 6) 读内容
mc cat local/demo/a.txt
# hello

# 7) 删
mc rm local/demo/a.txt
# Removed `local/demo/a.txt`.

4. 核心概念与 mc 命令

两个核心概念：

bucket（桶）：顶层容器，类似文件夹；命名全小写、全局唯一。
object（对象）：一个文件，由 桶名 / key 唯一定位（a/b/c.jpg 里的斜杠只是 key 的一部分，没有真正的目录）。

mc（MinIO Client，兼容 S3）常用命令：

命令	作用
`mc alias set <别名> <endpoint> <ak> <sk>`	配置一个连接
`mc mb <别名>/<桶>`	建桶
`mc ls <别名>` / `mc ls <别名>/<桶>`	列桶 / 列桶内文件
`mc cp <本地> <别名>/<桶>/`	上传
`mc cp <别名>/<桶>/<文件> <本地>`	下载
`mc cat <别名>/<桶>/<文件>`	看内容
`mc rm <别名>/<桶>/<文件>`	删文件
`mc mirror <本地> <别名>/<桶>`	整目录同步（镜像）
`mc find <别名>/<桶> --name "*.png"`	查找
`mc policy set <权限> <别名>/<桶>`	设桶权限

5. 权限与预签名

桶权限三档（mc policy）：none（私有，默认）、download（公开只读）、public（公开读写）。默认私有，外部访问要靠预签名。

预签名 URL：用 accessKey 在服务端生成一个带签名、带过期时间的临时链接，前端拿它直接上传/下载，accessKey 不暴露给前端：

mc share download --expire 1h <别名>/<桶>/<文件>   # 生成 1 小时有效的下载链接
mc share upload   --expire 1h <别名>/<桶>           # 生成上传链接

代码里对应 presignedGetObject / presignedPutObject。

6. 基本使用规则

文件进对象存储，DB 只存 URL：别把文件塞数据库（BLOB 会让库膨胀、备份慢）。
私有桶 + 预签名访问敏感文件，别图省事全公开。
accessKey 用最小权限子账号，绝不用 root key 给前端（预签名就是为了不给 key）。
限制单文件大小和类型（应用层或预签名时限定），防恶意上传。
客户端和服务端时间同步（NTP），否则签名校验失败（S3 签名容忍约 15 分钟时差）。
兼容 S3 协议：换阿里云 OSS / AWS S3 只改 endpoint + accessKey，代码不动。

7. 核心词汇速记

术语	一句话
bucket（桶）	文件的顶层容器，类似文件夹
object（对象）	一个文件，由 `桶名/key` 定位
endpoint	S3 API 地址，`http://localhost:9000`
accessKey / secretKey	账号密码，这里都是 `minioadmin`
预签名 URL	带签名的临时链接，让前端直传而不暴露 key
S3 协议	AWS 定的对象存储接口，MinIO/阿里云 OSS 都兼容

二、作用与定位

MinIO 是开源的对象存储，兼容 AWS S3 协议。核心价值：

存文件：图片、视频、文档、备份，存成「对象」而非文件系统。
S3 兼容：API 和阿里云 OSS、AWS S3 几乎一致，本地用 MinIO、生产换 OSS 几乎不改代码。
私有部署：数据在自己机器上，不依赖云厂商。

一句话：应用要存海量文件（用户头像、上传内容、备份），用对象存储（MinIO/OSS），别存本地磁盘。

三、何时该用 / 何时用别的

场景	选择
用户上传的图片/视频/文档	对象存储（MinIO/OSS）
临时文件、配置文件	本地磁盘
要公开 CDN 分发	OSS/CDN
数据私有、不能上云	MinIO（自建）

别存数据库（BLOB）：文件塞 DB 会让库膨胀、备份慢、查询拖累。文件进对象存储，DB 只存 URL。

四、核心机制速览

bucket（桶）：顶层容器，类似「文件夹」。权限按 bucket 设（私有 / 公开读）。
object（对象）：文件本身，由 bucket名 + object名（key） 唯一定位。没有真正的目录层级（a/b/c.jpg 是 key 里的斜杠）。
预签名 URL：服务端用 accessKey 生成一个带签名的临时 URL，前端拿它直接传/取文件，accessKey 不暴露给前端。
纠删码（Erasure Coding）：MinIO 把数据 + 校验块分散存多块盘，坏几块盘仍能恢复，数据安全。
S3 协议：PutObject/GetObject/presignedPutObject 等。

用图理解纠删码：对象上传时被切成「数据块 + 校验块」分散写到集群各节点，丢掉不超过校验块数的部分仍能还原——这就是 MinIO 用少量冗余换高可用的原理。

flowchart TB O["上传对象"] --> S["切分为数据块 + 校验块"] S --> N1["节点1"] S --> N2["节点2"] S --> N3["节点3"] S --> N4["节点4"] N2 -.->|"盘坏丢失"| R["凭其余块仍可还原"]

五、常见问题与排查

1. 前端直传报 CORS 错

原因：浏览器跨域请求 MinIO，MinIO 没配 CORS。

解决：在 bucket 或 MinIO 服务配 CORS 允许你的前端域名（PUT/GET/POST 方法、Authorization 等头）。OSS 控制台也有同样配置。

2. 直传格式：PUT 文件而非 FormData

坑：前端用惯了 FormData（multipart）上传，但 S3/MinIO 预签名 URL 要求 body 直接是文件内容（不是 multipart）。

// 正确：直接 PUT 文件
await axios.put(presignedUrl, file);

3. 文件访问 403 / 下载不了

原因：bucket 是私有的，没签名访问不了。

解决：要么 bucket 设公开读（匿名可访问，仅适合公开内容），要么用预签名 GET URL（带签名、带过期时间）临时授权访问。

4. 时间不同步导致签名失效

原因：S3 签名校验请求时间，客户端和 MinIO 服务器时间差超 15 分钟会签名失败。

解决：服务器和客户端都开 NTP 时间同步。

5. accessKey 权限过大

原因：用 root 账号的 accessKey 给前端，等于裸奔。

解决：建子账号 / 限权策略（只给某个 bucket 的读写），用最小权限的 key。预签名 URL 本身就是「不把 key 给前端」的正确做法。

六、难点与解决方案

1. 大文件上传（分片 / 断点续传）

单个 PUT 上限通常 5GB，且网络抖动一断全重来。大文件用 multipart 分片上传：

文件切成多片（如每片 5–10MB）。
每片独立上传（可并发、可失败重试单片）。
全部传完发 CompleteMultipartUpload 合并。
中途断了，记录已传片，续传未传的（断点续传）。

S3/MinIO 的 createMultipartUpload / uploadPart / completeMultipartUpload API 支持这套。前端常用 aws-sdk 或封装好的库。

2. 权限策略（IAM）

不止「公开/私有」二选一。用 bucket policy 精细控制：

某个前缀公开读（photos/* 公开，private/* 私有）。
某 IP 段才能访问。
某账号只能读写特定 bucket。

policy 是 JSON，按 S3 的策略语法写。

3. 扩容与分布式

单机 MinIO 有上限。生产用分布式 MinIO：多节点多盘，MinIO 自动做纠删码分布、数据均衡。难点：扩容加节点时数据要 rebalance（MinIO 的「server pool 扩展」）。上线前规划好容量，扩容比缩容容易。

一张图看清分布式 MinIO 拓扑：客户端经负载均衡连任一节点读写，各 Server 节点组成集群、彼此同步冗余。

flowchart TB C["客户端"] -->|"读写"| L["负载均衡"] L --> S1["Server 节点1"] L --> S2["Server 节点2"] L --> S3["Server 节点3"] S1 <-->|"纠删码冗余"| S2 S2 <-->|"纠删码冗余"| S3

4. 从 MinIO 迁移到云 OSS（或反向）

因为都兼容 S3 协议，用 aws s3 sync 或 mc mirror（MinIO Client）批量同步即可，业务代码只改 endPoint + accessKey。这是用 MinIO（而非自研存储）的最大收益——不绑定。

七、生产环境要点

用预签名 URL 做前端直传，accessKey 不进前端。
私有 bucket + 预签名 GET 访问敏感文件，别图省事全公开。
分布式部署 + 纠删码，数据安全。
限制单文件大小和类型（在应用层或预签名时限定）。
CDN 回源：公开且高频访问的文件挂 CDN，减轻 MinIO 压力、加速。
备份：重要数据多副本或异地同步（mc mirror 定时同步到另一套）。

速查：常见问题对照

问题	原因	解决
前端直传 CORS	没配跨域	MinIO/OSS 配 CORS
签名失败 / 403	时间不同步 / key 错 / 过期	NTP 同步、检查 key、预签名未过期
直传 400	用了 FormData	改 `axios.put(url, file)`
大文件传失败	单 PUT 上限 / 网络断	用 multipart 分片上传
下载 403	私有 bucket 无签名	预签名 GET URL