xiaozhi-esp32-server项目WebSocket连接问题分析与解决

问题背景

在xiaozhi-esp32-server项目中使用Docker全模块部署时，测试页面test_page.html中的WebSocket连接出现异常，无法成功建立连接。虽然OTA功能正常工作，但WebSocket连接始终失败，无论使用本地IP(127.0.0.1)、Docker内部IP(172.19.0.4)还是服务器实际IP(10.212.255.202)都无法连接。

问题现象

测试页面尝试连接ws://10.212.255.202:8000/xiaozhi/v1/时出现连接失败。从用户提供的截图可以看到：

1. 浏览器控制台显示WebSocket连接错误
2. 服务器配置中WebSocket参数设置正确
3. OTA功能可以正常工作，说明基础网络通信正常

排查过程

初步检查

1. 防火墙状态检查：确认服务器防火墙已关闭，排除了防火墙拦截的可能性
2. 端口连通性测试：使用telnet命令测试8000端口，结果显示端口是开放的，可以建立TCP连接

深入分析

虽然telnet测试显示端口开放，但WebSocket连接仍然失败，这表明：

1. WebSocket服务可能没有正确启动或监听
2. 可能存在路径配置问题(/xiaozhi/v1/)
3. Docker网络配置可能有特殊限制
4. WebSocket协议握手过程可能失败

解决方案

经过多次尝试，最终通过以下步骤解决了问题：

1. 重建虚拟机环境：原有环境可能存在未知配置问题
2. 全新部署项目：确保所有组件都是最新且干净的安装
3. 验证网络配置：确认Docker容器间的网络通信正常
4. 检查WebSocket服务日志：确保服务启动无报错

经验总结

1. 当WebSocket连接失败但端口测试正常时，应该检查服务本身是否正常运行
2. Docker环境中的网络配置需要特别注意，特别是跨容器通信
3. 对于难以定位的问题，重建环境有时是最有效的解决方案
4. 建议在部署后立即测试WebSocket连接，以便快速发现问题

预防措施

为避免类似问题再次发生，建议：

1. 在部署脚本中加入WebSocket连接测试
2. 记录详细的部署日志，便于问题排查
3. 使用容器健康检查机制监控WebSocket服务状态
4. 编写详细的部署文档，包括常见问题解决方法

通过这次问题排查，我们更加理解了在容器化环境中部署WebSocket服务的注意事项，为后续项目部署积累了宝贵经验。