@shellus/way 0.6.1 → 0.6.10

package/README.md

@@ -67,22 +67,40 @@
 
 ## 依赖
 
-- Node.js >= 18
+- Linux x64 独立发行包无需预装 Node.js、npm、Bun 或 restic
+- npm 安装方式需要 Node.js >= 18
 - Linux x64 平台内置 [restic](https://restic.net/) 0.18.1，其他平台需自行安装 restic
 
 `way` 查找 restic 的顺序：
 
 1. `WAY_RESTIC_BIN` 指定的二进制
-2. Linux x64 包内置的 restic
-3. 系统 `PATH` 中的 `restic`
+2. Linux x64 npm 包内置的 restic
+3. Linux x64 独立发行包旁边或安装目录中的 restic
+4. 系统 `PATH` 中的 `restic`
 
 ## 安装
 
+### Linux x64 独立发行包（推荐）
+
+GitHub Release 提供 Linux x64 独立发行包，安装机无需预装 Node.js、npm、Bun 或 restic：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/shellus/way/master/scripts/install.sh | sudo sh
+```
+
+默认安装位置：
+
+- `way`: `/usr/local/bin/way`
+- 内置 restic: `/usr/local/lib/way/vendor/restic/linux-x64/restic`
+- 示例配置: `/usr/local/lib/way/*.yaml.example`
+
+### npm 安装
+
 ```bash
 npm install -g @shellus/way
 ```
 
-Linux x64 用户无需额外安装 restic。如需使用自定义 restic，可设置：
+Linux x64 安装方式无需额外安装 restic。如需使用自定义 restic，可设置：
 
 ```bash
 WAY_RESTIC_BIN=/usr/local/bin/restic way restic snapshots
@@ -93,9 +111,7 @@ WAY_RESTIC_BIN=/usr/local/bin/restic way restic snapshots
 ### 1. 初始化配置
 
 ```bash
-mkdir -p ~/.way
-cp $(npm root -g)/@shellus/way/repositories.yaml.example ~/.way/repositories.yaml
-cp $(npm root -g)/@shellus/way/rules.yaml.example ~/.way/rules.yaml
+way init
 ```
 
 编辑 `~/.way/repositories.yaml` 填入实际凭证，设置权限：
@@ -108,10 +124,10 @@ chmod 600 ~/.way/repositories.yaml
 
 ```bash
 # 本地仓库
-way init
+way restic init
 
 # S3 仓库（指定其他仓库）
-way --remote=s3 init
+way --remote=s3 restic init
 ```
 
 ### 3. 配置定时备份
@@ -163,6 +179,8 @@ way restic restore abc123 --target /tmp/restore  # → restic restore abc123 --t
 way --remote=oss restic snapshots
 ```
 
+`way backup` 会继续执行本轮全部目标项目并输出汇总。全部项目成功时退出码为 `0`；任一项目失败时退出码为 `1`。
+
 ## 生命周期
 
 ```mermaid
@@ -184,8 +202,8 @@ graph LR
 配置文件默认存放在 `~/.way/`，安装后复制示例文件并填入实际值：
 
 ```bash
-cp ~/.way/repositories.yaml.example ~/.way/repositories.yaml
-cp ~/.way/rules.yaml.example ~/.way/rules.yaml
+cp /usr/local/lib/way/repositories.yaml.example ~/.way/repositories.yaml
+cp /usr/local/lib/way/rules.yaml.example ~/.way/rules.yaml
 ```
 
 也可以通过 `WAY_DIR` 环境变量指定其他目录：
@@ -200,19 +218,62 @@ WAY_DIR=/path/to/config way restic snapshots
 
 - **defaults**: 全局默认配置（schedule、retention）
 - **projects**: 备份项目配置，可覆盖默认 schedule 和 retention
+- **projects.*.hooks**: 项目级备份钩子，支持 `before_backup` 和 `after_backup`
+- **uptime_kuma.push_url**: 全局 Uptime Kuma Push 地址，作为项目未配置通知地址时的回退
+- **projects.*.uptime_kuma.push_url**: 项目级 Uptime Kuma Push 地址，优先于全局地址
 - **maintenance**: 维护任务配置（prune、check）
 - **global_excludes**: 全局排除规则
 
+项目级钩子用于在 restic 备份前后执行一致性快照、校验或清理脚本：
+
+```yaml
+projects:
+  data:
+    paths:
+      - /path/to/data
+    hooks:
+      before_backup:
+        - run: /path/to/scripts/prepare-data-backup.sh
+          timeout: "10m"
+      after_backup:
+        - run: /path/to/scripts/verify-data-backup.sh
+          timeout: "5m"
+```
+
+`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
+uptime_kuma:
+  push_url: "https://uptime.example.com/api/push/global-placeholder"
+
+projects:
+  data:
+    paths: [/data]
+    uptime_kuma:
+      push_url: "https://uptime.example.com/api/push/data-placeholder"
+
+  root:
+    paths: [/root]
+    uptime_kuma:
+      push_url: "https://uptime.example.com/api/push/system-placeholder"
+```
+
+每个项目优先使用项目级 Push 地址，未配置时回退到全局地址。一次 `way backup` 中使用相同有效地址的项目只发送一条汇总通知；同组任一项目失败时状态为 DOWN，不同地址的通知互不覆盖。`--dry-run` 不发送通知，通知请求失败只记录错误，不改变备份结果。
+
 **项目级调度示例**：
 
 ```yaml
 defaults:
-  schedule: "0 */2 * * *"  # 默认每 2 小时
+  schedule: false  # 默认不自动调度
 
 projects:
   data:
     paths: [/data]
-    # 继承默认 schedule
+    schedule: "0 */2 * * *"  # 每 2 小时
 
   logs:
     paths: [/var/log]
@@ -220,20 +281,57 @@ projects:
 
   archive:
     paths: [/archive]
-    schedule: "0 2 * * 0"  # 每周日凌晨 2 点
+    schedule: false  # 只手动触发：way backup archive
     retention:
       keep_weekly: 8
       keep_monthly: 12
 ```
 
+**手动备份匹配目录示例**：
+
+日常备份可排除可重建依赖目录，避免遍历海量小文件：
+
+```yaml
+projects:
+  data:
+    paths: [/data]
+    excludes:
+      - node_modules
+      - vendor
+    schedule: "0 */2 * * *"
+```
+
+如果需要偶尔保留依赖目录，可单独配置只手动触发的项目：
+
+```yaml
+projects:
+  data_deps:
+    paths: [/data]
+    include_dirs:
+      - www/xhj/*/node_modules
+      - www/xhj/*/vendor
+    schedule: false
+```
+
+手动执行：
+
+```bash
+way backup data_deps
+```
+
+`include_dirs` 是相对 `paths` 的目录 glob，只支持路径段中的 `*`，不支持绝对路径和 `**`。命中目录后，`way` 会把该目录作为备份根路径写入临时 `--files-from` 列表。`include_dirs` 是专用模式，不应用 `global_excludes`，也不能同时配置项目级 `excludes`。
+
 **schedule 语法**（node-cron 格式）：
 
+`schedule` 支持 node-cron 字符串或 `false`。`false` 表示不创建自动调度任务，只能通过 `way backup <project>` 或 `way backup` 手动触发。项目未设置 `schedule` 时继承 `defaults.schedule`；如果全局和项目都未设置，则不自动调度。
+
 | 格式 | 说明 | 示例 |
 |------|------|------|
 | `"0 */2 * * *"` | 间隔表达式 | 每 2 小时 |
 | `"0 9,15,21 * * *"` | 多个时间点（逗号） | 每天 9:00、15:00、21:00 |
 | `"0 9-17 * * 1-5"` | 时间范围 | 工作日 9:00-17:00 每小时 |
 | `"*/30 * * * *"` | 分钟间隔 | 每 30 分钟 |
+| `false` | 禁用自动调度 | 只手动备份 |
 
 #### 排除规则通配符语法
 
@@ -364,4 +462,4 @@ way --remote=oss restic restore <snapshot-id> --target /tmp/restore
 - 变更规范和测试要求
 - 发布流程
 
-内部开发参考：[CLAUDE.md](CLAUDE.md)
+项目维护规则：[AGENTS.md](AGENTS.md)

package/dist/cli.js

@@ -2,6 +2,8 @@
 
 // src/cli.ts
 import { Command } from "commander";
+import fs6 from "fs";
+import path6 from "path";
 
 // src/core/config.ts
 import fs from "fs";
@@ -23,6 +25,8 @@ function loadConfig(wayDir, remoteName) {
 
 // src/core/restic.ts
 import { execa } from "execa";
+import fs3 from "fs";
+import path3 from "path";
 
 // src/core/restic-bin.ts
 import fs2 from "fs";
@@ -31,6 +35,34 @@ import { fileURLToPath } from "url";
 function getBundledResticBin(packageRoot) {
   return path2.join(packageRoot, "vendor/restic/linux-x64/restic");
 }
+function getStandaloneResticBinCandidates(executablePath) {
+  const binDir = path2.dirname(executablePath);
+  const archiveRoot = path2.dirname(binDir);
+  const prefixRoot = path2.dirname(binDir);
+  return [
+    path2.join(archiveRoot, "vendor/restic/linux-x64/restic"),
+    path2.join(prefixRoot, "lib/way/vendor/restic/linux-x64/restic")
+  ];
+}
+function getExampleConfigCandidates(file, packageRoot, executablePath) {
+  const binDir = path2.dirname(executablePath);
+  const archiveRoot = path2.dirname(binDir);
+  const prefixRoot = path2.dirname(binDir);
+  return [
+    path2.join(packageRoot, `${file}.example`),
+    path2.join(archiveRoot, `${file}.example`),
+    path2.join(prefixRoot, "lib/way", `${file}.example`)
+  ];
+}
+function resolveExampleConfigPath(file, options = {}) {
+  const packageRoot = options.packageRoot ?? findPackageRoot();
+  const executablePath = options.executablePath ?? process.execPath;
+  const existsSync = options.existsSync ?? fs2.existsSync;
+  for (const candidate of getExampleConfigCandidates(file, packageRoot, executablePath)) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(`Unable to find ${file}.example`);
+}
 function findPackageRoot(startDir = path2.dirname(fileURLToPath(import.meta.url))) {
   let current = startDir;
   while (true) {
@@ -45,11 +77,15 @@ function resolveResticBin(options = {}) {
   const platform = options.platform ?? process.platform;
   const arch = options.arch ?? process.arch;
   const packageRoot = options.packageRoot ?? findPackageRoot();
+  const executablePath = options.executablePath ?? process.execPath;
   const existsSync = options.existsSync ?? fs2.existsSync;
   if (env.WAY_RESTIC_BIN) return env.WAY_RESTIC_BIN;
   if (platform === "linux" && arch === "x64") {
     const bundled = getBundledResticBin(packageRoot);
     if (existsSync(bundled)) return bundled;
+    for (const candidate of getStandaloneResticBinCandidates(executablePath)) {
+      if (existsSync(candidate)) return candidate;
+    }
   }
   return "restic";
 }
@@ -73,13 +109,75 @@ function buildResticEnv(repo) {
   if (repo.credentials.secret_access_key) env.AWS_SECRET_ACCESS_KEY = repo.credentials.secret_access_key;
   return env;
 }
-function buildBackupArgs(name, project, globalExcludes) {
+function buildBackupArgs(name, project, globalExcludes, filesFrom) {
   const args = ["backup", `--tag=way:${name}`];
+  if (project.include_dirs?.length) {
+    if (project.excludes?.length) {
+      throw new Error(`Project ${name} cannot use excludes with include_dirs`);
+    }
+    if (!filesFrom) throw new Error(`Project ${name} uses include_dirs but no files-from list was provided`);
+    args.push(`--files-from=${filesFrom}`);
+    return args;
+  }
   const allExcludes = [...globalExcludes, ...project.excludes || []];
   for (const exclude of allExcludes) args.push(`--exclude=${exclude}`);
   args.push(...project.paths);
   return args;
 }
+function collectIncludeDirs(paths, includeDirs, options = {}) {
+  const readdirSync = options.readdirSync ?? ((dir) => fs3.readdirSync(dir, { withFileTypes: true }));
+  const matches = [];
+  function isDirectoryEntry(entry) {
+    return typeof entry.isDirectory === "function" ? entry.isDirectory() : entry.isDirectory;
+  }
+  function readDirectoryEntries(dir) {
+    try {
+      return readdirSync(dir);
+    } catch (error) {
+      console.error(`Failed to scan ${dir}:`, error);
+      return [];
+    }
+  }
+  function validatePattern(pattern) {
+    if (path3.isAbsolute(pattern)) {
+      throw new Error(`include_dirs pattern must be relative to project paths: ${pattern}`);
+    }
+    if (pattern.split("/").includes("**")) {
+      throw new Error(`include_dirs does not support **: ${pattern}`);
+    }
+  }
+  function matchSegment(name, pattern) {
+    if (pattern === "*") return true;
+    if (!pattern.includes("*")) return name === pattern;
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*");
+    return new RegExp(`^${escaped}$`).test(name);
+  }
+  function expandPattern(root, pattern) {
+    const segments = pattern.split("/").filter(Boolean);
+    let candidates = [path3.resolve(root)];
+    for (const segment of segments) {
+      const nextCandidates = [];
+      for (const candidate of candidates) {
+        const entries = readDirectoryEntries(candidate);
+        for (const entry of entries) {
+          if (!isDirectoryEntry(entry)) continue;
+          if (!matchSegment(entry.name, segment)) continue;
+          nextCandidates.push(path3.join(candidate, entry.name));
+        }
+      }
+      candidates = nextCandidates;
+      if (candidates.length === 0) break;
+    }
+    return candidates;
+  }
+  for (const pattern of includeDirs) validatePattern(pattern);
+  for (const sourcePath of paths) {
+    for (const pattern of includeDirs) {
+      matches.push(...expandPattern(sourcePath, pattern));
+    }
+  }
+  return Array.from(new Set(matches));
+}
 function buildRestoreArgs(name, project, options) {
   const args = [
     "restore",
@@ -88,7 +186,7 @@ function buildRestoreArgs(name, project, options) {
   ];
   if (options.host) args.push(`--host=${options.host}`);
   args.push(`--target=${options.target}`);
-  for (const path4 of project.paths) args.push(`--include=${path4}`);
+  for (const path7 of project.paths) args.push(`--include=${path7}`);
   if (options.dryRun) args.push("--dry-run");
   if (options.delete) args.push("--delete");
   if (options.verbose) args.push("--verbose=2");
@@ -115,6 +213,10 @@ async function execRestic(args, env, s3Options = []) {
 }
 
 // src/commands/backup.ts
+import fs4 from "fs";
+import os from "os";
+import path4 from "path";
+import { execaCommand } from "execa";
 async function backup(options) {
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, options.remote);
@@ -126,35 +228,182 @@ async function backup(options) {
   const extraArgs = options.extraArgs?.filter((arg) => arg !== "--dry-run") || [];
   const succeeded = [];
   const failed = [];
+  const projectResults = [];
   const startTime = Date.now();
   for (const projectName of projects) {
+    const projectStartTime = Date.now();
     const project = config.rules.projects[projectName];
+    const pushUrl = resolveUptimeKumaPushUrl(project, config.rules.uptime_kuma?.push_url);
     if (!project) {
       console.error(`Project not found: ${projectName}`);
       failed.push(projectName);
+      projectResults.push({
+        succeeded: [],
+        failed: [projectName],
+        duration: Date.now() - projectStartTime,
+        pushUrl
+      });
       continue;
     }
     console.log(`=== Backing up: ${projectName} ===`);
+    let filesFrom;
+    let projectSucceeded = false;
     try {
-      const args = buildBackupArgs(projectName, project, globalExcludes);
+      await runProjectHooks(project.hooks?.before_backup, {
+        projectName,
+        remote: options.remote,
+        wayDir,
+        dryRun,
+        label: "before_backup"
+      });
+      if (project.include_dirs?.length) {
+        const includedDirs = collectIncludeDirs(project.paths, project.include_dirs);
+        if (includedDirs.length === 0) {
+          console.log(`No include_dirs matched for ${projectName}`);
+          succeeded.push(projectName);
+          projectSucceeded = true;
+          continue;
+        }
+        filesFrom = path4.join(os.tmpdir(), `way-${projectName}-${Date.now()}-${process.pid}.files`);
+        fs4.writeFileSync(filesFrom, `${includedDirs.join("\n")}
+`);
+      }
+      const args = buildBackupArgs(projectName, project, globalExcludes, filesFrom);
       if (dryRun) args.push("--dry-run");
       args.push(...extraArgs);
       await execRestic(args, env, s3Options);
+      await runProjectHooks(project.hooks?.after_backup, {
+        projectName,
+        remote: options.remote,
+        wayDir,
+        dryRun,
+        label: "after_backup"
+      });
       succeeded.push(projectName);
+      projectSucceeded = true;
     } catch (error) {
       console.error(`Failed to backup ${projectName}:`, error);
       failed.push(projectName);
+    } finally {
+      if (filesFrom) fs4.rmSync(filesFrom, { force: true });
+      projectResults.push({
+        succeeded: projectSucceeded ? [projectName] : [],
+        failed: projectSucceeded ? [] : [projectName],
+        duration: Date.now() - projectStartTime,
+        pushUrl
+      });
     }
   }
   const duration = Date.now() - startTime;
   console.log("\n=== Summary ===");
   if (succeeded.length > 0) console.log("Succeeded:", succeeded.join(", "));
   if (failed.length > 0) console.log("Failed:", failed.join(", "));
-  if (!dryRun && config.rules.uptime_kuma?.push_url) {
-    await notifyUptimeKuma({ succeeded, failed, duration }, config.rules.uptime_kuma.push_url);
+  if (!dryRun) {
+    for (const [pushUrl, result] of groupUptimeKumaResults(projectResults)) {
+      await notifyUptimeKuma(result, pushUrl);
+    }
   }
   return { succeeded, failed, duration };
 }
+function resolveUptimeKumaPushUrl(project, globalPushUrl) {
+  return project?.uptime_kuma?.push_url || globalPushUrl;
+}
+function groupUptimeKumaResults(projectResults) {
+  const groupedResults = /* @__PURE__ */ new Map();
+  for (const projectResult of projectResults) {
+    if (!projectResult.pushUrl) continue;
+    const result = groupedResults.get(projectResult.pushUrl) || {
+      succeeded: [],
+      failed: [],
+      duration: 0
+    };
+    result.succeeded.push(...projectResult.succeeded);
+    result.failed.push(...projectResult.failed);
+    result.duration += projectResult.duration;
+    groupedResults.set(projectResult.pushUrl, result);
+  }
+  return groupedResults;
+}
+var HOOK_FORCE_KILL_DELAY_MS = 1e3;
+function normalizeHook(hook) {
+  if (typeof hook === "string") return { run: hook };
+  return hook;
+}
+function parseTimeout(timeout) {
+  if (timeout === void 0) return void 0;
+  if (typeof timeout === "number") return timeout;
+  const match = timeout.match(/^(\d+)(ms|s|m|h)?$/);
+  if (!match) throw new Error(`Invalid hook timeout: ${timeout}`);
+  const value = Number(match[1]);
+  const unit = match[2] || "ms";
+  switch (unit) {
+    case "ms":
+      return value;
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 60 * 1e3;
+    case "h":
+      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) {
+    const normalized = normalizeHook(hook);
+    if (!normalized.run) throw new Error(`Project ${context.projectName} has an empty ${context.label} hook`);
+    if (context.dryRun) {
+      console.log(`[dry-run] ${context.label}: ${normalized.run}`);
+      continue;
+    }
+    console.log(`Running ${context.label} hook for ${context.projectName}: ${normalized.run}`);
+    const subprocess = execaCommand(normalized.run, {
+      shell: true,
+      stdio: "inherit",
+      timeout: parseTimeout(normalized.timeout),
+      detached: process.platform !== "win32",
+      env: {
+        WAY_PROJECT: context.projectName,
+        WAY_REMOTE: context.remote,
+        WAY_DIR: context.wayDir,
+        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) {
   const status = result.failed.length > 0 ? "down" : "up";
   const msg = `Succeeded: ${result.succeeded.length}, Failed: ${result.failed.length}`;
@@ -240,12 +489,22 @@ async function gc(options) {
 
 // src/commands/systemd.ts
 import { execSync } from "child_process";
-import fs3 from "fs";
-import path3 from "path";
+import fs5 from "fs";
+import path5 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];
+  return whichWay();
+}
 async function systemd(options) {
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, options.remote);
-  const wayPath = execSync("which way", { encoding: "utf-8" }).trim();
+  const wayPath = resolveWayCommandPath();
   const currentUser = execSync("whoami", { encoding: "utf-8" }).trim();
   const serviceContent = `[Unit]
 Description=Way Backup Daemon
@@ -269,9 +528,9 @@ WantedBy=multi-user.target
     return;
   }
   const systemdDir = "/etc/systemd/system";
-  const servicePath = path3.join(systemdDir, "way-backup.service");
+  const servicePath = path5.join(systemdDir, "way-backup.service");
   if (options.action === "install") {
-    fs3.writeFileSync(servicePath, serviceContent);
+    fs5.writeFileSync(servicePath, serviceContent);
     execSync("systemctl daemon-reload");
     execSync("systemctl enable way-backup.service");
     execSync("systemctl start way-backup.service");
@@ -287,7 +546,7 @@ WantedBy=multi-user.target
       execSync("systemctl disable way-backup.service", { stdio: "ignore" });
     } catch {
     }
-    if (fs3.existsSync(servicePath)) fs3.unlinkSync(servicePath);
+    if (fs5.existsSync(servicePath)) fs5.unlinkSync(servicePath);
     execSync("systemctl daemon-reload");
     console.log("Systemd service uninstalled");
   }
@@ -300,6 +559,23 @@ WantedBy=multi-user.target
 import cron from "node-cron";
 var isRunning = false;
 var taskQueue = [];
+function resolveProjectSchedule(project, defaults = {}) {
+  if (project.schedule !== void 0) return project.schedule;
+  return defaults?.schedule ?? false;
+}
+function isEnabledSchedule(schedule) {
+  return typeof schedule === "string";
+}
+function assertValidSchedule(schedule, label) {
+  if (schedule === "") {
+    throw new Error(`${label} must be a cron expression or false. Use false to disable scheduling.`);
+  }
+}
+function addScheduledBackup(scheduledBackups, schedule, projectName) {
+  const projects = scheduledBackups.get(schedule) || [];
+  projects.push(projectName);
+  scheduledBackups.set(schedule, projects);
+}
 async function executeTask(task) {
   taskQueue.push(task);
   if (isRunning) return;
@@ -318,18 +594,28 @@ async function daemon(options) {
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, options.remote);
   console.log("Way daemon started");
+  const scheduledBackups = /* @__PURE__ */ new Map();
   for (const [name, project] of Object.entries(config.rules.projects)) {
-    const schedule = project.schedule || config.rules.defaults?.schedule || "0 */2 * * *";
+    const schedule = resolveProjectSchedule(project, config.rules.defaults);
+    assertValidSchedule(schedule, `projects.${name}.schedule`);
+    if (!isEnabledSchedule(schedule)) {
+      console.log(`Skipped scheduled backup for ${name}`);
+      continue;
+    }
+    addScheduledBackup(scheduledBackups, schedule, name);
+  }
+  for (const [schedule, projects] of scheduledBackups.entries()) {
     cron.schedule(schedule, () => {
       executeTask(async () => {
-        console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running backup: ${name}`);
-        await backup({ remote: options.remote, projects: [name] });
+        console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running backup: ${projects.join(", ")}`);
+        await backup({ remote: options.remote, projects });
       });
     });
-    console.log(`Scheduled backup for ${name}: ${schedule}`);
+    console.log(`Scheduled backup for ${projects.join(", ")}: ${schedule}`);
   }
   const pruneSchedule = config.rules.maintenance?.prune?.schedule;
-  if (pruneSchedule) {
+  assertValidSchedule(pruneSchedule, "maintenance.prune.schedule");
+  if (isEnabledSchedule(pruneSchedule)) {
     cron.schedule(pruneSchedule, () => {
       executeTask(async () => {
         console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running prune`);
@@ -339,7 +625,8 @@ async function daemon(options) {
     console.log(`Scheduled prune: ${pruneSchedule}`);
   }
   const checkSchedule = config.rules.maintenance?.check?.schedule;
-  if (checkSchedule) {
+  assertValidSchedule(checkSchedule, "maintenance.check.schedule");
+  if (isEnabledSchedule(checkSchedule)) {
     cron.schedule(checkSchedule, () => {
       executeTask(async () => {
         console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running check`);
@@ -359,30 +646,67 @@ async function daemon(options) {
 
 // src/cli.ts
 var program = new Command();
-program.name("way").version("0.6.1").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.10").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
   $ way backup --dry-run       \u6A21\u62DF\u5907\u4EFD\uFF08\u4E0D\u5B9E\u9645\u5199\u5165\uFF09
   $ way restore data --target /tmp/restore --dry-run
+  $ way --remote=oss backup    \u4F7F\u7528 oss \u4ED3\u5E93\u6267\u884C\u5907\u4EFD\uFF08\u5168\u5C40\u9009\u9879\u9700\u653E\u5728\u5B50\u547D\u4EE4\u524D\uFF09
+  $ way init                   \u521D\u59CB\u5316 way \u914D\u7F6E\u6587\u4EF6
   $ way gc                     \u6E05\u7406\u65E7\u5FEB\u7167
   $ way systemd install        \u5B89\u88C5\u5B9A\u65F6\u4EFB\u52A1
   $ way restic snapshots       \u67E5\u770B\u5FEB\u7167\u5217\u8868
   $ way restic restore abc123 --target /tmp/restore
   $ way --remote=s3 restic snapshots  \u4F7F\u7528 s3 \u4ED3\u5E93
 
+\u73AF\u5883\u53D8\u91CF:
+  WAY_DIR=/path/to/config      \u6307\u5B9A\u914D\u7F6E\u76EE\u5F55\uFF08\u9ED8\u8BA4: ~/.way\uFF09
+  WAY_RESTIC_BIN=/path/restic  \u6307\u5B9A restic \u4E8C\u8FDB\u5236\uFF0C\u4F18\u5148\u4E8E\u5185\u7F6E restic \u548C PATH
+
 \u6587\u6863: https://github.com/shellus/way
 `);
 function collectBackupArgs(command) {
   return command.args.filter((a) => a.startsWith("-") && !["--dry-run"].includes(a));
 }
-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").allowUnknownOption().allowExcessArguments().action(async function(projects) {
+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
+
+\u73AF\u5883\u53D8\u91CF:
+  WAY_DIR=/path/to/config         \u6307\u5B9A\u914D\u7F6E\u76EE\u5F55\uFF08\u9ED8\u8BA4: ~/.way\uFF09
+  WAY_RESTIC_BIN=/path/restic     \u6307\u5B9A restic \u4E8C\u8FDB\u5236\uFF0C\u4F18\u5148\u4E8E\u5185\u7F6E restic \u548C PATH
+`;
+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 });
+  for (const file of files) {
+    const target = path6.join(wayDir, file);
+    if (fs6.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);
+    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 dryRun = this.opts().dryRun;
   const extraArgs = collectBackupArgs(this);
-  await backup({ remote, projects: projects.filter((p) => !p.startsWith("-")), extraArgs, dryRun });
+  const result = await backup({
+    remote,
+    projects: projects.filter((p) => !p.startsWith("-")),
+    extraArgs,
+    dryRun
+  });
+  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").action(async function(projects, cmdOptions) {
+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;
   await restore({
     remote,
@@ -395,25 +719,25 @@ program.command("restore [projects...]").description("\u6309 rules.yaml \u6062\u
     verbose: cmdOptions.verbose
   });
 });
-program.command("gc").description("\u6E05\u7406\u65E7\u5FEB\u7167").option("--dry-run", "\u6A21\u62DF\u6E05\u7406\uFF08\u4E0D\u5B9E\u9645\u5220\u9664\uFF09").action(async function(cmdOptions) {
+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;
   await gc({ remote, dryRun: cmdOptions.dryRun });
 });
-program.command("systemd <action>").description("\u7BA1\u7406 systemd \u5B9A\u65F6\u4EFB\u52A1 (show|install|uninstall|status)").action(async (action, options, command) => {
+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;
   await systemd({ remote, action });
 });
-program.command("daemon").description("\u542F\u52A8\u5E38\u9A7B\u8FDB\u7A0B\uFF0C\u6309\u914D\u7F6E\u5B9A\u65F6\u6267\u884C\u5907\u4EFD").action(async (options, command) => {
+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;
   await daemon({ remote });
 });
-program.command("env").description("\u663E\u793A\u73AF\u5883\u53D8\u91CF").action(() => {
+program.command("env").description("\u663E\u793A\u73AF\u5883\u53D8\u91CF").addHelpText("after", commonHelpText).action(() => {
   const env = Object.entries(process.env).sort(([a], [b]) => a.localeCompare(b));
   for (const [key, value] of env) {
     console.log(`${key}=${value}`);
   }
 });
-program.command("restic [args...]").description("\u663E\u5F0F\u900F\u4F20\u7ED9 restic").allowUnknownOption().allowExcessArguments().action(async function(args) {
+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 wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, remote);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellus/way",
-  "version": "0.6.1",
+  "version": "0.6.10",
   "description": "将备份作为持续运营的项目，而非一次性任务。基于 restic 的策略封装。",
   "type": "module",
   "bin": {
@@ -8,6 +8,8 @@
   },
   "scripts": {
     "build": "tsup src/cli.ts --format esm --clean",
+    "build:standalone": "bun build src/cli.ts --compile --target=bun-linux-x64-baseline --outfile dist/standalone/way",
+    "package:linux-x64": "npm run build:standalone && node scripts/package-release.mjs",
     "dev": "tsup src/cli.ts --format esm --watch",
     "test": "vitest",
     "test:run": "vitest run",

package/rules.yaml.example

@@ -5,19 +5,20 @@
 # 全局默认配置
 defaults:
   # schedule 使用 node-cron 语法（分 时 日 月 周）
+  # 设置为 false 表示不自动调度，只允许手动执行 way backup
   # 支持多种表达方式：
   #   "0 */2 * * *"      - 每 2 小时
   #   "0 9,15,21 * * *"  - 每天 9:00、15:00、21:00
   #   "0 9-17 * * 1-5"   - 工作日 9:00-17:00 每小时
-  schedule: "0 */2 * * *"
+  schedule: false
   retention:
     keep_daily: 7
     keep_weekly: 4
     keep_monthly: 6
 
-# Uptime Kuma 通知（备份完成后推送状态）
+# Uptime Kuma 全局通知（可选，未配置项目级地址时作为回退）
 uptime_kuma:
-  push_url: "https://uptime.example.com/api/push/xxxxx"
+  push_url: "https://uptime.example.com/api/push/global-placeholder"
 
 # 备份项目
 projects:
@@ -25,6 +26,17 @@ projects:
     description: 数据目录
     paths:
       - /path/to/data
+    schedule: "0 */2 * * *"  # 每 2 小时自动备份
+    # 项目级地址优先于全局地址；相同地址的项目会合并为一条通知
+    uptime_kuma:
+      push_url: "https://uptime.example.com/api/push/data-placeholder"
+    hooks:
+      before_backup:
+        - run: /path/to/scripts/prepare-data-backup.sh
+          timeout: "10m"
+      after_backup:
+        - run: /path/to/scripts/verify-data-backup.sh
+          timeout: "5m"
     excludes:
       - cache
       - tmp
@@ -41,13 +53,22 @@ projects:
     description: 历史归档
     paths:
       - /archive
-    schedule: "0 2 * * 0"  # 每周日凌晨 2 点
+    schedule: false  # 只手动触发：way backup archive
     retention:
       keep_weekly: 8
       keep_monthly: 12
       keep_yearly: 3
     excludes: []
 
+  data_deps:
+    description: 手动备份 /path/to/data 下所有依赖目录
+    paths:
+      - /path/to/data
+    include_dirs:
+      - www/xhj/*/node_modules
+      - www/xhj/*/vendor
+    schedule: false  # 只手动触发：way backup data_deps
+
 # 全局排除规则 - 适用于所有项目
 global_excludes:
   # 包管理
@@ -79,4 +100,4 @@ maintenance:
   prune:
     schedule: "0 4 * * 0"  # 每周日凌晨 4 点清理
   check:
-    schedule: ""           # 留空不执行
+    schedule: false        # 不执行