Bad asset URLs causing UI to be unusable when delivered via non-standard port

用户在 HTTPS 非标准端口反向代理环境中运行 Gradio(6.17.3),前端 UI 因资源加载失败而完全不可用。具体架构为: HTTPS + 非默认端口 → 反向代理 → Docker → Gradio 。

Bad asset URLs causing UI to be unusable when delivered via non-standard port

Bad asset URLs causing UI to be unusable when delivered via non-standard port

快速结论:当 Gradio 通过非标准端口(如 20080)的反向代理提供页面时,CSS、JS 等资源 URL 拼接时丢失端口号,导致 UI 完全不可用。优先排查是否使用了 Gradio 6.17.x 版本,并检查 root 变量拼接逻辑。

问题场景

用户在 HTTPS 非标准端口反向代理环境中运行 Gradio(6.17.3),前端 UI 因资源加载失败而完全不可用。具体架构为:HTTPS + 非默认端口反向代理DockerGradio

报错原文

The URLs for:
- theme.css
- iframeResizer.contentWindow.min.js
- /gradio_api/upload_progress
- ... (maybe more?)

are concatenated with the `root` variable, instead of just being an absolute path (see /manifest.json).
Therefore the resulting URLs contain only the hostname without the port number, which causes the UI to fail if a non-standard port is used.

原因分析

Issue 中明确指出 Gradio 前端将资源 URL 与 root 变量进行拼接,而非使用绝对路径(如 /manifest.json)。当反向代理运行在非标准端口时,root 变量仅保留主机名(hostname)而丢失端口号,导致浏览器无法正确解析资源 URL。问题影响多个资源文件(theme.css、iframeResizer.contentWindow.min.js、upload_progress 等)。Issue 作者推测 root 变量原本用于设置基础路径(base path),但不适合用于拼接包含端口的主机地址。

环境排查

  • Gradio 版本:6.17.x 及之前版本(6.20.x 中已修复,但作者测试时遇到其他异常)
  • 部署方式:反向代理(如 Nginx) → Docker → Gradio
  • 代理协议/端口:HTTPS + 非标准端口(如 20080)
  • Gradio 前端模式:通常为 SPA(单页应用)

解决步骤

  1. 确认问题症状:在浏览器开发者工具中检查网络请求,确认 theme.cssiframeResizer.contentWindow.min.js 等资源的请求 URL 是否缺少端口号(例如请求 https://machine.local/theme.css 而非 https://machine.local:20080/theme.css)。
  2. 可优先尝试:从 Issue 评论区 PR 安装预发布版本(基于 commit a70d093),命令:pip install https://huggingface.co/buckets/gradio/pypi-previews/resolve/a70d093e35660c0f19a904bea5bc958c0ee1e0e7/gradio-6.20.0-py3-none-any.whl。注意:原作者在升级时遇到了模块重复注册异常,需排查项目依赖兼容性。
  3. 替代方案:如果无法升级,可尝试在反向代理(如 Nginx)中显式设置 HostX-Forwarded-Host 头,确保 Gradio 能接收到完整的 host(含端口)信息。但这属于 workaround,不保证完全修复。
  4. 长期修复:参考 Issue 中建议的方法——在前端使用 <base href="..." /> 标签让浏览器自行处理资源解析,或直接使用绝对路径(如 /manifest.json)替代 root 变量拼接。此修复已在 Gradio 后续版本中合并。

验证方法

通过反向代理访问 Gradio URL(例如 https://machine.local:20080),检查浏览器控制台无资源加载错误(404 或连接拒绝),且 UI 正常渲染。theme.cssiframeResizer.contentWindow.min.js 等资源应正确加载,不再包含 root 变量拼接导致的错误路径。

参考来源

gradio-app/gradio #13600

GamsGo AI

AI 工具推荐

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

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

了解 GamsGo AI

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

celebrityanime
celebrityanime
文章: 13326

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注