MinIO是分布式对象存储系统，Golang仅作为客户端与其S3兼容API交互；本地开发需设endpoint为"http://localhost:9000"且useSSL=false，生产HTTPS环境须配可信证书或自定义http.Client绕过校验。
MinIO 本身已是分布式系统，Golang 不是用来“构建分布式文件存储”的底层框架，而是作为客户端语言与 MinIO 交互的工具。你真正要做的，是用 Golang 正确集成 MinIO 的 S3 兼容 API，而不是试图在 Golang 里重写 MinIO 的分布式逻辑。
minio-go/v7 初始化时 endpoint 和 useSSL 怎么配才不报错
常见错误是 failed to connect to server 或 x509: certificate signed by unknown authority，本质是 endpoint 地址和 TLS 配置不匹配。
- 本地单节点开发：endpoint 写成
"http://localhost:9000"（注意带http://），useSSL设为false - Docker 容器内访问宿主机 MinIO：endpoint 不能用
localhost，得换成宿主机 IP（如"http://172.17.0.1:9000"）或 Docker 网络别名 - 生产环境启用了 HTTPS：endpoint 必须是
"https://your-minio-domain.com"，且证书必须可信；若自签证书，需在minio.Options中传入自定义http.Client并禁用证书校验（仅测试用） - MinIO Console 端口（默认 9001）≠ API 端口（默认 9000），Golang SDK 只连 API 端口
上传大文件时为什么卡住或内存暴涨
直接用 PutObject 传整个 []byte 或未分块的 *os.File，会导致 Golang 进程一次性加载全部内容到内存，尤其在 100MB+ 文件场景下极易 OOM。
- 正确做法是用
PutObject接收io.Reader，让 MinIO 客户端内部流式上传，例如传*os.File或multipart.Reader - 避免先读全文件再上传：
data, _ := os.ReadFile("big.zip")→minioClient.PutObject(..., bytes.NewReader(data), ...) - 对 HTTP 请求体（如 gin.Context.Request.Body）直接传给
PutObject即可，无需中间拷贝 - 如需断点续传或进度反馈，改用
PutObjectWithContext+ 自定义io.Reader包裹器（带回调）
BucketExists 和 MakeBucket 调用顺序容易踩什么坑
很多人把 MakeBucket 放在每次上传前无条件调用，结果频繁报 BucketAlreadyOwnedByYou 错误，或并发时触发竞态。
立即学习“go语言免费学习笔记（深入）”；
-
MakeBucket是幂等操作，但失败后不重试会中断流程；建议只在服务启动时初始化 bucket，而非每次请求都调 -
BucketExists返回true仅表示 bucket 存在，不保证有写权限；需额外用StatObject测试写入能力（如上传 1B 临时对象再删） - MinIO 默认不允许跨 region 创建 bucket；若 endpoint 含 region（如
"us-east-1"），MakeBucketOptions中 region 必须显式匹配，否则报错 - 集群模式下 bucket 创建是全局操作，但 list buckets 可能因缓存延迟短暂看不到新 bucket，建议创建后 sleep 100ms 再验证
MinIO 的分布式能力由它自身保障，Golang SDK 的职责就是稳定、低开销地调用它的 API。最容易被忽略的是：不要在上传路径里做文件解压、格式转换、缩略图生成这类 CPU 密集操作——这些该交给独立 worker 处理，否则会拖垮整个上传吞吐。
