Frappe Docker项目中WebSocket连接问题的分析与解决

问题背景

在Frappe Docker项目部署过程中，WebSocket连接失败是一个常见问题。具体表现为浏览器控制台出现"WebSocket connection failed"错误，导致实时数据更新功能无法正常工作。本文将从技术角度深入分析该问题的成因，并提供完整的解决方案。

问题现象

部署Frappe/ERPNext系统后，前端页面无法建立WebSocket连接，控制台显示类似以下错误：

WebSocket connection to 'wss://xxxx/socket.io/?EIO=4&transport=websocket&sid=elHjhjQeQBL4OM48AAAv' failed

此时检查frappe.realtime.socket.connected状态会返回false，表明WebSocket连接确实未能建立。

根本原因分析

经过深入排查，发现问题的核心在于FRAPPE_SITE_NAME_HEADER环境变量的配置不当。这个变量在Frappe Docker架构中扮演着关键角色：

1. Nginx代理配置：该变量值会被用于Nginx配置模板中，特别是处理socket.io服务器请求的路由规则
2. 请求头验证：Frappe后端会验证请求头中的站点名称是否匹配
3. WebSocket握手：在建立WebSocket连接时，该值必须与实际访问域名一致

解决方案

正确的配置方法如下：

1. 使用完整域名：FRAPPE_SITE_NAME_HEADER必须设置为完整的访问域名，而非简短的站点名称
2. Nginx配置同步：确保Nginx配置中的相关路由规则与这个域名值匹配
3. 环境一致性：所有相关服务（前端、WebSocket、后端）都应使用相同的域名配置

配置示例

在docker-compose.yml文件中，正确的配置应类似：

environment:
  FRAPPE_SITE_NAME_HEADER: your-full-domain.com

在common_site_config.json中，确保WebSocket相关配置正确：

{
  "socketio_port": 9000,
  "redis_socketio": "redis://redis-queue:6379"
}

验证步骤

1. 检查WebSocket容器是否正常运行且健康状态为"healthy"
2. 确认Nginx访问日志中WebSocket连接请求是否被正确处理
3. 在前端控制台验证frappe.realtime.socket.connected状态是否为true
4. 测试实时功能（如消息通知、数据更新）是否正常工作

总结

WebSocket连接问题在Frappe Docker部署中较为常见，但通过正确配置FRAPPE_SITE_NAME_HEADER环境变量，并确保整个架构中各组件配置一致，可以有效解决。理解Frappe架构中WebSocket的工作机制对于排查此类问题至关重要。建议在部署前仔细阅读相关环境变量说明文档，避免因配置不当导致功能异常。