客户端使用服务器IPv4地址无法连接WebSocket服务端如何排查

这类localhost可访问、IPv4地址无法访问的问题90%以上是服务监听绑定配置错误，剩下基本是防火墙、网络配置问题，按以下顺序排查即可： #

1. 优先检查服务端监听地址配置 #

绝大多数人踩的第一个坑：服务默认只绑定了回环地址。
当你启动WebSocket服务时，如果传入的host参数为localhost或者127.0.0.1，系统只会把服务挂载到本地回环网卡上，仅接受来自本机localhost的请求，所有来自物理网卡、其他设备的请求都会被直接拒绝。

• 正确配置：将host参数改为0.0.0.0，代表监听本机所有网卡（包括回环、有线、无线网卡）的入站请求。
  以常用的websockets库为例，两种写法对比如下：

错误写法（仅本地可访问）：

import asyncio
import websockets

async def handler(websocket):
    # 你的业务逻辑
    pass

async def main():
    async with websockets.serve(handler, "localhost", 8765):
        await asyncio.Future()

asyncio.run(main())

正确写法（局域网可访问）：

import asyncio
import websockets

async def handler(websocket):
    # 你的业务逻辑
    pass

async def main():
    async with websockets.serve(handler, "0.0.0.0", 8765):
        await asyncio.Future()

asyncio.run(main())

改完配置重启服务后，可以通过命令确认监听状态：

• Windows系统执行：netstat -ano | findstr "你的服务端口"
• Linux/macOS系统执行：ss -tulpn | grep 你的服务端口
  如果返回结果中本地地址列显示0.0.0.0:你的端口，说明监听配置生效；如果显示127.0.0.1:你的端口，说明绑定配置未生效，检查代码中host参数是否被其他配置覆盖、是否重启了服务。

2. 检查系统/第三方防火墙拦截 #

如果监听地址配置正确，本机用IPv4地址依然连不上，基本是防火墙拦截了非回环网卡的入站请求：

• 先临时关闭系统防火墙测试连接，如果关闭后可以连通，说明是防火墙规则问题，不需要长期关闭防火墙，只需要给你的WebSocket服务对应端口添加入站允许规则即可：
  • Windows：打开「高级安全Windows Defender防火墙」，新建入站规则，允许对应TCP端口的入站连接
  • Linux（ufw防火墙）：执行sudo ufw allow 你的端口号/tcp生效规则
  • macOS：在系统设置-网络-防火墙配置中，给Python运行环境添加入站连接白名单
• 如果你装了第三方杀毒、安全软件，也要检查这类软件的网络防护规则是否拦截了对应端口。

3. 检查网络配置问题 #

如果本机用IPv4已经能连通，但是ESP、树莓派等其他设备连不上，按以下点排查：

• 确认你用的IPv4地址是当前连接局域网的物理网卡地址：不要选WSL、虚拟机等虚拟网卡的IP，物理网卡的局域网IP一般是192.168.x.x、10.x.x.x、172.16-31.x.x网段，可通过ipconfig(Windows)、ip a(Linux/macOS)查询
• 确认所有设备在同一个局域网下：不要出现电脑连主Wi-Fi、IoT设备连访客Wi-Fi的情况
• 检查路由器是否开启了AP隔离（客户端隔离）：该功能会禁止局域网内设备互相通信，登录路由器后台关闭该功能即可
• 如果你用的端口是1024以下的特权端口，建议换成1024-65535之间的端口，避免系统权限限制导致的连接失败

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