GridFS 本身不会死锁，所谓“死锁”实为多应用共用同一 bucketName 导致的 fs.files 文档级锁争抢与 chunk 写入顺序依赖被打破；必须为不同应用/租户分配独立 bucketName 并显式传入实例化参数，避免复用默认 "fs" 或全局 bucket 实例。
GridFS 本身不会死锁，所谓“死锁”其实是并发写同名 bucket 时的元数据竞争 + 驱动缓冲区阻塞导致的请求挂起或超时，本质是 fs.files 集合的文档级锁争抢和 chunk 写入顺序依赖被打破。
为什么多个应用写同一个 bucketName 会“卡住”
GridFS 写入分两步：先批量插入 fs.chunks 文档，最后才插入一条 fs.files 元数据。当多个应用共用同一 bucketName（比如默认 "fs"），它们都在往同一个 fs.files 集合插入文档，而 MongoDB 对该集合的 _id 字段有唯一约束，驱动内部又依赖 fs.files._id 生成 files_id 去写 chunks —— 这就形成了隐式串行依赖：
- 应用 A 开始上传，分配
_id: ObjectId("...a")，开始写 chunks，但还没写完fs.files - 应用 B 同时上传，也试图分配新
_id，但因fs.files插入未完成，B 的 chunk 写入可能卡在等待 A 的事务释放锁 - 尤其在 WiredTiger
concurrentTransactions.write耗尽时，后续请求排队，表现就像“死锁”
必须避免复用 bucket 实例和 bucketName
不同应用、不同租户、甚至不同业务场景，都不该共享同一个 bucketName。这不是“建议”，而是物理隔离前提：
- 每个应用启动时用独立
bucketName，如"app_a_uploads"、"app_b_uploads"，对应生成独立的app_a_uploads.files和app_a_uploads.chunks集合 - 不要在代码里写死
new GridFSBucket(db)，必须显式传入{ bucketName: "xxx" } - PyMongo 示例：
bucket = GridFSBucket(db, bucket_name="tenant_x_files")；Node.js：new GridFSBucket(db, { bucketName: "tenant_x_files" }) - 如果已有历史数据，可用
db.collection("fs.files").rename("legacy_fs_files")搬迁，但 rename 不支持跨库，且需停写
写入时启用 retryWrites 并确认配置生效
即使做了 bucket 隔离，主节点切换仍可能导致 chunk 写入中断。这时仅靠隔离不够，还需让底层 insertOne 可重试：
- 连接字符串必须带
retryWrites=true，例如：mongodb://host:27017/db?retryWrites=true&w=majority - 驱动版本必须 ≥ 4.0（PyMongo）或 ≥ 4.12（Node.js Driver），旧版 ignore retryWrites 参数
- 集群必须是副本集或分片集群；单节点不支持 retryable writes
- 验证是否生效：
db.runCommand({getCmdLineOpts: 1})查parsed.replSet是否存在，再看驱动日志是否打印retrying write due to NotPrimaryError
chunkSizeBytes 和 writeConcern 必须按 bucket 实例绑定
不同应用对吞吐、一致性要求不同，不能靠全局配置覆盖。比如 A 应用要强一致，B 应用重速度——它们的 bucket 实例必须各自声明参数：
-
chunkSizeBytes影响每秒 chunk 插入次数，设为256 * 1024是多数场景平衡点，但小文件多时可调小（如32 * 1024）减少碎片 -
writeConcern必须在实例化时传入，bucket = GridFSBucket(db, { bucketName: "x", writeConcern: { w: "majority", j: true } })，否则默认w: 1，元数据存在但 chunk 丢失 - 切勿复用一个
bucket实例供多个应用调用，它内部缓存了files_id生成逻辑和连接上下文
真正容易被忽略的是：你看到的“死锁”现象，往往发生在上线后压测阶段，而开发环境单应用跑得飞快——这说明问题不在代码逻辑，而在多实例部署时的 bucket 命名和连接配置没对齐。检查每个服务的启动参数、连接串、驱动版本，比查锁表更有效。
