Perplexica项目WebSocket连接失败问题分析与解决方案

问题背景

Perplexica是一个开源的人工智能搜索项目，近期用户反馈在更新代码后出现了"Failed to connect to the server"的错误提示。这个问题主要影响系统的WebSocket连接功能，导致前端无法与后端正常通信。

错误现象分析

从日志中可以观察到几个关键错误信息：

1. 后端服务启动时频繁出现Ollama模型加载失败的错误：

error: Error loading Ollama models: TypeError: fetch failed
error: Error loading Ollama embeddings model: TypeError: fetch failed

2. 前端控制台显示WebSocket连接失败，并出现404错误

3. 网络请求中最后可见的是WebSocket协议切换请求(状态码101)，但后续连接被中断

根本原因

经过深入分析，发现该问题主要由以下几个因素共同导致：

1. 网络配置问题：Docker容器内部的localhost与宿主机网络环境不匹配。容器内的localhost指向的是容器自身的网络命名空间，而非宿主机的网络。

2. Ollama服务配置不当：Ollama服务默认只监听127.0.0.1，需要通过systemd配置修改为监听0.0.0.0才能被容器访问。

3. WebSocket连接稳定性：在网络质量不佳时，WebSocket连接容易中断且缺乏重试机制。

4. Docker基础镜像限制：使用node:slim作为基础镜像可能缺少某些网络依赖库。

解决方案

1. 网络配置修正

修改docker-compose.yaml文件，使用宿主机的实际IP地址而非localhost：

perplexica-frontend:
  build:
    context: .
    dockerfile: app.dockerfile
    args:
      - NEXT_PUBLIC_API_URL=http://192.168.x.x:3001/api
      - NEXT_PUBLIC_WS_URL=ws://192.168.x.x:3001

2. Ollama服务配置

确保Ollama服务监听所有网络接口：

[Service]
Environment="OLLAMA_HOST=0.0.0.0"

3. Docker基础镜像优化

将backend.dockerfile中的基础镜像从node:slim改为完整版node:

FROM node:18

4. 防火墙配置

确保宿主机的防火墙允许Ollama服务端口(默认11434)的入站连接。

进阶建议

1. 网络质量监控：在网络不稳定的环境中，建议实现WebSocket连接的重试机制。

2. 容器网络优化：考虑使用Docker的host网络模式或自定义网络桥接，简化网络配置。

3. 错误处理增强：前端应增加更友好的连接状态提示和自动重连功能。

总结

Perplexica的连接问题是一个典型的容器化应用网络配置挑战。通过正确配置服务监听地址、优化Docker网络设置和选择合适的基础镜像，可以有效解决这类连接问题。对于生产环境部署，还需要考虑网络稳定性、安全策略和错误恢复机制等更全面的因素。

项目维护者已在最新版本中优化了相关代码，建议用户按照更新指南升级到最新版本以获得最佳体验。