51 lines
3.4 KiB
Markdown
51 lines
3.4 KiB
Markdown
# 故障排查
|
|
|
|
本文只提供可审计的人工恢复步骤。应用不得把这里的操作包装成自动删除、重命名、隔离或重试按钮。
|
|
|
|
## 不安全图标缓存(`unsafe_cache`)
|
|
|
|
### 诊断含义
|
|
|
|
`unsafe_cache` 表示请求对应的磁盘缓存 entry 是 symlink、目录或其他非普通文件。`IconCache` 会立即 fail closed:不读取或跟随该 entry,不删除、改写或重命名它,也不继续远端获取。本次图标请求保持占位,其他软件列表功能不应被阻塞。
|
|
|
|
modern 与 Win7 详情只显示以下安全字段:
|
|
|
|
- 诊断码:`unsafe_cache`。
|
|
- 应用 ID:Catalog 的稳定 app ID。
|
|
- 缓存定位符:`<digest>-<dpi>.icon`,其中 digest 是已验证 `sha256:` 引用去掉前缀后的 64 位十六进制值,DPI 是 48～768 的已验证整数。
|
|
|
|
定位符不包含 cache root、原始 URL/query、后台 error、token 或 link target。不得要求用户从 UI 猜测这些内容。
|
|
|
|
### 确认缓存根
|
|
|
|
定位符对应的逻辑位置是:
|
|
|
|
```text
|
|
<configured-icon-cache-root>/<digest>-<dpi>.icon
|
|
```
|
|
|
|
安装模式正式装配的目标根是:
|
|
|
|
```text
|
|
%LOCALAPPDATA%\OwnSoftBox\cache\icons\
|
|
```
|
|
|
|
当前仓库尚未在生产 `cmd` 中装配 `NewIconCache`、`IconEventDelivery.LoadAndPublish` 或真实 `IconFetcher`;因此在该装配任务完成前,事实来源始终是调用方传给 `NewIconCache` 的 root,不能仅凭上述目标路径断定实际位置。测试临时目录也不是用户数据目录。
|
|
|
|
### 人工恢复步骤
|
|
|
|
1. 完全退出 SoftBox,并用受信任的系统管理工具确认 modern/Win7 客户端及相关后台进程均已退出。不要在应用仍可能访问缓存时处理 entry。
|
|
2. 记录诊断码、应用 ID、缓存定位符、发生时间和客户端版本。不要复制 URL/query、凭据或未经验证的 link target。
|
|
3. 从部署配置或未来的生产装配记录确认 configured icon cache root。确认它位于预期 OwnSoftBox 数据根内,其父目录可信,且 root 本身不是 symlink、junction 或其他 reparse point。无法确认时立即停止并联系管理员。
|
|
4. 只从已核验 root 的父目录侧定位 root 和该 locator。不要打开可疑 entry,不要进入目录,不要解析、跟随或访问其 target;检查应使用不跟随链接的元数据能力。
|
|
5. 由管理员按组织的事件响应/文件处置策略处理。可选择从可信父目录侧整体移走已核验的 icon cache 目录,或只处置精确 locator 对应的 entry;任何操作都必须作用于目录项本身且不得递归跟随链接。处理前保留第 2 步的安全诊断信息。
|
|
6. 在可信父目录下重新建立空的普通 `icons` 目录后再启动客户端。生产图标装配完成后,后续 cache miss 才会通过已验证 Fetcher 重建普通缓存文件;当前仓库不能宣称重启已经具备该能力。
|
|
7. 若相同 locator 再次出现 `unsafe_cache`,立即停止重复处理,保留新的安全诊断并升级给管理员调查 cache root 权限、外部写入者和部署配置。
|
|
|
|
### 禁止操作
|
|
|
|
- 不在应用内自动 delete、rename、quarantine 或 retry 可疑 entry。
|
|
- 不提供或执行会递归遍历、跟随 reparse point、通配整个用户目录的清理命令。
|
|
- 不通过打开 target 来判断其内容,不把绝对路径、target 或原始错误复制到 UI/事件。
|
|
- 不把普通损坏文件、离线、hash/decode 失败当成 `unsafe_cache`;这些情况继续使用 `invalid_content` 或 `unavailable`。
|