用FastAPI实现业务API文件上传,如何限制大小并清理失败后的临时文件?
用 FastAPI 接收 UploadFile 时,可以在分块复制过程中累计文件字节数:超过上限就返回 413,并在 finally 中关闭上传对象、删除尚未提交的暂存文件。文件完整写入并通过业务校验后,再将暂存文件原子地改名为正式文件,避免失败时留下半成品。
还要区分“单个文件上限”和“整个 HTTP 请求上限”。FastAPI 会先解析 multipart/form-data,之后才进入路由函数;因此,路由里的文件大小检查不能阻止解析阶段先接收请求。通常应在入口网关同时限制请求体大小,再由 FastAPI 检查单个文件大小。
两种大小限制分别解决什么问题
下面的实现将单个文件限制为 10 MiB,即 10 <em> 1024 </em> 1024 字节。应用收到文件后,按 1 MiB 分块读取,累计值一旦超过上限,就停止写入并返回 413 Payload Too Large。
入口层限制的是整条请求体,包含 multipart 边界、文件头以及其他表单字段。它应比单文件上限略大,例如单文件上限为 10 MiB 时,先将请求体上限设为 12 MiB,再根据实际表单字段调整。该限制可以在请求到达 FastAPI 之前拦截过大的请求。

FastAPI 端点:分块写入并清理失败文件
使用 UploadFile 需要安装 python-multipart。下面的示例使用 AnyIO 异步写文件,并将暂存文件和正式文件放在同一目录,便于成功后通过改名完成提交。
pip install fastapi uvicorn python-multipart anyio
先为应用服务账号准备好上传目录,例如 /srv/myapp/uploads。目录应由应用账号管理,不应允许其他用户写入。示例中不使用客户端提供的文件名作为磁盘路径;正式文件名由服务端生成。
import logging
import os
import tempfile
import uuid
from pathlib import Path
import anyio
from fastapi import FastAPI, File, HTTPException, UploadFile
app = FastAPI()
logger = logging.getLogger(__name__)
UPLOAD_DIR = Path("/srv/myapp/uploads")
MAX_FILE_BYTES = 10 * 1024 * 1024
CHUNK_SIZE = 1024 * 1024
@app.post("/api/files", status_code=201)
async def upload_file(file: UploadFile = File(...)):
file_id = uuid.uuid4().hex
staged_path: Path | None = None
final_path = UPLOAD_DIR / f"{file_id}.bin"
committed = False
total = 0
try:
UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
# mkstemp 会创建权限较严格的临时文件。
fd, temp_name = tempfile.mkstemp(
prefix=".upload-",
suffix=".part",
dir=UPLOAD_DIR,
)
staged_path = Path(temp_name)
os.close(fd)
async with await anyio.open_file(staged_path, "r+b") as destination:
while True:
chunk = await file.read(CHUNK_SIZE)
if not chunk:
break
if total + len(chunk) > MAX_FILE_BYTES:
raise HTTPException(
status_code=413,
detail="单个文件不能超过 10 MiB",
)
total += len(chunk)
await destination.write(chunk)
await destination.flush()
# 暂存文件和正式文件位于同一文件系统。
os.replace(staged_path, final_path)
committed = True
return {
"file_id": file_id,
"size_bytes": total,
}
except HTTPException:
raise
except OSError:
logger.exception("上传文件暂存或提交失败")
raise HTTPException(status_code=500, detail="文件保存失败")
finally:
try:
await file.close()
except Exception:
logger.exception("关闭上传源文件失败")
if not committed and staged_path is not None:
try:
staged_path.unlink(missing_ok=True)
except OSError:
logger.exception("清理上传暂存文件失败")
这里有两种不同的临时文件:

- FastAPI/Starlette 在解析 multipart 请求时管理上传对象内部的临时存储。应用显式调用
await file.close();请求结束时,框架也会关闭解析得到的上传对象。 - 代码创建的
.part文件由路由函数负责清理。超限、磁盘写入失败或改名失败时,finally会尝试删除它;成功改名后,committed变为True,不会删除正式文件。
上传大小通过实际读取到的字节累计,而不是依赖客户端提交的文件名或 Content-Length。单个分块只有 1 MiB,因此即使最后一个分块导致超限,也不会把超限部分写入暂存文件。mkstemp 创建的文件权限较严格,改名后权限会随文件保留。
在入口层限制整个请求体
以 Nginx 为例,可在对应接口的 location 中设置请求体上限:
location = /api/files {
client_max_body_size 12m;
proxy_pass http://127.0.0.1:8000;
}
这里的 12m 限制整条 HTTP 请求,而不是只限制文件内容。单文件上限是 10 MiB,剩余空间用于 multipart 边界和请求头等开销。如果接口还接收较大的表单字段,或一次允许上传多个文件,应根据实际请求构成调整入口上限。
Nginx 返回的 413 不一定采用 FastAPI 的 JSON 错误格式:因为请求可能尚未转发给应用,响应由入口层生成。测试时应分别确认入口层和应用层的响应行为。如果应用可以绕过 Nginx 直接被外部访问,入口限制也就失效了;应限制应用端口的访问范围,或在实际接收请求的网关上配置等效的请求体上限。
仅在 FastAPI 路由中检查 Content-Length 不够可靠:该头可能不存在,也不能替代对实际接收数据的限制。对 UploadFile 方案而言,路由函数运行时 multipart 已经解析;因此入口层限制是保护解析阶段临时存储的重要边界。还应按并发量评估解析临时目录和入口层请求缓冲目录的磁盘空间。
A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器,产品覆盖常规业务部署与不同存储需求。香港、美国及日本的部分方案配备NVMe或SSD存储,另有多块企业级硬盘配置,可为文件上传API运行、临时文件写入和业务文件存储提供相应的计算与磁盘资源基础,支持不同地区和容量需求的部署。
失败清理的边界与后续处理
finally 能清理由代码正常执行到异常退出时留下的暂存文件,但无法处理进程被强制终止、机器掉电等情况。可安排定期任务清理符合命名规则且已经陈旧的 .part 文件。清理时应先确认文件属于该上传目录和该命名规则,并将保留时间设得长于系统允许的最长上传时间,避免删掉仍在写入的文件。
若上传后还要写数据库、扫描文件或调用其他服务,建议先在暂存路径完成必要校验,再将文件提交为正式文件。文件改名和数据库事务不能天然组成一个原子操作:例如文件已改名但数据库提交失败时,可能留下没有数据库记录的正式文件。可以在业务流程中对这种情况执行补偿删除,或安排任务核对存储文件与数据库记录。
客户端文件名、扩展名和 Content-Type 都不能单独作为可信依据。需要保留原始文件名时,应将其作为元数据保存,并做长度和字符校验;不要直接拼入磁盘路径。需要限制类型时,应结合业务允许列表和内容检查,而不是只看扩展名。
调用与验证
使用 curl 以 multipart 形式上传:
curl -i -F "file=@./sample.bin" http://127.0.0.1:8000/api/files
小于上限的文件会得到 201 响应,返回服务端生成的 file_id 和实际写入的字节数。准备一个超过 10 MiB 的文件再次上传,应用层应返回 413,对应的 .part 文件应被清理。若请求体先超过 Nginx 的上限,则请求会由 Nginx 拦截,FastAPI 路由不会处理这次上传。
排查遗留暂存文件时,可以先只列出目标目录中的匹配项:
find /srv/myapp/uploads -maxdepth 1 -type f -name '.upload-*.part' -print
这条命令只用于检查,不会删除文件。确认命名规则、上传最长耗时和保留期限后,再将清理逻辑纳入受控的定时任务。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9873.html