77 lines
8.2 KiB
Markdown
77 lines
8.2 KiB
Markdown
---
|
||
description: "排查 Desktop 故障或收集报告时阅读，了解恢复操作、报告内容、操作历史和退出限制。"
|
||
---
|
||
|
||
# Desktop 故障恢复与诊断
|
||
|
||
[English](README.md) | 中文
|
||
|
||
## 概述
|
||
|
||
本参考文档说明 Desktop 的原生故障恢复、诊断报告、近期插件操作记录，以及采集和退出时的限制。
|
||
|
||
## 目录
|
||
|
||
- [遇到故障怎么办](#recovery)
|
||
- [报告包含什么](#report-contents)
|
||
- [近期操作记录](#operation-records)
|
||
- [采集与退出行为](#collection-and-shutdown)
|
||
|
||
<a id="recovery"></a>
|
||
|
||
## 遇到故障怎么办
|
||
|
||
主窗口创建、主文档加载、preload、渲染器、Web 初始化或后端的致命失败，会在每个应用进程中打开一次原生恢复对话框。对话框显示首次错误末尾的限长摘要，标明截断情况，并提供“退出”“重启”“禁用第三方插件、备份 profile patch 并重启”，以及报告仍在保存或已保存时的“获取诊断报告”。启动失败保留 Web 加载页和动画；运行中失败保留当前页面。预期关闭、取消导航和普通请求错误不会触发恢复。共享 Web 插件管理器报告包操作错误；插件变更后的 Host 启动失败会进入原生恢复。不通过启动超时推断故障。包含 `listen EADDRINUSE` 的监听失败以退出其他正在运行的 DSH 实例的提示替代诊断和重装建议，提供“退出”“重启”，以及报告仍在保存或已保存时的“获取诊断报告”。
|
||
|
||
Host 设置可用前，恢复对话框使用本地缓存中最后确认的 Desktop 语言；缓存不存在或无效时回退到系统语言。
|
||
|
||
恢复操作等待 Host 关闭后才修改插件启用状态。原生恢复操作在 profile 事务锁内调用共享 app-boot 恢复函数。它禁用第三方 bundle，并将 profile 的 `cordis.patch.yml` 重命名为 `cordis.patch.yml.bak-<timestamp>`（重名时追加序号），无需解析；下次启动创建空 patch。已安装包和已有备份保留。home 级 patch 不变。Electron 控制台记录备份路径（或原文件不存在）以及 home 级 patch 未修改。profile 数据无效、重命名失败或写入失败会作为恢复操作错误报告；已完成的修改保留，Desktop 不会假装恢复成功后重启。Desktop 不提供 profile 重置操作或应急 HTML 文档。
|
||
|
||
<a id="report-contents"></a>
|
||
|
||
## 报告包含什么
|
||
|
||
原生弹窗详情最多包含 1,200 个 UTF-16 代码单元和八行诊断，并附上崩溃报告路径或仍在保存、无法保存的状态。获取仍在保存或无法保存的报告时，保留恢复操作失败的标题和详情。配置路径和启动条目排在组合清单之前，避免输出截断时被插件记录挤掉。Host 错误诊断仅保留 stderr 输出的最后 64 Ki 个字符。更早的输出会被丢弃，避免长期运行的 Host 使壳的诊断缓冲区无限增长。
|
||
|
||
首个致命弹窗打开前，Electron 会向平台日志目录（`app.getPath('logs')`：macOS 为 `~/Library/Logs/DeepSeek Harness`，Windows 与 Linux 为应用 `userData` 目录下的 `logs`）写入一份崩溃报告，最多等待写入一秒；写入缓慢或失败时明确显示仍在保存或无法保存。“获取诊断报告”检查同一次写入，并在系统文件管理器中定位已保存的文件，不停止 Host 或重启；超过首次等待期限后写入完成的文件仍可获取。用户可将文件作为工单附件。附件只包含最初的故障；后续恢复操作错误保留在对话框中，需要另行截图。获取已保存报告会显示分享或打开失败的标题，同时保留恢复错误详情。写入失败时隐藏获取报告按钮，并提示提供窗口截图。
|
||
|
||
文件 `crash-<UTC 时间>-<source>.log` 记录来源（`host` 为 Host 退出、`web-boot` 为渲染进程启动失败、`renderer` 为渲染进程或文档失败、`main` 为壳自身错误）、后端是否已就绪、应用与运行时版本、包含可枚举属性与 cause 链的错误（截至 256 KiB）、Host 在退出前通过 IPC 报告启动失败时的错误及显式选择的启动元数据（最多 64 Ki 个字符，包含截断提示；启动错误的原始错误文本和启动条目详情分别限制为 8 Ki 个字符，并明确标注截断，为结构化元数据保留空间），以及主窗口最近的 error 级 console 输出（最多 64 KiB）。
|
||
|
||
因此 Host 退出报告包含保留的 stderr 尾部，其中可能含有插件输出。关闭过程中的致命失败只写报告、不弹窗。平台支持时文件仅所有者可读；启动时保留最新十份报告并删除更早的，不触碰目录中的其他文件。
|
||
|
||
<a id="operation-records"></a>
|
||
|
||
## 近期操作记录
|
||
|
||
操作记录目录与应用单实例锁均按 `userData` 隔离；共享平台日志目录不用于保存操作记录。读取器只读取 `userData/plugin-operations` 下的两个操作记录文件。修复未写完的尾行时保留当前段的完整行与上一段。
|
||
|
||
版本豁免变更复用 bundle 启停记录字段。豁免版本与安装版本相同时，记录无法区分豁免变更与 bundle 开关。
|
||
|
||
Host 的 `transportDropped` 只表示最近一次成功发送时的计数下界；Desktop 拒绝的非法或运行 ID 不匹配记录不计入该值。
|
||
|
||
操作历史保留两个 256 KiB 文件段，单条记录不超过 4 KiB，排队写入不超过 64 KiB。
|
||
|
||
退出、恢复重启和安装准备最多等待排队写入 500 ms；超时会停用后续写入，此后的排空调用立即返回，不会再次等待；但已经发出的操作系统请求仍可能随后结束。
|
||
|
||
记录覆盖 Host 启动后观察到的管理器操作，不包含直接执行的 CLI 命令或手工文件修改。包管理器输出保留在原有详细日志中，不复制到摘要。缺失记录、只有开始没有结束的操作以及损坏的历史，都不能说明操作已成功。此收集不诊断内核卡死、OOM 或原生崩溃。
|
||
|
||
持久化失败也会在本次壳生命周期内停用写入，包括恢复或安装器失败后继续运行的情况，以限制重复失败的 I/O，并避免在可能残缺的写入后追加记录。重启应用会创建新写入器。遗漏和修复计数仅覆盖当前壳生命周期。保留文件段提供比报告附件更大的本地排障历史窗口。
|
||
|
||
<a id="collection-and-shutdown"></a>
|
||
|
||
## 采集与退出行为
|
||
|
||
基本报告保存后，壳会尝试通过独立 Worker 追加近期插件管理记录；该 Worker 以 `lib/operation-report-worker.js` 打包在 `app.asar` 中。完成标记和遗漏计数用于区分已完成收集与缺失或不完整的材料。
|
||
|
||
Host 在加载 profile 前报告运行 ID；Host 错误中的 `hostRunId` 与该次运行的操作记录使用同一标识。在此通知之前发生的失败，其运行标识仍为未知。近期操作只是上下文，不是因果证据。
|
||
|
||
收集只读取 `userData/plugin-operations` 下归其管理的两个文件，最多读取 64 KiB 和 100 条记录；完整追加内容不超过 64 KiB。
|
||
|
||
500 ms 收集预算中的最后 100 ms 用于协作取消，随后才请求强制终止 Worker；只有 Worker 退出后才确认收集结束。应用退出、恢复退出或重启、确认安装更新也会取消收集，并最多等待 500 ms 确认 Worker 退出。退出清理中的拒绝会被记录，但不会跳过其他清理等待。退出过程中，延迟保存完成的基本报告不会再启动收集器。更新安装失败后可再次收集。
|
||
|
||
Worker 在有界记录之间处理取消消息；已经发出的文件打开、状态读取、读取或关闭操作必须等待完成，单条记录的同步解析不能被抢占。最后的追加写入传入取消信号，但仍可能留下部分字节。协作清理未及时完成时仍需强制终止。
|
||
|
||
基本报告独立可用。同时只运行一个收集器；并发报告保留基本内容，不追加辅助部分。终止请求被拒绝时，必须观察到退出才能释放该名额。“获取诊断报告”可能在追加完成前定位基本文件。完成标记仅表示收集结束，不表示捕获了全部操作；排队字节数和遗漏计数说明缺失材料。
|
||
|
||
故障构造与验收步骤见[本地验证](../../tests/README.zh.md#verification-diagnostics)；应用概览与开发入口见 [Desktop README](../../README.zh.md)。
|