上传前必须配置好七牛云accesskey和secretkey，否则签名失败或401 unauthorized；gin需用qiniu/api.v7动态生成带有效期的上传凭证，密钥须通过环境变量加载，严禁硬编码或泄露至前端。
上传前必须配置好七牛云的 AccessKey 和 SecretKey
没配对密钥，后续所有操作都会卡在签名失败或 401 Unauthorized。Gin 本身不处理鉴权，得自己用七牛 SDK（github.com/qiniu/api.v7）生成上传凭证。别直接硬编码密钥——用环境变量或配置文件加载，否则上线后密钥泄露风险极高。
常见错误是把 SecretKey 当成明文传给前端，或者用 time.Now().Unix() 做过期时间但没加时区校准，导致凭证提前失效。正确做法是用 auth.NewAuth(<code>AccessKey, SecretKey) + PutPolicy.ExpireInSeconds(3600) 生成带有效期的 token。
-
AccessKey和SecretKey从七牛控制台「密钥管理」获取，不是账号密码 - 上传 token 必须每次请求动态生成，不能复用超过 1 小时
- 若用自定义域名，
PutPolicy.Scope要写成"bucketName:key"，不是纯 bucket 名
Gin 接收文件时别用 c.FormFile 直接读取原始图片
七牛推荐服务端直传（即前端拿 token 后直传到七牛，不经过你的服务器），但如果你需要先在 Gin 层做校验（比如限制大小、检查 MIME 类型、预处理裁剪参数），就得用 c.MultipartForm() 或 c.Request.ParseMultipartForm()，而不是简单调 c.FormFile("file") —— 后者会触发一次内存拷贝，大图容易 OOM。
更稳妥的做法是：用 c.Request.Body 流式读取，配合 io.LimitReader 控制最大上传体积（比如限制 10MB），再交给 image.DecodeConfig 判断格式是否合法。裁剪逻辑（如宽高比校验、缩放比例）也应在此阶段完成，避免无效文件走到七牛上传环节。
- 用
c.Request.ContentLength做前置判断，超限直接返回413 Payload Too Large - 不要依赖
Content-Type头，它可被伪造；用http.DetectContentType检查前 512 字节 - 若需裁剪，优先用
golang.org/x/image/draw在内存中处理，别等上传完再回调处理
裁剪 URL 生成要区分「私有空间」和「公开空间」
七牛的图片样式（如 ?imageView2/1/w/300/h/200/q/85）只有在公开 bucket 下能直接拼接访问；私有 bucket 必须带签名 URL，否则返回 403 Forbidden。很多人测试时用的是公开空间，上线切私有后才发现图片全挂了。
生成私有样式 URL 的关键在于：先构造原始图片 URL，再用 auth.SignDownloadURL 加签，且必须带上样式参数（不能后加）。例如原始地址是 https://your-bucket.qiniup.com/photo.jpg，要裁剪为 300x200，就得先拼成 https://your-bucket.qiniup.com/photo.jpg?imageView2/1/w/300/h/200，再对此完整字符串签名。
- 私有 bucket 的样式 URL 过期时间由
SignDownloadURL的expires参数控制，通常设为 3600 秒足够 - 如果前端需要长期可用的裁剪图，应在上传时就调用七牛的
pfop（持久化处理）API，生成新 key - 注意 CDN 缓存行为：带样式的 URL 默认不缓存，但加了
?v=xxx时间戳反而可能绕过 CDN，得看七牛控制台的缓存规则配置
并发上传多个文件时，token 复用和 error 处理容易出错
一个上传 token 只能用于单个文件（除非显式设置 PutPolicy.Scope 为 "bucketName:" 表示不限 key），但很多人在循环里反复用同一个 token，结果第二个文件就报 invalid token。另外，Gin 默认的 multipart 解析不支持并发读取同一 Request.Body，直接 go routine 处理会导致 body 读空或 panic。
正确方式是：每个文件单独生成 token；用 form.FileHeader 提前拿到所有文件头，再逐个开 goroutine 处理（注意加 context 超时控制）。错误必须分别收集，不能因为一个失败就中断整个批次——七牛上传接口本身支持批量，但 Gin 层要自己做聚合。
- 别在 goroutine 里直接用
c.Request.Body，改用header.Open()获取每个文件的独立 reader - 上传失败时，七牛返回的
error类型多为*qiniu.Error，需断言后取Err.Code和Err.Message做针对性提示 - 若同时上传 10 张图，建议用
errgroup控制并发数（如 3～5），避免打爆七牛连接数限制
hash 和 key 怎么存进你自己的数据库，那属于业务逻辑，跟上传链路本身无关。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
