DSH Bug 反馈:会话日志迁移在 exFAT 等"无硬链接"文件系统上失败(ENOTSUP);且迁移会就地改写数据文件导致无法回滚

[061026liuchen-create]

Summary

把 DSH_HOME 放在 exFAT 移动硬盘上(便携盘 / 多设备共用数据的常见做法)后,升级到 0.1.5-rc.1:

1. 恢复任何旧会话都会失败,报 ENOTSUP: operation not supported on socket;
2. 该版本还会就地改写其他数据文件(如 .credentials.yaml),由于写文件是"临时文件 + 改名",
   会把 DSH_HOME 里的符号链接替换成真实文件;于是回滚到 0.1.0-rc.6 后 dsh 直接无法启动。

同机、同数据、同一份会话日志下,0.1.0-rc.6 一切正常 —— 说明是 0.1.5 新增的迁移逻辑引入的回归。
影响:数据目录放在此类文件系统上的用户,既升不上去、也退不回来。

Reproduction

1. 将 DSH_HOME 放在 exFAT 卷上(例如移动 SSD;FAT32、多数网络盘与 FUSE 挂载同样无硬链接);
2. 该目录下已存在旧格式的会话日志;
3. 升级 dsh 到 0.1.5-rc.1(macOS,Apple Silicon);
4. 在界面里打开/恢复任一旧会话(触发 v2 → v3 日志迁移)。

Current behavior

① 会话迁移失败:

resume failed for session "session-<id>": Error: ENOTSUP: operation not supported on socket,
link '/Users/<user>/.dsh/sessions/--<projKey>--/session-<id>/session.migration.<token>.jsonl.zstd.tmp'
  -> '/Users/<user>/.dsh/sessions/--<projKey>--/session-<id>/session.v3.jsonl.zstd' (gateway/internal)

补充观察:临时文件 .migration.*.tmp 已成功写出,失败发生在发布(publish)这一步;
失败后盘上没有残留脏文件,原有会话文件完好(逐帧 zstd 校验通过)。

② 回滚后无法启动(迁移不可逆):

Error: dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include):
failed to apply loader entry credentials (@deepseek-ai/dsh-credentials-local):
credentials-local: the value for "version" in /Users/<user>/.dsh/.credentials.yaml must be a string

原因:0.1.0-rc.6 的 parseCredentialsDocument() 要求该文件是扁平的「名字 → 非空字符串」映射,
遇到迁移写出的 version(非字符串)/嵌套结构会直接抛 TypeError 并中止整个插件树加载。
而 0.1.5 的迁移已经把这个文件改写成新格式,回滚 runtime 并不会还原数据文件 —— 用户被卡死。

Expected behavior

1. 在"不支持硬链接"的文件系统上应能正常完成迁移与恢复(例如把发布方式回退为同目录 rename,
   rename 在 exFAT 上可用且原子);若确实无法支持,至少给出明确提示
   ("当前文件系统不支持硬链接,会话日志迁移不可用"),而不是包装成 resume failed。
2. 数据格式迁移应可回滚:迁移前保留旧格式备份,或新版保持对旧格式的读取兼容。
3. 写入时若目标路径是符号链接,应写穿到目标本身,而不是用改名把链接替换成真实文件
   (便携盘方案正是"DSH_HOME = 指向数据目录的链接集合",这一行为会直接破坏该结构)。

Environment

• dsh:0.1.5-rc.1(失败)/ 0.1.0-rc.6(同机同数据,正常)

• OS:macOS(Apple Silicon,M 系列)

• 文件系统:exFAT(移动 SSD;同问题也适用于 FAT32、多数网络盘/NFS/SMB、FUSE 挂载)

• 代码定位:@deepseek-ai/dsh-session-persistence-jsonl/lib/index.js → publishCurrentExclusive()

  async function publishCurrentExclusive(staged, currentPath, internals) {
    if (internals.platform === "win32") try {
      await internals.publishNewWin32(staged, currentPath);
      return true;
    } catch (error) { if (isEEXIST(error)) return false; throw error; }
  
    try {
      await internals.fs.link(staged, currentPath);   // ← POSIX/macOS:硬链接
    } catch (error) {
      if (isEEXIST(error)) return false;              // ← 只容忍 EEXIST
      throw error;                                    // ← ENOTSUP 直接抛出 → 迁移中断
    }
    await syncDirectory(dirname(currentPath), internals);
    return true;
  }

  版本对照:dsh-session-persistence-jsonl@0.1.0-rc.6 中不存在 .migration. / publishCurrentExclusive / fs.link(;
  0.1.5-rc.1 三者俱全。凭据侧的解析要求见 dsh-credentials-local/lib/index.js 的 parseCredentialsDocument()。

• 建议修法:

  1. 把"硬链接不可用"当作能力而非错误:ENOTSUP/EPERM/EACCES/EXDEV 时回退为同目录 rename 发布
     (必要时先做目标存在性检查)。
  2. 启动时在数据目录做一次能力探测(试建一个硬链接并缓存结果),据此选择发布策略并输出清晰日志。
  3. 迁移前为将被改写的文件生成 <file>.bak-v<旧版本>;或保持旧格式可读,避免"升了就不能退"。
  4. 写文件时检测符号链接并写穿到目标,不要用 rename 替换链接本身。

[argszero]

感谢这份报告 —— 三条现象描述我都能在源码里逐行对上。但对照源码后，你贴的四条建议里有两条与仓库自身的既有契约/同文件另一处实现相冲突，另有一条机制归因需要修正。逐条给证据。

① 你的 publishCurrentExclusive 定位正确，而且范围比你报告的更大

src/generation.ts:828-835 与你贴的构建产物一致：只容忍 EEXIST，其余 errno（含 ENOTSUP）原样抛出。补充两点：

• 同一个包里还有第二处 fs.link() 依赖，而且它的注释把设计意图写得最清楚 —— src/index.ts:1132-1134：

  // Publish via link()+unlink(), NOT rename(): link fails with EEXIST if the // final path already exists, so two processes materializing the same id // concurrently cannot clobber each other. rename() would silently overwrite.

  即：link() 在这里不是"实现细节"，它就是并发保护的载体。

• 更关键的是这条路径的触发面：materialize（index.ts:1098-1113）是惰性首写路径 —— 新会话的第一次 append（:818）和空会话创建（:831）都要走它。所以在没有硬链接的卷上，不只是"旧会话迁移失败"，任何新会话的第一次落盘都会失败。你症状里"恢复旧会话"只是最快撞上的那条。

② ★ Windows 分支已经给出了答案 —— 它从不依赖硬链接

publishCurrentExclusive 的 win32 分支走 publishNewWin32，实现在 src/win32.ts:134-138：

moveFileExW(toNamespacedPath(existing), toNamespacedPath(replacement), MOVEFILE_WRITE_THROUGH)

不带 MOVEFILE_REPLACE_EXISTING。目标已存在时 Win32 返回 ERROR_FILE_EXISTS，由本文件自己的 errnoCode()（win32.ts:80-82）映射成 EEXIST ⇒ 于是 publishCurrentExclusive 得到它认识的那个错误码，返回 false 走冲突比对路径。

也就是说：仓库里已经存在一个 no-clobber、原子、且完全不需要硬链接的发布原语（MoveFileExW 无 REPLACE_EXISTING 在 FAT/exFAT 上同样可用）。所以"在 exFAT 上做不到 no-clobber"这个前提不成立 —— 缺的只是把它接到 POSIX 分支。

由此，你建议 1 里"必要时先做目标存在性检查（再 rename）"这一步是多余且有害的：

• rename 本身就是原子的存在性检查；"先查再改"把原子性换成了 TOCTOU 窗口；
• POSIX rename 目标存在时静默覆盖 ⇒ 丢掉的恰好是上面 :1132-1134 声明要保的并发保护。

而注释里 /* v8 ignore else -- a non-collision filesystem error propagates unchanged. */（:831）是覆盖率标注，不是 dead code；构建产物 lib/index.js:827 的 internals.platform === 'win32' 是活分支。

③ ★ 你的建议 4（写穿符号链接）与仓库契约正相反

packages/util/atomic-write/src/index.ts:65-69 逐字：

* at the temp path, and the fresh inode carries options.mode through the * rename, so replacing a wider-permission file narrows it without a chmod * race. The rename also replaces a symlinked target itself instead of writing * through to its referent, and the same-directory sibling keeps the rename on * one filesystem.

再加 :86-88：temp 以 wx 打开（flag: 'wx'）—— 目的是拒绝跟随一个被预埋在 temp 路径上的符号链接。

这是安全设计而不是疏漏：若写入原语"写穿到目标"，一名能在数据目录里放置链接的攻击者就能把 ~/.dsh 的写入引导到任意位置。而 credentials-local/src/index.ts 用的是同一个 writeFileAtomic（见下）⇒ 你建议的这条改法会把凭据写入变成可被链接重定向。

你要的"便携盘 = DSH_HOME 指向真身的链接集合"这个用法，正解是显式配置数据目录指向真身，而不是让写入原语悄悄跟随链接。会话侧更直接：src/index.ts:860-863 每次读/写前 lstat(currentPath)，是符号链接就抛 target is a symbolic link ⇒ 写穿会让新写入的日志在此后的读路径上全部被拒。

④ "迁移不可逆"的归因需要修正（结论方向对，机制不对）

归因正确的部分：迁移确实会就地改写 .credentials.yaml —— credentials-local/src/index.ts:820 if (renderFlatLayoutMigration(text) !== undefined) text = await this.migrateFlatDocument() → :848 await writeFileAtomic(this.spec.filename, migrated, { mode: 0o600, dirMode: 0o700 })（:812 先 assertOwnerOnly）。你日志里那个 must be a string 是旧版 runtime 当时的解析器报的：rc.6（你成功的那个版本）与 0.1.5 的当前解析器都已是结构化文档 —— 缺 version 报 "pre-release flat layout"（:208-211），version 不匹配报具体值（:215-218）。

但"就地改写导致无法回滚"这个因果链要拆开：

• 这段「平面 → 版本化」升级的注释 :833-834 明写 "Remove with the pre-release stance at the first tagged release." ⇒ 它是既有的预发布期一次性升级，不是 0.1.5 新引入的；0.1.5-rc 新增的是日志迁移，顺带触发了它。
• v3 发布并不会让 v2 消失：format.ts:57 generationLogFilename(version, compression) 按版本号命名世代并让它们共存（v0 保留原名，之后带 vN），我从代码里也没找到删除源世代的步骤。会话侧失败后"盘上无残留脏文件、原文件完好"正是 publishPreparedMigration 的 catch（generation.ts:934-937 removeTemporary）。
• 所以升级后起不来，原因是 rc.6 那个 runtime 读不动已被改写的凭据文档（数据面跨版本兼容性缺失），而不是"迁移把会话日志改坏了"。⇒ 你说的"回滚数据文件"就是对的方向，但机制应表述为迁移的数据面不具备跨版本兼容。

⑤ 建议 2（启动能力探测）我同意，但降级判据必须收窄

仓库内部其实已经意识到这件事，packages/fs/fs-local/src/fsio.ts:496-497 逐字：

* Link errno values vary by platform and filesystem. Inspect the target entry after failure so a collision is not confused with missing hard-link support.

只是没做"该 FS 根本没有硬链接"这一档降级。另外 util/atomic-write/src/index.ts:70-72 已有 Windows 瞬时 EACCES/EBUSY/EPERM 有界重试的先例。

启动探测可以留作日志/诊断，但降级判据必须逐个 errno 白名单（ENOTSUP / EOPNOTSUPP / ENOSYS / EPERM / EACCES），并且显式排除 EEXIST —— 一旦把 EEXIST 也当成"不支持链接"，就把并发保护变成了静默覆盖。macOS 上 ENOTSUP 与 EOPNOTSUPP 是同一个值，两个都列不亏。

⑥ 家族与落点

这个家族我这边已归档三例：#3577（Windows 同目录 rename 报 EXDEV）、#5432（HarmonyOS hmdfs 上 materializePosix 的 link() 报 EPERM，无硬链接则全量阻断）、#5704（fs-local 的 .tmpdir + link() 在 exFAT 上报 EISDIR，errno 被误译）。你这帖是第四例，并且补上了两块新拼图：迁移路径的触发 与 错误被归类成 resume failed（实际上 isErrnoException 判定在 generationFailure index.ts:682 会把 errno 原样上抛，所以文案归因在更外层）。

落点如实说：fs.link 依赖与默认 internals 都是 generation.ts:212-228 的包内常量；session-persistence-jsonl 是按 id 装配的后端（packages/bundle/base/cordis.patch.yml:110-111），替换它等于替换整个持久化后端 —— 所以这属于 core 修复，不是插件能挂载的面，我没有做插件形态的方案。

如果你愿意，我可以把这份对照整理成 PR 级 diff（POSIX 分支降级到"Win32 原语等价物 / 同目录 no-replace 发布 + EEXIST 显式排除 + 不动 atomic-write 的链接语义"）供 maintainer 取用。

⑦ 边界

全部结论基于 c291e7961a（= tag dsh-v0.1.5-rc.2）读源码与注释原文；我没有 exFAT 卷可以复现，因此 errno 与失败行为以你的实测为证据，我给出的是机械的源码断言（行号、谓词、注释逐字）。你标题写的是 rc.1，源码树是 rc.2 —— 上述几处两版一致。