Unable to correctly handle file download with multiple deployments

问题场景

在 Gradio 应用部署为多个副本（多 Pod/多实例）时，用户通过后端函数生成文件（如 Excel、报表等），文件保存在处理该请求的副本本地磁盘。随后用户点击 gr.File() 组件的下载按钮，当负载均衡器将下载请求路由到未存储该文件的副本时，下载失败并返回 403 错误。多次点击下载按钮可能偶然成功，原因是请求最终落回生成文件的那个副本。

报错原文

{"detail":"File not allowed: /.../T/gradio//report.txt."}   -> 403
  attempt 1 -> 403
  attempt 2 -> 403
  attempt 3 -> 403

原因分析

Gradio 生成文件后返回的 FileData 对象，其 url 字段内嵌了该文件在生成副本上的绝对路径（例如 http://127.0.0.1:7890/gradio_api/file=/.../report.txt）。该 URL 仅在生成文件的副本上有效，因为 Gradio 通过该副本内存中的 created_paths 集合校验文件访问权限。

当负载均衡器将下载请求分发到另一个副本时，该副本的 created_paths 中没有对应路径，于是拒绝访问。由于文件路径实际不存在于该副本，但 Gradio 将其判定为“未经授权的路径”，因此返回 403 File not allowed，而非 404 Not Found，这会让多副本部署下的问题排查更具迷惑性。

可能原因：部署架构中缺少会话粘性，导致上传/生成与下载请求被分发到不同副本。

环境排查

• 确认 Gradio 版本是否为 6.22.0 或更高版本（Issue 在该版本上复现）。
• 确认部署架构是否为多副本（多 Pod/多实例），并检查负载均衡器的会话保持策略。
• 确认负载均衡器是否已开启粘性会话（Sticky Sessions）或会话亲和性（Session Affinity）。
• 检查文件下载请求的 URL 中是否包含 gradio_api/file= 路径，并验证该路径是否指向生成文件的副本。

解决步骤

1. 推荐方案（官方确认）：启用粘性会话。参考 Gradio 官方 Docker 多副本部署指南，在负载均衡器（如 Nginx、AWS ALB、Kubernetes Ingress 等）上配置 Sticky Sessions，使同一用户的请求始终路由到同一副本。配置方法请查阅：https://gradio.app/guides/deploying-gradio-with-docker#enable-stickiness-for-multiple-replicas
2. 验证复现环境：如需复现问题，可参考 Issue 中的最小复现脚本，启动两个独立 Gradio 进程（如端口 7890 和 7891），模拟两个互不共享文件缓存的副本。
3. 替代方案（未经验证，可优先尝试）：在文件生成完成后，将文件上传到私有对象存储（如 GCS），并在 gr.File() 中返回该 URL，确保任意副本都能访问。此方案可解决无粘性会话的场景，但需评估上传/下载的额外延迟与存储成本。

验证方法

启用粘性会话后，连续执行多次“生成文件 → 点击下载”操作，每次均应直接下载成功，无需多次点击重试。可通过观察下载请求被路由到的副本日志来确认同一用户的请求均落在同一副本。若使用替代方案（对象存储），可从任一副本发起下载请求，确认均能成功获取文件。

参考来源

gradio-app/gradio #10583

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。