Maybe Finance 项目中的 WebSocket 连接问题分析与解决方案

问题背景

在自托管 Maybe Finance 项目时，用户遇到了两个主要的技术问题：一是系统持续显示"Syncing accounts data"状态无法完成同步，二是在日志中频繁出现 WebSocket 连接错误。这些问题影响了系统的正常功能，特别是账户同步和净值计算功能。

问题分析

同步功能异常

同步功能无法完成的问题根源在于数据库中存在状态为"failed"或"pending"的同步记录。这些记录阻塞了新的同步请求，导致系统无法正确计算账户净值。这是一个典型的数据库状态管理问题，需要清理无效的同步记录才能恢复正常功能。

WebSocket 连接错误

日志中出现的错误信息表明，系统尝试建立 WebSocket 连接时失败。具体错误为"Failed to upgrade to WebSocket"，并显示缺少必要的 HTTP 头信息(HTTP_CONNECTION 和 HTTP_UPGRADE)。这通常发生在反向代理配置不当的情况下，特别是当 Nginx 没有正确转发 WebSocket 所需的特殊头信息时。

解决方案

同步功能修复

1. 连接到 Maybe Finance 的数据库
2. 执行以下 SQL 命令清理无效的同步记录：

DELETE FROM syncs
WHERE status IN ('failed', 'pending');

3. 重新触发账户同步操作

这个操作会清除所有失败和待处理的同步记录，允许系统创建新的有效同步任务。

WebSocket 连接修复

针对 Nginx 反向代理配置问题，需要进行以下调整：

1. 在 Nginx 配置文件中为 Maybe Finance 的服务添加专门的 /cable 路径处理
2. 确保配置中包含 WebSocket 连接所需的特殊头信息

完整的 Nginx 配置示例：

server {
    listen 443 ssl;
    server_name maybe.example.com;
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/key.key;

    location / {
        proxy_pass http://backend:3004;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    location /cable {
        proxy_pass http://backend:3004/cable;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

关键配置说明：

1. proxy_http_version 1.1：启用 HTTP/1.1 协议，这是 WebSocket 的基础
2. Upgrade $http_upgrade：转发客户端请求的 Upgrade 头
3. Connection "upgrade"：将连接类型设置为 upgrade，这是 WebSocket 握手的关键

技术原理

WebSocket 连接机制

WebSocket 协议通过在标准 HTTP 连接上执行"升级"握手来建立持久连接。完整的握手过程需要：

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

在反向代理环境中，这些特殊头信息必须被明确地转发到后端服务器，否则握手会失败。

Maybe Finance 的实时通信需求

Maybe Finance 使用 Action Cable（基于 WebSocket 的技术）来实现以下功能：

1. 实时同步状态更新
2. 后台任务进度通知
3. 即时数据刷新

这些功能都依赖于稳定的 WebSocket 连接，因此正确的代理配置至关重要。

实施建议

1. 在修改 Nginx 配置后，务必测试配置语法并重载服务：

nginx -t
nginx -s reload

2. 对于生产环境，建议设置适当的 WebSocket 超时和缓冲区参数：

proxy_read_timeout 86400;
proxy_send_timeout 86400;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;

3. 监控 WebSocket 连接状态，可以使用浏览器开发者工具或专门的 WebSocket 测试工具验证连接是否正常建立。

总结

Maybe Finance 项目在自托管环境下可能会遇到同步功能和 WebSocket 连接的问题。通过清理数据库中的无效同步记录和正确配置 Nginx 反向代理的 WebSocket 支持，可以有效地解决这些问题。理解 WebSocket 的工作原理和 Action Cable 的技术需求，有助于更好地维护和优化 Maybe Finance 的自托管实例。