架构说明

HealthGuard 采用经典的三层架构设计，采集端、服务端与展示端职责清晰，便于独立扩展与私有化部署。

系统架构图

┌─────────────────────────────────────────────────────────────┐
│                        采集端 (SDK)                          │
│  ┌─────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  H5 SDK     │  │ 微信小程序 SDK   │  │  未来更多平台    │  │
│  │  (npm)      │  │  (js 文件引入)   │  │                 │  │
│  └──────┬──────┘  └────────┬────────┘  └─────────────────┘  │
└─────────┼──────────────────┼────────────────────────────────┘
          │                  │
          └────────┬─────────┘
                   ▼
┌─────────────────────────────────────────────────────────────┐
│                      服务端 (Collector)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Events API │  │   Auth API  │  │   Query API         │  │
│  │  (事件上报)  │  │  (用户认证)  │  │  (Dashboard 查询)    │  │
│  └──────┬──────┘  └─────────────┘  └─────────────────────┘  │
│         │                                                    │
│  ┌──────┴──────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ 事件校验     │  │  Issue      │  │   数据聚合           │  │
│  │ (schema)    │  │  Aggregator │  │  (趋势/概览)         │  │
│  └──────┬──────┘  └─────────────┘  └─────────────────────┘  │
│         │                                                    │
│  ┌──────┴──────┐                                             │
│  │  Event Store │  (SQLite / PostgreSQL / 未来扩展)           │
│  └─────────────┘                                             │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│                     展示端 (Dashboard)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Issue 列表   │  │  数据概览    │  │  应用管理           │  │
│  │ (聚合错误)   │  │  (指标看板)  │  │  (appKey)           │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

数据流

一条错误事件从发生到在 Dashboard 中展示，经历以下流程：

应用发生 JS 错误
      │
      ▼
SDK 捕获错误 ──► 附加上下文（堆栈、面包屑、设备信息）
      │
      ▼
本地队列缓冲 ──► 批量压缩 ──► 失败重试
      │
      ▼
POST /api/events/batch
      │
      ▼
Collector 校验 ──► 存储原始事件
      │
      ▼
Issue Aggregator ──► 按 fingerprint 聚合 ──► 更新 Issue 统计
      │
      ▼
Dashboard 查询 ──► 展示聚合后的 Issue 与趋势

各层职责

SDK 层

• H5 SDK：通过 npm install @healthguard/sdk-web 引入，自动拦截 window.onerror、unhandledrejection、fetch、XMLHttpRequest
• 小程序 SDK：以 JS 文件形式引入，包装 App() 和 Page() 生命周期，拦截 wx.request
• 核心设计：采集端只做一件事——可靠地把事件送到 Collector。聚合、分析、展示均在服务端完成，确保 SDK 轻量

Collector 层

• REST API：提供事件上报、用户认证、数据查询接口
• 事件校验：校验 appKey、事件 schema、防重复
• Issue 聚合：根据错误指纹（fingerprint）自动归类相同错误，生成 Issue
• 存储抽象：默认 SQLite，可通过配置切换至 PostgreSQL 等生产级数据库

Dashboard 层

• Issue 管理：查看聚合后的错误列表、详情、受影响用户数
• 数据概览：事件总量、错误率、请求失败率、性能指标趋势
• 应用管理：创建应用、生成 appKey、配置告警规则（未来版本）

部署拓扑

最小化部署（开发/测试）：

[Collector + SQLite]  ←──  [Dashboard (静态文件)]
       ▲
       │ SDK 上报
   [H5 / 小程序]

生产部署建议：

         ┌──► [Collector 实例 1]
[负载均衡] ───► [Collector 实例 2]  ←──  [PostgreSQL]
         └──► [Collector 实例 3]
                     │
               [Dashboard CDN]

扩展点

扩展方向	方式	说明
新平台 SDK	参考现有 SDK 实现相同协议	只需对接 /api/events/batch
新存储后端	实现 EventStore 接口	目前已有 SQLite，可扩展至 PostgreSQL / ClickHouse
告警通道	监听 Issue 聚合事件	Webhook / Email / 钉钉 / Slack
SourceMap	上传 sourcemap 文件	服务端反解压缩后的堆栈