Chatwoot项目中WebSocket实时消息更新问题的分析与解决

问题背景

在Chatwoot客服系统项目中，用户反馈了一个关于WebSocket实时通信的问题：当通过Chatwoot小部件进行对话时，发送的消息无法实时显示，必须手动刷新页面才能看到新消息。虽然WebSocket连接已成功建立，后端日志也显示消息处理正常，但前端界面却无法实时更新。

技术环境分析

该问题出现在以下技术环境中：

• Chatwoot版本：3.15.0
• 部署方式：Docker容器化部署
• 反向代理：使用pfSense的HAProxy进行SSL终止
• 数据库：PostgreSQL
• 缓存：Redis用于缓存和Sidekiq任务队列

问题现象

具体表现为：

1. 用户打开网站上的Chatwoot小部件并开始对话
2. 发送消息后，消息不会立即显示在小部件中
3. 后端日志确认消息已成功处理
4. 只有手动刷新页面后，消息才会显示

根本原因分析

经过深入排查，发现问题的根源在于WebSocket握手过程中的HTTP头信息处理不当。具体原因包括：

1. WebSocket握手头缺失：WebSocket连接需要特定的HTTP头信息(Connection: Upgrade和Upgrade: websocket)来完成握手，而HAProxy默认配置没有正确处理这些头信息。

2. SSL终止配置问题：Chatwoot配置了FORCE_SSL=true，要求所有连接都使用HTTPS，但内部服务实际上使用的是HTTP连接。

3. 代理头信息传递不完整：反向代理没有正确传递X-Forwarded-Proto头，导致后端服务无法识别原始连接的安全性。

解决方案

针对上述问题，我们实施了以下解决方案：

1. HAProxy配置优化

在pfSense的HAProxy配置中添加以下规则：

http-request set-header Connection "Upgrade" if { hdr(Upgrade) -i websocket }
http-request set-header Upgrade "websocket" if { hdr(Upgrade) -i websocket }
http-request set-header X-Forwarded-Proto https

这些规则确保：

• 正确设置WebSocket握手所需的头信息
• 明确标识原始连接为HTTPS
• 保持WebSocket连接的稳定性

2. SSL配置调整

考虑到HAProxy已经处理了SSL终止，我们可以：

• 保持外部HTTPS连接的安全性
• 允许内部服务使用HTTP通信
• 通过X-Forwarded-Proto头确保后端服务了解原始连接的安全性

技术原理详解

WebSocket握手过程

WebSocket协议通过HTTP/HTTPS连接发起，但随后升级为全双工通信。完整的握手过程需要：

1. 客户端发送包含Upgrade头的HTTP请求
2. 服务器响应确认升级
3. 连接从HTTP协议切换到WebSocket协议

HAProxy中的WebSocket支持

HAProxy作为反向代理，需要特别配置才能正确处理WebSocket协议。关键点包括：

• 识别WebSocket升级请求
• 保持连接的长久性
• 正确转发必要的头信息

SSL终止架构

在SSL终止架构中：

• 外部客户端与HAProxy建立HTTPS连接
• HAProxy解密流量后，以HTTP形式转发到内部服务
• X-Forwarded-Proto头告知内部服务原始连接是HTTPS

实施建议

对于类似架构的实施，建议：

1. 明确网络拓扑：清晰划分安全边界，确定SSL终止的位置
2. 完整测试WebSocket功能：部署后应全面测试实时通信功能
3. 监控连接状态：建立对WebSocket连接状态的监控机制
4. 日志记录：确保详细记录WebSocket握手和通信过程

总结

通过分析Chatwoot项目中的WebSocket实时消息问题，我们不仅解决了特定的技术故障，还深入理解了WebSocket在反向代理环境中的工作方式。正确的头信息处理和SSL终止配置是确保实时通信功能正常工作的关键。这一解决方案不仅适用于Chatwoot项目，也可为其他类似架构的WebSocket实现提供参考。