Gradio 部署实战使用 Nginx 反向代理将 Gradio 应用挂载到网站子路径【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio本篇指南面向希望把 Gradio 应用部署到自有 Web 服务器而非 Hugging Face Spaces 的开发者完整讲解如何通过 Nginx 反向代理把 Gradio 应用挂载到既有网站的指定子路径如https://example.com/gradio-demo。读完本文你将掌握 Nginx 的proxy_pass配置要点、X-Forwarded-Host/X-Forwarded-Proto等关键请求头的作用、Gradiolaunch(root_path...)的配套使用以及从启动、后台驻留到最终访问验证的完整落地流程。为什么需要 Nginx 反代 GradioGradio 本身是一个 Python Web 应用框架开发完成后一条.launch()命令即可在本地启动。当需要把它接入一个已经在运行中的站点例如https://www.example.com由 Nginx 承载时最简单的做法就是让 Nginx 作为反向代理把站点下的某个子路径如/gradio-demo的请求全部转发给后台运行的 Gradio 进程。这种架构有两个天然诉求也是本指南的核心URL 挂载Gradio 默认假设自己运行在域名的根路径/上一旦被挂到/gradio-demo这类子路径前端所有静态资源与 API 请求的 URL 都必须加上此前缀否则页面会以“残破”状态加载。WebSocket 支持Gradio 的事件交互与流式输出依赖长连接Nginx 侧必须正确透传Upgrade/Connection等头才能让队列与事件推送正常工作。仓库中另一篇部署文档 deploying-gradio-with-docker.md 也明确指出当把 Gradio 部署到 Nginx 等代理之后时必须正确配置代理以保证应用在生产环境中正常可用正是本篇要解决的主题。前置条件在动手之前请确认以下条件已满足一台 Linux Web 服务器已安装并正常运行 Nginx服务器上已安装 Gradiopip install gradio已有一个可正常工作的 Gradio 应用保存为服务器上的一个 Python 文件。第一步编辑 Nginx 配置声明子路径转发Nginx 主配置默认位于/etc/nginx/nginx.conf。首先在主配置的http块中加入一行让 Nginx 加载sites-enabled目录下的 server 块配置include /etc/nginx/sites-enabled/*;随后在/etc/nginx/sites-available目录不存在则先创建中新建一个代表该应用的配置文件例如sudo nano /etc/nginx/sites-available/my_gradio_app将下面这段 server 块粘贴进去。它监听 80 端口并把example.com下的/gradio-demo/子路径代理到本机7860端口上运行的 Gradio 进程server { listen 80; server_name example.com www.example.com; # Change this to your domain name location /gradio-demo/ { # Change this if youd like to server your Gradio app on a different path proxy_pass http://127.0.0.1:7860/; # Change this if your Gradio app will be running on a different port proxy_buffering off; proxy_redirect off; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Proto $scheme; } }各指令的语义与改动建议如下指令作用需要修改的场景server_name example.com www.example.com;声明该 server 块负责的域名替换为你的真实域名location /gradio-demo/声明要挂载的站点子路径想换路径时改动需与后面root_path严格一致proxy_pass http://127.0.0.1:7860/;转发目标Gradio 换了端口则同步修改proxy_buffering off;关闭缓冲利于流式输出实时到达浏览器流式/长连接场景强烈建议保留proxy_http_version 1.1;Upgrade/Connection为 WebSocket 升级做准备事件与流式功能依赖勿删Host/X-Forwarded-Host/X-Forwarded-Proto向后端透传原始 Host、原始协议影响 Gradio 拼接公开 URL见下文请求头为什么必须设置X-Forwarded-Host与X-Forwarded-Proto设置这两个头至关重要。Gradio 依赖它们配合下文的root_path参数来推导出应用对外服务的公开 URL并用该 URL 去加载各类静态资源。如果缺少这些头应用可能加载出残破的页面CSS/JS 资源路径错乱、接口请求指向错误地址。从仓库源码可以印证这一点。在 route_utils.py 的get_request_origin()中若请求带有x-forwarded-host头Gradio 直接以它为基准构造根 URL若请求带有x-forwarded-proto且值为https则把根 URL 的协议替换为https多个候选值如多个代理叠加转发时只取第一个逗号分隔的值。在 get_root_url() 中则进一步明确了root_path的解析顺序当root_path本身是完整 URL 时直接返回当请求带有x-forwarded-host时由代理头构造根 URL此时不再使用请求路由来推导。这意味着“Nginx 传对头”是 Gradio 正确自证身份、拼接资源地址的前提。关于$host与$http_host的注意点Nginx 的$host变量不包含端口。如果你是通过“裸 IP 端口”的形式对外提供服务而非标准域名 80/443就需要改用$http_host它会携带端口把配置中这两行替换掉proxy_set_header Host $host; proxy_set_header X-Forwarded-Host $host;换成proxy_set_header Host $http_host; proxy_set_header X-Forwarded-Host $http_host;别忘了启用配置/etc/nginx/sites-available中新增的配置还需要被链接到sites-enabled才会生效Nginx 常规做法Ubuntu 系发行版默认即如此。在配置目录间建立软链后再执行后文的重载/重启步骤sudo ln -s /etc/nginx/sites-available/my_gradio_app /etc/nginx/sites-enabled/若你的发行版 Nginx 配置风格不同如直接使用 conf.d请按对应约定把 server 块放入可被加载的位置即可server 块内容本身通用。第二步用root_path启动 Gradio 应用仅配好 Nginx 还不够——Gradio 进程必须知道自己在对外提供服务的子路径这由launch()的root_path参数指定它必须与 Nginx location 里写的子路径保持一致。不设置时应用默认假定挂在域名根路径因此任何非根路径挂载都会导致资源 404。root_path在 blocks.py 的launch()签名中是一个独立关键字参数其官方 docstringblocks.py描述得很精确应用挂载点不为/时使用典型场景就是“应用位于反向代理之后”。例如应用对外地址是https://example.com/myapp则应把root_path设为/myapp。相对子路径与完整 URL 两种形态root_path支持两种写法相对子路径推荐如/gradio-demo与 Nginx 的 location 一一对应域名变更时无需改动应用代码完整 URL如https://example.com/gradio-demo以http或https开头。此时 Gradio 将root_path整体当作绝对 URL 使用见 route_utils.py 中is_http_url_like分支域名一旦变化就需要同步更新该值灵活性略差。示例应用下面是与上文 Nginx 配置配套的最简 Gradio 应用延迟 4 秒模拟耗时推理便于验证 Nginx 关闭缓冲后页面与队列仍正常import gradio as gr import time def test(x): time.sleep(4) return x gr.Interface(test, textbox, textbox).queue().launch(root_path/gradio-demo)注意两点root_path/gradio-demo与 Nginx 中的location /gradio-demo/前缀一致调用了.queue()。Gradio 的事件队列通过 WebSocket/长连接与前端通信这正是 Nginx 侧需要透传Upgrade头、关闭缓冲的原因。生产部署建议始终保留.queue()。除了在代码里传参root_path也可以通过环境变量GRADIO_ROOT_PATH注入这更便于在容器或多环境场景下不改代码切换挂载点详见 blocks.py 中先读环境变量、缺省为空串的实现以及 环境变量说明文档。例如export GRADIO_ROOT_PATH/gradio-demo python my_gradio_app.py端口与监听地址与 Nginx 对应Gradio 默认监听127.0.0.1:7860见 http_server.py 中对GRADIO_SERVER_PORT与GRADIO_SERVER_NAME的默认处理。如果进程实际起在了其他端口务必回头同步修改 Nginx 的proxy_pass。可通过launch()参数显式指定也支持对应环境变量server_port/GRADIO_SERVER_PORT指定端口缺省从 7860 起寻找可用端口server_name/GRADIO_SERVER_NAME设为0.0.0.0可让应用对局域网可达但反代场景下保持默认127.0.0.1仅本机访问反而更安全——外部流量一律由 Nginx 收口避免绕过代理头伪造等风险。第三步后台运行 Gradio 应用如果直接在 SSH 会话里执行python一旦断开连接进程就会终止。文档推荐使用tmux让应用在后台持续运行输入tmux并回车进入一个新的 tmux 会话该步为可选但强烈建议启动应用python my_gradio_app.py默认情况下应用运行在localhost:7860若实际端口不同请按上文同步修改 Nginx 的proxy_pass。第四步退出会话并重启 Nginx若在 tmux 会话中先按CTRLBmacOS 为CMDB再按字母D键即可脱离会话回到原 shell而 Gradio 进程继续在后台运行重启 Nginx 使新配置生效sudo systemctl restart nginx完成上述步骤后在浏览器访问https://example.com/gradio-demo若按裸 IP 场景配置则为http://ip:port/gradio-demo即可看到运行在该子路径下的 Gradio 应用。常见问题与排查要点页面加载但样式/脚本全丢broken state多为缺少X-Forwarded-Host/X-Forwarded-Proto头或root_path与location前缀不一致。按上文核对两类配置。root_path已设置但请求仍指向根路径检查 Nginx 是否真的把转发请求带上了代理头多级代理时要保证每一级都正确透传Gradio 侧取第一个头值逗号分隔的首项。事件触发无响应 / 流式输出卡住确认proxy_buffering off、proxy_http_version 1.1、Upgrade/Connection头均已配置并保留.queue()。裸 IP 端口访问时 Host 错误将$host换为$http_host携带端口。想更换挂载路径需要同时改两处——Nginx 的location与应用的root_path或GRADIO_ROOT_PATH环境变量缺一不可。需要说明的是本文方案基于 HTTP 反向代理到本地端口如果 Gradio 进程部署在容器中反向代理的透传头、子路径与端口映射遵循同样的原则可结合 Docker 部署指南 一并阅读。文中涉及的启动参数与端口默认值均以当前仓库源码为准不同 Gradio 版本如有差异以对应版本仓库中的launch()文档为准。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gradio 部署实战：使用 Nginx 反向代理将 Gradio 应用挂载到网站子路径
Gradio 部署实战使用 Nginx 反向代理将 Gradio 应用挂载到网站子路径【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio本篇指南面向希望把 Gradio 应用部署到自有 Web 服务器而非 Hugging Face Spaces 的开发者完整讲解如何通过 Nginx 反向代理把 Gradio 应用挂载到既有网站的指定子路径如https://example.com/gradio-demo。读完本文你将掌握 Nginx 的proxy_pass配置要点、X-Forwarded-Host/X-Forwarded-Proto等关键请求头的作用、Gradiolaunch(root_path...)的配套使用以及从启动、后台驻留到最终访问验证的完整落地流程。为什么需要 Nginx 反代 GradioGradio 本身是一个 Python Web 应用框架开发完成后一条.launch()命令即可在本地启动。当需要把它接入一个已经在运行中的站点例如https://www.example.com由 Nginx 承载时最简单的做法就是让 Nginx 作为反向代理把站点下的某个子路径如/gradio-demo的请求全部转发给后台运行的 Gradio 进程。这种架构有两个天然诉求也是本指南的核心URL 挂载Gradio 默认假设自己运行在域名的根路径/上一旦被挂到/gradio-demo这类子路径前端所有静态资源与 API 请求的 URL 都必须加上此前缀否则页面会以“残破”状态加载。WebSocket 支持Gradio 的事件交互与流式输出依赖长连接Nginx 侧必须正确透传Upgrade/Connection等头才能让队列与事件推送正常工作。仓库中另一篇部署文档 deploying-gradio-with-docker.md 也明确指出当把 Gradio 部署到 Nginx 等代理之后时必须正确配置代理以保证应用在生产环境中正常可用正是本篇要解决的主题。前置条件在动手之前请确认以下条件已满足一台 Linux Web 服务器已安装并正常运行 Nginx服务器上已安装 Gradiopip install gradio已有一个可正常工作的 Gradio 应用保存为服务器上的一个 Python 文件。第一步编辑 Nginx 配置声明子路径转发Nginx 主配置默认位于/etc/nginx/nginx.conf。首先在主配置的http块中加入一行让 Nginx 加载sites-enabled目录下的 server 块配置include /etc/nginx/sites-enabled/*;随后在/etc/nginx/sites-available目录不存在则先创建中新建一个代表该应用的配置文件例如sudo nano /etc/nginx/sites-available/my_gradio_app将下面这段 server 块粘贴进去。它监听 80 端口并把example.com下的/gradio-demo/子路径代理到本机7860端口上运行的 Gradio 进程server { listen 80; server_name example.com www.example.com; # Change this to your domain name location /gradio-demo/ { # Change this if youd like to server your Gradio app on a different path proxy_pass http://127.0.0.1:7860/; # Change this if your Gradio app will be running on a different port proxy_buffering off; proxy_redirect off; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Proto $scheme; } }各指令的语义与改动建议如下指令作用需要修改的场景server_name example.com www.example.com;声明该 server 块负责的域名替换为你的真实域名location /gradio-demo/声明要挂载的站点子路径想换路径时改动需与后面root_path严格一致proxy_pass http://127.0.0.1:7860/;转发目标Gradio 换了端口则同步修改proxy_buffering off;关闭缓冲利于流式输出实时到达浏览器流式/长连接场景强烈建议保留proxy_http_version 1.1;Upgrade/Connection为 WebSocket 升级做准备事件与流式功能依赖勿删Host/X-Forwarded-Host/X-Forwarded-Proto向后端透传原始 Host、原始协议影响 Gradio 拼接公开 URL见下文请求头为什么必须设置X-Forwarded-Host与X-Forwarded-Proto设置这两个头至关重要。Gradio 依赖它们配合下文的root_path参数来推导出应用对外服务的公开 URL并用该 URL 去加载各类静态资源。如果缺少这些头应用可能加载出残破的页面CSS/JS 资源路径错乱、接口请求指向错误地址。从仓库源码可以印证这一点。在 route_utils.py 的get_request_origin()中若请求带有x-forwarded-host头Gradio 直接以它为基准构造根 URL若请求带有x-forwarded-proto且值为https则把根 URL 的协议替换为https多个候选值如多个代理叠加转发时只取第一个逗号分隔的值。在 get_root_url() 中则进一步明确了root_path的解析顺序当root_path本身是完整 URL 时直接返回当请求带有x-forwarded-host时由代理头构造根 URL此时不再使用请求路由来推导。这意味着“Nginx 传对头”是 Gradio 正确自证身份、拼接资源地址的前提。关于$host与$http_host的注意点Nginx 的$host变量不包含端口。如果你是通过“裸 IP 端口”的形式对外提供服务而非标准域名 80/443就需要改用$http_host它会携带端口把配置中这两行替换掉proxy_set_header Host $host; proxy_set_header X-Forwarded-Host $host;换成proxy_set_header Host $http_host; proxy_set_header X-Forwarded-Host $http_host;别忘了启用配置/etc/nginx/sites-available中新增的配置还需要被链接到sites-enabled才会生效Nginx 常规做法Ubuntu 系发行版默认即如此。在配置目录间建立软链后再执行后文的重载/重启步骤sudo ln -s /etc/nginx/sites-available/my_gradio_app /etc/nginx/sites-enabled/若你的发行版 Nginx 配置风格不同如直接使用 conf.d请按对应约定把 server 块放入可被加载的位置即可server 块内容本身通用。第二步用root_path启动 Gradio 应用仅配好 Nginx 还不够——Gradio 进程必须知道自己在对外提供服务的子路径这由launch()的root_path参数指定它必须与 Nginx location 里写的子路径保持一致。不设置时应用默认假定挂在域名根路径因此任何非根路径挂载都会导致资源 404。root_path在 blocks.py 的launch()签名中是一个独立关键字参数其官方 docstringblocks.py描述得很精确应用挂载点不为/时使用典型场景就是“应用位于反向代理之后”。例如应用对外地址是https://example.com/myapp则应把root_path设为/myapp。相对子路径与完整 URL 两种形态root_path支持两种写法相对子路径推荐如/gradio-demo与 Nginx 的 location 一一对应域名变更时无需改动应用代码完整 URL如https://example.com/gradio-demo以http或https开头。此时 Gradio 将root_path整体当作绝对 URL 使用见 route_utils.py 中is_http_url_like分支域名一旦变化就需要同步更新该值灵活性略差。示例应用下面是与上文 Nginx 配置配套的最简 Gradio 应用延迟 4 秒模拟耗时推理便于验证 Nginx 关闭缓冲后页面与队列仍正常import gradio as gr import time def test(x): time.sleep(4) return x gr.Interface(test, textbox, textbox).queue().launch(root_path/gradio-demo)注意两点root_path/gradio-demo与 Nginx 中的location /gradio-demo/前缀一致调用了.queue()。Gradio 的事件队列通过 WebSocket/长连接与前端通信这正是 Nginx 侧需要透传Upgrade头、关闭缓冲的原因。生产部署建议始终保留.queue()。除了在代码里传参root_path也可以通过环境变量GRADIO_ROOT_PATH注入这更便于在容器或多环境场景下不改代码切换挂载点详见 blocks.py 中先读环境变量、缺省为空串的实现以及 环境变量说明文档。例如export GRADIO_ROOT_PATH/gradio-demo python my_gradio_app.py端口与监听地址与 Nginx 对应Gradio 默认监听127.0.0.1:7860见 http_server.py 中对GRADIO_SERVER_PORT与GRADIO_SERVER_NAME的默认处理。如果进程实际起在了其他端口务必回头同步修改 Nginx 的proxy_pass。可通过launch()参数显式指定也支持对应环境变量server_port/GRADIO_SERVER_PORT指定端口缺省从 7860 起寻找可用端口server_name/GRADIO_SERVER_NAME设为0.0.0.0可让应用对局域网可达但反代场景下保持默认127.0.0.1仅本机访问反而更安全——外部流量一律由 Nginx 收口避免绕过代理头伪造等风险。第三步后台运行 Gradio 应用如果直接在 SSH 会话里执行python一旦断开连接进程就会终止。文档推荐使用tmux让应用在后台持续运行输入tmux并回车进入一个新的 tmux 会话该步为可选但强烈建议启动应用python my_gradio_app.py默认情况下应用运行在localhost:7860若实际端口不同请按上文同步修改 Nginx 的proxy_pass。第四步退出会话并重启 Nginx若在 tmux 会话中先按CTRLBmacOS 为CMDB再按字母D键即可脱离会话回到原 shell而 Gradio 进程继续在后台运行重启 Nginx 使新配置生效sudo systemctl restart nginx完成上述步骤后在浏览器访问https://example.com/gradio-demo若按裸 IP 场景配置则为http://ip:port/gradio-demo即可看到运行在该子路径下的 Gradio 应用。常见问题与排查要点页面加载但样式/脚本全丢broken state多为缺少X-Forwarded-Host/X-Forwarded-Proto头或root_path与location前缀不一致。按上文核对两类配置。root_path已设置但请求仍指向根路径检查 Nginx 是否真的把转发请求带上了代理头多级代理时要保证每一级都正确透传Gradio 侧取第一个头值逗号分隔的首项。事件触发无响应 / 流式输出卡住确认proxy_buffering off、proxy_http_version 1.1、Upgrade/Connection头均已配置并保留.queue()。裸 IP 端口访问时 Host 错误将$host换为$http_host携带端口。想更换挂载路径需要同时改两处——Nginx 的location与应用的root_path或GRADIO_ROOT_PATH环境变量缺一不可。需要说明的是本文方案基于 HTTP 反向代理到本地端口如果 Gradio 进程部署在容器中反向代理的透传头、子路径与端口映射遵循同样的原则可结合 Docker 部署指南 一并阅读。文中涉及的启动参数与端口默认值均以当前仓库源码为准不同 Gradio 版本如有差异以对应版本仓库中的launch()文档为准。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考