HyperDX 开源项目架构解析与开发指南
项目地址: https://gitcode.com/gh_mirrors/hy/hyperdx 项目概述
HyperDX 是一个现代化的可观测性平台，采用微服务架构设计，集成了日志、指标和追踪数据的收集、存储与分析功能。本文将深入解析其架构设计，并提供完整的本地开发环境搭建指南。
核心架构解析
数据处理流水线
-
数据采集层 (otel)
- 基于 OpenTelemetry Collector 实现
- 支持接收符合 OpenTelemetry 标准的数据
- 负责将原始数据转发至下游处理服务
-
数据摄入层 (ingestor)
- 采用 Vector 构建的事件处理管道
- 功能包括：
- 接收 OpenTelemetry 和非 OpenTelemetry 格式数据
- 数据解析与标准化处理
- 数据转发至聚合服务
-
数据聚合层 (aggregator)
- Node.js 实现的服务
- 核心职责：
- 接收来自 ingestor 的事件数据
- 执行身份验证
- 将有效数据写入 Clickhouse 存储
数据存储系统
-
Clickhouse
- 高性能列式数据库
- 存储所有事件数据
- 优势：高吞吐写入、高效分析查询
-
MongoDB
- 文档型数据库
- 存储用户数据、告警配置和仪表板定义
应用服务层
-
API 服务
- Node.js 实现
- 为前端提供数据查询接口
- 执行 Clickhouse 查询并返回结果
-
日志聚类服务 (miner)
- 基于 FastAPI 实现
- 集成 drain3 日志聚类算法
- 自动识别和归类相似日志模式
-
前端应用 (app)
- Next.js 框架构建
- 提供完整的用户交互界面
-
告警检测服务 (task-check-alerts)
- 持续监控数据指标
- 根据预设条件触发告警
本地开发环境搭建
基础环境准备
- 确保已安装 Docker 和 Docker Compose
- 建议分配至少 8GB 内存给 Docker
启动开发环境
执行以下命令启动完整开发栈：
docker compose -f ./docker-compose.dev.yml up -d
该命令会启动所有服务，并配置好服务间的网络连接。
启用自监控功能
如需启用系统自监控和演示日志功能：
- 首先访问本地前端界面创建账户
- 获取 ingestion API key
- 设置环境变量后重启服务：
HYPERDX_API_KEY=<你的API密钥> docker compose -f ./docker-compose.dev.yml up -d
开发特性说明
- 热重载支持：核心服务都配置了代码热更新，修改代码后会立即生效
- 服务隔离：各服务独立运行，便于针对性调试
测试执行指南
集成测试
运行完整集成测试套件：
make dev-int
针对性测试
如需运行特定测试文件：
make dev-int FILE=测试文件名
Windows 开发注意事项
在 WSL 2 环境下开发时需注意：
- Next.js 前端热重载在原生 Windows Docker 中可能无法正常工作
- 解决方案：
- 在 WSL 2 内直接运行 Docker 命令
- 项目目录应放在 WSL 文件系统内（如 /home/用户名）
- 避免使用 /mnt/c/ 等挂载目录
开发建议
- 性能监控：开发时可利用系统自监控功能观察各服务资源使用情况
- 调试技巧：
- 通过修改日志级别获取详细运行信息
- 使用 Docker 日志命令查看各服务输出
- 配置管理：重要参数建议通过环境变量配置，便于不同环境切换
通过本文介绍的开发环境搭建方法和架构理解，开发者可以快速开始 HyperDX 项目的功能开发和问题排查工作。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
