@shellus/way 0.6.9 → 0.6.11

package/README.md

@@ -68,7 +68,7 @@
 ## 依赖
 
 - Linux x64 独立发行包无需预装 Node.js、npm、Bun 或 restic
-- npm 安装方式需要 Node.js >= 18
+- npm 安装方式需要 Node.js >= 22.12
 - Linux x64 平台内置 [restic](https://restic.net/) 0.18.1，其他平台需自行安装 restic
 
 `way` 查找 restic 的顺序：
@@ -137,6 +137,15 @@ way systemd install
 way systemd status
 ```
 
+Windows 使用系统自带的任务计划程序守护 `way daemon`，不依赖 NSSM 或其他常驻工具：
+
+```powershell
+way windows-service install
+way windows-service status
+```
+
+`windows-service install` 会创建以 `SYSTEM` 身份在开机后运行的原生任务，并配置失败重启；注册和删除任务需要在提升权限的 PowerShell 中执行。任务仅守护 daemon，实际备份频率仍由 `rules.yaml` 的项目级 `schedule` 决定。
+
 ### 4. 手动执行备份
 
 ```bash
@@ -169,6 +178,12 @@ way systemd show        # 显示 systemd 配置
 way systemd status      # 查看服务状态
 way systemd uninstall   # 卸载服务
 
+# Windows 原生守护任务管理
+way windows-service install    # 注册开机启动、SYSTEM 身份运行的 daemon 守护任务
+way windows-service show       # 显示将要写入的任务与启动脚本
+way windows-service status     # 查看任务状态
+way windows-service uninstall  # 删除任务与启动脚本
+
 # 显式透传 restic（way 只设置环境变量）
 way restic snapshots    # → restic snapshots
 way restic check        # → restic check
@@ -193,6 +208,7 @@ graph LR
 
     G[systemd service] --> H[启动 daemon]
     H --> I[进程崩溃自动重启]
+    J[Windows Task Scheduler] --> H
 ```
 
 ---
@@ -224,6 +240,27 @@ WAY_DIR=/path/to/config way restic snapshots
 - **maintenance**: 维护任务配置（prune、check）
 - **global_excludes**: 全局排除规则
 
+`defaults.retention` 支持两种互斥模式：
+
+- 计数保留：`keep_daily`、`keep_weekly`、`keep_monthly`、`keep_yearly`，按 restic 分组规则保留周期快照。
+- 严格范围保留：`keep_hosts` 与 `max_age_days` 必须同时设置。Way 以执行时的当前时间计算截止点，只保留白名单主机在最近指定天数内的快照；其他快照使用明确 ID 删除。该模式不会使用 restic 相对最新快照计算的 `keep-within` 语义。
+
+两种模式不得混用。严格范围保留示例：
+
+```yaml
+defaults:
+  retention:
+    keep_hosts: [backup-host]
+    max_age_days: 7
+
+maintenance:
+  prune:
+    schedule: "0 4 * * *"
+    retry_lock: "30m"
+```
+
+`maintenance.prune.retry_lock` 会作为 restic 全局 `--retry-lock` 参数传递。正式启用严格范围保留前必须先执行 `way gc --dry-run`，核对输出的保留和删除快照列表。
+
 项目级钩子用于在 restic 备份前后执行一致性快照、校验或清理脚本：
 
 ```yaml
@@ -242,6 +279,8 @@ projects:
 
 `before_backup` 失败会跳过该项目的 restic 备份并标记项目失败；`after_backup` 只在 restic 成功后执行，失败同样会标记项目失败。`--dry-run` 模式只打印钩子命令，不实际执行。钩子命令按 shell 命令执行，并会收到 `WAY_PROJECT`、`WAY_REMOTE`、`WAY_DIR`、`WAY_DRY_RUN` 环境变量。
 
+Linux 上的 hook 达到 `timeout` 后，Way 会终止对应 shell 的完整进程组；进程未在宽限期内退出时会继续强制终止，避免数据库导出、压缩或同步子进程脱离 Way 后持续运行。hook 仍应保持幂等，并自行清理失败时生成的临时文件。
+
 **项目级 Uptime Kuma 通知示例**：
 
 ```yaml
@@ -323,6 +362,8 @@ way backup data_deps
 
 `schedule` 支持 node-cron 字符串或 `false`。`false` 表示不创建自动调度任务，只能通过 `way backup <project>` 或 `way backup` 手动触发。项目未设置 `schedule` 时继承 `defaults.schedule`；如果全局和项目都未设置，则不自动调度。
 
+daemon 的调度心跳最多容忍 5 秒延迟；事件循环短暂阻塞后仍会补执行本轮任务，超过窗口则由 node-cron 报告为 missed execution。
+
 | 格式 | 说明 | 示例 |
 |------|------|------|
 | `"0 */2 * * *"` | 间隔表达式 | 每 2 小时 |
@@ -359,6 +400,8 @@ repositories:
 
 建议设置文件权限：`chmod 600 ~/.way/repositories.yaml`
 
+`repositories.yaml` 和 `rules.yaml` 支持 YAML merge anchor（`<<`）；Way 使用 YAML 1.2 Core Schema 并显式启用 merge tag，不会同时启用 YAML 1.1 的日期自动转换等额外类型。
+
 ## 配置备份
 
 `~/.way/` 目录包含所有配置和凭证，建议整体备份到安全位置：
@@ -460,4 +503,4 @@ way --remote=oss restic restore <snapshot-id> --target /tmp/restore
 - 变更规范和测试要求
 - 发布流程
 
-内部开发参考：[CLAUDE.md](CLAUDE.md)
+项目维护规则：[AGENTS.md](AGENTS.md)

package/dist/cli.js

@@ -2,22 +2,24 @@
 
 // src/cli.ts
 import { Command } from "commander";
-import fs6 from "fs";
-import path6 from "path";
+import fs7 from "fs";
+import path8 from "path";
 
 // src/core/config.ts
 import fs from "fs";
 import path from "path";
-import yaml from "js-yaml";
+import * as yaml from "js-yaml";
+var configSchema = yaml.CORE_SCHEMA.withTags(yaml.mergeTag);
 function loadConfig(wayDir, remoteName) {
   const repoFile = path.join(wayDir, "repositories.yaml");
-  const repoConfig = yaml.load(fs.readFileSync(repoFile, "utf8"));
+  const repoConfig = yaml.load(fs.readFileSync(repoFile, "utf8"), { schema: configSchema });
   const repoName = remoteName === "default" ? repoConfig.default : remoteName;
   const repository = repoConfig.repositories[repoName];
   if (!repository) throw new Error(`Repository not found: ${repoName}`);
   const rulesFile = path.join(wayDir, "rules.yaml");
-  const rules = yaml.load(fs.readFileSync(rulesFile, "utf8"));
-  if ("schedule" in rules && "backup" in (rules.schedule || {})) {
+  const rules = yaml.load(fs.readFileSync(rulesFile, "utf8"), { schema: configSchema });
+  const legacySchedule = "schedule" in rules ? rules.schedule : void 0;
+  if (typeof legacySchedule === "object" && legacySchedule !== null && "backup" in legacySchedule) {
     throw new Error("\u68C0\u6D4B\u5230 v0.4.x \u65E7\u914D\u7F6E\u683C\u5F0F\uFF0C\u8BF7\u8FD0\u884C\u8FC1\u79FB\u811A\u672C\uFF1Anpx --yes @shellus/way@latest migrate-to-v0.5.sh \u6216\u624B\u52A8\u53C2\u8003 rules.yaml.example \u66F4\u65B0\u914D\u7F6E");
   }
   return { repository, rules };
@@ -178,6 +180,12 @@ function collectIncludeDirs(paths, includeDirs, options = {}) {
   }
   return Array.from(new Set(matches));
 }
+function normalizeResticPath(value, platform = process.platform) {
+  if (platform !== "win32") return value;
+  const match = value.match(/^([A-Za-z]):[\\/](.*)$/);
+  if (!match) return value.replace(/\\/g, "/");
+  return `/${match[1].toUpperCase()}/${match[2].replace(/\\/g, "/")}`;
+}
 function buildRestoreArgs(name, project, options) {
   const args = [
     "restore",
@@ -186,7 +194,7 @@ function buildRestoreArgs(name, project, options) {
   ];
   if (options.host) args.push(`--host=${options.host}`);
   args.push(`--target=${options.target}`);
-  for (const path7 of project.paths) args.push(`--include=${path7}`);
+  for (const path9 of options.includePaths || project.paths) args.push(`--include=${normalizeResticPath(path9, options.platform)}`);
   if (options.dryRun) args.push("--dry-run");
   if (options.delete) args.push("--delete");
   if (options.verbose) args.push("--verbose=2");
@@ -200,8 +208,18 @@ function buildS3Options(repo) {
   return options;
 }
 async function execRestic(args, env, s3Options = []) {
+  await runRestic(args, env, s3Options, false);
+}
+async function execResticCapture(args, env, s3Options = []) {
+  return runRestic(args, env, s3Options, true);
+}
+async function runRestic(args, env, s3Options, capture) {
   try {
-    await execa(resolveResticBin(), [...s3Options, ...args], { env: { ...process.env, ...env }, stdio: "inherit" });
+    const result = await execa(resolveResticBin(), [...s3Options, ...args], {
+      env: { ...process.env, ...env },
+      ...capture ? { stdout: "pipe", stderr: "inherit" } : { stdio: "inherit" }
+    });
+    return typeof result.stdout === "string" ? result.stdout : "";
   } catch (error) {
     if (error.code === "ENOENT") {
       console.error("Error: restic not found. Linux x64 packages include restic; other platforms must install it first.");
@@ -216,7 +234,7 @@ async function execRestic(args, env, s3Options = []) {
 import fs4 from "fs";
 import os from "os";
 import path4 from "path";
-import { execaCommand } from "execa";
+import { execa as execa2 } from "execa";
 async function backup(options) {
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, options.remote);
@@ -324,6 +342,7 @@ function groupUptimeKumaResults(projectResults) {
   }
   return groupedResults;
 }
+var HOOK_FORCE_KILL_DELAY_MS = 1e3;
 function normalizeHook(hook) {
   if (typeof hook === "string") return { run: hook };
   return hook;
@@ -346,6 +365,26 @@ function parseTimeout(timeout) {
       return value * 60 * 60 * 1e3;
   }
 }
+function isMissingProcessError(error) {
+  return error instanceof Error && "code" in error && error.code === "ESRCH";
+}
+function signalProcessGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch (error) {
+    if (isMissingProcessError(error)) return false;
+    throw error;
+  }
+}
+function hookTimedOut(error) {
+  return typeof error === "object" && error !== null && "timedOut" in error && error.timedOut === true;
+}
+async function terminateProcessGroup(pid) {
+  if (!signalProcessGroup(pid, "SIGTERM")) return;
+  await new Promise((resolve) => setTimeout(resolve, HOOK_FORCE_KILL_DELAY_MS));
+  signalProcessGroup(pid, "SIGKILL");
+}
 async function runProjectHooks(hooks, context) {
   if (!hooks?.length) return;
   for (const hook of hooks) {
@@ -356,10 +395,11 @@ async function runProjectHooks(hooks, context) {
       continue;
     }
     console.log(`Running ${context.label} hook for ${context.projectName}: ${normalized.run}`);
-    await execaCommand(normalized.run, {
+    const subprocess = execa2(normalized.run, {
       shell: true,
       stdio: "inherit",
       timeout: parseTimeout(normalized.timeout),
+      detached: process.platform !== "win32",
       env: {
         WAY_PROJECT: context.projectName,
         WAY_REMOTE: context.remote,
@@ -367,6 +407,19 @@ async function runProjectHooks(hooks, context) {
         WAY_DRY_RUN: context.dryRun ? "1" : "0"
       }
     });
+    const processGroupPid = process.platform === "win32" ? void 0 : subprocess.pid;
+    const cleanupOnExit = processGroupPid === void 0 ? void 0 : () => signalProcessGroup(processGroupPid, "SIGTERM");
+    if (cleanupOnExit) process.once("exit", cleanupOnExit);
+    try {
+      await subprocess;
+    } catch (error) {
+      if (processGroupPid !== void 0 && hookTimedOut(error)) {
+        await terminateProcessGroup(processGroupPid);
+      }
+      throw error;
+    } finally {
+      if (cleanupOnExit) process.removeListener("exit", cleanupOnExit);
+    }
   }
 }
 async function notifyUptimeKuma(result, pushUrl) {
@@ -386,8 +439,46 @@ async function notifyUptimeKuma(result, pushUrl) {
 }
 
 // src/commands/restore.ts
+import path5 from "path";
+function isWithin(parent, child, pathApi) {
+  const relative = pathApi.relative(parent, child);
+  return relative === "" || !relative.startsWith("..") && !pathApi.isAbsolute(relative);
+}
+function findCommonParent(paths, pathApi) {
+  let candidate = paths[0];
+  while (!paths.every((item) => isWithin(candidate, item, pathApi))) {
+    const parent = pathApi.dirname(candidate);
+    if (parent === candidate) return candidate;
+    candidate = parent;
+  }
+  return candidate;
+}
+function buildWindowsRestorePlans(project, target, snapshot = "latest") {
+  const pathApi = path5.win32;
+  const groups = /* @__PURE__ */ new Map();
+  for (const sourcePath of project.paths) {
+    const root = pathApi.parse(sourcePath).root.toLowerCase();
+    const paths = groups.get(root) || [];
+    paths.push(sourcePath);
+    groups.set(root, paths);
+  }
+  return Array.from(groups.values()).map((paths) => {
+    const parent = findCommonParent(paths.map((item) => pathApi.dirname(item)), pathApi);
+    const drive = parent[0].toUpperCase();
+    const rest = parent.slice(2).replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+    const snapshotPath = rest ? `/${drive}/${rest}` : `/${drive}`;
+    const includePaths = paths.map((item) => `/${pathApi.relative(parent, item).replace(/\\/g, "/")}`);
+    const targetPath = pathApi.join(target, ...snapshotPath.split("/").filter(Boolean));
+    return {
+      snapshot: `${snapshot}:${snapshotPath}`,
+      target: targetPath,
+      includePaths: Array.from(new Set(includePaths))
+    };
+  });
+}
 async function restore(options) {
   if (!options.target) throw new Error("--target is required");
+  const target = options.target;
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, options.remote);
   const env = buildResticEnv(config.repository);
@@ -405,15 +496,19 @@ async function restore(options) {
     }
     console.log(`=== Restoring: ${projectName} ===`);
     try {
-      const args = buildRestoreArgs(projectName, project, {
-        target: options.target,
-        snapshot: options.snapshot,
-        host: options.host,
-        dryRun: options.dryRun,
-        delete: options.delete,
-        verbose: options.verbose
-      });
-      await execRestic(args, env, s3Options);
+      const plans = process.platform === "win32" && project.paths.every((item) => /^[A-Za-z]:[\\/]/.test(item)) ? buildWindowsRestorePlans(project, target, options.snapshot) : [{ snapshot: options.snapshot, target, includePaths: void 0 }];
+      for (const plan of plans) {
+        const args = buildRestoreArgs(projectName, project, {
+          target: plan.target,
+          snapshot: plan.snapshot,
+          host: options.host,
+          dryRun: options.dryRun,
+          delete: options.delete,
+          verbose: options.verbose,
+          includePaths: plan.includePaths
+        });
+        await execRestic(args, env, s3Options);
+      }
       succeeded.push(projectName);
     } catch (error) {
       console.error(`Failed to restore ${projectName}:`, error);
@@ -428,18 +523,101 @@ async function restore(options) {
 }
 
 // src/commands/gc.ts
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function hasLegacyPolicy(retention) {
+  return [
+    retention.keep_daily,
+    retention.keep_weekly,
+    retention.keep_monthly,
+    retention.keep_yearly
+  ].some((value) => value !== void 0);
+}
+function isStrictPolicy(retention) {
+  return retention.keep_hosts !== void 0 || retention.max_age_days !== void 0;
+}
+function validateStrictPolicy(retention) {
+  if (!retention.keep_hosts?.length) {
+    throw new Error("Strict retention requires at least one defaults.retention.keep_hosts entry");
+  }
+  if (!Number.isFinite(retention.max_age_days) || retention.max_age_days <= 0) {
+    throw new Error("Strict retention requires defaults.retention.max_age_days to be a positive number");
+  }
+  if (hasLegacyPolicy(retention)) {
+    throw new Error("Strict keep_hosts/max_age_days retention cannot be combined with count-based keep_* retention");
+  }
+  const normalizedHosts = retention.keep_hosts.map((host) => host.trim());
+  if (normalizedHosts.some((host) => host.length === 0)) {
+    throw new Error("defaults.retention.keep_hosts cannot contain empty host names");
+  }
+  return { hosts: new Set(normalizedHosts), maxAgeDays: retention.max_age_days };
+}
+function buildSnapshotRetentionPlan(snapshots, retention, now = /* @__PURE__ */ new Date()) {
+  const { hosts, maxAgeDays } = validateStrictPolicy(retention);
+  const cutoff = new Date(now.getTime() - maxAgeDays * DAY_MS);
+  const keep = [];
+  const remove = [];
+  for (const snapshot of snapshots) {
+    const snapshotTime = new Date(snapshot.time);
+    if (Number.isNaN(snapshotTime.getTime())) {
+      throw new Error(`Snapshot ${snapshot.id} has an invalid timestamp: ${snapshot.time}`);
+    }
+    if (hosts.has(snapshot.hostname) && snapshotTime >= cutoff) {
+      keep.push(snapshot);
+    } else {
+      remove.push(snapshot);
+    }
+  }
+  return { cutoff, keep, remove };
+}
+function printSnapshots(label, snapshots) {
+  console.log(`${label} (${snapshots.length}):`);
+  for (const snapshot of snapshots) {
+    console.log(`  ${snapshot.id.slice(0, 8)}  ${snapshot.time}  ${snapshot.hostname}  ${(snapshot.tags || []).join(",") || "-"}`);
+  }
+}
+function buildResticOptions(s3Options, retryLock) {
+  const options = [...s3Options];
+  if (retryLock) options.push(`--retry-lock=${retryLock}`);
+  return options;
+}
+async function runStrictGc(retention, dryRun, env, resticOptions) {
+  const snapshotsJson = await execResticCapture(["snapshots", "--json", "--no-lock"], env, resticOptions);
+  const snapshots = JSON.parse(snapshotsJson);
+  if (!Array.isArray(snapshots)) throw new Error("restic snapshots --json did not return an array");
+  const plan = buildSnapshotRetentionPlan(snapshots, retention);
+  console.log(`Policy: keep hosts=${retention.keep_hosts.join(",")}, max age=${retention.max_age_days} days, cutoff=${plan.cutoff.toISOString()}`);
+  printSnapshots("Keep snapshots", plan.keep);
+  printSnapshots("Remove snapshots", plan.remove);
+  if (dryRun) {
+    console.log("Dry-run complete; no snapshots or repository data were modified.");
+    return;
+  }
+  if (plan.remove.length === 0) {
+    console.log("No snapshots matched cleanup; prune was skipped.");
+    return;
+  }
+  await execRestic(["forget", "--prune", ...plan.remove.map((snapshot) => snapshot.id)], env, resticOptions);
+}
 async function gc(options) {
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, options.remote);
   const retention = config.rules.defaults?.retention || {};
+  const dryRun = options.dryRun || false;
+  console.log("=== Cleaning snapshots ===");
+  const env = buildResticEnv(config.repository);
+  const resticOptions = buildResticOptions(
+    buildS3Options(config.repository),
+    config.rules.maintenance?.prune?.retry_lock
+  );
+  if (isStrictPolicy(retention)) {
+    await runStrictGc(retention, dryRun, env, resticOptions);
+    return;
+  }
   const keepDaily = retention.keep_daily || 7;
   const keepWeekly = retention.keep_weekly || 4;
   const keepMonthly = retention.keep_monthly || 6;
   const keepYearly = retention.keep_yearly;
-  console.log("=== Cleaning snapshots ===");
   console.log(`Policy: daily=${keepDaily}, weekly=${keepWeekly}, monthly=${keepMonthly}${keepYearly ? `, yearly=${keepYearly}` : ""}`);
-  const env = buildResticEnv(config.repository);
-  const s3Options = buildS3Options(config.repository);
   const args = [
     "forget",
     "--prune",
@@ -448,22 +626,22 @@ async function gc(options) {
     `--keep-monthly=${keepMonthly}`
   ];
   if (keepYearly) args.push(`--keep-yearly=${keepYearly}`);
-  if (options.dryRun) args.push("--dry-run");
-  await execRestic(args, env, s3Options);
+  if (dryRun) args.push("--dry-run");
+  await execRestic(args, env, resticOptions);
 }
 
 // src/commands/systemd.ts
 import { execSync } from "child_process";
 import fs5 from "fs";
-import path5 from "path";
+import path6 from "path";
 function resolveWayCommandPath(options = {}) {
   const env = options.env ?? process.env;
   const argv = options.argv ?? process.argv;
   const execPath = options.execPath ?? process.execPath;
   const whichWay = options.whichWay ?? (() => execSync("which way", { encoding: "utf-8" }).trim());
   if (env.WAY_BIN) return env.WAY_BIN;
-  if (path5.basename(execPath) === "way") return execPath;
-  if (argv[1] && path5.isAbsolute(argv[1])) return argv[1];
+  if (path6.basename(execPath) === "way") return execPath;
+  if (argv[1] && path6.isAbsolute(argv[1])) return argv[1];
   return whichWay();
 }
 async function systemd(options) {
@@ -493,7 +671,7 @@ WantedBy=multi-user.target
     return;
   }
   const systemdDir = "/etc/systemd/system";
-  const servicePath = path5.join(systemdDir, "way-backup.service");
+  const servicePath = path6.join(systemdDir, "way-backup.service");
   if (options.action === "install") {
     fs5.writeFileSync(servicePath, serviceContent);
     execSync("systemctl daemon-reload");
@@ -520,10 +698,136 @@ WantedBy=multi-user.target
   }
 }
 
+// src/commands/windows-service.ts
+import { execFileSync } from "child_process";
+import fs6 from "fs";
+import os2 from "os";
+import path7 from "path";
+var WINDOWS_TASK_NAME = "Way Backup Daemon";
+var WINDOWS_RUNNER_NAME = "way-daemon.cmd";
+function assertWindows(platform) {
+  if (platform !== "win32") throw new Error("windows-service is only available on Windows");
+}
+function assertSafeCmdValue(value, name) {
+  if (/[\r\n\0]/.test(value)) throw new Error(`${name} cannot contain line breaks or NUL bytes`);
+}
+function xmlEscape(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function resolveDaemonLaunch(options = {}) {
+  const env = options.env ?? process.env;
+  const argv = options.argv ?? process.argv;
+  const execPath = options.execPath ?? process.execPath;
+  if (env.WAY_BIN) return { command: env.WAY_BIN, args: ["daemon"] };
+  if (argv[1] && (path7.isAbsolute(argv[1]) || path7.win32.isAbsolute(argv[1]))) {
+    return { command: execPath, args: [argv[1], "daemon"] };
+  }
+  return { command: execPath, args: ["daemon"] };
+}
+function renderWindowsDaemonRunner(wayDir, launch, resticBin) {
+  for (const [name, value] of Object.entries({ wayDir, command: launch.command, resticBin })) {
+    if (value) assertSafeCmdValue(value, name);
+  }
+  for (const arg of launch.args) assertSafeCmdValue(arg, "daemon argument");
+  const setRestic = resticBin ? `set "WAY_RESTIC_BIN=${resticBin}"\r
+` : "";
+  const args = launch.args.map((arg) => `"${arg.replace(/"/g, '""')}"`).join(" ");
+  const command = `"${launch.command.replace(/"/g, '""')}"`;
+  return `@echo off\r
+setlocal\r
+set "WAY_DIR=${wayDir}"\r
+${setRestic}${command} ${args}\r
+`;
+}
+function renderWindowsTaskXml(runnerPath) {
+  assertSafeCmdValue(runnerPath, "runner path");
+  const argumentsValue = `/d /s /c ""${runnerPath}""`;
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo><Description>Way Backup Daemon</Description></RegistrationInfo>
+  <Triggers><BootTrigger><Enabled>true</Enabled><Delay>PT30S</Delay></BootTrigger></Triggers>
+  <Principals><Principal id="Author"><UserId>S-1-5-18</UserId><RunLevel>HighestAvailable</RunLevel></Principal></Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy><DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries><StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate><StartWhenAvailable>true</StartWhenAvailable><RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand><Enabled>true</Enabled><Hidden>true</Hidden><RunOnlyIfIdle>false</RunOnlyIfIdle><WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit><Priority>7</Priority><RestartOnFailure><Interval>PT1M</Interval><Count>3</Count></RestartOnFailure>
+  </Settings>
+  <Actions Context="Author"><Exec><Command>cmd.exe</Command><Arguments>${xmlEscape(argumentsValue)}</Arguments></Exec></Actions>
+</Task>`;
+}
+function resolveResticPath(env, run) {
+  if (env.WAY_RESTIC_BIN) return env.WAY_RESTIC_BIN;
+  try {
+    return run("where.exe", ["restic.exe"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim().split(/\r?\n/)[0];
+  } catch {
+    return void 0;
+  }
+}
+async function windowsService(options, dependencies = {}) {
+  const platform = dependencies.platform ?? process.platform;
+  assertWindows(platform);
+  const env = dependencies.env ?? process.env;
+  const run = dependencies.execFileSync ?? execFileSync;
+  const writeFile = dependencies.writeFileSync ?? fs6.writeFileSync;
+  const unlink = dependencies.unlinkSync ?? fs6.unlinkSync;
+  const exists = dependencies.existsSync ?? fs6.existsSync;
+  const makeTempDir = dependencies.mkdtempSync ?? fs6.mkdtempSync;
+  const wayDir = env.WAY_DIR || path7.join(os2.homedir(), ".way");
+  const runnerPath = path7.join(wayDir, WINDOWS_RUNNER_NAME);
+  const launch = resolveDaemonLaunch({ env, argv: dependencies.argv, execPath: dependencies.execPath });
+  const runner = renderWindowsDaemonRunner(wayDir, launch, resolveResticPath(env, run));
+  const taskXml = renderWindowsTaskXml(runnerPath);
+  if (options.action === "show") {
+    console.log(`=== ${WINDOWS_TASK_NAME} ===`);
+    console.log(taskXml);
+    console.log(`=== ${runnerPath} ===`);
+    console.log(runner);
+    return;
+  }
+  if (options.action === "install") {
+    loadConfig(wayDir, options.remote);
+    fs6.mkdirSync(wayDir, { recursive: true });
+    writeFile(runnerPath, runner, { encoding: "utf8" });
+    const tempDir = makeTempDir(path7.join(os2.tmpdir(), "way-windows-service-"));
+    const xmlPath = path7.join(tempDir, "way-backup.xml");
+    try {
+      writeFile(xmlPath, `\uFEFF${taskXml}`, { encoding: "utf16le" });
+      run("schtasks.exe", ["/Create", "/TN", WINDOWS_TASK_NAME, "/XML", xmlPath, "/F"], { stdio: "inherit" });
+      run("schtasks.exe", ["/Run", "/TN", WINDOWS_TASK_NAME], { stdio: "inherit" });
+      console.log("Windows Way daemon task installed and started");
+    } finally {
+      if (exists(xmlPath)) unlink(xmlPath);
+      try {
+        fs6.rmdirSync(tempDir);
+      } catch {
+      }
+    }
+    return;
+  }
+  if (options.action === "uninstall") {
+    try {
+      run("schtasks.exe", ["/End", "/TN", WINDOWS_TASK_NAME], { stdio: "ignore" });
+    } catch {
+    }
+    try {
+      run("schtasks.exe", ["/Delete", "/TN", WINDOWS_TASK_NAME, "/F"], { stdio: "inherit" });
+    } catch {
+    }
+    if (exists(runnerPath)) unlink(runnerPath);
+    console.log("Windows Way daemon task uninstalled");
+    return;
+  }
+  run("schtasks.exe", ["/Query", "/TN", WINDOWS_TASK_NAME, "/FO", "LIST", "/V"], { stdio: "inherit" });
+}
+
 // src/commands/daemon.ts
 import cron from "node-cron";
 var isRunning = false;
 var taskQueue = [];
+var CRON_OPTIONS = {
+  missedExecutionTolerance: 5e3
+};
 function resolveProjectSchedule(project, defaults = {}) {
   if (project.schedule !== void 0) return project.schedule;
   return defaults?.schedule ?? false;
@@ -575,7 +879,7 @@ async function daemon(options) {
         console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running backup: ${projects.join(", ")}`);
         await backup({ remote: options.remote, projects });
       });
-    });
+    }, CRON_OPTIONS);
     console.log(`Scheduled backup for ${projects.join(", ")}: ${schedule}`);
   }
   const pruneSchedule = config.rules.maintenance?.prune?.schedule;
@@ -586,7 +890,7 @@ async function daemon(options) {
         console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running prune`);
         await gc({ remote: options.remote, dryRun: false });
       });
-    });
+    }, CRON_OPTIONS);
     console.log(`Scheduled prune: ${pruneSchedule}`);
   }
   const checkSchedule = config.rules.maintenance?.check?.schedule;
@@ -596,7 +900,7 @@ async function daemon(options) {
       executeTask(async () => {
         console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running check`);
       });
-    });
+    }, CRON_OPTIONS);
     console.log(`Scheduled check: ${checkSchedule}`);
   }
   process.on("SIGTERM", () => {
@@ -611,7 +915,7 @@ async function daemon(options) {
 
 // src/cli.ts
 var program = new Command();
-program.name("way").version("0.6.9").description("\u7B56\u7565\u5907\u4EFD\u5DE5\u5177 - \u57FA\u4E8E restic \u7684\u7B56\u7565\u5C01\u88C5").option("--remote <name>", "\u6307\u5B9A\u4ED3\u5E93", "default").addHelpText("after", `
+program.name("way").version("0.6.11").description("\u7B56\u7565\u5907\u4EFD\u5DE5\u5177 - \u57FA\u4E8E restic \u7684\u7B56\u7565\u5C01\u88C5").option("--remote <name>", "\u6307\u5B9A\u4ED3\u5E93", "default").addHelpText("after", `
 \u793A\u4F8B:
   $ way backup                 \u6267\u884C\u6240\u6709\u9879\u76EE\u5907\u4EFD
   $ way backup data            \u53EA\u5907\u4EFD data \u9879\u76EE
@@ -634,6 +938,9 @@ program.name("way").version("0.6.9").description("\u7B56\u7565\u5907\u4EFD\u5DE5
 function collectBackupArgs(command) {
   return command.args.filter((a) => a.startsWith("-") && !["--dry-run"].includes(a));
 }
+function resolveRemote(command) {
+  return command.optsWithGlobals().remote;
+}
 var commonHelpText = `
 \u5168\u5C40\u7528\u6CD5:
   way --remote=oss <command> ...  \u6307\u5B9A\u4ED3\u5E93\uFF08\u5168\u5C40\u9009\u9879\u9700\u653E\u5728\u5B50\u547D\u4EE4\u524D\uFF09
@@ -645,22 +952,22 @@ var commonHelpText = `
 program.command("init").description("\u521D\u59CB\u5316 way \u914D\u7F6E\u6587\u4EF6").addHelpText("after", commonHelpText).action(() => {
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const files = ["repositories.yaml", "rules.yaml"];
-  fs6.mkdirSync(wayDir, { recursive: true });
+  fs7.mkdirSync(wayDir, { recursive: true });
   for (const file of files) {
-    const target = path6.join(wayDir, file);
-    if (fs6.existsSync(target)) {
+    const target = path8.join(wayDir, file);
+    if (fs7.existsSync(target)) {
       throw new Error(`${target} already exists, aborting to avoid overwriting existing config.`);
     }
   }
   for (const file of files) {
     const source = resolveExampleConfigPath(file);
-    const target = path6.join(wayDir, file);
-    fs6.copyFileSync(source, target);
+    const target = path8.join(wayDir, file);
+    fs7.copyFileSync(source, target);
     console.log(`Created ${target}`);
   }
 });
 program.command("backup [projects...]").description("\u6309 rules.yaml \u6267\u884C\u5907\u4EFD").option("--dry-run", "\u6A21\u62DF\u5907\u4EFD\uFF08\u4E0D\u5B9E\u9645\u5199\u5165\uFF09").addHelpText("after", commonHelpText).allowUnknownOption().allowExcessArguments().action(async function(projects) {
-  const remote = this.parent.opts().remote;
+  const remote = resolveRemote(this);
   const dryRun = this.opts().dryRun;
   const extraArgs = collectBackupArgs(this);
   const result = await backup({
@@ -672,7 +979,7 @@ program.command("backup [projects...]").description("\u6309 rules.yaml \u6267\u8
   if (result.failed.length > 0) process.exitCode = 1;
 });
 program.command("restore [projects...]").description("\u6309 rules.yaml \u6062\u590D\u9879\u76EE").requiredOption("--target <dir>", "\u6062\u590D\u76EE\u6807\u76EE\u5F55").option("--snapshot <snapshot>", "\u5FEB\u7167 ID \u6216 latest", "latest").option("--host <host>", "\u53EA\u6062\u590D\u6307\u5B9A host \u7684\u5FEB\u7167").option("--dry-run", "\u6A21\u62DF\u6062\u590D\uFF08\u4E0D\u5B9E\u9645\u5199\u5165\uFF09").option("--delete", "\u5220\u9664\u76EE\u6807\u4E2D\u5FEB\u7167\u4E0D\u5B58\u5728\u7684\u6587\u4EF6").option("-v, --verbose", "\u663E\u793A\u8BE6\u7EC6\u6062\u590D\u8BA1\u5212\uFF08\u4F20\u9012 --verbose=2 \u7ED9 restic\uFF09").addHelpText("after", commonHelpText).action(async function(projects, cmdOptions) {
-  const remote = this.parent.opts().remote;
+  const remote = resolveRemote(this);
   await restore({
     remote,
     projects,
@@ -685,15 +992,19 @@ program.command("restore [projects...]").description("\u6309 rules.yaml \u6062\u
   });
 });
 program.command("gc").description("\u6E05\u7406\u65E7\u5FEB\u7167").option("--dry-run", "\u6A21\u62DF\u6E05\u7406\uFF08\u4E0D\u5B9E\u9645\u5220\u9664\uFF09").addHelpText("after", commonHelpText).action(async function(cmdOptions) {
-  const remote = this.parent.opts().remote;
+  const remote = resolveRemote(this);
   await gc({ remote, dryRun: cmdOptions.dryRun });
 });
 program.command("systemd <action>").description("\u7BA1\u7406 systemd \u5B9A\u65F6\u4EFB\u52A1 (show|install|uninstall|status)").addHelpText("after", commonHelpText).action(async (action, options, command) => {
-  const remote = command.parent.opts().remote;
+  const remote = resolveRemote(command);
   await systemd({ remote, action });
 });
+program.command("windows-service <action>").description("\u7BA1\u7406 Windows \u539F\u751F\u5F00\u673A\u5B88\u62A4\u4EFB\u52A1 (show|install|uninstall|status)").addHelpText("after", commonHelpText).action(async (action, options, command) => {
+  const remote = resolveRemote(command);
+  await windowsService({ remote, action });
+});
 program.command("daemon").description("\u542F\u52A8\u5E38\u9A7B\u8FDB\u7A0B\uFF0C\u6309\u914D\u7F6E\u5B9A\u65F6\u6267\u884C\u5907\u4EFD").addHelpText("after", commonHelpText).action(async (options, command) => {
-  const remote = command.parent.opts().remote;
+  const remote = resolveRemote(command);
   await daemon({ remote });
 });
 program.command("env").description("\u663E\u793A\u73AF\u5883\u53D8\u91CF").addHelpText("after", commonHelpText).action(() => {
@@ -703,7 +1014,7 @@ program.command("env").description("\u663E\u793A\u73AF\u5883\u53D8\u91CF").addHe
   }
 });
 program.command("restic [args...]").description("\u663E\u5F0F\u900F\u4F20\u7ED9 restic").addHelpText("after", commonHelpText).allowUnknownOption().allowExcessArguments().action(async function(args) {
-  const remote = this.parent.opts().remote;
+  const remote = resolveRemote(this);
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, remote);
   const env = buildResticEnv(config.repository);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellus/way",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "description": "将备份作为持续运营的项目，而非一次性任务。基于 restic 的策略封装。",
   "type": "module",
   "bin": {
@@ -39,20 +39,18 @@
   },
   "homepage": "https://github.com/shellus/way#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.12.0"
   },
   "dependencies": {
-    "commander": "^14.0.3",
-    "execa": "^9.6.1",
-    "js-yaml": "^4.1.1",
-    "node-cron": "^4.2.1"
+    "commander": "^15.0.0",
+    "execa": "^10.0.1",
+    "js-yaml": "^5.3.0",
+    "node-cron": "^4.6.0"
   },
   "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.5.0",
-    "@types/node-cron": "^3.0.11",
+    "@types/node": "^22.20.1",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
   }
 }

package/rules.yaml.example

@@ -15,6 +15,9 @@ defaults:
     keep_daily: 7
     keep_weekly: 4
     keep_monthly: 6
+    # 如需按当前时间实行严格范围保留，改用以下两个字段，且不要与上述 keep_* 混用：
+    # keep_hosts: [backup-host]
+    # max_age_days: 7
 
 # Uptime Kuma 全局通知（可选，未配置项目级地址时作为回退）
 uptime_kuma:
@@ -99,5 +102,6 @@ global_excludes:
 maintenance:
   prune:
     schedule: "0 4 * * 0"  # 每周日凌晨 4 点清理
+    # retry_lock: "30m"      # 备份仍持有仓库锁时等待，避免立即失败
   check:
     schedule: false        # 不执行