Spring Boot STOMP WebSocket本地正常 部署服务器后连接失败

问题复现 #

• 本地环境：Spring Boot + STOMP WebSocket服务运行正常，客户端通过ws://localhost:8080/tracker可成功建立连接
• 部署环境：服务上线后，分别尝试wss://myurl/tracker、wss://myurl:8080/tracker两种连接方式均握手失败
• 现有后端核心配置：

@Override
public void configureMessageBroker(MessageBrokerRegistry config) {
    config.enableSimpleBroker("/topic");
    config.setApplicationDestinationPrefixes("/app");
}

@Override
public void registerStompEndpoints(StompEndpointRegistry registry) {
    registry.addEndpoint("/tracker").setAllowedOrigins("*");
}

排查步骤与修复方案 #

1. 优先检查反向代理配置 #

90%以上的该类问题都是反向代理（生产环境常用Nginx）没有配置WebSocket协议升级规则导致。生产环境一般不会直接暴露8080端口，公网请求通过443/80端口经反向代理转发到后端服务，缺少WebSocket升级配置时代理会直接拒绝协议升级请求。
对应Nginx配置参考：

location /tracker {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}

配置完成后执行nginx -s reload重载规则，此时直接使用wss://myurl/tracker即可连接，不需要带8080端口。

2. 检查端口、协议与监听配置 #

如果不使用反向代理，打算直连8080端口，逐一确认以下配置：

• 云服务器安全组入方向规则放行8080端口TCP请求
• 服务器系统防火墙（firewalld/ufw/iptables）开放8080端口公网访问
• Spring Boot服务绑定地址为0.0.0.0:8080，而非仅绑定127.0.0.1本地回环地址
• 协议匹配：如果Spring Boot没有配置SSL证书，8080端口是普通HTTP协议，对应WebSocket连接前缀要用ws://，而非加密的wss://，协议不匹配会直接握手失败。

3. 补充兼容配置 #

部分运营商网络、企业代理会拦截原生WebSocket请求，可以在端点注册时开启SockJS支持提升兼容性：

@Override
public void registerStompEndpoints(StompEndpointRegistry registry) {
    registry.addEndpoint("/tracker").setAllowedOrigins("*").withSockJS();
}

客户端对应引入SockJS依赖初始化连接即可。

4. 检查跨域与拦截规则 #

当前代码虽然配置了setAllowedOrigins("*")，但如果项目存在全局CORS过滤器、Spring Security拦截规则、反向代理层跨域限制，也会导致握手被拦截，可临时关闭跨域与拦截校验定位问题，再按需调整规则。

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