pi-webdav-backup 1.3.3 → 1.4.0

package/README.md

@@ -636,6 +636,7 @@ 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 提升的依赖被当成缺失） |
@@ -662,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

@@ -95,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 看路径。
  * 用于合并时按身份去重（同身份视为同一个插件，不因版本号不同而重复）。
@@ -138,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);
   });

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;
@@ -306,6 +306,32 @@ 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

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