Gradio在本地跑得好好的,浏览器直接打开http://127.0.0.1:7860,页面能加载,对话也能多轮进行。一旦改用NGINX反代到域名或服务器端口,页面能打开,但生成内容超过十几秒,或者对话进行到一半,前端就提示Disconnected或Connection Error。这种情况在文本生成、语音识别、图像生成这些耗时任务里尤其常见,通常不是Gradio程序本身崩了,而是NGINX这一层的代理行为把连接打断了。如果你手头正好是这个现象,可以先按下面的顺序排查,不用急着改Gradio代码。
Gradio的前端和Python后端之间是用WebSocket保持长期通信的,页面上的每次生成任务都会在特定路径上建立一个WebSocket连接,任务结束后再关闭。NGINX默认是按普通HTTP请求来处理的,对Upgrade头这一类WebSocket握手信息不做特殊处理,因此连接很容易在空闲或长耗时阶段被代理层清理掉。这也是为什么直接访问本地端口没问题、反代后才出现断连的核心原因。
先确认断连发生在哪一层
动手改配置之前,建议先确认断连是NGINX引起的,还是Gradio后端自己断的。最简单的方法是保持直接访问本地端口不变,同时让出问题的客户端走反代路径,比较两边行为。另一个快速判断方式看日志。
打开NGINX的error.log,能翻到类似upstream prematurely closed connection while reading response header from upstream这一行,指向的就是反代到的那个7860端口。看到这个报错时,后端Gradio进程往往还在运行,重新刷新页面又能恢复几十秒,说明程序本身没有退出,只是代理层把连接状态弄丢了。这个现象还能帮你区分问题层次:如果后端直接访问也断,先查Gradio自己;只有反代之后才断,重点查NGINX配置。
基础反代配置:把WebSocket握手完整转交
NGINX反向代理WebSocket的关键,是把客户端发来的Upgrade和Connection请求头原样转发给后端,并且让与上游的通信使用HTTP/1.1。对应的location配置通常长这样:
location / {
proxy_pass http://127.0.0.1:7860;
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-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}这段配置放在NGINX的server块内,proxy_pass指向Gradio实际监听的地址和端口。关键参数是proxy_http_version 1.1和两个请求头设置,缺少任何一个都会导致握手不完整。配置改完后执行nginx -t检查语法,然后nginx -s reload生效。验证方式是在浏览器里强制刷新页面,重新触发一次生成任务,观察是否还会在半途断开。如果仍然断开,再往下看超时设置。
超时参数调整的取舍
握手成功后,NGINX默认的行为仍然会限制连接的空闲时长。默认的proxy_read_timeout是60秒,这意味着后端在60秒内没有往代理连接写入任何数据,NGINX就会主动断开。Gradio在处理长文本生成或图像任务时,经常出现几十秒没有输出的情况,因此这个默认值很容易触发断连。建议在location中显式调大:
proxy_connect_timeout 60s;
proxy_send_timeout 3600s;
proxy_read_timeout 3600s;其中proxy_read_timeout是这里最需要关注的,它控制的是两次读取之间的间隔,不是总时长。也就是说,即使任务运行很久,只要后端保持有数据写入,连接就不会被这个参数打断。调大之后的效果,是连接允许在更长时间内处于无数据状态。这里的取舍是,长时间占用连接会占用NGINX的worker连接数,如果并发访问量大,需要结合服务器的连接数上限来权衡,不建议无脑设置成很大的值。
挂在子路径时容易忽略的坑
如果你不只是反代根路径,而是把Gradio挂在某个子路径下,比http://example.com/gradio/这样的地址,情况会稍微复杂一点。此时location和proxy_pass需要配对处理,同时Gradio端要用launch()的root_path参数声明子路径,否则前端生成的WebSocket地址会指向错误的位置。
location /gradio/ {
proxy_pass http://127.0.0.1:7860/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}注意这里的proxy_pass末尾带了一个斜杠,不带斜杠和带斜杠对URI的转发方式是不同的。如果子路径反代后页面能打开但任务无法启动,先打开浏览器的开发者工具,查看WebSocket请求实际发到了哪个URL,再核对代码里root_path和NGINX的location是否匹配。
检查日志和验证连接
配置改动之后,建议同时查看NGINX访问日志和Gradio后端的运行日志。NGINX访问日志里能看到WebSocket握手请求返回的是101状态码,而不是常见的200或301。101才是WebSocket协议切换成功的标志,如果看到的是其他状态码,说明握手没有被正确代理。
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log这两条命令可以同时开两个终端窗口执行,也可以在bash里用多行命令放到后台,这里建议直接分开运行,便于对照时间点。失败时优先检查error.log里是否出现upstream prematurely closed、101切换失败等字样,access.log里注意状态码是否停留在200或502。
如果想用更直接的方式验证WebSocket链路是否畅通,可以用Python写一个简单的连接脚本,指向NGINX反代的地址,然后发起一次Gradio的队列请求。下面这段代码只做连接测试,不依赖Gradio的API细节:
import asyncio
import websockets
async def check():
uri = "wss://your.domain.com/queue/join"
async with websockets.connect(uri) as ws:
print("connected")
await ws.send('{"fn_index":0}')
msg = await ws.recv()
print(msg)
asyncio.run(check())脚本中的uri需要结合你实际的Gradio版本和挂载路径确认,/queue/join是常见版本中前端连接后端的地址。如果脚本能拿到返回消息,说明反代层的WebSocket链路是通的,问题更可能在超时和任务输出阶段;如果连接直接报错,则继续检查之前提到的Upgrade头、HTTP版本和子路径配置。
这类断连问题通常不会只由一个原因引起。配置头、超时参数、路径匹配是三个最常见的切入点,建议改一个参数就验证一次,不要一次性全部调整后再去测试,否则很难定位是哪一项起了作用。关键在于把问题限制在代理层还是应用层,其余的组合改动都留到确认之后再考虑。