zipcalm 0.0.0-stage → 1.0.2

package/server/core/fs/platformProfile.js

@@ -0,0 +1,167 @@
+// 平台画像：系统判断 + 侧栏模式 + 显示文案 + 根发现策略的**唯一入口**
+//
+// 为什么单独抽一个文件：这三件事原本散在四处知识里 ——
+//   ① roots.js 的两个枚举（PLATFORMS / SIDEBAR_MODES）
+//   ② roots.js 的 detectPlatform()（群晖特征文件常量也在这里）
+//   ③ roots.js 的 sidebarModeOf() 与 listRoots() 里的 if/else（决定根从哪来）
+//   ④ 前端 Sidebar.vue 里写死的「模式 → 标题」映射
+// 结果是「同一台机器该显示什么」由四处各自回答，加一个平台要改四个地方，必然漂移。
+//
+// 收敛后的规则：任何「这是什么系统 → 侧栏怎么显示 → 根从哪来」的判断，
+// **只允许**由 resolvePlatformProfile() 回答；其余模块（含前端）只消费它的返回值。
+//
+// 分工（识别层 / 表现层）：
+//   - **识别层**由 `sys-id` 提供（它判断"这是什么系统"，返回大写身份如 Synology / Linux）；
+//   - **表现层**（身份 → 侧栏模式 / 标题 / 根发现策略）是本项目的资产，留在下面的画像表里。
+// 换识别实现只动 detectPlatform 内部，画像表与所有调用方不变。
+
+import fs from 'node:fs';
+
+import { detectPlatform as detectSysIdPlatform } from 'sys-id';
+
+/** 平台常量（将来接入独立探测包时，这张表由包的规则数据取代） */
+export const PLATFORMS = Object.freeze({ SYNOLOGY: 'synology', WINDOWS: 'windows', POSIX: 'posix' });
+
+/** 侧栏模式：B = 列卷（默认）；C = 列共享文件夹（群晖） */
+export const SIDEBAR_MODES = Object.freeze({ VOLUMES: 'B', SHARES: 'C' });
+
+/** 群晖特征文件（docs/16 §2.1 实测依据） */
+const SYNOLOGY_MARKER = '/etc/synoinfo.conf'; // dsh-skip-sensitive
+
+/** 系统目录前缀：@appdata / @eaDir / #recycle 等不是用户数据目录 */
+const DEFAULT_SYSTEM_DIR_PREFIXES = Object.freeze(['@', '#']);
+
+/**
+ * 平台画像表：一个平台一行，决定它在界面上长什么样、根从哪来。
+ *
+ * 每个字段的用途：
+ *   mode              侧栏模式（B = 卷 / C = 共享）
+ *   volumeLabel       侧栏标题 —— 由后端下发，前端不再自己判断
+ *   rootsStrategy     根发现策略：`shares` 扫共享 / `volumes` 扫卷与挂载点
+ *   systemDirPrefixes 扫描时要排除的系统目录前缀
+ *   volumePattern     卷目录名的匹配规则
+ *
+ * 加平台 = 在这张表加一行 + 在 PLATFORMS 加一个值（等独立包接入后，连这一步都省掉）。
+ */
+export const PLATFORM_PROFILE = Object.freeze({
+  [PLATFORMS.SYNOLOGY]: Object.freeze({
+    mode: SIDEBAR_MODES.SHARES,
+    volumeLabel: '位置',
+    rootsStrategy: 'shares',
+    systemDirPrefixes: DEFAULT_SYSTEM_DIR_PREFIXES,
+    volumePattern: /^\/volume\d+$/,
+  }),
+  [PLATFORMS.WINDOWS]: Object.freeze({
+    mode: SIDEBAR_MODES.VOLUMES,
+    volumeLabel: '存储卷',
+    rootsStrategy: 'volumes',
+    systemDirPrefixes: DEFAULT_SYSTEM_DIR_PREFIXES,
+    volumePattern: /^\/volume\d+$/,
+  }),
+  [PLATFORMS.POSIX]: Object.freeze({
+    mode: SIDEBAR_MODES.VOLUMES,
+    volumeLabel: '存储卷',
+    rootsStrategy: 'volumes',
+    systemDirPrefixes: DEFAULT_SYSTEM_DIR_PREFIXES,
+    volumePattern: /^\/volume\d+$/,
+  }),
+});
+
+/** 未知平台一律回落 POSIX 画像：宁可显示成普通 Linux，也不能白屏 */
+const FALLBACK_PROFILE = PLATFORM_PROFILE[PLATFORMS.POSIX];
+
+/**
+ * 本项目小写强制值 → sys-id 身份（大写）。
+ * `posix` 落到 `Linux` 身份：本项目用它表示「非群晖、非 Windows」的通用表现。
+ */
+const FORCE_ENV_TO_IDENTITY = Object.freeze({
+  [PLATFORMS.SYNOLOGY]: 'Synology',
+  [PLATFORMS.WINDOWS]: 'Windows',
+  [PLATFORMS.POSIX]: 'Linux',
+});
+
+/**
+ * sys-id 身份 → 本项目枚举。
+ * 只有群晖与 Windows 需要区别对待；其余身份（Linux/macOS/fnOS/Unknown/未来新增）都是 posix。
+ */
+const IDENTITY_TO_PLATFORM = Object.freeze({
+  Synology: PLATFORMS.SYNOLOGY,
+  Windows: PLATFORMS.WINDOWS,
+});
+
+/**
+ * 平台探测：把识别工作交给 sys-id，本文件只维护「身份 → 本项目枚举」的映射。
+ *
+ * 三条与既有契约相关的处理（都不能省）：
+ *   1. 身份大写、本项目枚举小写 —— 只有 Synology / Windows 有专属枚举，
+ *      其余身份（Linux / macOS / fnOS / Unknown / 将来新增的平台）一律落到 posix，
+ *      因为界面只需要区分「群晖（列共享）/ Windows / 其他（列卷）」三种表现；
+ *   2. 强制值方向相反 —— 本项目环境变量是小写，sys-id 的 force 要大写身份，
+ *      `posix` 对应 sys-id 的 `Linux` 身份；不在映射表里的值**不传 force**，走正常探测；
+ *   3. sys-id 对非法 force 会抛错，而本项目既有契约是「非法强制值回落真实探测、不抛错」，
+ *      所以必须 try/catch 兜住。
+ *
+ * 保留最后一层本地兜底：sys-id 自身异常（规则目录缺失等）时不能让整个页面挂掉。
+ *
+ * @param {{env?: object, existsSync?: (p: string) => boolean}} [options]
+ */
+export function detectPlatform({ env = process.env, existsSync = fs.existsSync } = {}) {
+  const forced = env.ZIPCALM_FORCE_PLATFORM;
+  const forcedIdentity = FORCE_ENV_TO_IDENTITY[forced];
+  // sys-id 返回 { <身份>: {...} }，识别场景下只有一个键
+  const identify = (force) => Object.keys(detectSysIdPlatform([], {
+    env,
+    existsSync,
+    ...(force ? { force } : {}),
+  }))[0];
+
+  try {
+    return IDENTITY_TO_PLATFORM[identify(forcedIdentity)] || PLATFORMS.POSIX;
+  } catch {
+    // 强制值不可用（sys-id 认为非法）或识别过程出错：**不抛错**，按无 force 重探一次
+    try {
+      return IDENTITY_TO_PLATFORM[identify(undefined)] || PLATFORMS.POSIX;
+    } catch {
+      return detectPlatformLocally(existsSync);
+    }
+  }
+}
+
+/** 最后兜底：sys-id 完全不可用时的最小识别（保证不抛错、不白屏） */
+function detectPlatformLocally(existsSync) {
+  try {
+    if (existsSync(SYNOLOGY_MARKER)) return PLATFORMS.SYNOLOGY;
+  } catch {
+    // 探测失败按「不是群晖」处理
+  }
+  return process.platform === 'win32' ? PLATFORMS.WINDOWS : PLATFORMS.POSIX;
+}
+
+/**
+ * 平台 → 侧栏模式。
+ * 保留这个导出是为了不破坏既有调用方；**内部已改走画像表**，不再单独写一遍判断。
+ */
+export function sidebarModeOf(platform) {
+  return (PLATFORM_PROFILE[platform] || FALLBACK_PROFILE).mode;
+}
+
+/**
+ * **唯一入口**：一次给出「平台 + 该平台在界面上的一切表现」。
+ *
+ * 调用方拿到后不要再自己判断平台 —— 需要什么字段就用返回体里的：
+ *   const { platform, mode, volumeLabel, rootsStrategy, systemDirPrefixes, volumePattern } = resolvePlatformProfile();
+ *
+ * @param {{env?: object, existsSync?: (p: string) => boolean}} [options]
+ */
+export function resolvePlatformProfile({ env = process.env, existsSync = fs.existsSync } = {}) {
+  const platform = detectPlatform({ env, existsSync });
+  const profile = PLATFORM_PROFILE[platform] || FALLBACK_PROFILE;
+  return {
+    platform,
+    mode: profile.mode,
+    volumeLabel: profile.volumeLabel,
+    rootsStrategy: profile.rootsStrategy,
+    systemDirPrefixes: profile.systemDirPrefixes,
+    volumePattern: profile.volumePattern,
+  };
+}

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,178 @@
+// 存储根发现（docs/16）：按平台画像决定根从哪来
+//
+// 心智模型（docs/16 §一）：本项目的「根」不是文件系统 `/`，而是**可配置的存储根**。
+// NAS 用户想的是"照片在哪个共享"，桌面用户想的是"先看卷"——所以两套数据源、同一个形状：
+//   B 模式（非群晖）：卷 / 挂载点（/volume1、/mnt/data）
+//   C 模式（群晖）：  /volumeN 下的共享文件夹（排除 @ / # 开头的系统目录）
+//
+// **平台判断不在本文件**：`PLATFORMS` / `SIDEBAR_MODES` / `detectPlatform` / `sidebarModeOf`
+// 全部由 `platformProfile.js` 提供（本文件只做 re-export 兼容既有调用方）。
+// 本文件只负责「拿到画像后怎么扫根」。
+//
+// 所有失败都降级：扫不到就空列表、statfs 失败就容量 null —— 列卷失败绝不能让文件页打不开。
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+import {
+  PLATFORMS,
+  SIDEBAR_MODES,
+  detectPlatform,
+  resolvePlatformProfile,
+  sidebarModeOf,
+} from './platformProfile.js';
+
+// 兼容导出：既有调用方/测试脚本仍从 roots.js 取这些名字，签名与语义保持不变
+export { PLATFORMS, SIDEBAR_MODES, detectPlatform, sidebarModeOf };
+
+/** 默认根在列表里的固定 id */
+export const DEFAULT_ROOT_ID = 'default';
+
+/** B 模式的挂载点形态：/mnt/<name>、/media/<name>（只认一级，不认子目录） */
+const MOUNT_POINT_ONE_LEVEL = /^\/(mnt|media)\/[^/]+$/;
+
+const statfsOf = (target) => fsp.statfs(target);
+const readdirOf = (target) => fsp.readdir(target, { withFileTypes: true });
+
+/** 容量（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 [];
+  }
+}
+
+/** 顶层卷目录（/volumeN）—— 匹配规则由画像表提供，避免本文件另写一份 */
+async function listVolumeRoots(profile) {
+  const found = [];
+  for (const dirName of await listSubdirs('/')) {
+    const absPath = `/${dirName}`;
+    if (profile.volumePattern.test(absPath)) found.push(absPath);
+  }
+  return found.sort();
+}
+
+/**
+ * B 模式：自动发现卷/挂载点。
+ * 规则：画像表认可的 /volumeN + /proc/mounts 里的 /mnt|/media 挂载点（去重，按路径排序）。
+ * 为什么不全用 /proc/mounts：容器里它会列出一堆伪文件系统（proc/sysfs/tmpfs），对用户无意义。
+ */
+async function discoverVolumeDirs(profile) {
+  const found = new Set(await listVolumeRoots(profile));
+  // 只认"真正挂载了的"一级目录：/mnt/data、/media/usb 这种。
+  // 不能拿 /mnt/* 的**子目录**当卷 —— 很多机器 /mnt 本身就是一个挂载点，里面全是普通目录（实测踩过）。
+  for (const mountPoint of await readMountPoints()) {
+    if (MOUNT_POINT_ONE_LEVEL.test(mountPoint)) found.add(mountPoint);
+    if (profile.volumePattern.test(mountPoint)) found.add(mountPoint);
+  }
+  return [...found].sort();
+}
+
+/** C 模式：/volumeN 下的共享文件夹（排除画像表里的系统目录前缀，以及点开头的噪音目录） */
+async function discoverShares(profile) {
+  const shares = [];
+  for (const volumeAbs of await listVolumeRoots(profile)) {
+    for (const name of await listSubdirs(volumeAbs)) {
+      if (profile.systemDirPrefixes.some((prefix) => name.startsWith(prefix))) 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 → 直接用（两种模式都用它；显式配置优先于自动发现）
+ * - rootsStrategy=shares 且没配置 → 扫共享；扫不到任何共享 → 回退列出默认根（避免侧栏空白）
+ * - rootsStrategy=volumes 且没配置 → 扫卷；扫不到 → 只列默认根
+ * - ZIPCALM_SHOW_APP_ROOT=1 → 任何模式都额外列出默认根（标注「应用数据」）
+ *
+ * 返回体除根列表外还带 `volumeLabel`（侧栏标题由后端下发，前端不再自己判断平台）。
+ * @param {{storage: object, env?: object}} options
+ */
+export async function listRoots({ storage, env = process.env }) {
+  const profile = resolvePlatformProfile({ env });
+  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 (profile.rootsStrategy === 'shares') {
+    const shares = await discoverShares(profile);
+    roots = shares.length > 0 ? shares : [defaultRoot];
+  } else {
+    const volumes = await discoverVolumeDirs(profile);
+    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: profile.platform,
+    mode: profile.mode,
+    // 侧栏标题的唯一来源：平台画像 → 后端下发 → 前端只渲染
+    volumeLabel: profile.volumeLabel,
+    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('/')}`;
+}