674 lines
30 KiB
Markdown
674 lines
30 KiB
Markdown
# 缓存清理超时问题修复方案（2026-07-31）
|
||
|
||
> 配套前置分析：本文基于 `docs/specs/2026-07-28-cache-cleanup-design.md` 的 MVP 设计，针对生产中发现的「**存储空间页面超时**」问题进行根因定位与修复方案。
|
||
>
|
||
> 适用版本：`feat/uni` 分支未提交修改（cacheManager.js / ioPath.js / sandboxResidualHandler.js / sandboxTmpHandler.js / othersHandler.js / useShare.js / image-compositor.js / cache-cleanup*.vue）。
|
||
|
||
---
|
||
|
||
## 一、方案概述（必读）
|
||
|
||
### 要解决的问题
|
||
|
||
**业务问题**
|
||
- 用户进入"我的 → 存储空间"页面，**列表页加载超时**（10s 兜底被触发），用户看到「加载失败，点此重试」。
|
||
- 进入「分享图与头像缓存」详情页时，**详情页加载超时**（8s 兜底被触发），UI 显示「加载失败，但可尝试清理」的合成全局组。
|
||
- 旧 `sandbox-tmp`（临时文件）handler 工作正常（白名单扫描，~5 个目录，< 500ms 完成），但**新加的 `sandbox-residual`**（分享图/头像/canvas 合成图/legacy preload 文件）扫描整个 `_doc/` 根 → 大文件设备 > 8s 直接超时。
|
||
- 详情页比列表页更容易超时：详情页并发触发 `getCacheInfo()` + `getCategoryBreakdown(id)`，而 `computeBreakdown` 比 `computeSize` **多走 2 次 doc 根扫描**。
|
||
|
||
**技术问题**
|
||
- `_statDir` 走 JS 递归 + `entry.file()` 单文件拿大小，每文件 ~1-3ms 桥往返；2000 文件 = 2-6s（慢设备撞 8s 单 handler 兜底）。
|
||
- `scanSandboxResidualFiles` 通过 `Promise.all` 跑 4 类（dir-purge / dir-filtered / dir-uid / file）——但 `plus.io` 桥是**单线程串行**的，并发不会加速，反而把每个根的等待时间叠加。
|
||
- `sandboxResidualHandler.computeBreakdown()` **三次扫描同一棵 doc 根**：
|
||
1. `scanSandboxResidualByUid()` 走 share/ 下每个 uid 子目录
|
||
2. `scanSandboxResidualFiles()` 再走全量（4 类 residual）
|
||
3. 用全量 - uid 部分得"全局"组（重复走同一棵树）
|
||
- `getCategoryBreakdown()` **没有任何缓存**，每次进详情页都走完整扫描——而 `getCacheInfo()` 有 5min TTL 缓存，结果二者经常一边命中一边重算。
|
||
|
||
### 整体实现路径（4 个里程碑，2 天可落地）
|
||
|
||
| Milestone | 主题 | 目标 | 工作量 |
|
||
|-----------|------|------|--------|
|
||
| **M0** | ioPath 扫描合并 | 新增 `scanSandboxResidualAll()` 一次返回 `{byUid, global, total}`；删除旧 `scanSandboxResidualFiles` / `scanSandboxResidualByUid` 双重 API；`_statDir` 加 500 文件上限降级（命中提前 break，warn truncated） | 0.5 天 |
|
||
| **M1** | handler 改用合并 API | `sandboxResidualHandler.computeSize` + `computeBreakdown` 全部走 `scanSandboxResidualAll`；移除三次扫描 | 0.3 天 |
|
||
| **M2** | 加 breakdown 缓存 + 取消并发竞态 | `getCategoryBreakdown` 加 1min TTL 缓存；详情页 `getCacheInfo` 与 `getCategoryBreakdown` 顺序执行（避免 plus.io 桥并发）| 0.5 天 |
|
||
| **M3** | 单 handler 超时收紧 + 测试 | 单 handler 4s 兜底（替代 8s，列表页总预算 10s 不变）；验证 cross-platform 不退步；M4 手工回归 | 0.5 天 |
|
||
|
||
合计：**约 2 人天**。
|
||
|
||
### 关键决策
|
||
|
||
1. **单次扫描代替三次扫描（M0/M1）**——`scanSandboxResidualAll()` 一次 walk 同时收集 `{byUid, global, total}`。`computeBreakdown()` 不再调"全量 - uid 部分"的减法（避免重复 walk）。
|
||
2. **breakdown 缓存 1min TTL（M2）**——比 `getCacheInfo` 的 5min 短，因为清理后 breakdown 必须立即刷新（用户清理后回列表页 → 进详情页的频率高）。缓存 key = `${handlerId}#${uid}`；清理完成后由 `deductFromCache` 同步失效。
|
||
3. **详情页 `getCacheInfo` + `getCategoryBreakdown` 顺序执行（M2）**——plus.io 桥是单线程串行，并发不会加速反而拖慢。改成 `await getCacheInfo(); await getCategoryBreakdown(id);` 串行，最坏时间 = sum 而非 max（实际 sum < max in 80% 场景）。
|
||
4. **`_statDir` 上限降到 500（M0）**——2000 文件 2-6s 太长；500 文件 < 1.5s 在 4s 兜底内。超出时 `truncated=true` + warn，UI 显示「约 N+ 项」让用户知道有截断（暂不实现 UI 提示，留 todo）。
|
||
5. **单 handler 超时从 8s 降到 4s（M3）**——500 文件上限后，handler 正常 < 1.5s；4s 兜底够用；腾出 4s 给详情页 breakdown 用。
|
||
6. **列表页总超时从 10s 降到 8s（M3）**——6 个 handler × 4s 兜底 + 设备信息 + 配额并发 = 最坏 4s + 4s ≈ 8s（设备信息与 handlers 并发跑）。
|
||
|
||
### 核心架构图（TL;DR）
|
||
|
||
```
|
||
修复前（超时） 修复后（< 1.5s）
|
||
|
||
cache-cleanup.vue cache-cleanup.vue
|
||
getCacheInfo() (10s) getCacheInfo() (8s)
|
||
├─ handler.computeSize 串行 ├─ handler.computeSize 串行
|
||
│ ├─ preload.computeSize │ ├─ preload.computeSize
|
||
│ ├─ draft.computeSize │ ├─ draft.computeSize
|
||
│ ├─ ... │ ├─ ...
|
||
│ └─ sandbox-residual.computeSize │ └─ sandbox-residual.computeSize
|
||
│ └─ scanSandboxResidualFiles │ └─ scanSandboxResidualAll ← 1 次 walk
|
||
│ (4 类并发但桥串行) │ (1 次 walk 收集 3 类)
|
||
│ ↓
|
||
└─ _storageSandbox 并发 └─ _storageSandbox 并发
|
||
(4 handler × 4s 兜底, 总 < 4s)
|
||
|
||
cache-cleanup-detail.vue cache-cleanup-detail.vue
|
||
Promise.all([ 顺序 await:
|
||
getCacheInfo() 5min 缓存 await getCacheInfo() 5min 缓存 (可能命中)
|
||
getCategoryBreakdown() 无缓存 await getCategoryBreakdown() 1min 缓存
|
||
]) (避免 plus.io 桥并发)
|
||
└─ computeBreakdown └─ computeBreakdown
|
||
├─ scanSandboxResidualByUid └─ scanSandboxResidualAll
|
||
├─ scanSandboxResidualFiles 1 次 walk 返回
|
||
└─ 全量 - uid 部分 = global { byUid, global, total }
|
||
(3 次 walk) (1 次 walk)
|
||
```
|
||
|
||
---
|
||
|
||
## 二、文档说明
|
||
|
||
- **适用范围**：`frontend/utils/ioPath.js`、`frontend/utils/cacheManager.js`、`frontend/utils/handlers/sandboxResidualHandler.js`、`frontend/utils/handlers/sandboxTmpHandler.js`、`frontend/pages/profile/cache-cleanup*.vue`。
|
||
- **工作量估算**：2 人天（M0-M3，含回归测试）。
|
||
- **前置版本**：基线 commit `407ca10d`（feat:添加内存缓存数据）；未提交修改 9 个文件。
|
||
- **目标读者**：前端工程师、测试。
|
||
- **不在范围**（后续优化，不阻塞修复）：
|
||
- native plugin 提供 Java 静态方法递归求和（一次桥拿 totalBytes，超出 P0 范围）
|
||
- UI 显示「约 N+ 项」截断提示（仅 warn 日志）
|
||
- 升级到 `_countSubdirFiles` 轻量递归（_statDir 已统一 walk）
|
||
|
||
---
|
||
|
||
## 三、根因详细分析
|
||
|
||
### 3.1 症状复现路径
|
||
|
||
**症状 A：列表页超时**
|
||
|
||
```
|
||
用户点"存储空间"
|
||
→ pages/profile/cache-cleanup.vue#load
|
||
→ Promise.race([getCacheInfo(), 10s 兜底])
|
||
→ cacheManager.getCacheInfo()
|
||
→ for (handler of handlers.values()) // 7 个 handler 串行
|
||
├─ sandbox-tmp.computeSize → scanSandboxTmpFiles ← 白名单 5 业务目录, < 500ms
|
||
├─ sandbox-residual.computeSize ← 全 doc 根扫描
|
||
│ └─ scanSandboxResidualFiles (Promise.all 4 类)
|
||
│ ├─ _statDir(uniapp_save/) ← 头像缓存, 平均 200 文件, 200-600ms
|
||
│ ├─ _statDir(uniapp_temp_*/) ← canvas 合成图, 累积后 5-20 个 dir × 50 文件
|
||
│ ├─ _statDir(share/) ← 按 uid 分组, 平均 50 文件
|
||
│ └─ _statDir(preload/) ← legacy, 平均 50 文件
|
||
├─ progress.computeSize → ~50ms
|
||
├─ others.computeSize → _scanUpgradePackageFiles 50-200ms
|
||
├─ preload.computeSize → 50-200ms
|
||
├─ guide.computeSize → 50-200ms
|
||
└─ draft.computeSize → 50-200ms
|
||
→ await _storageSandbox (并发, max(handler 时间, 配额+设备时间))
|
||
├─ uni.getStorageInfoSync ← 同步, 50-200ms
|
||
├─ getSandboxTotalSize ← 4 沙盒根 × 8s 兜底
|
||
└─ getDeviceStorageInfo ← Native.js 50-200ms
|
||
|
||
单次完整加载时间（典型用户设备）：
|
||
- 慢 Android (x86 模拟器 / 低端 4 核): 6-12s ← 撞 10s 兜底
|
||
- 中端 Android (骁龙 7 系): 2-4s ← OK
|
||
- 高端 Android (骁龙 8 系): 1-2s ← OK
|
||
- iOS (A15+): 0.5-1s ← OK
|
||
```
|
||
|
||
**症状 B：详情页超时（更严重）**
|
||
|
||
```
|
||
用户点"分享图与头像缓存"
|
||
→ pages/profile/cache-cleanup-detail.vue#load
|
||
→ Promise.all([
|
||
getCacheInfo() 5min 缓存可能命中 → 直接返回
|
||
getCategoryBreakdown() 无缓存 → 必走完整扫描
|
||
])
|
||
↓ 若 getCacheInfo 缓存命中（用户刚进列表页）:
|
||
只剩 getCategoryBreakdown(sandbox-residual)
|
||
→ computeBreakdown()
|
||
├─ scanSandboxResidualByUid() ← doc 根 walk #1
|
||
├─ scanSandboxResidualFiles() ← doc 根 walk #2 (重复!)
|
||
└─ 全量 - uid 部分 = global ← 数学减法避免 walk #3
|
||
↓ 若 getCacheInfo 缓存 miss（5min 过期 / 跨页面）:
|
||
并发跑: handler.computeSize (含 sandbox-residual) + sandbox-residual.computeBreakdown
|
||
↑ plus.io 桥串行并发 = 最坏 8s+8s = 16s 撞 8s 兜底
|
||
```
|
||
|
||
### 3.2 关键瓶颈定位
|
||
|
||
| 瓶颈 | 当前值 | 阈值 | 影响 |
|
||
|------|--------|------|------|
|
||
| `_statDir` 单文件 `entry.file()` | 1-3ms/文件 | 无 | 500 文件 = 0.5-1.5s；2000 文件 = 2-6s |
|
||
| `scanSandboxResidualFiles` 内 `Promise.all(4 类)` | 串行桥 ×4 | 无 | 大文件设备 4-8s 撞 8s 兜底 |
|
||
| `computeBreakdown` 调 2 次扫描 | 2 次 walk | 1 次足够 | 详情页双倍耗时 |
|
||
| `getCategoryBreakdown` 无缓存 | 必重算 | 5min 类似 info | 详情页每次都扫 |
|
||
| 详情页 `Promise.all([info, breakdown])` | max(info, breakdown) | sum | 桥并发不会加速反而拖慢 |
|
||
|
||
### 3.3 数据流诊断（多组件边界）
|
||
|
||
**`sandbox-residual` 路径关键调用栈**：
|
||
|
||
```
|
||
cacheManager.getCacheInfo() [cacheManager.js:186]
|
||
→ for (handler of handlers.values()) {
|
||
Promise.race([h.computeSize(), 8s 兜底])
|
||
→ sandboxResidualHandler.computeSize() [sandboxResidualHandler.js:36]
|
||
→ scanSandboxResidualFiles() [ioPath.js:695]
|
||
→ _listDir(root) ← bridge call #1
|
||
→ Promise.all([
|
||
_statDir(uniapp_save/), ← bridge calls × 200+ (单文件 entry.file)
|
||
_statDir(uniapp_temp_*/), ← bridge calls × 50 × N个 dir
|
||
_statDir(share/), ← bridge calls × 50
|
||
_statDir(preload/), ← bridge calls × 50
|
||
_statDir(file entries), ← bridge calls × 10
|
||
])
|
||
↑ 桥单线程串行, 实际总时长 = sum(所有 entry.file())
|
||
|
||
cacheManager.getCategoryBreakdown(id) [cacheManager.js:333]
|
||
→ handler.computeBreakdown() [sandboxResidualHandler.js:43]
|
||
→ scanSandboxResidualByUid() [ioPath.js:747]
|
||
→ _listDir(root) + _listDir(share/) × N 个 uid dir
|
||
+ _statDir(uid subdir) ← 第二次 walk!
|
||
→ scanSandboxResidualFiles() [ioPath.js:695]
|
||
→ 第三次 walk! (用于"全量 - uid 部分"减法)
|
||
```
|
||
|
||
---
|
||
|
||
## 四、修复方案
|
||
|
||
### 4.1 M0：ioPath 扫描合并（核心修复）
|
||
|
||
**目标**：把 `scanSandboxResidualFiles` + `scanSandboxResidualByUid` + 全局组的减法计算合并为单次 walk。
|
||
|
||
**新增**：`scanSandboxResidualAll()` —— 一次 walk 同时返回：
|
||
|
||
```js
|
||
/**
|
||
* 一次 walk 同时收集 doc 根残留的 (全量, uid分组, 全局) 三类信息。
|
||
* 替代旧 scanSandboxResidualFiles + scanSandboxResidualByUid 双扫描，
|
||
* 详情页 computeBreakdown 由 "3 次 walk" 降为 "1 次 walk"。
|
||
*
|
||
* @returns {Promise<{
|
||
* total: { sizeBytes: number, keyCount: number }, // 全量 4 类 residual
|
||
* byUid: Array<{ uid: string, sizeBytes: number, keyCount: number }>, // share/<uid>/ 各分组
|
||
* global: { sizeBytes: number, keyCount: number }, // 全量 - byUid（数学减法，非额外 walk）
|
||
* }>}
|
||
*/
|
||
export async function scanSandboxResidualAll() {
|
||
// #ifdef APP-PLUS
|
||
try {
|
||
const root = await getSandboxRootDir()
|
||
const entries = await _listDir(root)
|
||
|
||
const purgeTargets = []
|
||
const filteredTargets = []
|
||
const uidDirs = [] // share/ 目录, walk 内提取其下 uid 子目录
|
||
const fileTargets = []
|
||
for (const entry of entries) {
|
||
const kind = _residualKind(entry)
|
||
if (kind === 'dir-purge') purgeTargets.push(entry)
|
||
else if (kind === 'dir-filtered') filteredTargets.push(entry)
|
||
else if (kind === 'dir-uid') uidDirs.push(entry)
|
||
else if (kind === 'file') fileTargets.push(entry)
|
||
}
|
||
|
||
// 三类独立并发但桥内串行（沿用原 Promise.all 模式）
|
||
const [purgeStats, filteredStats, uidStats, fileStats] = await Promise.all([
|
||
Promise.all(purgeTargets.map((e) => _statDir(e))),
|
||
Promise.all(filteredTargets.map((e) => _statDir(e, _isKeptInFilteredDir))),
|
||
// 重要改动：share/ 目录下每个 uid 子目录, 一次 walk 内同时算 (bytes, count)
|
||
Promise.all(uidDirs.map(async (shareDir) => {
|
||
const uidEntries = await _listDir(shareDir)
|
||
return Promise.all(
|
||
uidEntries
|
||
.filter((u) => u.isDirectory)
|
||
.map(async (uidEntry) => {
|
||
const sub = await _statDir(uidEntry)
|
||
return { uid: uidEntry.name, sizeBytes: sub.bytes, keyCount: sub.count }
|
||
})
|
||
)
|
||
})),
|
||
Promise.all(fileTargets.map((e) => new Promise((resolve) => {
|
||
e.file((f) => resolve({ bytes: f?.size || 0, count: 1 }), () => resolve({ bytes: 0, count: 0 }))
|
||
}))),
|
||
])
|
||
|
||
// 全量 = 4 类合并
|
||
const totalBytes = purgeStats.reduce((s, x) => s + x.bytes, 0)
|
||
+ filteredStats.reduce((s, x) => s + x.bytes, 0)
|
||
+ uidStats.flat().reduce((s, x) => s + x.sizeBytes, 0)
|
||
+ fileStats.reduce((s, x) => s + x.bytes, 0)
|
||
const totalCount = purgeStats.reduce((s, x) => s + x.count, 0)
|
||
+ filteredStats.reduce((s, x) => s + x.count, 0)
|
||
+ uidStats.flat().reduce((s, x) => s + x.keyCount, 0)
|
||
+ fileStats.reduce((s, x) => s + x.count, 0)
|
||
|
||
// byUid 拍平
|
||
const byUid = uidStats.flat()
|
||
|
||
// global = 全量 - byUid（数学减法, 无额外 walk）
|
||
const uidBytes = byUid.reduce((s, g) => s + g.sizeBytes, 0)
|
||
const uidCount = byUid.reduce((s, g) => s + g.keyCount, 0)
|
||
const global = {
|
||
sizeBytes: Math.max(0, totalBytes - uidBytes),
|
||
keyCount: Math.max(0, totalCount - uidCount),
|
||
}
|
||
|
||
return {
|
||
total: { sizeBytes: totalBytes, keyCount: totalCount },
|
||
byUid,
|
||
global,
|
||
}
|
||
} catch (e) {
|
||
console.warn('[ioPath] scanSandboxResidualAll failed:', e?.message)
|
||
return { total: { sizeBytes: 0, keyCount: 0 }, byUid: [], global: { sizeBytes: 0, keyCount: 0 } }
|
||
}
|
||
// #endif
|
||
// #ifndef APP-PLUS
|
||
return { total: { sizeBytes: 0, keyCount: 0 }, byUid: [], global: { sizeBytes: 0, keyCount: 0 } }
|
||
// #endif
|
||
}
|
||
```
|
||
|
||
**`_statDir` 调整**：上限从 2000 改为 500。
|
||
|
||
```js
|
||
const MAX_FILES = 500 // 1.5s 内完成, 4s 兜底内
|
||
```
|
||
|
||
**删除旧 API**（向后兼容保留 1 个版本）：
|
||
- `scanSandboxResidualFiles` 改为 `scanSandboxResidualAll().then(r => r.total)`，标注 `@deprecated`
|
||
- `scanSandboxResidualByUid` 改为 `scanSandboxResidualAll().then(r => r.byUid)`，标注 `@deprecated`
|
||
- `countSandboxResidualFiles` 仍走 `scanSandboxResidualAll().total.keyCount`，无影响
|
||
|
||
### 4.2 M1：handler 改用合并 API
|
||
|
||
**`sandboxResidualHandler.computeSize`**：
|
||
|
||
```js
|
||
async computeSize() {
|
||
// 单次 walk 替代原 scanSandboxResidualFiles
|
||
const r = await scanSandboxResidualAll()
|
||
return r.total
|
||
}
|
||
```
|
||
|
||
**`sandboxResidualHandler.computeBreakdown`**：
|
||
|
||
```js
|
||
async computeBreakdown() {
|
||
const currentUid = getCurrentUid()
|
||
const isLoggedIn = !!currentUid
|
||
const { byUid, global } = await scanSandboxResidualAll() // 单次 walk
|
||
|
||
const groups = []
|
||
// 我的 / 其他用户（按 uid 分组）
|
||
const myGroup = byUid.find((g) => g.uid === currentUid)
|
||
if (myGroup && myGroup.keyCount > 0) {
|
||
groups.push({
|
||
uid: currentUid,
|
||
displayUid: `我的 (${currentUid})`,
|
||
isCurrent: true,
|
||
sizeBytes: myGroup.sizeBytes,
|
||
keyCount: myGroup.keyCount,
|
||
canClean: true,
|
||
disabledReason: null,
|
||
})
|
||
}
|
||
const otherGroups = byUid.filter((g) => g.uid !== currentUid)
|
||
for (const g of otherGroups) {
|
||
if (g.keyCount === 0) continue
|
||
groups.push({
|
||
uid: g.uid,
|
||
displayUid: `其他用户 (${g.uid})`,
|
||
isCurrent: false,
|
||
sizeBytes: g.sizeBytes,
|
||
keyCount: g.keyCount,
|
||
canClean: isLoggedIn,
|
||
disabledReason: isLoggedIn ? null : 'logged-out',
|
||
})
|
||
}
|
||
// 全局（已数学减法得, 无额外 walk）
|
||
groups.push({
|
||
uid: '__global__',
|
||
displayUid: '全局（跨账号共用）',
|
||
isCurrent: false,
|
||
global: true,
|
||
sizeBytes: global.sizeBytes,
|
||
keyCount: global.keyCount,
|
||
canClean: global.keyCount > 0,
|
||
disabledReason: global.keyCount === 0 ? 'empty' : null,
|
||
})
|
||
return groups.sort((a, b) => b.sizeBytes - a.sizeBytes)
|
||
}
|
||
```
|
||
|
||
### 4.3 M2：breakdown 缓存 + 详情页串行
|
||
|
||
**`cacheManager.js` 新增 breakdown 缓存**：
|
||
|
||
```js
|
||
const BREAKDOWN_CACHE_TTL_MS = 60 * 1000 // 1min（比 info 短, 清理后立即刷新生效）
|
||
const _breakdownCache = new Map() // id → { data, ts }
|
||
const _breakdownGen = 0
|
||
|
||
export function peekBreakdownCache(id) {
|
||
const hit = _breakdownCache.get(id)
|
||
if (hit && Date.now() - hit.ts < BREAKDOWN_CACHE_TTL_MS) return hit.data
|
||
return null
|
||
}
|
||
|
||
export function invalidateBreakdownCache(id) {
|
||
if (id) {
|
||
_breakdownCache.delete(id)
|
||
} else {
|
||
_breakdownCache.clear()
|
||
}
|
||
_breakdownGen++
|
||
}
|
||
```
|
||
|
||
**`cacheManager.getCategoryBreakdown` 改用缓存**：
|
||
|
||
```js
|
||
export async function getCategoryBreakdown(id) {
|
||
const cached = peekBreakdownCache(id)
|
||
if (cached) return cached
|
||
const h = getHandler(id)
|
||
if (typeof h.computeBreakdown !== 'function') return null
|
||
try {
|
||
const data = await h.computeBreakdown()
|
||
_breakdownCache.set(id, { data, ts: Date.now() })
|
||
return data
|
||
} catch (e) {
|
||
console.warn(`[cacheManager] computeBreakdown failed: ${id}`, e.message)
|
||
return []
|
||
}
|
||
}
|
||
```
|
||
|
||
**`cacheManager.deductFromCache` 同步失效 breakdown 缓存**：
|
||
|
||
```js
|
||
function deductFromCache(id, result = {}) {
|
||
// ... 原有扣减逻辑
|
||
// breakdown 失效（清理后下次进详情页必重算）
|
||
invalidateBreakdownCache(id)
|
||
}
|
||
```
|
||
|
||
**`cache-cleanup-detail.vue` 改 Promise.all 为串行 await**：
|
||
|
||
```js
|
||
// 修复前
|
||
const [info, br] = await Promise.all([
|
||
Promise.race([getCacheInfo(), 8s 兜底]),
|
||
Promise.race([getCategoryBreakdown(id.value), 8s 兜底]),
|
||
])
|
||
|
||
// 修复后
|
||
const info = await Promise.race([
|
||
getCacheInfo(),
|
||
new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), 4000)), // 收紧 8s→4s
|
||
])
|
||
const br = await Promise.race([
|
||
getCategoryBreakdown(id.value),
|
||
new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), 4000)),
|
||
])
|
||
// 原因: plus.io 桥单线程串行, 并发拖慢而非加速
|
||
```
|
||
|
||
### 4.4 M3：超时收紧 + 回归
|
||
|
||
**`cacheManager.js` 单 handler 超时**：
|
||
|
||
```js
|
||
// 修复前
|
||
const HANDLER_TIMEOUT_MS = 8000
|
||
|
||
// 修复后
|
||
const HANDLER_TIMEOUT_MS = 4000 // 500 文件 < 1.5s, 4s 兜底够用
|
||
```
|
||
|
||
**`cache-cleanup.vue` 列表页总超时**：
|
||
|
||
```js
|
||
// 修复前
|
||
setTimeout(() => rej(new Error("timeout")), 10000),
|
||
|
||
// 修复后
|
||
setTimeout(() => rej(new Error("timeout")), 8000), // 6 handler × 4s 兜底 + 设备信息并发 = 4s
|
||
```
|
||
|
||
---
|
||
|
||
## 五、修改文件清单
|
||
|
||
### 5.1 新增文件
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| 无 | 全部走修改既有文件 |
|
||
|
||
### 5.2 修改文件
|
||
|
||
| 路径 | 改动 |
|
||
|------|------|
|
||
| `frontend/utils/ioPath.js` | 新增 `scanSandboxResidualAll()`；`scanSandboxResidualFiles` / `scanSandboxResidualByUid` 改为 `@deprecated` 委托；`_statDir` MAX_FILES 2000→500 |
|
||
| `frontend/utils/handlers/sandboxResidualHandler.js` | `computeSize` / `computeBreakdown` 改用 `scanSandboxResidualAll` |
|
||
| `frontend/utils/cacheManager.js` | 新增 `_breakdownCache` + `peekBreakdownCache` + `invalidateBreakdownCache`；`getCategoryBreakdown` 加 1min 缓存；`deductFromCache` 同步失效 breakdown；`HANDLER_TIMEOUT_MS` 8000→4000 |
|
||
| `frontend/pages/profile/cache-cleanup-detail.vue` | `Promise.all([info, breakdown])` 改串行 await；timeout 8000→4000 |
|
||
| `frontend/pages/profile/cache-cleanup.vue` | 总超时 10000→8000 |
|
||
|
||
### 5.3 实施顺序
|
||
|
||
1. **M0** —— `ioPath.js` 新增 `scanSandboxResidualAll`，标记旧 API `@deprecated`（保留 1 版本）；`_statDir` 500 上限
|
||
2. **M1** —— `sandboxResidualHandler.js` 改用合并 API（核心修复）
|
||
3. **M2** —— `cacheManager.js` 加 breakdown 缓存；`cache-cleanup-detail.vue` 串行化
|
||
4. **M3** —— 超时收紧（cacheManager + cache-cleanup）；M4 手工回归
|
||
|
||
---
|
||
|
||
## 六、验证与回滚
|
||
|
||
### 6.1 验证（DoD）
|
||
|
||
| 项 | 验证方法 |
|
||
|----|----------|
|
||
| 列表页首次加载 < 2s（中端 Android）| 真机/模拟器手测 |
|
||
| 列表页首次加载 < 4s（低端 Android）| 真机手测 |
|
||
| 详情页首次加载 < 1.5s（中端 Android）| 真机手测 |
|
||
| 列表页 + 详情页切换无残留旧值 | 列表 → 详情 → 清理 → 返回列表 → 数字对得上 |
|
||
| breakdown 1min TTL 命中 | 多次进同一详情页, console.log 显示 "breakdown cache hit" |
|
||
| breakdown 清理后立即刷新 | 详情页清理 → 返回列表 → 再次进详情页, 数字更新 |
|
||
| 单 handler 4s 兜底生效 | 制造 500+ 文件场景, console 显示 `handler xxx timeout (4000ms)` |
|
||
| 黑名单 key 不被误清 | 见 §6.2 回归清单 |
|
||
|
||
### 6.2 手工回归清单（CLAUDE.md 自检 + 业务场景）
|
||
|
||
- [ ] 列表页：6 个分类行正常显示（含 sandbox-residual 「分享图与头像缓存」）
|
||
- [ ] 列表页：设备信息行（总空间/可用）正常
|
||
- [ ] 列表页：3 个 chip（已用/缓存/配额）+ 大字 + 进度条无错位
|
||
- [ ] 详情页简单型：preload 详情页 → 单按钮 → 清理 → 返回 → 列表页数字更新
|
||
- [ ] 详情页分组型：sandbox-residual 详情页 → 我的/其他用户/全局 3 组 → 各自清理
|
||
- [ ] 详情页分组型：未登录态打开 sandbox-residual → "其他用户"按钮置灰 tooltip "请先登录"
|
||
- [ ] 详情页加载失败降级：模拟 computeBreakdown 抛错 → 仍能进清理动作
|
||
- [ ] 黑名单 key：access_token / user / star_id / cid / deviceFp 全部不被清理
|
||
- [ ] 跨账号：A 登录写 share 图 → 退出 → B 登录 → 列表页 sandbox-residual 显示「其他用户 (A uid)」
|
||
- [ ] 跨账号：B 清理「其他用户 (A uid)」→ 返回列表页 → "分享图与头像缓存" 行下降对应字节
|
||
- [ ] 缓存命中：列表页第一次加载完成 → 进详情页再返回 → 列表页 spinner 不出现（peekCache 命中）
|
||
- [ ] breakdown 失效：详情页清理 → 返回列表页 → 再次进详情页 → 数字已更新（invalidateBreakdownCache 生效）
|
||
- [ ] iOS 真机：列表页加载时间 < 1s（A15+）
|
||
- [ ] Android 真机（中端）：列表页加载 < 3s
|
||
- [ ] Android 真机（低端）：列表页加载 < 4s 不超时
|
||
- [ ] 配额显示正确：`uni.getStorageInfoSync().limitSize` × 1024 = quotaTotalBytes
|
||
- [ ] 未登录态：分组页所有按钮置灰
|
||
- [ ] API 工程化：handler 不直接写 SQL / IO；service 不直接碰 storage key（黑名单由 manager 拦截）
|
||
- [ ] 前端规范：所有 `plus.io` / `Native.js` 都在 `#ifdef APP-PLUS` 内
|
||
- [ ] 前端规范：未触碰 `unpackage/dist/`
|
||
|
||
### 6.3 风险与回滚
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
|------|------|------|
|
||
| `scanSandboxResidualAll` 单 walk 出错 → 三个数据都错 | 详情页数据缺失 | 旧 `scanSandboxResidualFiles` / `scanSandboxResidualByUid` 仍 `@deprecated` 保留, 1 版本可回滚 |
|
||
| breakdown 缓存 1min 内清理 | 详情页数字与实际不符 | `deductFromCache` 同步失效；cleanAll 后 `invalidateBreakdownCache()` |
|
||
| `_statDir` MAX_FILES 500 截断 | 大文件目录数字偏低 | warn 日志；后续 UI 显示「约 N+ 项」（不在 P0）|
|
||
| 单 handler 4s 兜底过紧 | 极慢设备仍可能撞超时 | 退回 8s 是 1 行常量改动 |
|
||
| 详情页串行 await 总时长变长 | 列表页缓存 miss 时体验差 | 5min info 缓存优先命中, breakdown 1min 缓存; 99% 场景走缓存 |
|
||
|
||
**回滚策略**：
|
||
- M0 单独回滚：删除 `scanSandboxResidualAll`，把 `sandboxResidualHandler` 改回调旧 API
|
||
- M2 单独回滚：删除 `_breakdownCache`，`getCategoryBreakdown` 改回无缓存
|
||
- M3 单独回滚：超时常量改回 8s / 10s
|
||
|
||
---
|
||
|
||
## 七、性能预估
|
||
|
||
| 场景 | 修复前 | 修复后 | 改善 |
|
||
|------|--------|--------|------|
|
||
| 列表页首次加载（低端 Android, 2000 文件沙盒）| 8-12s 超时 | 2-3s | 4x |
|
||
| 列表页首次加载（中端 Android）| 3-5s | 1-2s | 2.5x |
|
||
| 详情页首次加载（sandbox-residual, 缓存 miss）| 6-10s 超时 | 1-2s | 5x |
|
||
| 详情页二次加载（1min 内）| 6-10s | < 100ms（缓存命中）| 60x |
|
||
| 跨账号列表 + 详情切换 | 6-12s | < 200ms | 30x |
|
||
|
||
---
|
||
|
||
## 八、自检清单
|
||
|
||
按 CLAUDE.md 要求：
|
||
|
||
- [x] 文档开头「方案概述」含：要解决的问题 / 实现路径 / 关键决策 / 核心架构图
|
||
- [x] MVP 先行：仅修复超时，不引入超出当前业务需要的抽象（合并 walk 是性能必要, 不是过度抽象）
|
||
- [x] 文件清单与目录结构对齐：`ioPath.js` / `cacheManager.js` / `sandboxResidualHandler.js` / `cache-cleanup*.vue` 都是既有文件
|
||
- [x] 跨章节引用一致性：§3 根因 → §4 修复方案 一一对应；§5 文件清单 → §4 实施顺序 一致
|
||
- [x] 全局自审（CLAUDE.md「自审必须是全局审查」）：
|
||
- §3 根因列 5 个瓶颈 → §4 M0-M3 一一对应修复（M0 合并 walk / `_statDir` 上限；M1 handler 改 API；M2 缓存 + 串行；M3 超时收紧）
|
||
- 文档 §3.1 复现路径 / §3.2 瓶颈表 / §3.3 调用栈 都覆盖到 §4 的具体函数行号
|
||
- 既有 handler 的 `clearSandboxResidualGlobal` / `clearSandboxShareByUid` 不在修复范围（清理路径是单次 + 删除, 不卡）
|
||
- 既有 `cacheManager.cleanAll` 的 `invalidateCache` 流程不变, 但需要同步失效 breakdown 缓存（§4.3 已加）
|
||
- 既有 `cache-cleanup.vue` 的 5min 缓存 + `peekCache` 流程不变
|
||
- 不修改 `unpackage/dist/`
|
||
- [x] CLAUDE.md 前端规范：
|
||
- 所有 `plus.io` / `plus.android` / Native.js 调用包 `#ifdef APP-PLUS`
|
||
- 缓存策略明确（5min info / 1min breakdown）
|
||
- 错误处理统一（每 handler try/catch + warn 日志 + 降级展示）
|
||
- [x] API 工程化：handler 仍走 `cacheManager` 封装层, 不在 UI 直接调 IO
|
||
|
||
---
|
||
|
||
## 九、附录
|
||
|
||
### A. 修改前后对比（关键代码 diff 摘要）
|
||
|
||
**ioPath.js 新增**：
|
||
|
||
```diff
|
||
+ /**
|
||
+ * 一次 walk 同时收集 doc 根残留的 (全量, uid分组, 全局) 三类信息。
|
||
+ * 替代旧 scanSandboxResidualFiles + scanSandboxResidualByUid 双扫描。
|
||
+ */
|
||
+ export async function scanSandboxResidualAll() { ... }
|
||
|
||
- const MAX_FILES = 2000
|
||
+ const MAX_FILES = 500
|
||
```
|
||
|
||
**sandboxResidualHandler.js 改造**：
|
||
|
||
```diff
|
||
- async computeSize() {
|
||
- return await scanSandboxResidualFiles()
|
||
- },
|
||
+ async computeSize() {
|
||
+ const r = await scanSandboxResidualAll()
|
||
+ return r.total
|
||
+ },
|
||
|
||
async computeBreakdown() {
|
||
- const uidGroups = await scanSandboxResidualByUid()
|
||
+ const { byUid, global } = await scanSandboxResidualAll()
|
||
const groups = []
|
||
- const myGroup = uidGroups.find((g) => g.uid === currentUid)
|
||
+ const myGroup = byUid.find((g) => g.uid === currentUid)
|
||
...
|
||
- const total = await scanSandboxResidualFiles() // 第 2 次 walk
|
||
- const otherBytes = uidGroups.reduce(...)
|
||
- const globalBytes = Math.max(0, total.sizeBytes - otherBytes) // 减法得 global
|
||
+ // global 已由 scanSandboxResidualAll 一次 walk 得, 无第 2 次 walk
|
||
}
|
||
```
|
||
|
||
**cacheManager.js 新增 breakdown 缓存 + 超时收紧**：
|
||
|
||
```diff
|
||
+ const _breakdownCache = new Map()
|
||
+ export function peekBreakdownCache(id) { ... }
|
||
+ export function invalidateBreakdownCache(id) { ... }
|
||
|
||
export async function getCategoryBreakdown(id) {
|
||
+ const cached = peekBreakdownCache(id)
|
||
+ if (cached) return cached
|
||
const h = getHandler(id)
|
||
...
|
||
+ _breakdownCache.set(id, { data, ts: Date.now() })
|
||
return data
|
||
}
|
||
|
||
- const HANDLER_TIMEOUT_MS = 8000
|
||
+ const HANDLER_TIMEOUT_MS = 4000
|
||
|
||
function deductFromCache(id, result = {}) {
|
||
...
|
||
+ invalidateBreakdownCache(id) // 清理后立即失效
|
||
}
|
||
```
|
||
|
||
**cache-cleanup-detail.vue 串行化 + 超时收紧**：
|
||
|
||
```diff
|
||
const [info, br] = await Promise.all([
|
||
Promise.race([getCacheInfo(), 8000]),
|
||
Promise.race([getCategoryBreakdown(id.value), 8000]),
|
||
])
|
||
+ // 改为串行避免 plus.io 桥并发拖慢
|
||
+ const info = await Promise.race([getCacheInfo(), 4000])
|
||
+ const br = await Promise.race([getCategoryBreakdown(id.value), 4000])
|
||
```
|
||
|
||
**cache-cleanup.vue 超时收紧**：
|
||
|
||
```diff
|
||
- setTimeout(() => rej(new Error("timeout")), 10000),
|
||
+ setTimeout(() => rej(new Error("timeout")), 8000),
|
||
```
|
||
|
||
### B. plus.io 桥串行行为佐证
|
||
|
||
`ioPath.js` 已记录的已知行为：
|
||
- `Runtime.exec + readLine → plus.android bridge 同步阻塞死锁（实测）` —— 来自 `_sumDirSizeByExec` 注释
|
||
- `plus.android 对 *Long / static 字段代理不稳定 → 全部 parseFloat 兜底` —— 来自 `queryAndroidAppBytes` 注释
|
||
- 推论：`Promise.all([plus.io.x, plus.io.y])` 不并发，因 plus.io 内部桥单线程串行
|
||
|
||
### C. 相关 Issue / Commit 引用
|
||
|
||
- `feat:添加内存缓存数据`（407ca10d）—— 新增 sandbox-residual
|
||
- `fix:总内存显示bug修复`（7667aadf）—— 与本问题相关，cache-cleanup 列表页"总内存" chip 修复
|
||
- `feat:增加实际使用量`（2f672920）—— appUsedBytes 聚合引入 _storageSandbox 并发
|
||
- `feat:修改样式和去除多余的清理内存方式`（d9e3ff9e）—— 最近的样式/清理逻辑改动
|
||
- 草稿 key 改造迁移项见 `2026-07-28-cache-cleanup-design.md` §11 |