Keila项目WebSocket连接问题排查与解决方案

在部署Keila邮件营销平台时，用户反馈在创建邮件活动时遇到了编辑器无法正常工作的问题。本文将详细分析该问题的成因，并提供完整的解决方案。

问题现象

用户在使用Keila的邮件编辑器时发现：

1. 纯文本模式下，输入内容无法在预览区域显示
2. Markdown和区块编辑器模式下，完全无法输入内容
3. 浏览器控制台显示WebSocket连接失败的错误信息

根本原因分析

通过检查发现，问题源于Nginx反向代理配置不完整，导致WebSocket协议无法正常工作。Keila的实时编辑器功能依赖于WebSocket连接，当这个连接建立失败时，编辑器功能就会完全失效。

解决方案

完整的Nginx反向代理配置应包含以下关键指令：

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://keila:4000;
        proxy_http_version 1.1;  # 关键配置
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }
}

配置说明

1. proxy_http_version 1.1：强制使用HTTP/1.1协议，这是WebSocket正常工作所必需的
2. Upgrade和Connection头：处理协议升级请求，允许从HTTP切换到WebSocket
3. 其他头信息：确保原始请求信息正确传递到后端服务

验证方法

配置修改后，可以通过以下方式验证是否生效：

1. 检查浏览器开发者工具中的Network标签页，确认WebSocket连接状态为101 Switching Protocols
2. 在Keila编辑器中尝试输入内容，确认所有功能恢复正常
3. 查看Nginx和Keila的日志，确认没有错误信息

最佳实践建议

1. 对于所有需要WebSocket支持的反向代理场景，都应包含上述关键配置
2. 定期检查SSL证书的有效性，避免因证书过期导致连接问题
3. 考虑增加WebSocket连接的超时设置，以适应长时间运行的编辑器会话

通过以上配置调整，Keila的邮件编辑器功能应该能够完全恢复正常工作。这个解决方案不仅适用于Keila项目，对于其他需要WebSocket支持的Elixir/Phoenix应用也同样适用。