Vaadin23 Spring Boot+Nginx出现WebSocket 501及客户端同步问题排查

初始问题 #

Vaadin 23 结合 Spring Boot 的应用前端通过 Nginx 部署后，偶尔会出现无响应情况，浏览器控制台报 501 错误，对应的请求链接如下：

GET wss://example.com/?v-r=push&v-uiId=6&v-pushId=bc1ba5ed-b57c-48eb-ae1d-beba3104d29e&X-Atmosphere-tracking-id=0&X-Atmosphere-Framework=3.1.2-javascript&X-Atmosphere-Transport=websocket&X-Atmosphere-TrackMessageSize=true&Content-Type=application/json; charset=UTF-8&X-atmo-protocol=true

更新内容1：当前 Nginx 配置 #

server {

    root /var/www/html/domain.com;

    index index.html index.htm index.nginx-debian.html;

    server_name domain.com;

    sendfile                   on;
    tcp_nodelay                on;
    tcp_nopush                 on;
  
    etag                       off;
    if_modified_since          off;
  
#   proxy_buffering            off;

    proxy_buffer_size          128k;
    proxy_buffers              4 256k;
    proxy_busy_buffers_size    256k;

    proxy_cache                off;
    proxy_cache_convert_head   off;
    proxy_max_temp_file_size   0;
    client_max_body_size       0;
  
    proxy_http_version         1.1;
    proxy_pass_request_headers on;
    proxy_pass_request_body    on;
  
    proxy_read_timeout         1m;
    proxy_connect_timeout      1m;
    reset_timedout_connection  on;
  
    proxy_redirect             off;
    resolver                   77.88.8.8 77.88.8.1 8.8.8.8 8.8.4.4 valid=1d;
  
    gzip                       off;
    gzip_proxied               off;

    location / {

        include /etc/nginx/snippets/cors.conf;
        proxy_pass http://127.0.0.1:8080;
            proxy_redirect http://127.0.0.1:8080 /;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Real-IP $remote_addr; 
    }

     location /api {
            proxy_pass http://127.0.0.1:8080;
            proxy_redirect http://127.0.0.1:8080 /api;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Real-IP $remote_addr;
        }
}

更新内容2：添加 WebSocket 配置后仍有异常 #

在location /段中补充了以下配置：

proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_read_timeout 3600;
    proxy_connect_timeout 600;

但仍出现错误：未捕获的Promise错误：客户端正在重新同步

问题分析与解决方案 #

1. 初始501错误根源 #

501 错误是因为 Nginx 未正确处理 WebSocket 升级请求——最初的配置缺少 WebSocket 代理必需的Upgrade和Connection请求头，导致 wss 协议请求无法正确转发到后端 Vaadin 应用，触发「未实现」错误。

2. 添加配置后仍出现同步错误的可能原因 #

• 超时设置不匹配：虽然调高了 Nginx 的超时时间，但后端 Spring Boot/Vaadin 的 Push 超时参数可能更短，导致连接提前断开。需确保后端超时时间≥Nginx 设置。
• CORS 配置遗漏：当前location /引入了cors.conf，需确认配置中允许 WebSocket 相关请求头（如Upgrade、Connection）跨域，否则会影响握手流程。
• 缓冲机制干扰：当前注释了proxy_buffering off;，但 Vaadin Push 要求关闭代理缓冲，否则会导致消息延迟或丢失，引发客户端同步异常。
• Atmosphere 头传递问题：Vaadin 基于 Atmosphere 实现 Push，需确保 Nginx 完整传递X-Atmosphere-*系列请求头，否则会破坏握手逻辑。

修正后的关键配置建议 #

第一步：在 Nginx 的http块添加变量映射

兼容非 WebSocket 请求的Connection头处理：

http {
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    # 其他原有 http 配置...
}

第二步：更新location /配置

location / {
    include /etc/nginx/snippets/cors.conf;
    proxy_pass http://127.0.0.1:8080;
    proxy_redirect http://127.0.0.1:8080 /;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;

    # WebSocket 核心配置
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 86400; # 适配长连接的超时时间
    proxy_connect_timeout 600;

    # 关闭缓冲，避免 Push 消息延迟
    proxy_buffering off;
}

第三步：后端 Vaadin 配置检查

在application.properties中确认 Push 相关参数：

vaadin.push.enabled=true
vaadin.push.timeout=86400000 # 与 Nginx proxy_read_timeout 对应，单位毫秒
vaadin.push.transport=websocket

内容的提问来源于stack exchange，提问作者alexanoid