架构说明
HealthGuard 采用经典的三层架构：采集端（SDK）、服务端（Collector）和展示端（Dashboard）。所有数据都存储在你自己的基础设施中，默认不上传任何第三方服务。
系统架构图
text
┌─────────────────────────────────────────────────────────────┐
│ 采集端（SDKs） │
│ ┌────────────┐ ┌──────────────────┐ ┌─────────────────┐ │
│ │ H5 / Web │ │ 微信小程序 │ │ uni-app 多端 │ │
│ │ sdk-web │ │ sdk-miniprogram │ │ sdk-uniapp │ │
│ └──────┬─────┘ └─────────┬────────┘ └────────┬────────┘ │
└─────────┼──────────────────┼────────────────────┼───────────┘
│ │ │
└──────────────────┼────────────────────┘
▼
┌──────────────────────┐
│ Collector (Server) │
│ Node.js + Fastify │
│ REST API / 聚合 │
└──────────┬───────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ PostgreSQL │ │ Dashboard │ │ Repair Agent │
│ 持久化存储 │ │ Vue 3 + Vite │ │ 可选修复工具 │
└───────────────┘ └───────────────┘ └───────────────┘数据流
- 采集：SDK 在客户端捕获错误、HTTP 请求、性能指标和面包屑。
- 校验：事件通过
@health-guard/core中的 Zod Schema 校验，并生成 fingerprint 用于 Issue 聚合。 - 上报：SDK 将事件批量上报到 Collector 的
POST /api/events/batch。 - 存储：Collector 将事件写入 PostgreSQL。
- 聚合：根据 fingerprint 将相似事件聚合成 Issue。
- 查询：Dashboard 通过认证后的 API 查询项目、Issue、事件明细等数据。
技术栈
| 层级 | 技术 | 说明 |
|---|---|---|
| SDKs | TypeScript + tsup | 浏览器、微信小程序、uni-app 三端 |
| 事件协议 | Zod | 统一的事件 Schema 与校验 |
| Collector | Node.js + Fastify | 高性能 REST API |
| 数据库 | PostgreSQL 16 | 事件、Issue、用户、项目数据持久化 |
| Dashboard | Vue 3 + Vite | 响应式管理后台，支持中英文 |
| 部署 | Docker + Docker Compose | 一键私有化部署 |
仓库结构
text
healthguard/
├── apps/
│ ├── dashboard/ # Vue 3 管理后台
│ └── server/ # Fastify 采集服务
├── packages/
│ ├── core/ # 共享事件 Schema 与工具
│ ├── sdk-web/ # H5 / Web SDK
│ ├── sdk-miniprogram/ # 微信小程序 SDK
│ ├── sdk-uniapp/ # uni-app 多端 SDK
│ └── repair-agent/ # 本地修复 Agent（可选）
├── examples/
│ └── vue3-demo/ # H5 示例应用
├── docker-compose.yml # 一键部署
└── docs/ # 运维与决策文档安全与隐私
- 所有查询类 API 都需要 Bearer Token 认证。
- SDK 默认过滤 URL Query 中的敏感字段（
authorization、token、password等）。 - 业务自定义字段可通过
context/requestData透传，但每层最多 20 个键。 - 数据完全私有化，不依赖第三方监控平台。