pi-webdav-backup 1.3.2 → 1.4.0

package/README.md

@@ -442,10 +442,13 @@ node "$env:USERPROFILE\.pi\agent\extensions\webdav-backup\cli.mjs" install-cron
 新电脑往往已经装过一些插件——可能和备份里同名但版本不同，也可能多装了备份里没有的。
 直接覆盖会**把同名插件降级、把本机多装的声明抹掉、留下版本混合的“缝合”目录**。所以写回有两种模式：
 
-| 模式 | settings.json 的 packages | 本机已装的插件实现 | 本机多装的插件 |
-|---|---|---|---|
-| **合并**（默认，推荐） | 本机声明优先，追加备份里本机没有的 | **保留本机版本**，不覆盖 | 保留（声明与代码都留） |
-| 替换（旧机原样） | 完全用备份版 | 被备份覆盖（同名降级） | 声明被移除（代码不删） |
+| 模式 | settings.json 的 packages | npm/package.json 的 dependencies | 本机已装的插件实现 | 本机多装的插件 |
+|---|---|---|---|---|
+| **合并**（默认，推荐） | 本机声明优先，追加备份里本机没有的 | 本机依赖优先，追加备份里本机没有的 | **保留本机版本**，不覆盖 | 保留（声明与代码都留） |
+| 替换（旧机原样） | 完全用备份版 | 完全用备份版 | 被备份覆盖（同名降级） | 声明被移除（代码不删） |
+
+> **为何要合并 `npm/package.json`**：pi 启动时会拿它与 `node_modules` 做协调（npm install）。
+> 若直接覆盖成备份版，本机独有的插件会被 npm 当成多余包【卸载】。所以合并模式会保留本机已有依赖。
 
 - 交互式 `/backup restore`：本机有插件声明时会先让你选（默认合并）
 - 命令行：`--mode merge`（默认）/ `--mode replace`
@@ -633,6 +636,8 @@ node extensions/webdav-backup/verify-load.mjs
 
 | 版本 | 内容 |
 |---|---|
+| **v1.4.0** | **跨平台健壮性**：① 合并/恢复时**过滤旧机器专属的绝对路径本地源**（`E:\...`、`/home/...`、UNC）——`pi install /绝对/路径` 会把路径写进 settings.json，跨机恢复时无效，现在不再带入目标机；② WebDAV 客户端对 **423 Locked / 429 / 5xx 与网络抖动自动重试**（指数退避，尊重 `Retry-After`，上限 4 次），修复实测中两个实例并发上传导致的 423 直接失败；新增 `test-webdav.mjs`（故障注入）与跨平台路径回归用例 |
+| **v1.3.3** | **修复合并模式会卸载本机插件**：`restore-apply` 合并模式此前只合并 `settings.json`，却用备份版**覆盖** `npm/package.json`——pi 下次启动的 npm 协调会把本机独有插件当成多余包卸载（实测于 Windows→Linux 同步）。现改为同时合并 `npm/package.json` 的 `dependencies`（本机优先），结果里标 `npm-dependencies`。另：文档补充「多机同步」与「跨平台密钥」流程 |
 | **v1.3.2** | **跨平台多机同步**：依赖体检修正（npm 提升到父级的依赖不再误报为缺失，按 Node 模块解析算法沿祖先 `node_modules` 查找）；文档新增「跨平台密钥（多机同步）」与「多机同步（Windows ↔ Linux）」流程，明确多机用 `file:` / `$ENV` 而非 `dpapi:`，并给出常见坑 |
 | **v1.3.1** | 依赖体检误报修正（npm 提升的依赖被当成缺失） |
 | **v1.3.0** | **换机一键还原**：新增 `includePlugins`（把插件实现 `node_modules` 一并备份，重机恢复即可直接用，无需联网重装）；新增 `restore-apply` / `/backup restore-apply`（把恢复结果写回当前 `~/.pi/agent`，覆盖前备份、幂等、防止 `__REDACTED__` 覆盖真值）；**写回默认【合并模式】**：本机已装插件保留不被覆盖、`settings.json` 只合并 `packages`（避免删掉/降级本机插件），可选 `--mode replace` 完全还原；`/backup restore` 默认询问是否写回当前 pi，已含插件时不再提示联网补装；`/backup-setup` 向导新增插件代码选项；脱敏审计跳过第三方插件代码（避免误报）；排除规则重构（`includePlugins` 开关控制 node_modules） |
@@ -658,7 +663,9 @@ node extensions/webdav-backup/verify-load.mjs
 | 想立刻看到日志 | `/backup-log` |
 | DPAPI 解密失败 | 密文只能在本机本用户下解；换机器/换用户需重新 `/backup keys set` |
 | 提示「环境变量未设置」 | `/backup keys set` 改用 dpapi，或先设好该环境变量 |
+| 恢复报 `HTTP 423` | 网盘并发锁；v1.4.0+ 会自动重试（指数退避，尊重 `Retry-After`）。若持续失败，请确认没有安装**两份** backup 插件（退出时会同时备份），可用 `/backup list` + `pi list` 检查 |
 | 恢复报 `HTTP 302` | Cloudreve/群晖等把下载重定向到对象存储（腾讯云 COS 等）；客户端已自动跟随跨主机 302（不携带凭据），请升级到 v1.1.0+ |
+| 恢复后 `settings.json` 多了无效路径 | v1.4.0+ 已过滤旧机器的绝对路径本地源；旧版残留可手动删除 |
 | 恢复后插件不生效 | 若备份时未开启 `includePlugins`，插件代码（`node_modules`）不在备份里，需联网补装：`/backup repair-plugins`（可带 `--dir`）。推荐下次备份开启 `includePlugins: true`，下次即可一键还原 |
 | 写回时提示跳过某些文件 | 归档里是 `__REDACTED__` 而本地已有真实密钥时会被跳过（避免把真密钥抹掉）；确认要覆盖可加 `--force` |
 | 补装报 `git clone` 失败 | 确认能访问 github.com 等源；ref 是 commit SHA 时会自动回退为完整 clone + checkout，仍失败则看日志里的 git 输出 |

package/extensions/webdav-backup/apply.mjs

@@ -64,6 +64,11 @@ export function isPluginImplementationPath(rel) {
   return r.startsWith("git/") || r.includes("/node_modules/");
 }
 
+/** agentDir 下的 npm 包清单（决定 pi 启动时 npm 装/卸哪些插件） */
+export function isNpmManifestPath(rel) {
+  return String(rel).replace(/\\/g, "/") === "npm/package.json";
+}
+
 /**
  * 求一个插件实现文件所属的「插件根目录」相对路径，用于判定本机是否已装该插件：
  *   npm/node_modules/foo/lib/x.js       → npm/node_modules/foo
@@ -90,13 +95,41 @@ export function pluginRootRel(rel) {
   return null;
 }
 
-/** 取 packages 声明的来源字符串（兼容字符串与 { source, ... } 对象） */
+/**
+ * 取 packages 声明的来源字符串（兼容字符串与 { source, ... } 对象）
+ */
 function packageSourceString(p) {
   if (typeof p === "string") return p;
   if (p && typeof p === "object" && typeof p.source === "string") return p.source;
   return null;
 }
 
+/**
+ * 判断一条 packages 声明是否是「本机绝对路径」形式的本地源。
+ *
+ * 为何重要：`pi install /绝对/路径` 会把该机器的绝对路径写进 settings.json。
+ * 跨平台/跨机器恢复时，这种路径在目标机上必然无效（且可能指到完全无关的位置），
+ * 所以合并时要过滤掉，不要带过去。
+ *
+ * 只认「路径形」字符串；`npm:` / `git:` / `https://` / `builtin:` 等来源不受影响。
+ * 注意：相对路径（如 `./ext`、`ext`）是可移植的，不过滤。
+ */
+export function isMachineSpecificPackagePath(source) {
+  const s = packageSourceString(source);
+  if (!s) return false;
+  const v = s.trim();
+  if (!v) return false;
+  // 显式来源前缀：不是本地路径
+  if (/^(npm:|git:|github:|https?:|ssh:|builtin:|file:)/i.test(v)) return false;
+  // Windows 盘符绝对路径：C:\foo 或 C:/foo
+  if (/^[A-Za-z]:[\\/]/.test(v)) return true;
+  // UNC 路径：\\server\share
+  if (/^\\\\/.test(v)) return true;
+  // POSIX 绝对路径：/home/me/ext（含 \\home 形式的 Windows 风格根部）
+  if (v.startsWith("/") || v.startsWith("\\\\")) return true;
+  return false;
+}
+
 /**
  * 计算一条 packages 声明的「身份」：npm 看包名、git 看 host/path、local 看路径。
  * 用于合并时按身份去重（同身份视为同一个插件，不因版本号不同而重复）。
@@ -133,11 +166,18 @@ export function mergeSettingsPackages(backupText, localText) {
 
   const backupPkgs = Array.isArray(backup.packages) ? backup.packages : [];
   const localPkgs = Array.isArray(local?.packages) ? local.packages : [];
-  // 本机没有任何声明 → 直接用备份版即可（全新机器场景）
-  if (localPkgs.length === 0) return null;
+
+  // 本机没有任何声明（新机场景）：用备份版，但仍过滤掉旧机器专属的绝对路径
+  if (localPkgs.length === 0) {
+    const kept = backupPkgs.filter((p) => !isMachineSpecificPackagePath(p));
+    if (kept.length === backupPkgs.length) return null; // 无外来源，无需改写
+    return JSON.stringify({ ...backup, packages: kept }, null, 2);
+  }
 
   const localIds = new Set(localPkgs.map(packageIdentity).filter(Boolean));
   const extra = backupPkgs.filter((p) => {
+    // 备份里指向旧机器绝对路径的本地源，在目标机上无效 → 不合并
+    if (isMachineSpecificPackagePath(p)) return false;
     const id = packageIdentity(p);
     return id && !localIds.has(id);
   });
@@ -145,6 +185,46 @@ export function mergeSettingsPackages(backupText, localText) {
   return JSON.stringify({ ...backup, packages: [...localPkgs, ...extra] }, null, 2);
 }
 
+/**
+ * 合并 npm/package.json 的 dependencies：本机已有优先（保留版本），追加备份里本机没有的。
+ *
+ * 为何必须合并：pi 启动时会拿 npm/package.json 与 node_modules 做协调（npm install）。
+ * 若 merge 写回时用备份版直接覆盖，本机独有的插件会被 npm 当成多余包【卸载】。
+ * 返回合并后的 JSON 文本；无可合并时返回 null（调用方按普通逻辑处理）。
+ */
+export function mergeNpmDependencies(backupText, localText) {
+  let backup;
+  let local;
+  try {
+    backup = JSON.parse(String(backupText).replace(/^\uFEFF/, ""));
+  } catch {
+    return null;
+  }
+  try {
+    local = JSON.parse(String(localText).replace(/^\uFEFF/, ""));
+  } catch {
+    return null;
+  }
+  if (!backup || typeof backup !== "object") return null;
+
+  const backupDeps = backup.dependencies && typeof backup.dependencies === "object" ? backup.dependencies : {};
+  const localDeps = local?.dependencies && typeof local.dependencies === "object" ? local.dependencies : {};
+  if (Object.keys(localDeps).length === 0) return null;
+
+  // 本机已声明的依赖保留本机版本；备份独有的追加进来
+  const merged = { ...localDeps };
+  let added = 0;
+  for (const [name, range] of Object.entries(backupDeps)) {
+    if (!(name in merged)) {
+      merged[name] = range;
+      added++;
+    }
+  }
+  // 本机声明已包含备份全部依赖且无新增 → 无需改写
+  if (added === 0 && Object.keys(merged).length === Object.keys(localDeps).length) return null;
+  return JSON.stringify({ ...backup, dependencies: merged }, null, 2);
+}
+
 /** 递归列出恢复目录下、应写回 agentDir 的文件（跳过 extra/ 与元数据） */
 export function listRestoredFiles(restoredDir, { extraPrefix = "extra/" } = {}) {
   const root = resolve(restoredDir);
@@ -224,6 +304,21 @@ export function applyRestoredFiles(restoredDir, agentDir, opts = {}) {
       }
     }
 
+    // merge：npm/package.json 只合并 dependencies，保留本机独有插件。
+    // 否则覆盖后，pi 下次启动的 npm 协调会把本机独有的包当成多余包卸载。
+    let mergedNpm = false;
+    if (merge && isNpmManifestPath(f.rel) && existsSync(target)) {
+      try {
+        const mergedText = mergeNpmDependencies(srcBuf.toString("utf8"), readFileSync(target, "utf8"));
+        if (mergedText !== null) {
+          srcBuf = Buffer.from(mergedText, "utf8");
+          mergedNpm = true;
+        }
+      } catch {
+        /* 合并失败则退回普通处理 */
+      }
+    }
+
     // merge：本机已装该插件（插件根目录已存在）→ 跳过整个插件，避免降级与版本混合。
     // 但若该文件与本地完全一致，则归为 unchanged（保证重复写回幂等）。
     if (merge) {
@@ -281,11 +376,13 @@ export function applyRestoredFiles(restoredDir, agentDir, opts = {}) {
       let backup = null;
       if (existsSync(target)) backup = backupExisting(target, "apply");
       writeFileSync(target, srcBuf);
-      applied.push({ rel: f.rel, target, backup, merged: mergedSettings });
-      if (mergedSettings) merged.push({ rel: f.rel, target });
+      applied.push({ rel: f.rel, target, backup, merged: mergedSettings || mergedNpm });
+      if (mergedSettings) merged.push({ rel: f.rel, target, kind: "settings-packages" });
+      if (mergedNpm) merged.push({ rel: f.rel, target, kind: "npm-dependencies" });
       log(
         `  ${backup ? "已覆盖" : "已写入"} ${f.rel} → ${target}` +
           (mergedSettings ? "（已合并 packages，保留本机插件声明）" : "") +
+          (mergedNpm ? "（已合并 dependencies，保留本机插件依赖）" : "") +
           (backup ? `（原文件备份为 ${backup}）` : ""),
       );
     } catch (e) {

package/extensions/webdav-backup/cli.mjs

@@ -246,7 +246,11 @@ async function main() {
       if (!has("--dry-run")) {
         logTo(`已写回 agent 目录：${agentDir}（${mergeMode ? "合并模式" : "替换模式"}）`);
         logTo(`  写入/覆盖 ${r.applied.length} 个，内容一致 ${r.unchanged.length} 个，失败 ${r.failed.length} 个`);
-        if (r.merged?.length) logTo(`  🔀 settings.json 已合并 packages，保留本机已有插件声明`);
+        if (r.merged?.length) {
+          const kinds = r.merged.map((m) => m.kind).filter(Boolean);
+          if (kinds.includes("settings-packages")) logTo(`  🔀 settings.json 已合并 packages，保留本机已有插件声明`);
+          if (kinds.includes("npm-dependencies")) logTo(`  🔀 npm/package.json 已合并 dependencies，保留本机独有插件依赖`);
+        }
         for (const x of r.skipped) logTo(`  ➖ ${x.rel}（${x.reason}）`);
         for (const x of r.failed) logTo(`  ❌ ${x.rel} — ${x.error}`);
         if (pluginReady) logTo("插件实现代码已随备份恢复，无需联网重装。");

package/extensions/webdav-backup/dav-mock.mjs

@@ -15,6 +15,7 @@ export function startDavServer({
   password = "pass",
   requireAuth = true,
   redirectGetsTo = null,
+  failFirstPuts = 0,
 } = {}) {
   /** @type {Map<string, Buffer>} */
   const store = new Map();
@@ -22,6 +23,7 @@ export function startDavServer({
   const expectedAuth = "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
   let putCount = 0;
   let getCount = 0;
+  let lockedCount = 0;
   let lastAuth = null;
 
   const server = http.createServer((req, res) => {
@@ -98,6 +100,12 @@ export function startDavServer({
       const chunks = [];
       req.on("data", (c) => chunks.push(c));
       req.on("end", () => {
+        // 故障注入：前 N 次 PUT 返回 423 Locked
+        if (lockedCount < failFirstPuts) {
+          lockedCount++;
+          res.writeHead(423, { "Retry-After": "1" }).end("locked");
+          return;
+        }
         putCount++;
         store.set(key, Buffer.concat(chunks));
         res.writeHead(201).end();
@@ -152,13 +160,14 @@ export function startDavServer({
         port,
         store,
         dirs,
-        stats: () => ({ putCount, getCount }),
+        stats: () => ({ putCount, getCount, lockedCount }),
         get lastAuth() {
           return lastAuth;
         },
         reset: () => {
           putCount = 0;
           getCount = 0;
+          lockedCount = 0;
         },
       });
     });

package/extensions/webdav-backup/test-apply.mjs

@@ -29,7 +29,7 @@ import { collectFiles } from "./collect.mjs";
 import { runBackup } from "./backup.mjs";
 import { restoreBackup } from "./restore.mjs";
 import { analyzePlugins } from "./packages.mjs";
-import { applyRestoredFiles, listRestoredFiles, hasPluginCode, pluginRootRel, packageIdentity, mergeSettingsPackages } from "./apply.mjs";
+import { applyRestoredFiles, listRestoredFiles, hasPluginCode, pluginRootRel, packageIdentity, mergeSettingsPackages, isMachineSpecificPackagePath } from "./apply.mjs";
 
 let pass = 0;
 let fail = 0;
@@ -298,7 +298,7 @@ async function main() {
     rmSync(live2, { recursive: true, force: true });
   }
 
-  // ── 8. mergeSettingsPackages：本机无声明时返回 null（用备份原样）
+  // 8. mergeSettingsPackages：本机无声明时返回 null（用备份原样）
   {
     check("本机无 packages 声明时不合并", mergeSettingsPackages('{"packages":["npm:A"]}', '{"theme":"x"}') === null);
     const m = mergeSettingsPackages('{"packages":["npm:A","npm:B"],"theme":"light"}', '{"packages":["npm:B@2"],"theme":"dark"}');
@@ -306,6 +306,76 @@ async function main() {
     check("合并保留本机声明优先、追加备份独有", JSON.stringify(o.packages) === JSON.stringify(["npm:B@2", "npm:A"]) && o.theme === "light", String(m));
   }
 
+  // ── 8b. 回归：跨机同步不得带入旧机器的绝对路径本地源
+  {
+    // isMachineSpecificPackagePath 单测
+    check("识别 Windows 盘符路径", isMachineSpecificPackagePath("E:\\Users\\me\\ext") === true);
+    check("识别正斜杠盘符路径", isMachineSpecificPackagePath("C:/Users/me/ext") === true);
+    check("识别 POSIX 绝对路径", isMachineSpecificPackagePath("/home/me/ext") === true);
+    check("识别 UNC 路径", isMachineSpecificPackagePath("\\\\server\\share\\ext") === true);
+    check("npm 源不误判", isMachineSpecificPackagePath("npm:foo") === false);
+    check("git 源不误判", isMachineSpecificPackagePath("git:github.com/u/r@v1") === false);
+    check("https 源不误判", isMachineSpecificPackagePath("https://github.com/u/r") === false);
+    check("相对路径不误判（可移植）", isMachineSpecificPackagePath("./ext") === false);
+
+    // 合并时：备份里的 Windows 绝对路径不得进入 Linux 的 packages
+    const backup = JSON.stringify({ packages: ["npm:pi-signal-footer", "E:\\Users\\Administrator\\Desktop\\projects\\pi-webdav-backup"] });
+    const live = JSON.stringify({ packages: ["npm:@zhangweiii/pi-status-line"] });
+    const merged = JSON.parse(mergeSettingsPackages(backup, live));
+    check("合并过滤掉旧机器绝对路径", !merged.packages.some((p) => /^[A-Za-z]:[\\/]/.test(p)), JSON.stringify(merged.packages));
+    check("合并仍保留可移植的 npm 源", merged.packages.includes("npm:pi-signal-footer"), JSON.stringify(merged.packages));
+    check("合并保留本机声明", merged.packages.includes("npm:@zhangweiii/pi-status-line"));
+
+    // 全新机（本机无 packages）：同样要过滤外来绝对路径
+    const fresh = mergeSettingsPackages(backup, JSON.stringify({ theme: "dark" }));
+    check("全新机场景也过滤外来绝对路径", fresh !== null && !JSON.parse(fresh).packages.some((p) => /^[A-Za-z]:[\\/]/.test(p)), String(fresh));
+    check("全新机仅剩可移植源则不改写", mergeSettingsPackages('{"packages":["npm:A"]}', '{}') === null);
+  }
+
+  // ── 9. 回归：npm/package.json 必须合并 dependencies（否则 pi 会卸载本机独有插件）
+  {
+    // 备份来源（Windows）：只依赖 A、B
+    const backup = mkdtempSync(join(tmpdir(), "pi-npm-merge-bk-"));
+    mkdirSync(join(backup, "npm"), { recursive: true });
+    writeFileSync(join(backup, "settings.json"), JSON.stringify({ packages: ["npm:A", "npm:B"] }));
+    writeFileSync(
+      join(backup, "npm", "package.json"),
+      JSON.stringify({ name: "pi-extensions", private: true, dependencies: { A: "^1.0.0", B: "^2.0.0" } }),
+    );
+
+    // 目标机器（Linux）：已装 A（本机版本）+ 本机独有的 Z
+    const live = mkdtempSync(join(tmpdir(), "pi-npm-merge-live-"));
+    mkdirSync(join(live, "npm"), { recursive: true });
+    writeFileSync(join(live, "settings.json"), JSON.stringify({ packages: ["npm:A@9", "npm:Z"] }));
+    writeFileSync(
+      join(live, "npm", "package.json"),
+      JSON.stringify({ name: "pi-extensions", private: true, dependencies: { A: "^9.0.0", Z: "^0.1.0" } }),
+    );
+
+    const r = applyRestoredFiles(backup, live, { merge: true });
+    const deps = JSON.parse(readFileSync(join(live, "npm", "package.json"), "utf8")).dependencies;
+    check("merge 后 npm 依赖保留本机 A@9", deps.A === "^9.0.0", JSON.stringify(deps));
+    check("merge 后 npm 依赖保留本机独有 Z", deps.Z === "^0.1.0", JSON.stringify(deps));
+    check("merge 后 npm 依赖追加备份独有的 B", deps.B === "^2.0.0", JSON.stringify(deps));
+    check("merged 列表标出 npm-dependencies", r.merged?.some((m) => m.kind === "npm-dependencies"), JSON.stringify(r.merged));
+
+    // replace：完全用备份版（Z 会从 package.json 消失，由 pi 下次启动自行卸载）
+    const live2 = mkdtempSync(join(tmpdir(), "pi-npm-merge-live2-"));
+    mkdirSync(join(live2, "npm"), { recursive: true });
+    writeFileSync(join(live2, "settings.json"), JSON.stringify({ packages: ["npm:A@9", "npm:Z"] }));
+    writeFileSync(
+      join(live2, "npm", "package.json"),
+      JSON.stringify({ name: "pi-extensions", private: true, dependencies: { A: "^9.0.0", Z: "^0.1.0" } }),
+    );
+    applyRestoredFiles(backup, live2, { merge: false });
+    const deps2 = JSON.parse(readFileSync(join(live2, "npm", "package.json"), "utf8")).dependencies;
+    check("replace 后 npm 依赖完全变回备份版", JSON.stringify(deps2) === JSON.stringify({ A: "^1.0.0", B: "^2.0.0" }), JSON.stringify(deps2));
+
+    rmSync(backup, { recursive: true, force: true });
+    rmSync(live, { recursive: true, force: true });
+    rmSync(live2, { recursive: true, force: true });
+  }
+
   console.log(lines.join("\n"));
   console.log(`\n结果：${pass} 通过，${fail} 失败`);
   process.exit(fail === 0 ? 0 : 1);

package/extensions/webdav-backup/test-webdav.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * test-webdav.mjs — WebDAV 客户端健壮性测试
+ *
+ * 背景：网盘在并发上传/维护时返回 423 Locked / 429 / 5xx；此前无任何重试，
+ * 一次抖动就让整次备份失败（实测：两份 backup 插件同时退出 → 423）。
+ *
+ * 验证：
+ *   1. PUT 遇 423 Locked → 自动重试并最终成功
+ *   2. Retry-After 头被尊重（不改变正确性，仅验证不报错）
+ *   3. 持续 423 超过重试上限时明确失败（不会无限重试）
+ *   4. check/list/统计仍正常
+ */
+
+import { startDavServer } from "./dav-mock.mjs";
+import { WebDAVClient } from "./webdav.mjs";
+
+let pass = 0;
+let fail = 0;
+const lines = [];
+const check = (n, c, d = "") => {
+  if (c) { pass++; lines.push(`  ✅ ${n}`); }
+  else { fail++; lines.push(`  ❌ ${n}${d ? ` — ${d}` : ""}`); }
+};
+
+async function main() {
+  console.log("pi WebDAV 备份 — WebDAV 客户端健壮性测试\n");
+
+  // ── 1. PUT 前 2 次返回 423，之后成功（验证重试）
+  {
+    const dav = await startDavServer({ failFirstPuts: 2 });
+    dav.dirs.add("/dav");
+    const c = new WebDAVClient({ baseUrl: `http://127.0.0.1:${dav.port}/dav`, username: "user", password: "pass", timeoutMs: 10000 });
+    let ok = false, err = null;
+    try {
+      await c.put("/dav/x.txt", Buffer.from("hello"), { contentType: "text/plain" });
+      ok = true;
+    } catch (e) { err = e.message; }
+    const s = dav.stats();
+    check("423 后自动重试并成功", ok === true, err || "");
+    check("确实经历了 2 次锁定", s.lockedCount === 2, JSON.stringify(s));
+    check("最终成功写入（putCount=1）", s.putCount === 1, JSON.stringify(s));
+    const got = await c.get("/dav/x.txt");
+    check("重试后内容正确", got && got.toString("utf8") === "hello");
+    dav.server.close();
+  }
+
+  // ── 2. 持续 423 超过上限 → 明确失败（不悬挂）
+  {
+    const dav = await startDavServer({ failFirstPuts: 999 });
+    dav.dirs.add("/dav");
+    const c = new WebDAVClient({ baseUrl: `http://127.0.0.1:${dav.port}/dav`, username: "user", password: "pass", timeoutMs: 10000 });
+    const t0 = Date.now();
+    let failed = false, msg = "";
+    try {
+      await c.put("/dav/y.txt", Buffer.from("x"));
+    } catch (e) { failed = true; msg = e.message; }
+    const ms = Date.now() - t0;
+    check("持续 423 最终失败（不无限重试）", failed === true);
+    check("错误信息含 HTTP 423", /423/.test(msg), msg);
+    check("重试次数有上限（<40s）", ms < 40000, `${ms}ms`);
+    dav.server.close();
+  }
+
+  // ── 3. 常规操作不受影响
+  {
+    const dav = await startDavServer();
+    dav.dirs.add("/dav");
+    const c = new WebDAVClient({ baseUrl: `http://127.0.0.1:${dav.port}/dav`, username: "user", password: "pass", timeoutMs: 10000 });
+    const chk = await c.check();
+    check("check 正常", chk.ok === true, JSON.stringify(chk));
+    await c.mkdirp("dav/sub");
+    await c.put("/dav/sub/a.txt", Buffer.from("A"));
+    const list = await c.list("dav/sub");
+    check("list 能看到刚上传的文件", list.some((e) => e.name === "a.txt" && !e.isCollection), JSON.stringify(list.map((e) => e.name)));
+    await c.del("/dav/sub/a.txt");
+    const list2 = await c.list("dav/sub");
+    check("delete 生效", !list2.some((e) => e.name === "a.txt"));
+    dav.server.close();
+  }
+
+  console.log(lines.join("\n"));
+  console.log(`\n结果：${pass} 通过，${fail} 失败`);
+  process.exit(fail === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.log(lines.join("\n"));
+  console.error(`\n测试异常：${e?.stack ?? e}`);
+  process.exit(1);
+});

package/extensions/webdav-backup/webdav.mjs

@@ -17,6 +17,30 @@ import { URL } from "node:url";
 const UA = "pi-webdav-backup/1.0";
 const MAX_REDIRECTS = 5;
 
+/**
+ * 瞬时错误重试参数。
+ *
+ * 背景：网盘（坚果云/群晖/Cloudreve 等）在并发上传、扫描或维护时会返回
+ * 423 Locked / 429 / 5xx；同一文件在稍后重试即可成功。之前没有任何重试，
+ * 一次抖动就导致整次备份失败（实测：两个实例同时退出备份 → 423）。
+ */
+const MAX_RETRIES = 4;
+const RETRY_BASE_DELAY_MS = 800;
+const RETRYABLE_STATUS = new Set([423, 425, 429, 500, 502, 503, 504]);
+const RETRYABLE_METHODS = new Set(["PUT", "MKCOL", "DELETE", "PROPFIND", "HEAD", "GET"]);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** 解析 Retry-After（秒数或 HTTP 日期），返回毫秒；无法解析返回 null */
+function parseRetryAfter(value) {
+  if (!value) return null;
+  const s = String(value).trim();
+  if (/^\d+$/.test(s)) return Number(s) * 1000;
+  const t = Date.parse(s);
+  if (!Number.isNaN(t)) return Math.max(0, t - Date.now());
+  return null;
+}
+
 function request(url, { method, headers = {}, body = null, timeoutMs = 60000, insecureTls = false, redirects = MAX_REDIRECTS }) {
   return new Promise((resolve, reject) => {
     let u;
@@ -100,6 +124,34 @@ function basicAuth(username, password) {
   return { Authorization: `Basic ${token}` };
 }
 
+/**
+ * 带重试的请求：对 423/429/5xx 与网络抖动指数据退避重试（仅幂等方法）。
+ * PUT 幂等（整体覆盖同名文件），故也可安全重试。
+ * @returns {Promise<{status:number, headers:object, body:Buffer}>}
+ */
+async function requestWithRetry(url, opts) {
+  const method = String(opts.method || "GET").toUpperCase();
+  const retryable = RETRYABLE_METHODS.has(method);
+  let lastRes = null;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    let res;
+    try {
+      res = await request(url, opts);
+    } catch (e) {
+      // 网络层错误（超时/断连）也重试
+      if (!retryable || attempt === MAX_RETRIES) throw e;
+      await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
+      continue;
+    }
+    lastRes = res;
+    if (!retryable || !RETRYABLE_STATUS.has(res.status) || attempt === MAX_RETRIES) return res;
+    const hinted = parseRetryAfter(res.headers?.["retry-after"]);
+    const delay = hinted ?? RETRY_BASE_DELAY_MS * 2 ** attempt;
+    await sleep(Math.min(delay, 15000));
+  }
+  return lastRes;
+}
+
 export class WebDAVClient {
   constructor({ baseUrl, username, password, timeoutMs = 60000, insecureTls = false }) {
     if (!/^https?:\/\//i.test(baseUrl)) {
@@ -122,7 +174,7 @@ export class WebDAVClient {
   }
 
   async #req(method, remotePath, { headers = {}, body = null } = {}) {
-    return request(this.urlFor(remotePath), {
+    return requestWithRetry(this.urlFor(remotePath), {
       method,
       headers: { ...this.auth, ...headers },
       body,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-webdav-backup",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "pi 配置与插件数据自动备份到 WebDAV（坚果云 / Nextcloud / 群晖 / 自建）：归档与快照两种模式、AES-256-GCM 加密、DPAPI 密钥管理、敏感字段脱敏、agentDir 之外的额外数据（extraScope）、插件实现代码随备份（includePlugins）实现换机一键还原、退出自动备份与每日定时备份。",
   "keywords": [
     "pi-package",