FastAPI中直接用File/UploadFile上传大文件会失败，因其默认将整个文件读入内存，500MB文件易触发OOM或被反向代理中断；且缺乏分片元信息，无法支持断点续传，必须改用原始request body流式接收并显式解析分片。
为什么直接用 File 上传大文件会失败
FastAPI 的 File 和 UploadFile 默认把整个文件读进内存，上传 500MB 文件时可能瞬间吃光服务器内存，触发 OOM 或被 Nginx/uvicorn 中途切断连接。更关键的是，它不提供分片元信息（如当前块序号、总块数、文件唯一 ID），根本没法做断点续传。
实际要做的不是“上传文件”，而是“接收并拼接分片”，所以必须绕过 File，改用原始请求体 + 显式解析。
- 禁用
File/UploadFile，改用Request读取原始 body - 前端必须按固定规则命名分片（如
chunk_00123.bin）或在请求头里带X-Upload-ID、X-Chunk-Index等字段 - 服务端需维护分片状态（临时目录、已收块列表、合并标记），不能依赖内存缓存
如何设计分片上传接口（POST + 多参数）
推荐用标准 REST 风格：单个上传接口处理所有分片，靠请求头区分阶段。避免为“上传”“合并”“校验”拆多个 endpoint，否则前端逻辑碎片化、状态难同步。
核心参数全走 header，body 留给二进制数据：
立即学习“Python免费学习笔记（深入）”；
-
X-Upload-ID：客户端生成的 UUID，标识整个文件上传会话 -
X-Chunk-Index：当前分片序号（从 0 开始） -
X-Total-Chunks：总分片数（用于判断是否收齐） -
X-File-Name：原始文件名（仅用于最终保存，不参与校验） -
Content-Type: application/octet-stream：明确告知是裸二进制流
示例请求（curl）：
curl -X POST http://localhost:8000/upload \ -H "X-Upload-ID: a1b2c3d4" \ -H "X-Chunk-Index: 2" \ -H "X-Total-Chunks: 5" \ -H "X-File-Name: report.pdf" \ -H "Content-Type: application/octet-stream" \ --data-binary @chunk_002.bin
怎么安全地存储和合并分片
分片不能存在内存里，也不能直接写到目标路径——万一合并中断，目标文件就损坏了。正确做法是：分片存临时目录，合并成功后再原子性重命名。
- 每个
X-Upload-ID对应一个子目录，如/tmp/uploads/a1b2c3d4/ - 分片文件名用
{index:06d}.bin格式（如000002.bin），方便排序和校验缺失 - 收到最后一块（
X-Chunk-Index == X-Total-Chunks - 1）后，启动合并：按序读取所有.bin文件，write()追加到新文件 - 合并完成后，删临时目录；失败则保留，供前端查询进度或重试
注意：合并时别用 shutil.copyfileobj 直接拼，它不保证顺序——必须显式遍历 sorted(os.listdir(...)) 并按数字序读。
断点续传的关键：如何告诉前端“我收到了哪些块”
前端需要知道哪些分片已成功，才能跳过重传。FastAPI 接口返回 JSON 即可，但结构必须稳定：
- 成功上传单个分片：返回
{"status": "ok", "uploaded_chunks": [2]} - 查询进度（GET /upload/status/{upload_id}）：返回
{"total": 5, "received": [0,1,2,4], "missing": [3]} - 合并完成：返回
{"status": "completed", "file_url": "/files/report.pdf"}
别省事返回 200 OK 就完事——没有明确的 missing 列表，前端根本没法做断点逻辑。临时目录里存个 chunks.json 记录已收索引，比每次 os.listdir 扫更快也更可靠。
真正的难点不在上传，而在多实例部署时的分片状态共享。单机没问题，上 Kubernetes 就得换 Redis 存 received_chunks 列表，否则分片打到不同 pod 就乱了。
