用NGINX反代本地Gradio应用时WebSocket断连问题的解决方法

文章导读
Gradio在本地跑得好好的,浏览器直接打开http://127.0.0.1:7860,页面能加载,对话也能多轮进行。一旦改用NGINX反代到域名或服务器端口,页面能打开,但生成内容超过十几秒,或者对话进行到一半,前端就提示Disconnected或Connection Error。这种情况在文本生成、语音识别、图像生成这些耗时任务里尤其常见,通常不是Gradio程序本身崩了,而是NGINX这一层
📋 目录
  1. 一 先确认断连发生在哪一层
  2. 二 基础反代配置:把WebSocket握手完整转交
  3. 三 超时参数调整的取舍
  4. 四 挂在子路径时容易忽略的坑
  5. 五 检查日志和验证连接
A A

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配置通常长这样:

用NGINX反代本地Gradio应用时WebSocket断连问题的解决方法
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连接数,如果并发访问量大,需要结合服务器的连接数上限来权衡,不建议无脑设置成很大的值。

用NGINX反代本地Gradio应用时WebSocket断连问题的解决方法

挂在子路径时容易忽略的坑

如果你不只是反代根路径,而是把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。

用NGINX反代本地Gradio应用时WebSocket断连问题的解决方法

如果想用更直接的方式验证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版本和子路径配置。

这类断连问题通常不会只由一个原因引起。配置头、超时参数、路径匹配是三个最常见的切入点,建议改一个参数就验证一次,不要一次性全部调整后再去测试,否则很难定位是哪一项起了作用。关键在于把问题限制在代理层还是应用层,其余的组合改动都留到确认之后再考虑。