zipcalm 0.0.0-stage → 1.0.1

package/server/core/fs/repairNames.js

@@ -0,0 +1,150 @@
+// 修复"已解压目录"里的乱码文件名（POST /fs/repair-names 的实现）
+//
+// 场景：文件早就解压完了（可能是旧版本 unrar 解的），磁盘上是 U+FFFE + 私有区转义的怪名字。
+// 这时不可能重解压，只能就地改名 —— 本模块负责扫描、预览、并按需真改。
+//
+// 纪律：
+//   - **dryRun 默认 true**：不显式传 false 就只出清单（项目对"文件移动/批量重命名"的硬要求）
+//   - **绝不覆盖**：目标已存在 → 记 conflicts，不动的文件一个都不动
+//   - **从深到浅改名**：先改子目录里的文件，再改目录本身（否则父目录改名后子路径全失效）
+//   - **跳过符号链接**：不跟随、不改名（链接目标可能根本不在本根内）
+//   - **有损名不猜**：带 `?` 且无 U+FFFE 标记的名字进 unrecoverable，不做 GBK 猜测
+//   - 深度/条数上限：这是网络盘（CIFS），不能让一次请求跑飞
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+import { hasEscapeMarker, repairName } from '../../plugins/formats/_shared/nameRepair.js';
+import { resolveRequestPath } from './safePath.js';
+
+const DEFAULT_MAX_DEPTH = 6;
+const MAX_DEPTH_LIMIT = 12;
+const DEFAULT_MAX_ENTRIES = 5000;
+const MAX_ENTRIES_LIMIT = 20000;
+/** 报告里每类最多列多少条（数量永远是精确的，列表是截断的） */
+const REPORT_LIMIT = 50;
+
+function clampInt(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) return fallback;
+  return Math.min(max, Math.max(min, parsed));
+}
+
+/** 递归收集条目（不跟随符号链接），带深度上限与条数上限 */
+async function collectEntries(rootAbs, maxDepth, maxEntries) {
+  const collected = [];
+  let truncated = false;
+  const walk = async (dirAbs, prefix, depth) => {
+    if (depth > maxDepth || truncated) return;
+    const dirents = await fsp.readdir(dirAbs, { withFileTypes: true }).catch(() => []);
+    for (const dirent of dirents) {
+      if (collected.length >= maxEntries) {
+        truncated = true;
+        return;
+      }
+      // 符号链接一律跳过：不跟随、不改名
+      if (dirent.isSymbolicLink()) continue;
+      const abs = path.join(dirAbs, dirent.name);
+      const relative = prefix ? `${prefix}/${dirent.name}` : dirent.name;
+      collected.push({ abs, relative, isDir: dirent.isDirectory(), depth: relative.split('/').length });
+      if (dirent.isDirectory()) await walk(abs, relative, depth + 1);
+    }
+  };
+  await walk(rootAbs, '', 1);
+  return { collected, truncated };
+}
+
+/** 判定单个条目该"还原 / 有损 / 不动" */
+function classifyEntry(entry) {
+  const baseName = path.posix.basename(entry.relative);
+  const verdict = repairName(baseName);
+  if (verdict.repaired) {
+    const parentRelative = path.posix.dirname(entry.relative);
+    const toRelative = parentRelative === '.' ? verdict.name : `${parentRelative}/${verdict.name}`;
+    return { kind: 'candidate', to: toRelative, hex: verdict.hex, reason: verdict.reason };
+  }
+  // 没有转义标记但带 `?` → 引擎当时输出了有损问号，原始字节已丢，救不回来（不猜 GBK）
+  if (!hasEscapeMarker(baseName) && baseName.includes('?')) {
+    return { kind: 'unrecoverable', reason: 'lossy' };
+  }
+  if (verdict.reason) return { kind: 'unrecoverable', reason: verdict.reason };
+  return { kind: 'skip', reason: null };
+}
+
+/**
+ * 扫描（并按需执行）目录内的乱码名还原。
+ * @param {{rootAbs: string}} ctx
+ * @param {{path: string, dryRun?: boolean, maxDepth?: number, maxEntries?: number}} body
+ */
+export async function repairNamesInDirectory(ctx, body) {
+  if (typeof body.path !== 'string' || body.path.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'path 必填');
+  }
+  const dryRun = body.dryRun !== false; // 默认 true：不显式传 false 就不动文件
+  const maxDepth = clampInt(body.maxDepth, DEFAULT_MAX_DEPTH, 1, MAX_DEPTH_LIMIT);
+  const maxEntries = clampInt(body.maxEntries, DEFAULT_MAX_ENTRIES, 1, MAX_ENTRIES_LIMIT);
+
+  const { userPath, realPath } = await resolveRequestPath(ctx, body.path);
+  const stat = await fsp.lstat(realPath).catch(() => null);
+  if (!stat) throw apiError(ERROR_CODES.PATH_NOT_FOUND, '目录不存在', { path: userPath });
+  if (!stat.isDirectory()) throw apiError(ERROR_CODES.VALIDATION_FAILED, '只支持对目录做批量修复', { path: userPath });
+
+  const { collected, truncated } = await collectEntries(realPath, maxDepth, maxEntries);
+  // 从深到浅：先改子项，再改父目录（父目录改名会自动带走已改好的子项）
+  collected.sort((a, b) => b.depth - a.depth);
+
+  const candidates = [];
+  const unrecoverable = [];
+  const conflicts = [];
+
+  for (const entry of collected) {
+    const verdict = classifyEntry(entry);
+    if (verdict.kind === 'unrecoverable') {
+      unrecoverable.push({ path: entry.relative, reason: verdict.reason });
+      continue;
+    }
+    if (verdict.kind !== 'candidate') continue;
+
+    const targetAbs = path.join(realPath, ...verdict.to.split('/'));
+    // 绝不覆盖：目标已存在 → 记冲突并跳过
+    const exists = await fsp.lstat(targetAbs).catch(() => null);
+    if (exists) {
+      conflicts.push({ from: entry.relative, to: verdict.to, reason: 'target-exists' });
+      continue;
+    }
+    candidates.push({ entry, to: verdict.to, hex: verdict.hex, targetAbs });
+  }
+
+  let renamed = 0;
+  if (!dryRun) {
+    for (const candidate of candidates) {
+      try {
+        await fsp.mkdir(path.dirname(candidate.targetAbs), { recursive: true });
+        await fsp.rename(candidate.entry.abs, candidate.targetAbs);
+        renamed += 1;
+      } catch {
+        // 改名失败（权限/竞态）：计入冲突，不影响其他条目
+        conflicts.push({ from: candidate.entry.relative, to: candidate.to, reason: 'rename-failed' });
+      }
+    }
+  }
+
+  return {
+    path: userPath,
+    dryRun,
+    maxDepth,
+    scanned: collected.length,
+    truncated,
+    candidates: candidates.slice(0, REPORT_LIMIT).map((item) => ({ from: item.entry.relative, to: item.to, hex: item.hex })),
+    unrecoverable: unrecoverable.slice(0, REPORT_LIMIT),
+    conflicts: conflicts.slice(0, REPORT_LIMIT),
+    counts: {
+      candidates: candidates.length,
+      unrecoverable: unrecoverable.length,
+      conflicts: conflicts.length,
+      renamed,
+    },
+    renamed,
+  };
+}

package/server/core/fs/roots.js

@@ -0,0 +1,185 @@
+// 存储根发现（docs/16）：平台探测 → 侧栏模式 → 卷/共享列表
+//
+// 心智模型（docs/16 §一）：本项目的「根」不是文件系统 `/`，而是**可配置的存储根**。
+// NAS 用户想的是"照片在哪个共享"，桌面用户想的是"先看卷"——所以两套数据源、同一个形状：
+//   B 模式（非群晖）：卷 / 挂载点（/volume1、/mnt/data）
+//   C 模式（群晖）：  /volumeN 下的共享文件夹（排除 @ / # 开头的系统目录）
+//
+// 所有失败都降级：扫不到就空列表、statfs 失败就容量 null —— 列卷失败绝不能让文件页打不开。
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+
+/** 平台常量（将来加厂商在这里加一个值即可） */
+export const PLATFORMS = Object.freeze({ SYNOLOGY: 'synology', WINDOWS: 'windows', POSIX: 'posix' });
+/** 侧栏模式：B = 列卷（默认）；C = 列共享文件夹（群晖） */
+export const SIDEBAR_MODES = Object.freeze({ VOLUMES: 'B', SHARES: 'C' });
+/** 默认根在列表里的固定 id */
+export const DEFAULT_ROOT_ID = 'default';
+
+/** 群晖特征文件（docs/16 §2.1 实测依据） */
+const SYNOLOGY_MARKER = '/etc/synoinfo.conf';
+/** 群晖系统目录前缀：@appdata / @eaDir / #recycle 等不是共享 */
+const SYSTEM_DIR_PREFIX = /^[@#]/;
+/** B 模式的挂载点形态：/mnt/<name>、/media/<name>（只认一级，不认子目录） */
+const MOUNT_POINT_ONE_LEVEL = /^\/(mnt|media)\/[^/]+$/;
+/** 群晖卷名规则：/volume1 /volume2 ... */
+const SYNOLOGY_VOLUME = /^\/volume\d+$/;
+
+const statfsOf = (target) => fsp.statfs(target);
+const readdirOf = (target) => fsp.readdir(target, { withFileTypes: true });
+
+/**
+ * 平台探测：环境变量覆盖优先（测试必需），其次群晖特征文件，最后按 Node platform 归类。
+ * @param {{env?: object, existsSync?: (p: string) => boolean}} [options]
+ */
+export function detectPlatform({ env = process.env, existsSync = fs.existsSync } = {}) {
+  const forced = env.ZIPCALM_FORCE_PLATFORM;
+  if (forced === PLATFORMS.SYNOLOGY || forced === PLATFORMS.POSIX || forced === PLATFORMS.WINDOWS) return forced;
+  try {
+    if (existsSync(SYNOLOGY_MARKER)) return PLATFORMS.SYNOLOGY;
+  } catch {
+    // 探测失败按"不是群晖"处理：回退 B 模式，不能因为探测异常让整个页面挂掉
+  }
+  if (process.platform === 'win32') return PLATFORMS.WINDOWS;
+  return PLATFORMS.POSIX;
+}
+
+/** 平台 → 侧栏模式（未知/将来厂商：默认 B，绝不白屏） */
+export function sidebarModeOf(platform) {
+  return platform === PLATFORMS.SYNOLOGY ? SIDEBAR_MODES.SHARES : SIDEBAR_MODES.VOLUMES;
+}
+
+/** 容量（statfs）；拿不到就两项都 null —— 契约要求降级不报错 */
+export async function rootStats(absPath) {
+  try {
+    const stat = await statfsOf(absPath);
+    const blockSize = Number(stat.bsize) || 0;
+    const totalBytes = blockSize * (Number(stat.blocks) || 0);
+    const freeBytes = blockSize * (Number(stat.bavail ?? stat.bfree) || 0);
+    if (!(totalBytes > 0)) return { totalBytes: null, freeBytes: null };
+    return { totalBytes, freeBytes };
+  } catch {
+    return { totalBytes: null, freeBytes: null };
+  }
+}
+
+/** 目录里的子目录名（失败返回 []） */
+async function listSubdirs(dirAbs) {
+  try {
+    const dirents = await readdirOf(dirAbs);
+    return dirents.filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name);
+  } catch {
+    return [];
+  }
+}
+
+/** 读 /proc/mounts 的挂载点（Linux）；失败返回 [] */
+async function readMountPoints() {
+  try {
+    const text = await fsp.readFile('/proc/mounts', 'utf8');
+    return text.split('\n')
+      .map((line) => line.split(/\s+/))
+      .filter((fields) => fields.length >= 2)
+      .map((fields) => fields[1].replace(/\\040/g, ' '));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * B 模式：自动发现卷/挂载点。
+ * 规则：/volumeN + /proc/mounts 里的 /mnt|/media 挂载点（去重，按路径排序）。
+ * 为什么不全用 /proc/mounts：容器里它会列出一堆伪文件系统（proc/sysfs/tmpfs），对用户无意义。
+ */
+async function discoverVolumeDirs() {
+  const found = new Set();
+  for (const dirName of await listSubdirs('/')) {
+    if (/^volume\d+$/.test(dirName)) found.add(`/${dirName}`);
+  }
+  // 只认"真正挂载了的"一级目录：/mnt/data、/media/usb 这种。
+  // 不能拿 /mnt/* 的**子目录**当卷 —— 很多机器 /mnt 本身就是一个挂载点，里面全是普通目录（实测踩过）。
+  for (const mountPoint of await readMountPoints()) {
+    if (MOUNT_POINT_ONE_LEVEL.test(mountPoint)) found.add(mountPoint);
+    if (SYNOLOGY_VOLUME.test(mountPoint)) found.add(mountPoint);
+  }
+  return [...found].sort();
+}
+
+/** C 模式：/volumeN 下的共享文件夹（排除 @ / # 系统目录） */
+async function discoverShares() {
+  const volumes = [];
+  for (const dirName of await listSubdirs('/')) {
+    if (/^volume\d+$/.test(dirName)) volumes.push(`/${dirName}`);
+  }
+  const shares = [];
+  for (const volumeAbs of volumes.sort()) {
+    for (const name of await listSubdirs(volumeAbs)) {
+      if (SYSTEM_DIR_PREFIX.test(name)) continue;
+      // 点开头的目录（.pnpm-store / .git / .Trash …）对用户是噪音：
+      // DSM 的共享文件夹本来就不会以点开头，列出来只会让列表变脏。
+      if (name.startsWith('.')) continue;
+      shares.push({ id: name, label: name, path: path.posix.join(volumeAbs, name) });
+    }
+  }
+  return shares;
+}
+
+/**
+ * 构造根列表。
+ * - 配置了 storage.roots → 直接用（两种模式都用它；显式配置优先于自动发现）
+ * - C 模式且没配置 → 扫共享；扫不到任何共享 → 回退列出默认根（避免侧栏空白）
+ * - B 模式且没配置 → 扫卷；扫不到 → 只列默认根
+ * - ZIPCALM_SHOW_APP_ROOT=1 → 任何模式都额外列出默认根（标注「应用数据」）
+ * @param {{storage: object, env?: object}} options
+ */
+export async function listRoots({ storage, env = process.env }) {
+  const platform = detectPlatform({ env });
+  const mode = sidebarModeOf(platform);
+  const configured = Array.isArray(storage.roots) && storage.roots.length > 0
+    ? storage.roots.map((root) => ({ id: root.id, label: root.label || root.id, path: root.path }))
+    : null;
+  const defaultRoot = { id: DEFAULT_ROOT_ID, label: '应用数据', path: storage.root };
+
+  let roots;
+  if (configured) {
+    roots = configured;
+  } else if (mode === SIDEBAR_MODES.SHARES) {
+    const shares = await discoverShares();
+    roots = shares.length > 0 ? shares : [defaultRoot];
+  } else {
+    const volumes = await discoverVolumeDirs();
+    roots = volumes.length > 0
+      ? volumes.map((volumePath) => ({ id: volumePath.replace(/^\/+/, ''), label: path.basename(volumePath), path: volumePath }))
+      : [defaultRoot];
+  }
+
+  // 环境变量开关：把应用存储根也列进来（默认关；群晖上开发/验收时很有用）
+  if (env.ZIPCALM_SHOW_APP_ROOT === '1' && !roots.some((root) => path.resolve(root.path) === path.resolve(defaultRoot.path))) {
+    roots = [...roots, { ...defaultRoot, label: '应用数据（storage.root）' }];
+  }
+
+  const withStats = await Promise.all(roots.map(async (root) => ({ ...root, ...(await rootStats(root.path)) })));
+  return { platform, mode, roots: withStats, canSwitch: withStats.length > 1 };
+}
+
+/**
+ * 按 rootId 取根（幂等；未知 id → VALIDATION_FAILED，绝不静默回落默认根 —— 静默回落会让用户以为切了根）。
+ * @param {{roots: Array<{id: string, path: string}>, rootAbs: string}} fsContext
+ * @param {string|undefined} rootId
+ * @returns {{id: string, absPath: string}}
+ */
+export function resolveRoot(fsContext, rootId) {
+  // 未指定或就是 default：用配置里的 storage.root。
+  // 注意 default **不一定出现在 /fs/volumes 的列表里**（C 模式默认只列共享），但请求必须能用它 ——
+  // 否则"不带 rootId 的请求能工作、带 rootId=default 反而 400"，自相矛盾。
+  if (!rootId || rootId === DEFAULT_ROOT_ID) return { id: DEFAULT_ROOT_ID, absPath: fsContext.rootAbs };
+  const matched = (fsContext.roots || []).find((root) => root.id === rootId);
+  if (!matched) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, `未知的 rootId：${rootId}`, { rootId });
+  }
+  return { id: matched.id, absPath: matched.path };
+}

package/server/core/fs/safePath.js

@@ -0,0 +1,173 @@
+// 路径白名单（M1 的安全红线，对应 docs/M0/不变量清单.md ⭐INV-06）
+//
+// 契约（docs/M0/API规范.md §一）：API 收到的 `path` 一律是「相对存储根的 POSIX 路径」，根为 `/`。
+// 本模块负责把它变成**进程内可用的原生绝对路径**，并保证永远落在存储根之内。
+//
+// 三层防护（缺一不可）：
+//   ① 形态校验：拒绝 null 字节、超长、以及任何 `..` 段（含百分号编码后的 `..`）；
+//   ② 归一化 + 前缀校验：path.resolve(root, ...segments) 后必须 === root 或以 root + 分隔符 开头
+//      —— 必须带分隔符比较，否则 /data-evil 会被 /data 放行（docs/10 §七 记录过的真实缺陷）；
+//   ③ realpath 二次校验：解析符号链接后再比一次，防止 root 内的链接指向 root 之外。
+//
+// 参考实现：docs/10 §二.3 `safePath.ts:35-53`（拆段拒绝 .. + startsWith 校验）、
+//           `cloudcmd/server/root.js:8-18`（越界即 throw）。
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError, toApiError } from '../../lib/errors.js';
+
+/** API 里的根路径写法 */
+export const ROOT_USER_PATH = '/';
+
+/** 安全解码一个路径段（解码失败就按原样处理，不抛错） */
+function decodeSegment(segment) {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+/**
+ * 校验并归一化用户路径（纯函数，不碰文件系统）。
+ * @param {unknown} raw 原始 path 参数
+ * @param {{maxPathLength?: number, maxPathSegmentLength?: number}} [options]
+ *        —— 两个上限都来自配置（server/config/defaults.js 的 limits），不写死
+ * @returns {{userPath: string, segments: string[]}} 归一化后的 API 路径（以 / 开头）
+ */
+export function normalizeUserPath(raw, options = {}) {
+  const maxPathLength = options.maxPathLength || 4096;
+  const maxPathSegmentLength = options.maxPathSegmentLength || 255;
+
+  if (typeof raw !== 'string' || raw.length === 0) {
+    throw apiError(ERROR_CODES.INVALID_PATH, 'path 不能为空');
+  }
+  if (raw.length > maxPathLength) {
+    throw apiError(ERROR_CODES.INVALID_PATH, `path 超过长度上限（${maxPathLength}）`, { length: raw.length });
+  }
+
+  // 统一分隔符：Windows 风格反斜杠按 / 处理，避免 ..\..\ 之类绕过
+  const unified = raw.replace(/\\/g, '/');
+  if (unified.includes('\0')) {
+    throw apiError(ERROR_CODES.INVALID_PATH, 'path 包含非法字符（null 字节）');
+  }
+
+  const segments = unified.split('/').filter((segment) => segment !== '' && segment !== '.');
+
+  for (const segment of segments) {
+    // ① 单段长度上限（可配）：在进入任何磁盘调用**之前**就拦掉，
+    //    否则底层会抛 ENAMETOOLONG，容易冒成 500（真实修复的 bug）。
+    //    用字节数比较：POSIX NAME_MAX 是字节上限，不是字符数（中文目录名一字 3 字节）。
+    const segmentBytes = Buffer.byteLength(segment, 'utf8');
+    if (segmentBytes > maxPathSegmentLength) {
+      throw apiError(ERROR_CODES.INVALID_PATH, `path 单段超过长度上限（${maxPathSegmentLength} 字节）`, {
+        segmentBytes,
+        limit: maxPathSegmentLength,
+      });
+    }
+
+    // ② 明文 ..
+    if (segment === '..') {
+      throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, 'path 不允许包含上级目录引用（..）', { segment });
+    }
+    // ③ 编码形态（%2e%2e / 双重编码）：解一次码后仍可能是 .. 或再次带 .. 的形式
+    const decoded = decodeSegment(segment);
+    if (decoded === segment) continue;
+    if (decoded.includes('\0')) {
+      throw apiError(ERROR_CODES.INVALID_PATH, 'path 包含非法字符（编码后的 null 字节）');
+    }
+    const decodedParts = decoded.split(/[\\/]/);
+    if (decodedParts.includes('..')) {
+      throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, 'path 包含编码后的上级目录引用（..）', { segment, decoded });
+    }
+  }
+
+  return { userPath: `${ROOT_USER_PATH}${segments.join('/')}`, segments };
+}
+
+/**
+ * 把用户路径解析为存储根内的绝对路径（同步、纯计算 + 前缀校验）。
+ * @param {string} rootAbs 存储根（绝对路径）
+ * @param {unknown} raw 用户路径
+ * @param {{maxPathLength?: number}} [options]
+ * @returns {{userPath: string, absPath: string, rootAbs: string}}
+ */
+export function resolveWithinRoot(rootAbs, raw, options = {}) {
+  const root = path.resolve(rootAbs);
+  const { userPath, segments } = normalizeUserPath(raw, options);
+
+  // 关键：用 resolve(root, ...segments)，而不是 resolve(原始输入)——
+  // 绝对路径输入（如 /etc/passwd）已被拆成段，因此只会落在 root 之下，永远不会解析到系统路径。
+  const absPath = path.resolve(root, ...segments);
+
+  // 前缀校验必须带路径分隔符（防止 /data-evil 被 /data 放行）
+  if (absPath !== root && !absPath.startsWith(root + path.sep)) {
+    throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, 'path 超出可访问范围', { userPath, absPath });
+  }
+
+  return { userPath, absPath, rootAbs: root };
+}
+
+/**
+ * 解析符号链接后的二次校验（INV-06 第 9 条）。
+ * @param {string} rootAbs 存储根
+ * @param {string} absPath 已经过 resolveWithinRoot 的绝对路径
+ * @param {{mustExist?: boolean}} [options] mustExist=false 时不存在则原样返回
+ * @returns {Promise<string>} 真实路径（或原路径）
+ */
+export async function assertRealPathWithinRoot(rootAbs, absPath, options = {}) {
+  const mustExist = options.mustExist !== false;
+  const root = path.resolve(rootAbs);
+
+  let realPath;
+  try {
+    realPath = await fs.realpath(absPath);
+  } catch (error) {
+    if (!mustExist && error && error.code === 'ENOENT') return absPath;
+    throw toApiError(error);
+  }
+
+  // root 自身也可能是个符号链接（NAS 上常见），所以两边都取 realpath 再比
+  let realRoot;
+  try {
+    realRoot = await fs.realpath(root);
+  } catch {
+    realRoot = root;
+  }
+
+  if (realPath !== realRoot && !realPath.startsWith(realRoot + path.sep)) {
+    throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, '符号链接指向存储根之外', { absPath, realPath });
+  }
+  return realPath;
+}
+
+/**
+ * 一步到位：用户路径 → 白名单内的真实绝对路径（REST 路由最常用）。
+ * @param {{rootAbs: string, maxPathLength?: number}} ctx
+ * @param {unknown} raw
+ * @param {{mustExist?: boolean}} [options]
+ */
+export async function resolveRequestPath(ctx, raw, options = {}) {
+  const { userPath, absPath } = resolveWithinRoot(ctx.rootAbs, raw, {
+    maxPathLength: ctx.maxPathLength,
+    maxPathSegmentLength: ctx.maxPathSegmentLength,
+  });
+  const realPath = await assertRealPathWithinRoot(ctx.rootAbs, absPath, options);
+  return { userPath, absPath, realPath };
+}
+
+/** 由 API 路径取父路径（根返回 null），供前端面包屑/返回上级 */
+export function parentUserPath(userPath) {
+  if (!userPath || userPath === ROOT_USER_PATH) return null;
+  const parent = path.posix.dirname(userPath);
+  return parent === '.' ? ROOT_USER_PATH : parent;
+}
+
+/** 把绝对路径转回 API 用户路径（绝对路径只允许出现在进程内部） */
+export function toUserPath(rootAbs, absPath) {
+  const root = path.resolve(rootAbs);
+  const relative = path.relative(root, path.resolve(absPath));
+  if (relative === '') return ROOT_USER_PATH;
+  return `/${relative.split(path.sep).join('/')}`;
+}

package/server/core/fs/search.js

@@ -0,0 +1,108 @@
+// 文件名搜索（docs/16 批次②的需求①）：只在**当前根内**按文件名做子串匹配
+//
+// 为什么不做全文索引：这是「找某个文件在哪」的诉求，不是内容检索；索引要持久化、要失效策略、
+// 要吃内存，对一个 NAS 文件管理器属于 YAGNI。这里用**有界遍历**：深度/结果数/耗时三重上限，
+// 超了就把 truncated 置真并返回已有结果 —— 宁可给部分结果，也不能让一次搜索把服务拖住。
+//
+// 安全：不跟随符号链接（越界链接一律不进入）；跳过黑名单目录（如 @eaDir，避免翻元数据目录）。
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+
+/** 搜索边界（写死，不做成配置：这是"防止一次搜索拖垮服务"的保护，不是业务策略） */
+export const SEARCH_LIMITS = Object.freeze({
+  maxDepth: 6,
+  maxResults: 500,
+  timeoutMs: 3000,
+  /** 单目录最多读多少项，避免超大目录把一次 readdir 拖很久 */
+  maxEntriesPerDir: 5000,
+});
+
+/** 目录名是否属于"不搜"的（黑名单目录规则 + 点开头系统目录） */
+function isSkippedDir(name, layers) {
+  if (name.startsWith('.')) return true;
+  if (!Array.isArray(layers) || layers.length === 0) return false;
+  // 复用黑名单的目录名匹配（@eaDir 这类），但只对目录名，不误伤普通文件
+  return layers.some((layer) => (layer.patterns || []).some((pattern) => pattern === name));
+}
+
+/**
+ * 在 rootAbs 内按文件名子串搜索。
+ * @param {{rootAbs: string, userPath?: string}} ctx 当前根与搜索起点（用户路径，缺省根）
+ * @param {string} query 关键字（非空；大小写不敏感）
+ * @param {{limit?: number, layers?: Array}} [options]
+ * @returns {Promise<{items: Array, truncated: boolean, scannedDirs: number, elapsedMs: number}>}
+ */
+export async function searchFiles(ctx, query, options = {}) {
+  const keyword = String(query || '').trim().toLowerCase();
+  if (keyword.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'q 不能为空');
+  }
+  const limit = Math.min(SEARCH_LIMITS.maxResults, Math.max(1, Number(options.limit) || 100));
+  const rootAbs = ctx.rootAbs;
+  const startAbs = options.startAbs || rootAbs;
+  const startedAt = Date.now();
+  const items = [];
+  let scannedDirs = 0;
+  let truncated = false;
+
+  /** 时间预算耗尽就停（哪怕还没扫完） */
+  const budgetExceeded = () => Date.now() - startedAt > SEARCH_LIMITS.timeoutMs;
+
+  async function walk(dirAbs, depth) {
+    if (truncated || budgetExceeded() || items.length >= limit) {
+      truncated = true;
+      return;
+    }
+    scannedDirs += 1;
+    let dirents;
+    try {
+      dirents = await fsp.readdir(dirAbs, { withFileTypes: true });
+    } catch {
+      return; // 不可读的子树直接跳过（不打断整次搜索）
+    }
+    if (dirents.length > SEARCH_LIMITS.maxEntriesPerDir) {
+      dirents = dirents.slice(0, SEARCH_LIMITS.maxEntriesPerDir);
+      truncated = true;
+    }
+    for (const dirent of dirents) {
+      if (truncated || budgetExceeded() || items.length >= limit) {
+        truncated = true;
+        return;
+      }
+      if (dirent.isSymbolicLink()) continue; // 不跟随：越界链接不该被搜索"带进来"
+      const childAbs = path.join(dirAbs, dirent.name);
+      if (dirent.isDirectory()) {
+        // 目录也参与匹配（用户搜"照片在哪"时，目录名往往就是答案），但匹配后仍继续往下走
+        if (dirent.name.toLowerCase().includes(keyword)) {
+          items.push(await describeEntry(childAbs, rootAbs, 'dir'));
+        }
+        if (depth + 1 > SEARCH_LIMITS.maxDepth) continue;
+        if (isSkippedDir(dirent.name, options.layers)) continue;
+        await walk(childAbs, depth + 1);
+        continue;
+      }
+      if (!dirent.isFile()) continue;
+      if (!dirent.name.toLowerCase().includes(keyword)) continue;
+      items.push(await describeEntry(childAbs, rootAbs, 'file'));
+    }
+  }
+
+  await walk(startAbs, 0);
+  return { items, truncated, scannedDirs, elapsedMs: Date.now() - startedAt };
+}
+
+/** 单个命中项：只回传用户路径，**不带 absPath**（契约红线） */
+async function describeEntry(absPath, rootAbs, entryType) {
+  const stat = await fsp.lstat(absPath).catch(() => null);
+  const userPath = `/${path.relative(rootAbs, absPath).split(path.sep).join('/')}`;
+  return {
+    path: userPath,
+    name: path.basename(absPath),
+    type: entryType,
+    size: stat ? stat.size : 0,
+    mtime: stat ? Math.trunc(stat.mtimeMs) : 0,
+  };
+}