Docmost新安装后出现空白页面问题分析与解决方案

问题现象

在使用Docker Compose全新安装Docmost文档协作平台时，用户遇到了前端页面显示空白的问题。通过浏览器开发者工具检查，发现API请求返回404错误，提示"Workspace not found"。该问题出现在多个不同的浏览器中，包括Firefox、Chrome和Safari。

环境配置

用户使用的是标准Docker Compose部署方案，主要配置如下：

• Docmost镜像版本：latest
• 数据库：PostgreSQL 16
• 缓存：Redis 7.2
• 应用端口映射：8758:3000
• 环境变量包括APP_URL、APP_SECRET、DATABASE_URL和REDIS_URL

根本原因分析

经过排查，发现这个问题主要由两个因素导致：

1. APP_URL配置不当：原始配置中APP_URL设置为"http://localhost:3000"，而实际上应用通过8758端口对外暴露，这导致前端请求路径不正确。

2. 工作区初始化问题：系统检测到没有创建任何工作区时，会返回"Workspace not found"错误，这是预期行为，但前端未能正确处理这个响应并进行重定向。

解决方案

方法一：修正APP_URL配置

将docker-compose.yml文件中的APP_URL修改为实际访问地址：

environment:
  APP_URL: "http://实际IP地址:8758"

如果通过反向代理访问，则应设置为：

environment:
  APP_URL: "https://您的域名"

方法二：升级到最新版本

Docmost团队已在v0.2.1版本中修复了前端重定向逻辑问题。建议用户按照以下步骤升级：

1. 停止当前运行的容器
2. 拉取最新镜像
3. 重新启动服务

验证步骤

升级或修改配置后，可通过以下方式验证问题是否解决：

1. 清除浏览器缓存
2. 访问应用URL
3. 检查浏览器控制台是否有错误
4. 确认是否能够正常显示注册或登录界面

最佳实践建议

1. 环境变量配置：确保APP_URL与实际的访问地址完全一致，包括协议(http/https)、域名和端口。

2. 版本管理：建议固定使用特定版本而非latest标签，便于问题追踪和回滚。

3. 日志监控：部署后检查容器日志，确认数据库迁移是否成功完成。

4. 网络配置：如果使用反向代理，确保代理配置正确传递所有必要的头部信息。

通过以上措施，应该能够解决Docmost新安装后出现的空白页面问题，使系统正常运行。