@shellus/way 0.5.1 → 0.6.0

package/README.md

@@ -67,8 +67,14 @@
 
 ## 依赖
 
-- [restic](https://restic.net/) - 备份引擎
 - 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`
 
 ## 安装
 
@@ -76,6 +82,12 @@
 npm install -g @shellus/way
 ```
 
+Linux x64 用户无需额外安装 restic。如需使用自定义 restic，可设置：
+
+```bash
+WAY_RESTIC_BIN=/usr/local/bin/restic way restic snapshots
+```
+
 ## 快速开始
 
 ### 1. 初始化配置
@@ -112,18 +124,23 @@ way systemd status
 ### 4. 手动执行备份
 
 ```bash
-way run              # 备份所有项目
-way run data         # 只备份 data 项目
-way snapshots        # 查看快照
+way backup           # 备份所有项目
+way backup data      # 只备份 data 项目
+way restore data --target /tmp/restore --dry-run  # 按规则预演恢复
+way restic snapshots # 查看快照
 ```
 
 ## 命令参考
 
 ```bash
 # 备份命令
-way run                 # 执行所有项目备份
-way run data            # 只备份 data 项目
-way run data config     # 备份多个项目
+way backup              # 执行所有项目备份
+way backup data         # 只备份 data 项目
+way backup data config  # 备份多个项目
+way backup --dry-run    # 模拟备份（不实际写入）
+way restore data --target /tmp/restore              # 按规则恢复 data 项目
+way restore data --target /tmp/restore --dry-run    # 模拟恢复
+way restore data --target /tmp/restore --delete     # 删除目标中快照不存在的文件
 way gc                  # 按 retention 策略清理旧快照
 way gc --dry-run        # 模拟清理（不实际删除）
 
@@ -136,14 +153,14 @@ way systemd show        # 显示 systemd 配置
 way systemd status      # 查看服务状态
 way systemd uninstall   # 卸载服务
 
-# 透传 restic（way 只设置环境变量）
-way snapshots           # → restic snapshots
-way restore abc123      # → restic restore abc123
-way check               # → restic check
-way stats               # → restic stats
+# 显式透传 restic（way 只设置环境变量）
+way restic snapshots    # → restic snapshots
+way restic check        # → restic check
+way restic stats        # → restic stats
+way restic restore abc123 --target /tmp/restore  # → restic restore abc123 --target /tmp/restore
 
 # 指定 repository（默认用 repositories.yaml 中的 default）
-way --remote=oss snapshots
+way --remote=oss restic snapshots
 ```
 
 ## 生命周期
@@ -174,7 +191,7 @@ cp ~/.way/rules.yaml.example ~/.way/rules.yaml
 也可以通过 `WAY_DIR` 环境变量指定其他目录：
 
 ```bash
-WAY_DIR=/path/to/config way snapshots
+WAY_DIR=/path/to/config way restic snapshots
 ```
 
 ### rules.yaml
@@ -275,42 +292,68 @@ gpg -c way-config-$(date +%Y%m%d).tar.gz
 
 ## 数据恢复
 
-way 透传所有 restic 命令，恢复数据时只需通过 way 调用 restic 的恢复相关命令。way 负责设置仓库连接和认证环境变量，无需手动配置。
+way 提供两种恢复方式：
+
+1. **按规则恢复**：使用 `way restore`，根据 `rules.yaml` 中的项目路径和 `way:<project>` 标签恢复。
+2. **原始 restic 恢复**：使用 `way restic restore`，显式透传 restic 参数。
 
 ### 1. 查看快照列表
 
 ```bash
-way snapshots                    # 列出所有快照
-way snapshots --tag=way:home     # 只看 home 项目的快照
-way snapshots --tag=way:data     # 只看 data 项目的快照
+way restic snapshots                    # 列出所有快照
+way restic snapshots --tag=way:home     # 只看 home 项目的快照
+way restic snapshots --tag=way:data     # 只看 data 项目的快照
 ```
 
 ### 2. 浏览快照内容
 
 ```bash
-way ls <snapshot-id>             # 列出快照中的所有文件
-way ls <snapshot-id> /root/.ssh  # 列出快照中指定目录的文件
-way find --snapshot <id> <filename>  # 在快照中搜索文件
+way restic ls <snapshot-id>             # 列出快照中的所有文件
+way restic ls <snapshot-id> /root/.ssh  # 列出快照中指定目录的文件
+way restic find --snapshot <id> <filename>  # 在快照中搜索文件
+```
+
+### 3. 按规则恢复项目
+
+```bash
+# 恢复 data 项目的最新快照到指定目录
+way restore data --target /tmp/restore
+
+# 恢复所有项目
+way restore --target /tmp/restore
+
+# 指定快照 ID
+way restore data --snapshot abc123 --target /tmp/restore
+
+# 预演恢复，不实际写入
+way restore data --target /tmp/restore --dry-run
+
+# 让目标目录与快照一致，先 dry-run 核对删除清单
+way restore data --target /tmp/restore --delete --dry-run
+way restore data --target /tmp/restore --delete
 ```
 
-### 3. 恢复文件
+`way restore` 会为项目自动添加 `--tag=way:<project>` 和项目 `paths` 对应的 `--include` 参数。
+
+### 4. 原始 restic 恢复
 
 ```bash
-# 恢复整个快照到指定目录
-way restore <snapshot-id> --target /tmp/restore
+# 显式透传 restic restore
+way restic restore <snapshot-id> --target /tmp/restore
 
 # 只恢复特定路径
-way restore <snapshot-id> --target /tmp/restore --include /root/.ssh
+way restic restore <snapshot-id> --target /tmp/restore --include /root/.ssh
 
 # 恢复单个文件到标准输出（适合快速查看）
-way dump <snapshot-id> /root/.gitconfig
+way restic dump <snapshot-id> /root/.gitconfig
 ```
 
-### 4. 从其他仓库恢复
+### 5. 从其他仓库恢复
 
 ```bash
-way --remote=oss snapshots
-way --remote=oss restore <snapshot-id> --target /tmp/restore
+way --remote=oss restic snapshots
+way --remote=oss restore data --target /tmp/restore
+way --remote=oss restic restore <snapshot-id> --target /tmp/restore
 ```
 
 ## 开发

package/dist/cli.js

@@ -23,6 +23,38 @@ function loadConfig(wayDir, remoteName) {
 
 // src/core/restic.ts
 import { execa } from "execa";
+
+// src/core/restic-bin.ts
+import fs2 from "fs";
+import path2 from "path";
+import { fileURLToPath } from "url";
+function getBundledResticBin(packageRoot) {
+  return path2.join(packageRoot, "vendor/restic/linux-x64/restic");
+}
+function findPackageRoot(startDir = path2.dirname(fileURLToPath(import.meta.url))) {
+  let current = startDir;
+  while (true) {
+    if (fs2.existsSync(path2.join(current, "package.json"))) return current;
+    const parent = path2.dirname(current);
+    if (parent === current) return startDir;
+    current = parent;
+  }
+}
+function resolveResticBin(options = {}) {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  const packageRoot = options.packageRoot ?? findPackageRoot();
+  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;
+  }
+  return "restic";
+}
+
+// src/core/restic.ts
 function buildResticEnv(repo) {
   const env = {};
   switch (repo.type) {
@@ -48,6 +80,19 @@ function buildBackupArgs(name, project, globalExcludes) {
   args.push(...project.paths);
   return args;
 }
+function buildRestoreArgs(name, project, options) {
+  const args = [
+    "restore",
+    options.snapshot || "latest",
+    `--tag=way:${name}`,
+    `--target=${options.target}`
+  ];
+  for (const path4 of project.paths) args.push(`--include=${path4}`);
+  if (options.dryRun) args.push("--dry-run");
+  if (options.delete) args.push("--delete");
+  if (options.verbose) args.push("--verbose=2");
+  return args;
+}
 function buildS3Options(repo) {
   const options = [];
   if (repo.options?.bucket_lookup) {
@@ -57,25 +102,27 @@ function buildS3Options(repo) {
 }
 async function execRestic(args, env, s3Options = []) {
   try {
-    await execa("restic", [...s3Options, ...args], { env: { ...process.env, ...env }, stdio: "inherit" });
+    await execa(resolveResticBin(), [...s3Options, ...args], { env: { ...process.env, ...env }, stdio: "inherit" });
   } catch (error) {
     if (error.code === "ENOENT") {
-      console.error("Error: restic not found. Please install restic first.");
-      console.error("Visit: https://restic.net/");
+      console.error("Error: restic not found. Linux x64 packages include restic; other platforms must install it first.");
+      console.error("Set WAY_RESTIC_BIN to use a custom restic binary, or visit: https://restic.net/");
       process.exit(1);
     }
     throw error;
   }
 }
 
-// src/commands/run.ts
-async function run(options) {
+// src/commands/backup.ts
+async function backup(options) {
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, options.remote);
   const env = buildResticEnv(config.repository);
   const s3Options = buildS3Options(config.repository);
   const globalExcludes = config.rules.global_excludes || [];
   const projects = options.projects && options.projects.length > 0 ? options.projects : Object.keys(config.rules.projects);
+  const dryRun = options.dryRun || options.extraArgs?.includes("--dry-run") || false;
+  const extraArgs = options.extraArgs?.filter((arg) => arg !== "--dry-run") || [];
   const succeeded = [];
   const failed = [];
   const startTime = Date.now();
@@ -89,7 +136,8 @@ async function run(options) {
     console.log(`=== Backing up: ${projectName} ===`);
     try {
       const args = buildBackupArgs(projectName, project, globalExcludes);
-      if (options.extraArgs) args.push(...options.extraArgs);
+      if (dryRun) args.push("--dry-run");
+      args.push(...extraArgs);
       await execRestic(args, env, s3Options);
       succeeded.push(projectName);
     } catch (error) {
@@ -101,7 +149,7 @@ async function run(options) {
   console.log("\n=== Summary ===");
   if (succeeded.length > 0) console.log("Succeeded:", succeeded.join(", "));
   if (failed.length > 0) console.log("Failed:", failed.join(", "));
-  if (config.rules.uptime_kuma?.push_url) {
+  if (!dryRun && config.rules.uptime_kuma?.push_url) {
     await notifyUptimeKuma({ succeeded, failed, duration }, config.rules.uptime_kuma.push_url);
   }
   return { succeeded, failed, duration };
@@ -122,6 +170,47 @@ async function notifyUptimeKuma(result, pushUrl) {
   }
 }
 
+// src/commands/restore.ts
+async function restore(options) {
+  if (!options.target) throw new Error("--target is required");
+  const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
+  const config = loadConfig(wayDir, options.remote);
+  const env = buildResticEnv(config.repository);
+  const s3Options = buildS3Options(config.repository);
+  const projects = options.projects && options.projects.length > 0 ? options.projects : Object.keys(config.rules.projects);
+  const succeeded = [];
+  const failed = [];
+  const startTime = Date.now();
+  for (const projectName of projects) {
+    const project = config.rules.projects[projectName];
+    if (!project) {
+      console.error(`Project not found: ${projectName}`);
+      failed.push(projectName);
+      continue;
+    }
+    console.log(`=== Restoring: ${projectName} ===`);
+    try {
+      const args = buildRestoreArgs(projectName, project, {
+        target: options.target,
+        snapshot: options.snapshot,
+        dryRun: options.dryRun,
+        delete: options.delete,
+        verbose: options.verbose
+      });
+      await execRestic(args, env, s3Options);
+      succeeded.push(projectName);
+    } catch (error) {
+      console.error(`Failed to restore ${projectName}:`, error);
+      failed.push(projectName);
+    }
+  }
+  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(", "));
+  return { succeeded, failed, duration };
+}
+
 // src/commands/gc.ts
 async function gc(options) {
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
@@ -149,8 +238,8 @@ async function gc(options) {
 
 // src/commands/systemd.ts
 import { execSync } from "child_process";
-import fs2 from "fs";
-import path2 from "path";
+import fs3 from "fs";
+import path3 from "path";
 async function systemd(options) {
   const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
   const config = loadConfig(wayDir, options.remote);
@@ -178,9 +267,9 @@ WantedBy=multi-user.target
     return;
   }
   const systemdDir = "/etc/systemd/system";
-  const servicePath = path2.join(systemdDir, "way-backup.service");
+  const servicePath = path3.join(systemdDir, "way-backup.service");
   if (options.action === "install") {
-    fs2.writeFileSync(servicePath, serviceContent);
+    fs3.writeFileSync(servicePath, serviceContent);
     execSync("systemctl daemon-reload");
     execSync("systemctl enable way-backup.service");
     execSync("systemctl start way-backup.service");
@@ -196,7 +285,7 @@ WantedBy=multi-user.target
       execSync("systemctl disable way-backup.service", { stdio: "ignore" });
     } catch {
     }
-    if (fs2.existsSync(servicePath)) fs2.unlinkSync(servicePath);
+    if (fs3.existsSync(servicePath)) fs3.unlinkSync(servicePath);
     execSync("systemctl daemon-reload");
     console.log("Systemd service uninstalled");
   }
@@ -232,7 +321,7 @@ async function daemon(options) {
     cron.schedule(schedule, () => {
       executeTask(async () => {
         console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running backup: ${name}`);
-        await run({ remote: options.remote, projects: [name] });
+        await backup({ remote: options.remote, projects: [name] });
       });
     });
     console.log(`Scheduled backup for ${name}: ${schedule}`);
@@ -268,23 +357,40 @@ async function daemon(options) {
 
 // src/cli.ts
 var program = new Command();
-program.name("way").version("0.5.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.0").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 run                    \u6267\u884C\u6240\u6709\u9879\u76EE\u5907\u4EFD
-  $ way run data               \u53EA\u5907\u4EFD data \u9879\u76EE
-  $ way run --dry-run          \u6A21\u62DF\u5907\u4EFD\uFF08\u4E0D\u5B9E\u9645\u5199\u5165\uFF09
+  $ 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 gc                     \u6E05\u7406\u65E7\u5FEB\u7167
   $ way systemd install        \u5B89\u88C5\u5B9A\u65F6\u4EFB\u52A1
-  $ way snapshots              \u67E5\u770B\u5FEB\u7167\u5217\u8868
-  $ way --remote=s3 snapshots  \u4F7F\u7528 s3 \u4ED3\u5E93
+  $ 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
 
 \u6587\u6863: https://github.com/shellus/way
 `);
-program.command("run [projects...]").description("\u6267\u884C\u5907\u4EFD").option("--dry-run", "\u6A21\u62DF\u5907\u4EFD\uFF08\u4E0D\u5B9E\u9645\u5199\u5165\uFF09").allowUnknownOption().allowExcessArguments().action(async function(projects) {
+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) {
+  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 });
+});
+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("--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) {
   const remote = this.parent.opts().remote;
-  const extraArgs = this.args.filter((a) => a.startsWith("-") && !["--dry-run"].includes(a));
-  if (this.opts().dryRun) extraArgs.push("--dry-run");
-  await run({ remote, projects: projects.filter((p) => !p.startsWith("-")), extraArgs });
+  await restore({
+    remote,
+    projects,
+    target: cmdOptions.target,
+    snapshot: cmdOptions.snapshot,
+    dryRun: cmdOptions.dryRun,
+    delete: cmdOptions.delete,
+    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) {
   const remote = this.parent.opts().remote;
@@ -304,13 +410,16 @@ program.command("env").description("\u663E\u793A\u73AF\u5883\u53D8\u91CF").actio
     console.log(`${key}=${value}`);
   }
 });
-program.command("*", { isDefault: true }).description("\u900F\u4F20\u7ED9 restic").allowUnknownOption().allowExcessArguments().action(async function(name) {
+program.command("restic [args...]").description("\u663E\u5F0F\u900F\u4F20\u7ED9 restic").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);
   const env = buildResticEnv(config.repository);
   const s3Options = buildS3Options(config.repository);
-  const args = this.parent.args;
   await execRestic(args, env, s3Options);
 });
+if (process.argv.length <= 2) {
+  program.outputHelp();
+  process.exit(0);
+}
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellus/way",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "将备份作为持续运营的项目，而非一次性任务。基于 restic 的策略封装。",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   },
   "files": [
     "dist",
+    "vendor",
     "repositories.yaml.example",
     "rules.yaml.example",
     "migrate-to-v0.5.sh"
@@ -38,9 +39,6 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "peerDependencies": {
-    "restic": "*"
-  },
   "dependencies": {
     "commander": "^14.0.3",
     "execa": "^9.6.1",

package/vendor/restic/linux-x64/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2014, Alexander Neumann <alexander@bumpern.de>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/vendor/restic/linux-x64/VERSION

@@ -0,0 +1 @@
+restic 0.18.1 compiled with go1.25.1 on linux/amd64