分片上传关键在于服务端通过唯一upload_id识别同一文件的碎片，而非依赖文件名；客户端需调用/init获取upload_id，后续分片携带upload_id、chunk_index和total_chunks上传，服务端用Redis或数据库持久化分片状态以支持断点续传与安全合并。
分片上传的核心逻辑：客户端如何切片、服务端如何识别同一文件
关键不是“怎么传”，而是“怎么让服务端把一堆碎片认成同一个文件”。客户端必须提供唯一标识（比如 file_id 或基于文件内容生成的 upload_id），再配合每个分片的序号 chunk_index 和总片数 total_chunks。服务端靠 upload_id 聚合所有分片，不能只依赖文件名——重名、并发上传会冲突。
常见错误是直接用 filename 作为 key 存 Redis 或磁盘目录，结果用户同时上传两个同名 PDF，后一个覆盖前一个的分片状态，断点续传直接失效。
实操建议：
- 客户端在首次上传时调用
/upload/init接口，服务端生成并返回唯一upload_id（如 UUID4） - 后续每个分片 POST 到
/upload/chunk，携带upload_id、chunk_index、total_chunks和二进制数据 - 服务端用
upload_id作为 Redis key 存储分片元信息（如已接收哪些 index、文件原始名、总大小），避免状态散落
FastAPI 中处理分片上传的路由与依赖设计
不要把所有逻辑塞进一个 POST handler。用 FastAPI 的依赖注入拆解职责：校验 upload_id 是否合法、检查当前分片是否重复、判断是否为最后一片并触发合并。
例如写一个依赖函数 get_upload_state，它从 Redis 读取 upload_id 对应的状态，若不存在或过期就抛 HTTPException(status_code=404)；再写一个 validate_chunk 依赖，确保 chunk_index 在 [0, total_chunks) 范围内且未上传过。
实操建议：
- 用
BackgroundTasks做最终的文件合并，避免阻塞请求（尤其大文件） - 分片接口返回
200 OK即可，不要等合并完成；合并失败应单独记录日志并通知（如发 webhook 或写 DB 状态为failed） - 上传状态接口（如
/upload/status?upload_id=xxx）应返回已上传分片数、总片数、合并进度，方便前端刷新 UI
断点续传的关键：如何安全地恢复上传状态
断点续传 ≠ 重传全部，而是客户端先查服务端“我上次传到第几片了？”，然后从下一个 index 继续。这要求服务端持久化每个分片的接收状态，且不能因服务重启丢失。
Redis 是常用选择，但要注意：如果用内存型 Redis 且没开启 RDB/AOF，重启后所有分片状态清空，客户端以为能续传，实际得重头来。更稳妥的是用 SQLite 或 PostgreSQL 存分片元数据（upload_id, chunk_index, received_at, size_bytes），哪怕服务挂了也能恢复。
实操建议：
- 每个分片接收成功后，立刻写入数据库一条记录（带唯一约束：
upload_id + chunk_index），避免重复插入 - 状态查询接口（
/upload/resume）返回最大已接收chunk_index+ 1，即下次该传哪一片 - 客户端上传前先 GET
/upload/resume?upload_id=xxx，拿到next_index后再发对应分片，而不是盲目从 0 开始
合并分片与清理：别让临时文件堆积失控
合并不是简单把所有分片 cat 拼起来——分片顺序可能乱序到达，且要防止并发合并（两个请求同时检测到“最后一片”而触发两次合并）。必须加分布式锁，或用数据库行锁（UPDATE ... WHERE upload_id = ? AND status = 'pending'）保证幂等。
另外，临时分片文件不清理，磁盘迟早爆。不能等合并成功后再删——万一合并失败，碎片残留；也不能一收到就删——还没合并就被删了。合理做法是：合并成功后批量删除分片文件，并标记上传记录为 completed；失败则保留分片供重试，但加 TTL（如 24 小时自动过期）。
实操建议：
- 用
shutil.copyfileobj流式合并，避免把所有分片读进内存（尤其 GB 级文件） - 合并目标路径用
upload_id命名，而非原始文件名，防止路径遍历（如原始名含../../etc/passwd） - 临时分片存放在独立目录（如
/tmp/uploads/chunks/），定期用 cron 清理超时未完成的 upload_id 目录
最易被忽略的一点：前端上传库（如 uppy 或 web-uploader）默认的分片策略和 FastAPI 后端的元信息约定必须完全对齐——比如 chunk_index 是从 0 还是 1 开始、total_chunks 是否包含空片、MD5 校验是传整个文件还是每片单独算。协议不一致，断点续传就会静默失败。
