Apache DevLake 数据仪表盘显示问题排查指南

Apache DevLake 是一个开源的数据湖平台，用于收集、分析和可视化软件开发过程中的各种指标。在使用过程中，用户可能会遇到数据成功连接但仪表盘无法显示的问题。本文将详细介绍该问题的排查思路和解决方案。

问题现象分析

当用户完成数据源连接配置后，访问仪表盘页面时可能出现空白显示的情况。通过浏览器开发者工具检查，通常会发现以下两类错误信息：

1. WebSocket连接失败，指向/api/live/ws端点
2. 仪表盘数据API请求失败

这些现象表明前端界面与后端服务之间的实时通信和数据获取出现了问题。

根本原因探究

经过分析，这类问题通常由以下几个因素导致：

1. WebSocket配置不当：DevLake使用WebSocket实现实时数据更新，若服务端未正确配置跨域或WebSocket支持，会导致连接失败。

2. 服务依赖异常：DevLake由多个微服务组成(config-ui、devlake、mysql等)，任一服务启动失败都会影响整体功能。

3. 网络访问限制：网络策略可能阻止了必要的端口通信。

4. 版本兼容性问题：不同组件版本间可能存在兼容性缺陷。

详细解决方案

1. 验证WebSocket连接

首先需要确认WebSocket服务是否正常运行。可以通过以下方法测试：

// 在浏览器控制台执行以下代码测试WebSocket连接
const socket = new WebSocket("ws://localhost:4000/api/live/ws");

socket.onopen = () => console.log("WebSocket连接成功");
socket.onerror = (e) => console.error("连接错误:", e);
socket.onclose = (e) => console.log("连接关闭:", e.code, e.reason);

如果连接失败，需要检查：

• 确保GF_LIVE_ALLOWED_ORIGINS环境变量设置为'*'
• 确认4000端口未被占用且未被网络策略阻止

2. 检查服务状态

使用Docker Compose部署时，执行以下命令验证服务状态：

docker-compose ps

确保所有服务状态均为"Up"。特别注意config-ui和devlake两个核心服务。

3. 网络配置检查

确认主机网络配置：

• 本地网络策略是否放行了4000端口
• 如果是云服务器，检查访问控制规则
• 确保没有代理设置干扰本地连接

4. 数据采集验证

即使连接成功，仪表盘无数据也可能是采集任务未正确执行：

1. 进入DevLake控制台，检查"任务"页面
2. 确认对应数据源的任务状态为"SUCCESS"
3. 如有失败任务，查看日志获取详细信息

5. 高级排查手段

如果上述步骤未能解决问题，可以：

1. 检查各容器日志：

   docker-compose logs -f config-ui
   docker-compose logs -f devlake
   

2. 验证数据库连接：

   • 确认MySQL容器正常运行
   • 检查.env文件中的数据库配置是否正确

3. 尝试清理后重新部署：

   docker-compose down -v
   docker-compose up -d
   

预防措施

为避免类似问题再次发生，建议：

1. 部署前仔细阅读版本发布说明，了解已知问题
2. 使用稳定版本而非Beta版用于生产环境
3. 定期备份重要配置和数据
4. 监控服务运行状态，设置告警机制

通过系统化的排查和验证，大多数仪表盘显示问题都能得到有效解决。如问题持续存在，建议收集完整的环境信息和日志，向社区寻求进一步帮助。