如何在Python中使用FastAPI实现大文件分片断点续传-Python教程-PHP中文网

FastAPI中直接用File/UploadFile上传大文件会失败，因其默认将整个文件读入内存，500MB文件易触发OOM或被反向代理中断；且缺乏分片元信息，无法支持断点续传，必须改用原始request body流式接收并显式解析分片。

如何在python中使用fastapi实现大文件分片断点续传

为什么直接用 `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 留给二进制数据：

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

怎么安全地存储和合并分片

分片不能存在内存里，也不能直接写到目标路径——万一合并中断，目标文件就损坏了。正确做法是：分片存临时目录，合并成功后再原子性重命名。

Python Dependency Candidate Fetcher 2

根据包的能力以及 Jupyter 环境中的导入语句，从候选列表中挑选最适合用户表格工作流的 Python 包。

下载

每个 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 就乱了。