MinIO服务端用Docker启动需显式指定--console-address ":9001"（控制台端口）和默认API端口9000，凭证须与-e MINIO_ROOT_USER/-e MINIO_ROOT_PASSWORD严格一致且secretKey≥8位；Go客户端endpoint填"localhost:9000"（不带协议），Secure设false（本地HTTP），并封装单例、配置超时、流式直传避免落地磁盘。
MinIO 服务端怎么起，端口和凭证别配错
本地开发直接用 Docker 起 MinIO 最省事，但很多人卡在 endpoint 和认证上。关键不是“能不能跑起来”，而是 Gin 后端连得上、传得进、权限对不对。
常见错误现象：Connection refused 或 SignatureDoesNotMatch，基本都是 endpoint 写成 http://localhost:9000 却没开 HTTPS，或者 accessKey/secretKey 和容器启动时的环境变量不一致。
- Docker 命令必须显式指定
--console-address ":9001"，否则 Web 控制台打不开；API 默认走 9000 端口，不要加/minio或/api/v1这类路径 -
endpoint在 Go 代码里填"localhost:9000"（开发）或"minio.example.com:9000"（生产），不能带http://前缀 ——minio-go/v7的New函数会自己拼协议 - accessKey 和 secretKey 必须和
-e MINIO_ROOT_USER/-e MINIO_ROOT_PASSWORD完全一致，且 secretKey 至少 8 位；若用 bitnami/minio 镜像，注意它默认要求MINIO_ROOT_PASSWORD≥8 字符，否则容器启动失败
Go 代码里初始化 MinIO 客户端要注意什么
直接 new 一个 minio.Client 不够，得确保它能复用、可配置、带超时。硬编码 endpoint 和凭证的写法在 Gin 项目里迟早出问题。
推荐做法是把客户端封装成单例 + 配置注入，避免每次上传都新建连接。
- 用
minio.Options{Creds: credentials.NewStaticV4(...), Secure: false}初始化，Secure设为false表示走 HTTP（本地开发），生产环境必须设true并配好 TLS 证书 - 务必设置
Transport超时，否则大文件上传卡住时整个 Gin handler 会 hang 住：&http.Transport{IdleConnTimeout: 30 * time.Second, TLSHandshakeTimeout: 10 * time.Second} - 别在 handler 里调
minio.New—— 每次请求都建新 client 会耗尽 fd，应提前初始化好，通过依赖注入或全局变量传入
Gin 处理文件上传时如何直传 MinIO 而不落地磁盘
用户上传文件，Gin 接收后不存本地，直接流式转发到 MinIO，这是最常用也最容易翻车的路径。核心是别用 file.Open()，要用 multipart.File 的 reader 直接喂给 PutObject。
典型错误：先 c.FormFile("file") 拿到临时文件路径，再 os.Open —— 这等于多一次磁盘 IO，还可能因临时目录权限或清理策略失败。
- 用
file, header, err := c.Request.FormFile("file")获取 multipart file reader，header.Filename是原始名，header.Size可做大小限制 -
PutObject第三个参数接受io.Reader，直接传file即可，不用中间转[]byte—— 否则内存爆掉 - 务必检查
header.Size是否超过预期（比如 >50MB），在PutObject前就return，不然 MinIO 会接收完才报错，浪费带宽
生成预签名 URL 供前端直传或下载时容易漏掉的细节
前端需要上传凭证或下载链接时，后端用 PresignedPutObject 或 PresignedGetObject 生成签名 URL，但有效期、bucket、object key 的一致性常被忽略。
现象：前端拿到 URL 后 403 或 404，查日志发现签名过期、key 不匹配、或 bucket 名写错。
-
PresignedPutObject的objectName必须和前端实际 PUT 请求的 path 完全一致（包括前缀如uploads/2026/xxx.jpg），不能只传文件名 - 有效期单位是
time.Second，别误用time.Minute导致 URL 1 秒就失效；建议统一用15 * time.Minute做上传窗口 - 如果 MinIO 开了
region（比如us-east-1），Presigned*方法必须传对应 region，否则签名验证失败 —— 本地单节点默认 region 是us-east-1，但很多教程漏写
Gin 集成 MinIO 最麻烦的从来不是“怎么连上”，而是上传路径里隐含的协议、域名、权限、超时、并发这几层叠加后的连锁反应。哪怕 endpoint 对了，一个没设 timeout 的 client 也可能让整条 API 链路雪崩。
