直接用GridFS的FindOne查文件哈希行不通，因GridFSBucket默认不索引metadata字段，导致全表扫描、性能骤降；必须手动在fs.files上为"metadata.hash"建索引，并选用sha256、扁平化metadata、端到端哈希一致。
为什么直接用 GridFS 的 FindOne 查文件哈希行不通
很多人一上来就想：MongoDB 有 GridFS，我存文件前先算个 MD5，再用 FindOne 按 metadata.hash 查一遍，存在就跳过上传——听起来很合理，但实际会漏判。根本原因是：GridFSBucket 默认不索引 metadata 字段，FindOne 查询走全表扫描，随着文件增多，响应从毫秒变秒级，秒传体验直接崩掉。
实操建议：
- 必须手动在
fs.files集合上为常用查询字段建索引，例如：db.fs.files.createIndex({ "metadata.hash": 1 }) - 别把哈希值塞进
metadata后就完事，要确认索引已生效（用db.fs.files.getIndexes()看） - 哈希算法选
sha256而非md5，避免极低概率的碰撞在生产环境被放大
如何让 UploadStream 和秒传逻辑安全共存
GridFS 的 UploadStream 是流式写入，不能中途“撤回”。如果先查哈希发现已存在，又不小心调了 UploadStream，就会产生冗余 chunk（fs.chunks 多出一堆没人引用的数据），长期积累拖慢备份和清理。
正确做法是严格分离“判断”和“写入”两个阶段：
立即学习“go语言免费学习笔记（深入）”；
- 所有上传请求必须先走
FindOne查询fs.files，且查询条件包含{ "metadata.hash": "<code>xxx" } - 仅当查询返回
nil时，才调用bucket.UploadStream；否则直接返回已有文件的_id - 务必用
context.WithTimeout包裹查询和上传操作，防止某次卡死阻塞整个上传队列
metadata 字段设计要注意哪些坑
GridFS 不限制 metadata 结构，但乱塞字段会导致查询变慢、索引膨胀，甚至触发 BSON 16MB 上限。
推荐方案：
- 只存秒传必需字段：
hash（string）、size（int64）、uploaded_at（time.Time） - 避免嵌套结构，例如不要存
{"user": {"id": "u123", "name": "a"}}}，而应扁平化为{"user_id": "u123"} - 如果需关联业务数据，用独立字段存 ID（如
order_id），别把整条订单 JSON 塞进去 - 所有字符串类哈希值统一转小写存储，避免大小写不一致导致重复上传
客户端怎么配合才能真正“秒”传
服务端再快，客户端没算对哈希或并发乱发请求，照样失败。关键不是“服务端支持”，而是“端到端链路可控”。
必须做到：
- 客户端用相同哈希算法（推荐
sha256.Sum256）计算整个文件，不是读一部分就发请求 - 大文件分片上传场景下，秒传逻辑必须作用于完整文件哈希，而非单个分片
- HTTP 请求头带
X-File-Hash: xxx，服务端直接取该值做查询，避免 Base64 编码/解码引入额外错误 - 对同一文件的多次上传请求，加简单去重（比如内存里缓存最近 10 秒的 hash → response 映射），防止瞬间并发打穿查询
真正的难点不在 Go 怎么调 mongo-go-driver，而在于哈希计算一致性、索引有效性、以及客户端和服务端对“同一个文件”的定义是否完全对齐。少一个环节，秒传就变成“疑似秒传”。
