You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

5.6 KiB

日志采集与统一上报约定

客户端行为

app.config.json 的 diagnosticsUrl 是构建时指定的 HTTPS 接收地址,模板默认空。服务只在安装后的应用、有接收地址且用户打开「允许自动上报脱敏诊断」时发送;开发环境、未配置或未授权时保持本地记录。地址不接受用户名、密码、查询参数和片段,renderer 不能传入或更改目标地址。

主进程启动与故障、RPC 内部故障、窗口故障、renderer 未处理错误及 Vue 错误、更新状态转换与失败统一进入 DiagnosticService。renderer 只提交事件种类和白名单异常名称,不提交 error.message、stack、URL、组件实例或用户输入。electron-log 保留主进程本地日志,禁用它额外注入的 renderer preload;上报和导出不读取原始日志文件。

诊断包含时间、版本、平台、架构、事件编号、故障关联编号、受限异常分类和数字代码位置。没有用户账号、安装用户标识、文件路径、完整栈、笔记、凭据和任意错误消息。代码位置仍需结合相应版本的私有构建资料定位,当前不提供服务端自动符号化。

本地 diagnostics.json 使用原子替换,保留最近 7 天最多 200 条;容量或时间超出时丢弃最旧记录,包括尚未上报的记录,因此不是无损审计日志。原始 electron-log 单文件限制 2 MB。诊断队列属于应用基础能力,不随可选业务存储开关关闭。

用户开启授权之后只排队新增记录;此前本地记录不追溯自动上传。待发送 ID 随记录持久化,重启恢复;每批最多 20 条,成功后只移除这批 ID,新产生的记录继续保留。关闭授权会中止当前请求并清除待发 ID,本地记录仍保留,可通过「清除诊断」删除;已经到达服务器的数据不能由中止请求撤回,接收端需提供自己的删除策略。

请求总等待上限 10 秒,不跟随重定向、不附带 cookies 或内置 API 密钥。失败重试等待为 30、60、120、240 秒,随后最大 300 秒;等待期间记录仍受 7 天/200 条限制。HTTP 非确认状态都会重试;当前不解析 Retry-After。客户端不会把网络故障再递归加入待上报队列。

设置页可查看队列概况、发送待发记录、导出脱敏 JSON 和清除本地记录。导出使用主进程原生保存框并在返回后重新验证窗口来源,IPC 不接收任意保存路径。页面概况是读取时的快照,不代表实时上报监控。

后端 HTTP 接口 v1

部署示例地址:https://reports.example.com/v1/diagnostics。实际地址由发布者配置,示例域名不加入默认配置。

POST /v1/diagnostics
Content-Type: application/json
Idempotency-Key: <batchId UUID>
{
  "schemaVersion": 1,
  "batchId": "cc6875b6-8e26-4dc0-aad8-35738c0b8216",
  "records": [
    {
      "id": "145e42c4-7fcb-49ae-bc79-3f97b6ebf067",
      "timestamp": "2026-10-11T07:00:00.000Z",
      "level": "error",
      "source": "main",
      "code": "app.failure",
      "appVersion": "0.1.0",
      "electronVersion": "44.7.0",
      "platform": "win32",
      "arch": "x64",
      "diagnostic": {
        "incidentId": "ba702194-7bf7-4d7f-822c-4b7b442d08c9",
        "causes": [{ "name": "Error", "code": "ENOSPC" }],
        "positions": [{ "line": 120, "column": 8 }]
      }
    }
  ]
}

精确字段及事件枚举定义于 packages/contracts/src/diagnostics.ts;update.state 记录可额外携带 updateStatus。后端应校验 schemaVersion、批量数量、UUID、长度和枚举,设置请求体上限 256 KB,不接受未约定字段。

HTTP 结果 客户端处理 后端承诺
200 / 202 / 204 确认整批,移除这批待发 ID 整批已持久保存或进入可靠队列
400 / 401 / 403 / 413 保留并按退避重试 不确认任何记录,修正配置/协议后恢复
429 / 5xx / 网络断开 保留并按退避重试 不将请求失败当作客户端已丢弃
3xx 不跟随,保留重试 接口提供最终 HTTPS 地址

不支持部分确认。即使服务器已保存但响应丢失,客户端也会重发,因此后端必须以 record.id 去重,而不是只靠 batchId;重试会生成新的 batchId。重复记录应返回确认成功。

该接口当前不携带认证凭据:桌面应用不能通过内置静态密钥证明可信身份。初始接收端应设置体积、频率与存储配额,并按环境隔离;若后续需要登录鉴权,扩展为短期令牌机制,令牌不能写入此诊断载荷或 app.config.json。

后端建议按事件编号定位单条记录、按 incidentId 关联主进程本地日志、按版本/平台/事件统计发布问题;明确服务端保留期限、访问权限与删除流程。当前仓库没有接收端,尚未完成真实 HTTPS 服务联调。

原生崩溃转储

Electron Crashpad 在创建窗口前以 uploadToServer=false 启动,本地目录为 userData/crashes。转储可能包含进程内存,独立于脱敏 JSON:不会自动上传,也不进入诊断导出。7 天/200 条策略只适用于诊断记录,不适用于 Crashpad 内部文件。

未来若要接入原生转储上传,需要独立用户授权、兼容 Breakpad 的接收端和私有符号文件,不可把 JSON 日志接口直接当作崩溃转储接收端。见 Electron crashReporter。