小智ESP32服务器公网部署常见问题与解决方案

部署环境准备

在公网云服务器上部署小智ESP32服务器时，首先需要确保服务器环境满足基本要求。建议使用Docker容器化部署方式，这种方式能够快速搭建环境并避免依赖冲突问题。服务器应具备至少2GB内存和20GB存储空间，以确保服务稳定运行。

端口配置要点

公网部署最常见的问题就是端口访问失败。小智ESP32服务器默认使用8000端口(WebSocket)和8002端口(HTTP API)，在云服务器上需要特别注意：

1. 检查服务器安全组规则，确保8000和8002端口已开放访问
2. 验证防火墙设置，临时关闭防火墙测试或添加相应规则
3. 确认Docker容器端口映射正确，例如-p 8002:8002这样的映射关系

授权问题排查

当遇到401未授权错误时，通常有以下几种可能：

1. 访问地址不正确，正确的API地址应为http://服务器IP:8002/，而非包含/xiaozhi路径
2. 首次部署时未正确配置.config.yaml文件，需要从管理后台获取并配置正确的secret值
3. 服务启动顺序问题，应先启动manager-api和manager-web服务，注册管理员账号后再配置server

WebSocket连接异常处理

WebSocket服务启动后，如果测试页面无法连接，需要检查：

1. WebSocket地址格式应为ws://服务器IP:8000/xiaozhi/v1/
2. 浏览器控制台查看具体错误信息，常见的有跨域问题或协议错误
3. 服务端日志中的错误信息，如"missing Connection header"可能表明客户端请求头不完整

服务日志分析

通过docker logs -f xiaozhi-esp32-server命令可以查看实时日志，重点关注：

1. 各组件初始化状态，如TTS、LLM、VAD等模块是否成功加载
2. WebSocket服务启动信息，确认监听的IP和端口
3. 错误堆栈信息，特别是InvalidUpgrade等异常

最佳实践建议

1. 首次部署建议先在局域网测试通过后再迁移到公网
2. 使用Nginx反向代理可以简化端口管理并增强安全性
3. 定期备份配置文件和数据目录
4. 保持组件版本更新，但升级前注意查看变更日志

通过以上方法，大多数部署问题都能得到有效解决。如果遇到特殊问题，建议详细记录错误日志和环境信息，这将大大有助于问题诊断。