@shellus/way 0.5.2 → 0.6.0

package/README.md

@@ -68,7 +68,7 @@
 ## 依赖
 
 - Node.js >= 18
-- Linux x64 平台内置 [restic](https://restic.net/) 0.16.4，其他平台需自行安装 restic
+- Linux x64 平台内置 [restic](https://restic.net/) 0.18.1，其他平台需自行安装 restic
 
 `way` 查找 restic 的顺序：
 
@@ -85,7 +85,7 @@ npm install -g @shellus/way
 Linux x64 用户无需额外安装 restic。如需使用自定义 restic，可设置：
 
 ```bash
-WAY_RESTIC_BIN=/usr/local/bin/restic way snapshots
+WAY_RESTIC_BIN=/usr/local/bin/restic way restic snapshots
 ```
 
 ## 快速开始
@@ -124,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        # 模拟清理（不实际删除）
 
@@ -148,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
 ```
 
 ## 生命周期
@@ -186,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
@@ -287,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

@@ -80,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) {
@@ -100,8 +113,8 @@ async function execRestic(args, env, s3Options = []) {
   }
 }
 
-// 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);
@@ -157,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`;
@@ -267,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}`);
@@ -303,23 +357,40 @@ async function daemon(options) {
 
 // src/cli.ts
 var program = new Command();
-program.name("way").version("0.5.2").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 = this.args.filter((a) => a.startsWith("-") && !["--dry-run"].includes(a));
-  await run({ remote, projects: projects.filter((p) => !p.startsWith("-")), extraArgs, 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;
+  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;
@@ -339,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.2",
+  "version": "0.6.0",
   "description": "将备份作为持续运营的项目，而非一次性任务。基于 restic 的策略封装。",
   "type": "module",
   "bin": {

package/vendor/restic/linux-x64/VERSION

@@ -1 +1 @@
-restic 0.16.4 compiled with go1.22.2 on linux/amd64
+restic 0.18.1 compiled with go1.25.1 on linux/amd64