Incident Response

故障应急百科

本页记录 DSH STORE 的常见故障判断、低风险处置和证据边界。它的目的不是让用户跳过安全机制，而是先区分“页面缓存、Catalog、插件源码、真实 Profile 和运行时”五个不同表面，避免在错误位置反复重试或手工修改配置。

使用原则

1. 先保留证据，再做变更。 记录报错全文、发生时间、插件名、已安装版本、Catalog 固定 Commit 和 DSH 版本；不要记录凭据、完整 Profile、环境变量或私人文件。
2. 只信对应层级的证据。 GitHub Raw Catalog、GitHub Pages、国际站、国内站和真实 Profile 是不同表面。一个页面正常或一个静态检查通过，都不能证明其他表面正常。
3. 不手改 Profile。 安装、更新、启用、停用和移除必须使用官方 dsh CLI 与商城生成的一次性计划；不要手工改 package.json、锁文件、Bundle 列表或 Patch。
4. 未知不是通过。 “可安装”“运行验证”“安全审查”显示 unknown 或 partial 时，只能表示已有的那部分证据，不可推断为真实运行成功或独立安全审计。

快速分诊

现象	优先检查	不应做的事	升级条件
商城显示旧版本或旧仓库地址	GitHub Raw Catalog、GitHub Pages Catalog、当前访问的站点	直接编辑本地 Catalog 或反复安装	权威 Raw 已更新但目标站点仍旧时，按站点陈旧处理
商城页面加载失败	浏览器控制台的完整错误、DSH 版本、已安装包版本与固定 Commit	删除 Profile、覆盖 node_modules 或调用 Loader/Fiber 私有 API	出现模块未注册、重复入口或启动失败时
远端 Catalog 读取失败	管理器版本、错误中的字段/枚举、Raw Catalog 的 schema 变化	通过篡改远端 Catalog 绕过校验	当前管理器不能解析权威 Catalog 时
兼容性/安全状态为未知	条目的固定 Commit、兼容性声明、可复现的测试证据	将未知手工标记为“兼容”或“已审计”	用户需要安装或运行该插件前
更新提示有权限变化	更新差异、权限矩阵、固定源码和版本	自动接受变化或安装浮动 main	涉及文件、网络、命令、凭据或生命周期脚本时

场景一：Catalog 或页面不是最新

1. 先查看 权威 Catalog 的条目版本、固定 Commit 和 updatedAt。
2. 再分别打开 GitHub Pages 与正在使用的商城域名。它们的读取结果不一致时，记录“哪个表面陈旧”，不要把 Pages 成功误写成所有生产站都已刷新。
3. 浏览器只做一次硬刷新或使用无缓存窗口复核。仍不一致时，提交 Issue 并附上脱敏后的三个 URL、版本、Commit 和时间。

Catalog 的远端 GitHub main 是身份与准入的权威；本地捆绑快照只能作为离线回退，并应明确标识为回退状态。

场景二：出现“模块未注册”或插件页空白

这类错误通常说明浏览器模块、Bundle 入口与已安装包版本没有对齐，或 Profile 中存在冲突的旧入口。先保留控制台报错和“设置 → 插件”的已安装版本信息，然后检查：

1. Catalog 条目中的包名、固定 Commit、entryIds 是否与安装来源一致；
2. 当前 DSH 版本是否在该条目的兼容性范围内；
3. 是否同时保留了同一插件的旧包、旧 Patch 或重复入口。

不要尝试调用 Loader、Fiber 或私有模块 API 进行“补注册”。应由插件源码修复注册契约，并在一次性、可回滚的 Profile 计划中更新指定包；真实 Profile 的更新与重启需要单独确认。

场景三：管理器不能解析远端 Catalog

Catalog schema 增加新的证据状态、字段或兼容性表达后，旧管理器可能只能使用随包快照，或者报出无法识别的字段/状态。处理顺序是：

1. 将管理器本身更新到 Catalog 中固定的、明确声明支持当前 schema 的版本；
2. 用固定 Commit 重新读取 Catalog；
3. 将错误与旧/新版本对应关系记录到 Issue，补充回归测试；
4. 只有更新计划、备份、健康检查和回滚条件都齐备时，才执行真实 Profile 更新。

不要删除远端新字段、降级 Catalog 或伪造“已验证”状态来让旧版本继续工作。

场景四：兼容性、可安装性或安全审查一直是未知

这些字段相互独立：

• 已发现：有公开的固定源码与基础身份信息；
• 可安装：需要可复现的安装证据；
• 运行验证：需要具体 DSH 版本、系统和一次性或真实 Profile 的运行证据；
• 安全审查：需要明确范围、方法和结论，静态准入不自动等于独立审计。

若缺少证据，正确修复是补充固定 Commit、Bundle/入口、许可证、兼容性测试或审查记录，而不是把 unknown 改成绿色标签。详见安全与信任边界与自动收录与更新。

场景五：更新提示出现权限或生命周期变化

任何新增文件写入、网络访问、命令执行、凭据访问、安装脚本或外部依赖，都应触发逐次审阅。比较旧/新固定 Commit 的 manifest、Bundle Patch、入口、依赖与权限矩阵；只在理解变化后确认单个更新计划。对浮动分支、缺少完整 Commit、无法完整读取源码或无法说明权限的候选，保持阻止或未知状态。

提交故障报告的最小信息

请在 GitHub Issues 提供以下内容：

发生时间（含时区）：
访问表面（Raw / Pages / dsh.store / dsh-store.cn / 本地 Profile）：
DSH 版本：
插件包名与已安装版本：
Catalog 固定 Commit：
完整错误（已删除 token、Cookie、环境变量、私人路径和用户内容）：
是否已备份、是否执行过更新/重启：
复现步骤：

维护规则

每个新增或修订条目必须包含：触发条件、可验证的影响范围、权威来源、低风险处理步骤、禁止操作、证据等级与仍未验证的部分。源码、Catalog、Pages、独立生产站和真实 Profile 的结论必须分别记录。无法复现或来源不明的说法可以作为待核线索，但不得写成已确认事实。

若紧急修复需要修改真实 Profile、重启 Host 或部署独立生产站，必须创建带固定来源、文件哈希、备份、回滚和健康检查的一次性计划；本文档不授予这些操作权限。