feat(cache): add file-tree and download-link caches (DB by default)

[Wudarensheng]

feat(cache): add file-tree and download-link caches (DB by default)

Summary / 摘要

Browsing a directory and starting a download both hit the remote drive on every
single request. The download-link exchange (driver.get() → presigned / raw URL)
is usually the most expensive and most rate-limited step of the two. The upstream
OpenList.ts reference solves this with a two-level cache (file tree + download
links); this PR ports that design to this repository.

浏览目录和开始下载这两个动作，此前每次请求都会打到远端存储；其中「换链」
（driver.get() → 预签名 / 直链）通常是最贵、最容易被网盘限流的一步。
本 PR 参考上游 OpenList.ts 的实现，把它的两级缓存（文件树 + 下载链接）移植过来。

User-visible behavior / 用户可感知的变化

• Directory listings are served from cache (default TTL 30 min, following the
  per-storage cache_expiration and custom_cache_policies). Empty directories
  are cached too, so repeated browsing stops hitting the remote drive.
  / 目录列表改为走缓存（默认 30 分钟，跟随存储级 cache_expiration 与
  custom_cache_policies）；空目录同样会被缓存。
• Download links returned by drivers are reused for a short window (default
  5 min), so repeated downloads / previews skip the link exchange.
  / 驱动换来的直链会在短时间内复用（默认 5 分钟），重复下载 / 预览不再重复换链。
• Writes (mkdir / rename / remove / move / copy / put) invalidate the
  affected path plus its parent directory for the file tree, and the path
  itself for links. / 写操作后自动失效：文件树连带父目录，链接只失效自身。
• Storage create / update / enable / disable / delete clears that storage's cache
  entirely. / 存储的新增 / 修改 / 启停 / 删除会清空该存储的全部缓存。
• 4 new admin endpoints: GET /cache/status, POST /cache/clear,
  POST /storage/refresh, POST /storage/refresh_one.
  / 新增 4 个管理接口（含对齐参考实现的 refresh / refresh_one）。
• GET /env_check now also reports the resolved cache config and the actual
  backends in use. / /env_check 额外回显生效的缓存配置与实际后端。

Implementation / 重要实现变化

• New module src/backend/internal/cache/ — config.ts (env switches),
  store.ts (backend resolution + key encoding + envelope get/set/list/clear),
  filetree.ts, link.ts, index.ts (barrel + invalidation orchestration),
  plus cache.test.ts (22 cases).
• Backend selection is entirely env-driven: CACHE_DRIVER=db (the default)
  resolves to the same backend as DB_DRIVER via getStorageBackend(), so
  zero configuration means "cache in the database".
• Dedicated kv / blob / cfkv / do / memory backends must be opted into
  explicitly and are never auto-detected or auto-substituted — consistent with
  the existing rule that an explicitly configured driver never falls back. An
  unavailable backend is skipped with a one-time warning; if none are available
  the cache silently degrades to a no-op.
• Cache entries are written through the driver's raw put / get / delete /
  list (deliberately not via saveDb(), which would trigger whole-config
  serialization, write guards and field encryption), under an isolated key prefix
  <CACHE_PREFIX>_<kind>_<storageId>_<encodedPath> (kind = ft / ln), so
  business-data keys are never touched. Paths longer than the EdgeOne KV key limit
  are folded with a double FNV-1a hash.
• Safety boundary: only driver-layer results are cached (raw FileItem[] and
  raw links). Permissions, meta passwords, hide rules and signatures are still
  computed per request in server/fs.ts / server/raw.ts, so a cache hit cannot
  leak privileges across users. Any cache error degrades to a no-op and never
  fails the request.

Config / 配置 (all optional — defaults preserve "DB-only"):

Variable	Default	Meaning
CACHE_ENABLED	true	Master switch for both caches.
CACHE_DRIVER	db	Backend list, comma-separated: db / kv / blob / cfkv / do / memory / none.
CACHE_FILE_TREE	true	Toggle the file-tree cache.
CACHE_DOWNLOAD_LINK	true	Toggle the download-link cache.
CACHE_TTL	0	File-tree TTL in minutes; 0 = follow per-storage cache_expiration (30).
CACHE_LINK_TTL	5	Download-link TTL in minutes.
CACHE_EXCLUDE_DRIVERS	virtual,alias,url_tree,strm,chunk	Drivers excluded from caching.
CACHE_PREFIX	openlist_cache	Key prefix isolating cache entries from business data.

Compatibility / 兼容性

• Purely additive: no existing endpoint, config key, storage format or
  migration path is modified.

• Caching is enabled by default. Set CACHE_ENABLED=false (or
  CACHE_DRIVER=none) to restore the previous behavior exactly; a single storage
  can opt out with cache_expiration=0 or a custom_cache_policies rule.
  / 缓存默认开启；CACHE_ENABLED=false（或 CACHE_DRIVER=none）可完全恢复原行为，
  单个存储也可用 cache_expiration=0 退出。

• This PR has breaking changes.
  / 此 PR 包含破坏性变更。

• This PR changes public API, config, storage format, or migration behavior.
  / 此 PR 修改了公开 API、配置、存储格式或迁移行为。
  

• This PR requires corresponding changes in related repositories.
  / 此 PR 需要关联仓库同步修改。

Related repository PRs / 关联仓库 PR:

• OpenList: — (no change required; the 4 new admin endpoints have no frontend UI yet, follow-up optional)
• OpenList-Docs: to be opened — documents the 8 new CACHE_* variables and the cache admin endpoints

Testing / 测试

Platform: Windows 10/11, Node.js 22.22.2, tsx --test.

• go test ./... — N/A: this repository is the TypeScript / Cloudflare Workers
  port; no Go sources are changed.
• Type check: npx tsc -p tsconfig.json --noEmit — 0 errors in every file
  changed by this PR. (Repo-wide, 10 errors remain, all pre-existing and
  unrelated: pkg/validators.ts cannot resolve zod in this sandbox, and
  internal/model/db_cipher.test.ts has two pre-existing typing errors.)
• npm run test:cache — 22/22 pass
• npm run test:model — 39/39 pass
• npm run test:store — 12/12 pass
• npm run test:drivers — 111/111 pass
• npm run test:189 — 20/20 pass
• npm run test:server — 125/129 pass

The 4 test:server failures are pre-existing and unrelated to this PR. This was
verified by a control run: with this PR's four touched source files reverted to
HEAD, the suite produces the identical result (129 tests / 125 pass / 4 fail, the
same four cases):

• default_credentials.test.ts (3) — admin bootstrap / password-reset semantics.
  Its import closure (db, auth, user, password, middlewares, op/sshkey)
  does not contain any file this PR touches.

• seed.test.ts (1) — "CAS codec matches casmeta base64 JSON field names": the
  codec emits cloud / slice_md5s / slice_size beyond the field set the test
  asserts.

• Manual test / 手动测试: not performed — and here is why. This environment has
  no credentials for a live remote storage (网盘 / object storage), so the cache
  could not be exercised end-to-end against a real drive. Coverage is unit-level,
  against the in-memory driver. Suggested manual check before merge:
  1. Attach a real storage, list a directory twice — the second listing should be
  served from cache (no remote request).
  2. Download a file twice — the second download should reuse the cached link.
  3. Rename / delete a file — both caches for that path and its parent should be
  invalidated, and the next listing should reflect the change.
  4. GET /api/admin/cache/status should report non-zero file_tree /
  download_link entry counts.

Checklist / 检查清单

• I have read CONTRIBUTING.
  / 我已阅读 CONTRIBUTING.
• I confirm this contribution follows the repository license, contribution policy, and code of conduct.
  / 我确认此贡献符合仓库许可证、贡献规范和行为准则。
• I have formatted the changed code with gofmt, go fmt, or prettier where applicable.
  / 我已按适用情况使用 gofmt、go fmt 或 prettier 格式化变更代码。
  
• I have requested review from relevant maintainers or code owners where applicable.
  / 我已在适用情况下请求相关维护者或代码所有者审查。

AI Disclosure / AI 使用声明

• This PR includes AI-assisted content.
  / 此 PR 包含 AI 辅助内容。

Tools used / 使用工具:

• ChatGPT
• Codex
• GitHub Copilot
• Claude
• Gemini
• Other (please specify) / 其他（请注明）: WorkBuddy AI (DeepSeek-V4.1-Flash)

Usage scope / 使用范围:

• Code generation / 代码生成

• Refactoring / 重构

• Documentation / 文档

• Tests / 测试

• Translation / 翻译

• Review assistance / 审查辅助

• I have reviewed and validated all AI-assisted content included in this PR.
  / 我已审核并验证此 PR 中的所有 AI 辅助内容。
  

• I have ensured that all AI-assisted commits include Co-Authored-By attribution.
  / 我已确保所有 AI 辅助提交都包含 Co-Authored-By 归属信息。
  

• I can reproduce all AI-assisted content included in this PR without any AI tools.
  / 我可以在没有任何 AI 工具的情况下重现此 PR 中包含的所有 AI 辅助内容。

[PIKACHUIM]

这个改动比较大，由于有些网盘的直链TTL非常短
建议考虑一下使用独立的缓存时间选项控制（并且默认关闭

[pikachuren]

🙏 感谢 @Wudarensheng 提交！
🤖 AI 自动审核声明：本评审报告由 AI 自动生成，当前使用 GLM 模型进行分析。
⚠️ AI 分析结果仅供参考，可能存在误判或遗漏。如您发现任何问题或有不同意见，欢迎随时提出讨论和纠正。
⚠️ 重要提醒：即使 AI 评审认为代码质量良好且建议合并，最终是否合并仍需由项目维护者进行人工判定。

🔄 增量评审：上次评审 → 当前 head（218669d）

新增提交 fix(cache): 缓存键单射编码、补上传失效、前缀校验、链接缓存默认关闭，逐条回查如下。

新增改动的问题（按 P0/P1/P2 分级）：

• 💡 [P2] 超长路径折叠键（编码 >180 时取前 100 字符 + xg + 双 FNV-1a）在两个超长路径之间依赖 64 位哈希区分，理论上仍可碰撞——概率层面可接受，建议在注释中保留此已知限制（当前注释已写明，确认即可）。
• 💡 [P2] storageIdFromCacheKey 按第一个 _ 切分 storage id，而 encodeKeyPart 会原样保留 _；若 storage id 本身含 _ 会切错。实际 id 为自增数字，当前无触发路径，属防御性提醒。

本轮补充实测：用真实依赖运行 internal/cache/cache.test.ts 24/24 通过；并把上一轮评审中 5/5 碰撞的路径对（/a/b ↔ /ax2fb 等）在新 head 代码下用真实 buildCacheKey 重跑，0/5 碰撞——键单射修复经真实执行验证成立。

旧问题解决情况：

• ✅ 缓存键碰撞（P0，实测复现）→ 已修复。isCachePlain 不再原样保留小写 x（x → x78），CACHE_PLAIN_RE 同步排除 x，/a/b 与 /ax2fb 不再同键；长键折叠用 xg 标记（普通编码中 x 后必跟两位十六进制，xg 不可能出现），短键与长键不会互撞。原评审建议的参数化断言（任意两路径键不相等）建议补上。
• ✅ /fs/upload/complete、/fs/multipart/complete、/fs/other 未失效缓存 → 已修复（fs.ts:1041、1625、1128、1368 直传 URL 预失效）。
• ✅ CACHE_PREFIX 未校验字符集 → 已修复，parseCachePrefix 只允许 [A-Za-z0-9_]（≤64 字符），非法回退默认值并告警。
• ✅ 链接缓存 TTL 过短风险（评论区维护者建议）→ CACHE_DOWNLOAD_LINK 默认改为 false，并文档注明「确认网盘直链有效期后再显式开启」。
• ❌ 测试仍集中在 store 层假驱动，resolveDrivers 的 db 解析、op 层命中/失效集成无用例 → 未补。

🎯 结论：✅ Approve — P0 碰撞修复到位、失效边界补齐，集成测试可后续补充。

[PIKACHUIM]

代码没有明显问题但是不敢合，主要是怕影响已有稳定性
要不这个等多测试一下再合并吧？