AFFiNE自建服务中工作空间无法显示的WebSocket配置问题解析

在使用AFFiNE自建服务时，部分用户遇到了工作空间无法正常显示的问题。本文将深入分析该问题的成因，并提供完整的解决方案。

问题现象

用户报告在自建AFFiNE服务(版本22.05)中，新建的工作空间在下次登录时无法显示。具体表现为：

1. 首次创建的工作空间在创建时浏览器中可以正常访问
2. 更换浏览器或重启后，工作空间列表为空
3. 邀请协作的同事也无法访问共享的工作空间

根本原因分析

经过技术分析，该问题的核心在于WebSocket连接未正确配置。AFFiNE的实时协作功能高度依赖WebSocket协议来实现：

1. 数据同步机制：AFFiNE使用WebSocket保持客户端与服务端的持久连接，实现文档的实时同步
2. 首次访问特殊性：首次创建时能访问是因为浏览器缓存了部分数据，但这不是持久化方案
3. 反向代理影响：当使用Nginx等反向代理时，默认配置可能不会正确处理WebSocket连接

解决方案

针对Nginx反向代理的配置

对于使用Nginx作为反向代理的用户，需要添加以下配置：

location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

关键配置说明：

• proxy_http_version 1.1：启用HTTP/1.1协议，这是WebSocket的基础
• Upgrade和Connection头：告知Nginx需要将连接升级为WebSocket
• Host头：保持原始请求的主机信息

针对Docker部署的注意事项

对于Docker部署的用户，还需确保：

1. 容器端口映射正确，通常为3000端口
2. 检查防火墙设置，确保WebSocket端口(通常为ws://或wss://)未被阻止
3. 如果使用SSL，确认证书配置正确且包含WebSocket安全连接

验证方法

配置完成后，可通过以下方式验证WebSocket是否正常工作：

1. 浏览器开发者工具中查看Network标签页，应能看到WebSocket连接
2. 创建新工作空间后，关闭并重新打开浏览器，检查是否仍可访问
3. 邀请其他用户协作，确认他们能正常访问共享空间

最佳实践建议

1. 生产环境部署：建议使用域名和有效SSL证书，配置wss://安全连接
2. 性能优化：对于高并发场景，可考虑调整Nginx的WebSocket相关超时参数
3. 监控设置：建立对WebSocket连接状态的监控，及时发现并解决问题

通过正确配置WebSocket连接，AFFiNE自建服务的工作空间显示和协作功能将能稳定运行，为用户提供流畅的协作体验。