Sentry 错误上报

Last updated: 2026-07

本文定义 Chatbox Pro 的错误上报边界、分类字段、采样与隐私规则。Sentry 只用于调查产品故障；用户行为与转化漏斗继续使用 JK/Plausible。

目标

关键错误不漏报：崩溃、React ErrorBoundary、应用/数据库初始化、核心生成链路异常均完整保留。
事件可检索：每条事件都有来源、领域、操作、优先级和是否已处理等稳定标签。
降低噪音：预期的 API/网络/权限/取消错误不上报，普通且已处理的异常按比例采样。
避免重复：主进程同一异常对象在 DB、事务、IPC 多层被捕获时只发送一次。
默认匿名：调用方不主动附加提示词、消息或请求参数；发送前清理明确的私密字段和认证凭据。

覆盖范围

进程	错误入口	处理方式
Renderer	SDK 默认全局错误与未处理 Promise	作为 `critical` 保留，不再重复注册 window 监听
Renderer	React ErrorBoundary	`ui` 领域，按 boundary 名称分类，100% 保留
Renderer	启动、迁移、会话生成、Agent Mode	使用 `reportError()` 添加稳定上下文
Renderer	摘要、命名、token 估算、后台 license 校验	仅上报非预期异常，普通错误采样
Main	未捕获异常、应用启动失败	`application` 领域，100% 保留
Main	Renderer 进程异常退出	`renderer-process` 领域，记录 reason 与 exit code
Main	Knowledge Base / Session Attachment RAG	沿用 component/operation 上下文，并统一映射为稳定分类

以下情况不应进入 Sentry：

用户可理解且已有 UI 反馈的 API、网络、鉴权、额度或模型能力错误；
Clipboard、App Store 评分提示、远程模型列表等已有 fallback 的辅助功能失败；
主动取消产生的 AbortError；
ResizeObserver 和跨域 Script error 等浏览器噪音；
console.error。本地日志负责保留 console 信息，Sentry 不再劫持 console 或附加 console breadcrumbs。

统一标签

标签	示例	含义
`error_source`	`renderer` / `main`	事件来自哪个进程
`error_domain`	`ui`, `storage`, `ai-generation`, `knowledge-base`	失败所属产品/技术领域
`error_operation`	`migration`, `submit_message`, `database_initialization`	失败时正在执行的稳定操作名
`error_priority`	`critical`, `high`, `normal`	决定保留与采样策略
`error_handled`	`true` / `false`	应用是否捕获并继续运行
`error_sample_rate`	`1`, `0.1`, `0.2`	当前事件使用的采样率，便于解释数量

原有的 component、operation、platform、app_version、build_target、build_platform 继续保留，兼容历史查询。

优先级与采样

优先级	典型事件	Renderer	Main
`critical`	未处理错误、ErrorBoundary、进程退出、应用启动失败	100%	100%
`high`	数据迁移、数据库/向量库初始化、核心生成、Agent Mode	100%	100%
`normal`	已处理且有 fallback 的非预期异常	10%	20%

采样只影响发送，不改变本地日志。主进程还会按异常对象去重，因此同一错误在底层和上层被重复捕获时不会重复计数。

上报规范

Renderer 新增显式上报时使用 src/renderer/utils/sentry.ts：

reportError(error, {
  domain: 'session',
  operation: 'submit_message',
  priority: 'high',
})

调用前先判断错误是否为预期业务结果。只有调查故障所需的低基数字段才放 tag；数量、耗时、状态码等放 extra。不要附加原始消息、prompt、请求体、响应体、文件名、文件路径、查询文本、认证信息或用户标识。

生成链路统一使用 src/shared/models/error-classification.ts 判断预期错误，覆盖 Chatbox AI 额度/License/能力错误、Provider API 错误、网络错误和已有 fallback 的 OCR/图片能力错误。不要在各入口维护不同的错误白名单。

Main/Shared 通过 SentryAdapter.withScope() 设置相同标签。Knowledge Base 与 RAG 的既有 component / operation 会由统一策略自动映射。

隐私保护

发送前统一执行以下处理：

清除 event.user 和 request body；
数据迁移先于 Sentry、JK 和 Plausible 初始化，确保跨存储升级时使用迁移后的 consent；
迁移失败保留原始异常与堆栈，并附带失败的 configVersion 和目标版本；
设置关闭后立即停止发送；重新开启后无需重启应用即可恢复 Renderer 与 Main 上报；
删除名称明确表示凭据的请求头，例如 Authorization、Cookie、各类 API Key 和认证 Token；
移除 URL query 与 fragment；
递归清理 context、extra 和 breadcrumb 中名称明确的私密字段，例如 path、filename、query、prompt、messages、options，以及 password、secret、API Key、license key 和认证 Token；
字段名按 camelCase、snake_case 和 header-case 规范化后做精确名称或凭据后缀匹配，不使用宽泛子串匹配；
其他字段默认保留，包括 tokenCount、maxTokens、contentLength、queryDuration、promptVersion 等诊断信息；
对异常文本、stack frame 和 breadcrumb 中的 Bearer token、sk- key、macOS/Linux/Windows 用户主目录进行脱敏；
Renderer 不上传 console breadcrumbs。

Main 的 fatal handler 在未捕获异常时等待 Sentry flush（最多 2 秒）后以失败状态退出，避免关键崩溃事件只进入异步队列便被进程终止。

Sentry 查询建议

关键故障：error_priority:critical
按进程：error_source:main 或 error_source:renderer
按领域：error_domain:knowledge-base
按操作：error_operation:database_initialization
新版本回归：叠加 release:<version>、environment:production

观察事件量时需结合 error_sample_rate，普通错误的原始发生次数不能直接用发送数代替。