Frappe/ERPNext Docker 部署中的 WebSocket 连接问题分析与解决方案

问题背景

在基于 Docker 的 Frappe/ERPNext 部署中，许多开发者遇到了 WebSocket 连接无法建立的问题。这个问题主要表现为前端无法与 socket.io 服务建立稳定的 WebSocket 连接，导致实时功能无法正常工作。

问题现象

当使用默认的 docker-compose 配置部署 Frappe/ERPNext 时，前端容器虽然能够正常加载网页应用，但浏览器控制台会显示 WebSocket 连接错误。典型的错误信息包括：

• 无法建立到 ws://localhost:8080/socket.io 的连接
• 连接在页面加载过程中被中断
• HTTP 400 错误响应

根本原因分析

经过深入调试，发现问题根源在于 WebSocket 服务的中间件认证逻辑。具体来说：

1. WebSocket 服务在建立连接时会尝试通过 HTTP 请求获取用户信息
2. 这个请求的 URL 构造存在问题，没有正确处理端口信息
3. 当使用非标准端口（如 8080）时，请求会失败并返回 400 错误
4. 失败导致 WebSocket 连接无法完成认证，最终被中断

解决方案

临时解决方案

对于使用 v15.37.0 版本的用户，可以修改 WebSocket 服务的 URL 构造逻辑：

1. 修改 get_url 函数，使其能够正确处理端口信息
2. 从请求头中提取端口信息并包含在构造的 URL 中

长期解决方案

在较新版本的 Frappe 中，这个问题已经在开发分支中得到修复。新版本的 get_url 函数实现更加健壮，能够正确处理开发者模式下的端口配置。

最佳实践建议

1. 站点命名一致性：确保在创建站点时使用的名称与 FRAPPE_SITE_NAME_HEADER 环境变量完全一致
2. 端口配置：如果必须使用非标准端口，考虑在开发者模式下明确配置 webserver_port
3. 版本选择：考虑使用包含修复的较新版本 Frappe/ERPNext
4. 缓存清理：在应用更改后，务必清理浏览器缓存以避免旧代码的影响

总结

WebSocket 连接问题在 Frappe/ERPNext 的 Docker 部署中较为常见，主要源于 URL 构造逻辑对非标准端口的支持不足。通过理解问题本质并应用适当的解决方案，开发者可以确保实时功能的正常工作，为用户提供完整的应用体验。

对于生产环境部署，建议使用标准端口或通过反向代理（如 Nginx）处理端口转换，这可以避免许多与端口相关的问题。同时，保持对官方更新的关注，及时应用修复和改进也是维护系统稳定性的重要手段。