Apache DevLake 数据仪表盘不显示的排查与解决

Apache DevLake 是一款开源的数据湖平台，用于收集、分析和可视化软件开发过程中的各种数据。在使用过程中，用户可能会遇到数据连接成功但仪表盘不显示数据的问题。本文将深入分析这一常见问题的原因，并提供详细的解决方案。

问题现象分析

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

1. WebSocket 连接失败：指向 /api/live/ws 端点的连接无法建立
2. API 请求失败：获取仪表盘数据的接口返回错误

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

根本原因探究

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

1. WebSocket 配置不当：Grafana 服务未正确配置允许跨域 WebSocket 连接
2. 网络端口冲突：4000 端口可能被其他服务占用或防火墙阻止
3. 服务依赖异常：MySQL 或核心 DevLake 服务未正常启动
4. 环境变量缺失：关键的加密密钥等配置未正确设置
5. 版本兼容性问题：使用的组件版本之间存在不兼容

详细解决方案

1. 检查服务运行状态

首先确认所有相关容器是否正常运行：

docker-compose ps

应该能看到 mysql、devlake 和 config-ui 三个服务都处于 "Up" 状态。如有异常，检查日志：

docker-compose logs -f 服务名

2. 验证 WebSocket 配置

修改 docker-compose.yml 中 config-ui 服务的环境变量配置，确保包含：

environment:
  - GF_LIVE_ALLOWED_ORIGINS=*

3. 测试端口连通性

确保 4000 端口可访问：

curl -v http://localhost:4000/api/ping

如果无法连接，检查防火墙设置或端口占用情况。

4. 手动测试 WebSocket 连接

在浏览器控制台执行以下代码测试 WebSocket：

const socket = new WebSocket("ws://localhost:4000/api/live/ws");
socket.onopen = () => console.log("连接成功");
socket.onerror = (e) => console.error("连接失败", e);

5. 检查数据采集状态

即使连接成功，仪表盘无数据也可能是采集未完成：

1. 进入任务管理界面，确认数据采集任务状态
2. 检查是否有错误日志
3. 对于大型仓库，采集可能需要较长时间

6. 环境变量验证

确保 .env 文件中包含必要的配置：

• ENCRYPTION_SECRET：通过 openssl 生成的加密密钥
• DB_URL：数据库连接字符串
• GRAFANA_PORT：Grafana 服务端口

预防措施

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

1. 使用官方推荐的版本组合
2. 部署前仔细检查环境变量配置
3. 对于生产环境，建议使用更完善的监控方案
4. 定期备份重要配置和数据

总结

Apache DevLake 仪表盘数据显示问题通常源于服务间通信异常或配置不当。通过系统性地检查服务状态、网络连接和配置参数，大多数情况下都能快速定位并解决问题。对于复杂环境，建议分步骤验证各组件功能，逐步缩小问题范围。

掌握这些排查方法后，用户不仅能解决当前问题，还能提升对整个系统架构的理解，为后续的运维工作打下坚实基础。