Uvicorn不处理大文件上传逻辑,关键在UploadFile读取方式;默认内存缓存100KB,超量落盘,需流式读取防OOM;预签名直传S3/OSS最稳妥,后端仅生成凭证。

Uvicorn 本身不处理大文件上传的业务逻辑,它只负责接收和转发 HTTP 请求体。真正决定“能不能传、传多大、会不会崩”的,是 UploadFile 的读取方式、内存缓冲策略、以及你是否绕过了服务器中转——这点比调 uvicorn 参数重要得多。
UploadFile 默认行为会把整个文件读进内存
FastAPI 的 UploadFile 底层用的是 SpooledTemporaryFile,默认在内存中缓存最多 100KB(max_memory=102400),超过后才落盘。上传一个 500MB 的视频时,如果没做流式读取,await file.read() 会试图一次性加载全部内容到内存,直接 OOM。
- 别写
content = await file.read()—— 这是最大雷区 - 改用
async for chunk in file.file:或await file.file.read(8192)分块读 - 确保
file.file是可迭代的类文件对象(它确实是) - 上传路径里加
content_type: str = Form(...)等元数据,避免仅靠文件扩展名判断类型
Uvicorn 启动参数对大文件上传影响有限但不可忽略
--limit-concurrency 和 --timeout-keep-alive 不直接控制上传大小,但会影响长连接下的稳定性。上传大文件耗时久,若连接被中间件(Nginx/Cloudflare)或 Uvicorn 自身中断,就会失败。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
-
--timeout-keep-alive 30:建议设为 30 秒以上,避免上传中途断连 -
--limit-concurrency 1000:防止并发上传挤爆事件循环(尤其配合--workers使用) -
--backlog 2048:Linux 的listen()队列长度,上传请求多时能减少 Connection refused - 不要依赖
--limit-max-requests来防大文件——它只管请求数,不管单个请求体大小
真正有效的方案是绕过 Uvicorn 接收文件体
上传大文件最稳的方式,是根本不让文件经过你的 FastAPI/Uvicorn 进程。用预签名 URL 直传 S3/OSS,后端只生成凭证、校验结果、更新元数据。
- 客户端拿到
upload_url后,用PUT直传,不走你的 API 路由 - 服务端只需实现一个轻量接口:
POST /upload/presign返回带Content-Length限制的预签名 URL - 注意 S3 的
Content-Length必须精确匹配,否则签名失效;前端需先HEAD或 JS 获取文件 size - 如果你必须走后端中转(比如要鉴权、加水印、转码),那就得配好反向代理超时(Nginx 的
client_max_body_size和proxy_read_timeout)
最容易被忽略的一点:无论你用哪种方式,UploadFile.file 对象在请求结束时会被自动关闭并清理临时文件——但如果你自己用 open() 打开新文件写入,记得用 asyncio.to_thread() 包裹,否则阻塞事件循环。










