WebSocket连接失败：ws://192.168.63.111:8080/ws 无法建立

Question

常见问题：WebSocket连接失败 `ws://192.168.63.111:8080/ws` 无法建立，多因服务端未启动或端口未监听。首先确认后端WebSocket服务（如Spring Boot的`@EnableWebSocket`配置、Netty服务或Nginx代理配置）确已运行，并监听`0.0.0.0:8080`（而非仅`127.0.0.1`）；其次检查防火墙（如`ufw`或Windows Defender）是否放行8080端口；局域网环境下还需验证客户端与`192.168.63.111`网络互通（可`ping`和`telnet 192.168.63.111 8080`测试）；若服务部署在Docker中，需确认端口映射正确（`-p 8080:8080`）且容器内服务绑定到`0.0.0.0`；此外，浏览器控制台若报`ERR_CONNECTION_REFUSED`即服务不可达，报`ERR_CONNECTION_TIMED_OUT`则可能被中间设备拦截。建议用`curl -i http://192.168.63.111:8080/health`先验证HTTP服务可达性，再排查WebSocket握手（GET `/ws`）是否返回`101 Switching Protocols`。

Answer 1

```html

一、现象层：客户端连接失败的典型错误信号

浏览器控制台高频报错包括：WebSocket connection to 'ws://192.168.63.111:8080/ws' failed，伴随具体子错误如 ERR_CONNECTION_REFUSED（服务进程未监听）、ERR_CONNECTION_TIMED_OUT（网络路径中断或中间设备拦截）、net::ERR_NAME_NOT_RESOLVED（DNS/主机名解析失败）等。这些并非WebSocket协议层问题，而是TCP连接建立阶段即已失败——本质是四层（传输层）连通性缺失。

二、网络层：端到端连通性验证矩阵

测试命令	预期成功表现	失败含义	对应排查方向
ping 192.168.63.111	收到响应包（TTL、time=...）	ICMP被禁/主机关机/路由不可达	检查目标主机电源、网卡状态、VLAN划分
telnet 192.168.63.111 8080	出现空白光标或Connected to...	TCP三次握手失败	服务未启动、绑定地址错误、防火墙阻断、NAT映射缺失

三、服务层：后端WebSocket服务就绪性深度校验

仅确认进程存在（ps aux | grep java）远远不够。需验证：

• 监听地址：执行 ss -tlnp | grep :8080 或 netstat -tuln | grep :8080，确认监听为 *:8080 或 0.0.0.0:8080，而非 127.0.0.1:8080（后者仅限本机访问）；
• Spring Boot专项：检查是否启用 @EnableWebSocket 且配置了 WebSocketConfigurer 实现类，同时确认 server.address=0.0.0.0（非默认值）；
• Netty场景：核查 ChannelInitializer 中是否注册了 WebSocketServerProtocolHandler("/ws")，且 ServerBootstrap 绑定在 new InetSocketAddress(0.0.0.0, 8080)。

四、基础设施层：容器化与反向代理的隐性陷阱

Docker部署时常见误区：

# ❌ 错误：仅映射端口但应用绑定localhost
docker run -p 8080:8080 my-websocket-app

# ✅ 正确：确保容器内服务监听0.0.0.0 + 显式端口映射
docker run -p 8080:8080 --network host my-websocket-app  # 或使用host网络模式

Nginx代理需启用WebSocket支持：

location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

五、安全策略层：防火墙与SELinux的静默拦截

Linux系统须执行：

• sudo ufw status verbose → 若Active，则运行 sudo ufw allow 8080；
• sudo firewall-cmd --list-ports → 检查firewalld规则，执行 sudo firewall-cmd --add-port=8080/tcp --permanent && sudo firewall-cmd --reload；
• SELinux启用时，需设置布尔值：sudo setsebool -P httpd_can_network_connect 1（适用于以httpd用户运行的代理）。

六、协议层：WebSocket握手的HTTP兼容性验证

使用curl模拟WebSocket升级请求，验证服务端是否正确响应101状态码：

curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: $(openssl rand -base64 16)" \
  http://192.168.63.111:8080/ws

成功响应应包含：HTTP/1.1 101 Switching Protocols、Upgrade: websocket、Connection: Upgrade 及 Sec-WebSocket-Accept 头。

七、诊断流程图：结构化排障路径

graph TD
  A[浏览器报错] --> B{ERR_CONNECTION_REFUSED?}
  B -->|是| C[服务进程未启动/端口未监听]
  B -->|否| D{ERR_CONNECTION_TIMED_OUT?}
  D -->|是| E[防火墙/NAT/网络策略拦截]
  D -->|否| F[检查HTTP健康端点]
  F --> G[curl -i http://192.168.63.111:8080/health]
  G -->|200 OK| H[执行WebSocket握手测试]
  G -->|非200| I[基础HTTP服务异常]
  H --> J[curl模拟101响应]
  J -->|101返回| K[前端代码或SSL/WSS配置问题]
  J -->|非101| L[后端WebSocket配置缺陷]

```