一、问题描述

访问niceGUI服务，点击下载按钮无反应，后台控制台也无报错信息，F12查看，发现报错：Error during WebSocket handshake: Unexpected response code: 426。

二、分析原因：

这个 426 Upgrade Required 错误，结合下载按钮无反应的现象，核心问题在于 ​Nginx没有正确转发WebSocket升级请求所需的头部信息。

• ​WebSocket握手过程​：NiceGUI这类现代Web框架通常依赖WebSocket进行实时通信。建立连接时，浏览器会发送一个包含 Upgrade: websocket 头的HTTP请求，要求服务器将协议从HTTP升级为WebSocket。

• ​Nginx的默认行为​：默认配置下，Nginx不会转发 Upgrade 和 Connection 这类特殊的hop-by-hop头部。当这个升级请求被Nginx拦截但未正确传递给后端服务时，后端服务可能无法正常完成WebSocket握手，进而影响依赖WebSocket通信的功能（比如你的下载按钮事件传递），并返回426状态码。

三，解决方法

1.修改nginx.conf配置文件

确保基础WebSocket支持​，在 http { } 块内（通常在文件最顶部），确保有 map 指令来动态处理连接类型。如果还没有，请添加。通常默认在/etc/nginx目录下。

http {
    # 定义WebSocket连接升级策略
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    # ... 其他http块内的配置
}

2.修改反向代理的server配置块

server {
    listen 80;
    server_name your_server_domain_or_ip; # 你的服务器域名或IP

    location / {
        proxy_pass http://localhost:8080;  # 请确认此处的端口与你的NiceGUI服务实际端口一致

        # 核心修复：支持WebSocket协议升级
        proxy_http_version 1.1;  # 必须使用HTTP/1.1以支持协议升级[4,7](@ref)
        proxy_set_header Upgrade $http_upgrade;       # 转发Upgrade头
        proxy_set_header Connection $connection_upgrade; # 动态设置Connection头

        # 重要的基础代理头，确保后端获取真实客户端信息
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 调整超时设置（可选，针对长连接稳定性）
        proxy_read_timeout 300s;  # 增加读取超时，避免长时间无数据交互断开[5,7](@ref)
        proxy_send_timeout 300s;
    }
}