starseekai
/
light-sentry-sdk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
light-sentry-sdk/docs/00-architecture.md

10 KiB
Raw Permalink Blame History

Light-Sentry 轻量级前端监控系统 - 架构设计文档

一、设计理念

1.1 核心原则

  • 轻量优先：SDK < 10KB (gzip)，服务端单节点可运行
  • 插件化架构：核心极小，功能通过插件扩展，按需加载
  • 性能友好：不阻塞主线程，不影响页面性能
  • 易于部署：docker-compose up 一键启动，无需复杂运维
  • 兼容 Sentry：接口兼容 Sentry 协议，可平滑迁移

1.2 设计目标

指标 目标值 说明
SDK 核心体积 < 5KB gzip 只含事件总线和上报
SDK 完整体积 < 15KB gzip 含错误+性能+网络插件
单节点承载 10万+ 事件/天 1C2G 服务器
部署时间 < 5 分钟 docker-compose 一键部署
数据延迟 < 30 秒 从上报到可查询

二、整体架构

2.1 架构图

┌─────────────────────────────────────────────────────────────┐
│                        前端 SDK                              │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌──────────────┐  │
│  │ Error   │  │ Perf    │  │ Network │  │  Behavior    │  │
│  │ Plugin  │  │ Plugin  │  │ Plugin  │  │  Plugin      │  │
│  └────┬────┘  └────┬────┘  └────┬────┘  └──────┬───────┘  │
│       └─────────────┴─────────────┴──────────────┘          │
│                          │                                   │
│                    ┌─────┴─────┐                             │
│                    │   Core    │                             │
│                    │ (EventBus │                             │
│                    │  + Queue  │                             │
│                    │  + Report)│                             │
│                    └─────┬─────┘                             │
└──────────────────────────┼───────────────────────────────────┘
                           │ HTTP (beacon / fetch / img)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Nginx 反向代理                            │
│            限流 · CORS · 负载均衡 · SSL 卸载                 │
└──────────────────────────┬───────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   API 接入层 (Node.js)                       │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  1. DSN 认证 (publicKey 校验)                          │  │
│  │  2. 协议解析 (envelope / store / 自定义)               │  │
│  │  3. 数据清洗 (脱敏、过滤、去重)                        │  │
│  │  4. 错误指纹计算                                      │  │
│  │  5. 内存队列 + 批量写入                               │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────┬───────────────────────────┬──────────────────────┘
           ▼                           ▼
┌─────────────────────┐     ┌───────────────────────┐
│     Loki (日志)      │     │   MySQL (聚合数据)     │
│  - 原始错误堆栈      │     │  - 项目配置           │
│  - 性能指标明细      │     │  - 错误聚合统计       │
│  - 用户行为日志      │     │  - 性能指标趋势       │
│  保留: 7-30 天       │     │  - 告警规则           │
└─────────────────────┘     │  - 用户管理           │
                             └───────────┬───────────┘
                                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   查询 & 展示层                              │
│  ┌──────────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │  管理后台     │  │  告警引擎 │  │   Grafana 仪表盘     │  │
│  │  (原生 JS)    │  │ (规则引擎)│  │   (复用现有工具)      │  │
│  │  - 项目管理   │  │  - 规则  │  │  - 错误趋势图        │  │
│  │  - 错误查询   │  │  - 收敛  │  │  - 性能仪表盘        │  │
│  │  - 性能分析   │  │  - 通知  │  │  - 自定义面板        │  │
│  └──────────────┘  └──────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

2.2 模块职责

层级 模块 职责 技术选型
采集层 前端 SDK 数据采集、队列、上报 TypeScript + 插件化
接入层 API Server 认证、解析、清洗、入队 Node.js + Express
存储层 Loki 原始日志存储 Grafana Loki
存储层 MySQL 聚合数据、配置、用户 MySQL 8.0 / SQLite
计算层 聚合服务 错误聚合、性能统计 定时任务 / 实时聚合
计算层 告警引擎 规则匹配、告警通知 内置规则引擎
展示层 管理后台 项目管理、数据查询 原生 HTML + JS
展示层 Grafana 数据可视化 Grafana

三、数据流

3.1 错误上报流程

前端触发错误
    ↓
ErrorPlugin 捕获
    ↓
封装为标准事件格式
    ↓
加入内存队列
    ↓
批量/定时/页面隐藏 触发上报
    ↓
sendBeacon / fetch / img 标签
    ↓
Nginx (限流 + CORS)
    ↓
API Server
    ├─ DSN 认证
    ├─ envelope 解析
    ├─ 数据清洗 (脱敏IP、UA)
    ├─ 计算错误指纹
    └─ 写入内存队列
    ↓
批量消费
    ├─ 写入 Loki (原始数据)
    └─ 更新 MySQL 聚合表
    ↓
Grafana / 管理后台 查询
    ↓
告警引擎 检测规则
    ↓
触发通知 (Webhook / 邮件)

3.2 性能指标流程

PerformancePlugin 监听性能指标
    ↓
(FP / FCP / LCP / CLS / TTI / Long Task)
    ↓
采样过滤 (默认 10% 采样率)
    ↓
批量上报
    ↓
API Server 接收
    ├─ 数据校验
    └─ 写入 Loki
    ↓
定时聚合任务 (每 5 分钟)
    ├─ 计算 P50 / P90 / P95 / P99
    ├─ 按项目 + 页面 + 小时 聚合
    └─ 写入 MySQL 性能表
    ↓
Grafana 展示趋势图

四、技术选型说明

4.1 为什么用 Loki 而不是 ES/ClickHouse？

特性 Loki Elasticsearch ClickHouse
部署复杂度 极低（单二进制） 高（需调优） 中
资源消耗 低（内存 + 磁盘） 高（内存密集） 中高
查询性能 中等（日志足够） 高 极高
全文检索 支持（Label + grep） 强大 支持
Grafana 集成 原生 需配置 需配置
适合场景 日志、错误追踪 全文检索、复杂分析 OLAP、大数据量

结论：轻量级监控，Loki 足够用，运维成本最低，和 Grafana 集成最好。

4.2 为什么用 MySQL 存聚合数据？

  • 成熟稳定，运维简单
  • 聚合后数据量不大（每天几千~几万行）
  • 事务支持，数据一致性好
  • 管理后台查询方便
  • 小项目甚至可以用 SQLite，零运维

4.3 为什么前端用原生 JS？

  • 后台页面不复杂，原生 JS 足够
  • 无构建流程，修改即生效
  • 体积小，加载快
  • 不依赖前端框架生态，长期维护成本低

五、与现有 Light-Sentry 的关系

5.1 现有能力

  • ✅ Sentry 兼容接口（store / envelope）
  • ✅ Loki 原始日志存储
  • ✅ Grafana 仪表盘
  • ✅ 项目管理后台
  • ✅ Docker Compose 一键部署
  • ✅ NEL (Network Error Logging) 支持

5.2 待完善能力

  • 🚧 自研轻量 SDK
  • 🚧 错误指纹聚合
  • 🚧 性能指标聚合
  • 🚧 告警引擎
  • 🚧 源 map 解析
  • 🚧 用户会话追踪
  • 🚧 行为分析插件

六、文档目录

docs/
├── 00-architecture.md          # 本文档 - 整体架构
├── 01-sdk-design.md            # 前端 SDK 设计
├── 02-api-server.md            # 服务端接入层设计
├── 03-data-aggregation.md      # 数据聚合与存储设计
├── 04-alert-engine.md          # 告警引擎设计
├── 05-admin-dashboard.md       # 管理后台与可视化设计
└── 06-deployment.md            # 部署与运维设计