快速开始
本文档帮助你在 5 分钟内完成 HealthGuard 的本地启动和首次 SDK 接入。
前提条件
本地源码运行
# 克隆仓库
git clone https://github.com/Claud-Lu/healthguard.git
cd healthguard
# 安装依赖
yarn install
# 一键启动所有服务（Collector + Dashboard + Demo）
yarn dev:local启动后访问：
| 服务 | 地址 |
|---|---|
| Dashboard | http://127.0.0.1:5175 |
| Collector | http://127.0.0.1:3100/health |
| Demo | http://127.0.0.1:5174 |
创建应用
- 打开 Dashboard（http://127.0.0.1:5175）
- 注册账号并登录
- 点击"创建应用"，选择应用类型（H5 / 微信小程序）
- 复制生成的
appKey
点击左上角品牌区（Logo、HealthGuard 名称或账号）可回到项目首页；也支持 Tab 聚焦后按 Enter。未登录时仍进入登录页。
浏览问题与查看详情
进入项目时，默认仅显示占满宽度的问题列表，每条问题独占一行，从上到下排列。错误信息完整显示并自动换行，下方另起一排显示类型、次数、平台和时间等信息。点击卡片后才展开详情；点击「收起详情」恢复完整列表。搜索、筛选或切换项目会清除选择，关闭后的旧请求不会重新展开详情。手机端选中时自动滚动到详情，收起后回到卡片。
点击「归档」会弹出确认框，可填写归档备注（选填，最多 4000 字），确认后直接归档，不再要求修复或验证版本。取消或按 Escape 不会提交，失败会保留备注供重试。在「已归档」中可查看备注和归档时间，也可手动恢复到当前列表；恢复后保留上次备注。归档不表示已修复，后续上报继续计数并保持手动归档。修复由外部 AI/开发工具在业务仓库完成，页面保留「复制给 AI」，不再展示开始修复、版本验证、PR 表单或修复状态标签。列表和详情隐藏内部编号与指纹。
修改项目名称
在项目列表或项目详情的左侧列表中，点击项目标题右侧的「改名」。长标题会单行省略，悬停可查看完整名称。输入便于辨认的中文或英文名称并保存；也可取消或按 Escape 退出。名称去除首尾空白后需为 1–100 个字符，保存失败会保留输入供重试。
仅修改显示名称，原 appKey、SDK 接入配置、历史数据与通知规则保持不变；只有项目所有者可以修改。PostgreSQL 部署在刷新或重启后仍保留新名称。需要先部署包含重命名接口的 Collector，再更新 Dashboard。
从邮件列表识别错误
自动告警标题使用 [HealthGuard][完整 Issue ID] 提醒类型 · 项目名，完整错误编号放在提醒类型与项目名之前，便于在邮件列表或截图中区分问题。同一问题的新异常、复发和次数提醒沿用同一个 ID，与正文的 Issue ID 一致；Event ID 仅代表一次上报。
更新 Collector 后新生成的告警才使用新格式；已排队、历史邮件和测试邮件保持原标题。无需升级 SDK 或业务 App。通知入口中的发件名称由当前账号共用，收件人与触发规则按项目独立设置。
接入 H5 SDK
npm install @health-guard/sdk-webimport { createHealthGuardClient } from '@health-guard/sdk-web';
const client = createHealthGuardClient({
appKey: 'your-app-key',
endpoint: 'http://127.0.0.1:3100/api/events/batch',
autoCapture: true
});验证
- 在 Demo 页面或你的应用中触发一个 JavaScript 错误
- 返回 Dashboard，进入 Issue 列表
- 你应该能看到刚刚触发的错误已被聚合为一条 Issue
下一步
HTTP 标题显示完整地址
打开历史 HTTP 错误详情后，标题会从对应事件中补全真实请求域名、路径及非敏感查询参数，并保留完整错误内容；选中的列表项和 AI 报告同步。长地址自动换行。缺少绝对地址或方法、路径不匹配时保留历史摘要，不猜测域名。仅更新展示，不改变分组、修复和归档状态。
Issue 元信息靠右
Issue 列表的平台和时间整体靠右排列，类型和事件次数保留左侧；错误标题仍完整换行。窄列表及手机宽度下，右侧信息组会自动换行。
项目详情更紧凑
移除内容区重复的项目标题和说明，操作与筛选共用一排工具栏；统计名称和数字用小字号同行展示。列表仅按当前/已归档切换，不再显示修复状态标签。窄屏工具栏可换行，统计保持单排并可横向滚动，错误内容继续完整显示。 HTTP 事件卡片也会在窄详情栏中换行，避免撑宽页面。
筛选与搜索控件细节
下拉箭头统一向内留出 12px，文字预留 36px，选择器与日期控件等高并保留清晰的键盘焦点。搜索框移至 Issues 标题右侧，同一行展示，去掉重复的分组总数，顶部 Issues 统计仍显示总数；搜索与筛选规则不变。
分清事件与邮件时间
事件卡片和「复制给 AI」分别显示客户端发生、服务器接收与带符号时间差。发送记录列出客户端发生、服务器接收、邮件生成、发送处理开始与邮件服务器接受时间，页面使用浏览器本地时区，邮件正文标注 UTC。
发生时间来自客户端；时间差可能涉及补报、传输延迟或设备时钟偏差，不能仅凭当天收到邮件认定当天新发、当前版本故障或设备未升级。新增 receivedAt 来自 Collector 接收批次时的服务器时钟；旧数据库入库时间不等同于请求到达时间，不用于回填。旧记录缺失值明确显示「未记录」。SMTP 接受不代表进入收件箱，失败或投递未知不显示已接受。只需更新 Collector 与 Dashboard，无需升级 SDK/业务 App。
按设备排查异常（未发布）
项目详情的“设备异常”视图区分稳定设备标识、仅安装标识和无法识别记录，支持分类、短码/型号搜索、分页及每台设备的跨版本异常历史。计数覆盖所选平台/时间内的异常与失败请求（含已归档问题）；安装数不等于设备数，无法识别项按记录计数，历史不按型号合并。每行显示异常次数、首次/最近客户端发生时间、最近上报 App 版本；历史接收时间未知时明确提示。最新元数据按服务器接收时间排序，缺失时仅按客户端发生时间展示。短码只用于对照，完整 ID 才用于归集。Flutter App 可嵌入 设备诊断页；邮件版本取本次事件。源码完成不等于上线或平板验收。