@shellus/way 0.3.0

package/README.local.md

@@ -0,0 +1,44 @@
+# 本机环境配置
+
+## 存储后端
+
+腾讯云 COS（成都区域）：
+- Endpoint: `cos.ap-chengdu.myqcloud.com`
+- Bucket: `xa-backup-1251087920`
+- 需要 `s3.bucket-lookup=dns` 选项
+
+## 备份项目
+
+| 项目 | 路径 | 说明 |
+|------|------|------|
+| data | /data | Docker 服务、项目源码、开发工具配置 |
+| home | /root/.ssh, /root/.claude 等 | SSH 密钥、Claude 配置、Shell 配置 |
+| system | /etc/fstab | 系统挂载配置 |
+
+## 排除规则备忘
+
+playwright-mcp 浏览器缓存目录名是 `browser-profile`（不是 `chrome-profile`）。
+
+## 定时任务
+
+```
+1 12 * * *   way run    # 12:01 午休后
+30 15 * * *  way run    # 15:30 下午
+30 18 * * *  way run    # 18:30 下班前
+0 4 * * 0    way gc     # 每周日凌晨清理
+```
+
+安装：`way cron install`
+
+## 验证命令
+
+```bash
+# 查看快照
+way snapshots
+
+# 检查排除规则
+way ls <snapshot-id> | grep -E 'node_modules|Cache'
+
+# 测试备份
+way run --dry-run
+```

package/README.md

@@ -0,0 +1,225 @@
+# way - 策略备份
+
+将备份作为持续运营的项目，而非一次性任务。基于 restic 的策略封装。
+
+推荐在所有地方使用策略备份：开发环境、个人电脑、生产服务器。
+
+## 设计原理
+
+### 1. 备份目的
+
+- 意外修改或删除时，从备份提取
+- 硬盘损毁、机房失联时，从备份重建
+- 需要追溯历史状态时，查阅备份
+
+### 2. 不备份可重建内容
+
+可重建的内容不备份：docker 镜像、node_modules、缓存、构建产物等。判断标准不是"是否有价值"，而是"能否从其他来源恢复"。
+
+### 3. 备份是项目
+
+备份保护所有项目，其重要性是所有项目的总和。应作为最重要的项目持续运营。
+
+### 4. 频率匹配变化
+
+备份频率应匹配数据变化频率。高频变化时段多备份，低频时段少备份。
+
+### 5. 可验证原则
+
+未经验证的备份等于没有备份。定期验证备份可恢复，失败时必须有告警。
+
+### 6. 定期清理
+
+定期清理旧快照，防止存储膨胀。
+
+### 7. 同步不等于备份
+
+同步工具（如 Syncthing）会将误操作实时传播到所有节点。真正的备份必须具备版本历史和回滚能力。
+
+### 8. 备份隔离原则
+
+假设本机被入侵，攻击者不应能通过本机凭证定位或删除备份数据。
+
+### 9. 多层冗余原则
+
+单一备份链路存在单点故障风险。应在多个维度建立冗余：
+- 时间周期：高频 + 每日 + 每周
+- 存储介质：云存储 + 本地硬盘 + 异地服务器
+
+### 10. 恢复演练原则
+
+定期执行实际恢复演练，确认备份可解密、可读取，恢复时间在可接受范围内。
+
+---
+
+## 依赖
+
+- [restic](https://restic.net/) - 备份引擎
+- Node.js >= 18（npm 安装方式）或 yq（脚本安装方式）
+
+npm 安装方式会自动处理依赖，脚本安装方式的 install.sh 会自动安装 restic 和 yq。
+
+## 快速开始
+
+### 方式 1: npm 安装（推荐）
+
+```bash
+npm install -g @shellus/way
+
+# 初始化配置
+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
+```
+
+### 方式 2: 脚本安装
+
+```bash
+# 安装（way + restic + yq）
+curl -fsSL https://github.com/shellus/way/releases/latest/download/install.sh | bash
+```
+
+### 使用
+
+```bash
+
+# way 自己的命令（不与 restic 冲突）
+way run                 # 执行备份（读取 rules.yaml 的项目和排除规则）
+way run data            # 只备份 data 项目
+way gc                  # 按 retention 策略清理旧快照
+way cron install        # 安装定时任务
+way cron show           # 显示将要安装的 crontab
+
+# 透传 restic（way 只设置环境变量）
+way snapshots           # → restic snapshots
+way restore abc123      # → restic restore abc123
+way check               # → restic check
+way stats               # → restic stats
+way prune               # → restic prune（直接透传）
+
+# 指定 repository（默认用 repositories.yaml 中的 default）
+way --remote=oss snapshots
+```
+
+---
+
+## 配置说明
+
+配置文件默认存放在 `~/.way/`，安装后复制示例文件并填入实际值：
+
+```bash
+cp ~/.way/repositories.yaml.example ~/.way/repositories.yaml
+cp ~/.way/rules.yaml.example ~/.way/rules.yaml
+```
+
+也可以通过 `WAY_DIR` 环境变量指定其他目录：
+
+```bash
+WAY_DIR=/path/to/config way snapshots
+```
+
+### rules.yaml
+
+备份规则配置，参考 [`rules.yaml`](rules.yaml)：
+
+- **projects**: 备份项目、路径、专属排除规则
+- **schedule**: 备份时间、清理任务的 cron 表达式
+- **retention**: 快照保留策略
+- **global_excludes**: 全局排除规则
+
+#### 排除规则通配符语法
+
+restic 使用 Go 的 filepath.Match 语法：
+
+- `*` 匹配任意字符，但**不跨越目录分隔符**
+- `**` 匹配任意子目录
+
+示例：
+- `*Cache*` 只匹配当前目录下含 Cache 的文件/目录
+- `**/*Cache*` 匹配任意深度子目录下含 Cache 的文件/目录
+
+### repositories.yaml
+
+备份目的地配置，参考 [`repositories.yaml`](repositories.yaml)。
+
+### .env
+
+敏感凭证通过环境变量注入，在 `.env` 中定义：
+
+```bash
+RESTIC_PASSWORD=your-restic-password
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+```
+
+在 `repositories.yaml` 中使用 `${VAR}` 语法引用：
+
+```yaml
+credentials:
+  password: ${RESTIC_PASSWORD}
+  access_key_id: ${AWS_ACCESS_KEY_ID}
+```
+
+## 凭证离线备份
+
+`repositories.yaml` 和 `.env` 包含 restic 仓库密码和云存储凭证。这两个文件被 `.gitignore` 排除，不会进入版本控制，也不会被 way 自身备份。
+
+**如果本机不可访问且遗忘了这些凭证，所有备份数据将永久无法恢复。**
+
+必须在本机之外单独保存一份：
+
+- 密码管理器（推荐）
+- 加密笔记
+- 离线存储（U 盘、纸质打印）
+
+需要保存的信息：
+
+| 项目 | 来源 |
+|------|------|
+| restic 仓库密码 | `.env` 中的 `RESTIC_PASSWORD` |
+| S3 访问凭证 | `.env` 中的 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` |
+| 仓库地址 | `repositories.yaml` 中的 `url` |
+
+## 数据恢复
+
+way 透传所有 restic 命令，恢复数据时只需通过 way 调用 restic 的恢复相关命令。way 负责设置仓库连接和认证环境变量，无需手动配置。
+
+### 1. 查看快照列表
+
+```bash
+way snapshots                    # 列出所有快照
+way snapshots --tag=way:home     # 只看 home 项目的快照
+way snapshots --tag=way:data     # 只看 data 项目的快照
+```
+
+### 2. 浏览快照内容
+
+```bash
+way ls <snapshot-id>             # 列出快照中的所有文件
+way ls <snapshot-id> /root/.ssh  # 列出快照中指定目录的文件
+way find --snapshot <id> <filename>  # 在快照中搜索文件
+```
+
+### 3. 恢复文件
+
+```bash
+# 恢复整个快照到指定目录
+way restore <snapshot-id> --target /tmp/restore
+
+# 只恢复特定路径
+way restore <snapshot-id> --target /tmp/restore --include /root/.ssh
+
+# 恢复单个文件到标准输出（适合快速查看）
+way dump <snapshot-id> /root/.gitconfig
+```
+
+### 4. 从其他仓库恢复
+
+```bash
+way --remote=oss snapshots
+way --remote=oss restore <snapshot-id> --target /tmp/restore
+```
+
+## 开发
+
+参见 [CLAUDE.md](CLAUDE.md)。

package/dist/cli.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/core/config.ts
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import dotenv from "dotenv";
+
+// src/core/env.ts
+function expandEnv(value) {
+  if (!value) return "";
+  const match = value.match(/^\$\{(.+)\}$/);
+  if (match) {
+    return process.env[match[1]] || "";
+  }
+  return value;
+}
+
+// src/core/config.ts
+function loadConfig(wayDir, remoteName) {
+  const envPath = path.join(wayDir, ".env");
+  if (fs.existsSync(envPath)) {
+    dotenv.config({ path: envPath });
+  }
+  const repoFile = path.join(wayDir, "repositories.yaml");
+  const repoConfig = yaml.load(fs.readFileSync(repoFile, "utf8"));
+  const repoName = remoteName === "default" ? repoConfig.default : remoteName;
+  const repository = repoConfig.repositories[repoName];
+  if (!repository) throw new Error(`Repository not found: ${repoName}`);
+  if (repository.credentials.password) {
+    repository.credentials.password = expandEnv(repository.credentials.password);
+  }
+  if (repository.credentials.access_key_id) {
+    repository.credentials.access_key_id = expandEnv(repository.credentials.access_key_id);
+  }
+  if (repository.credentials.secret_access_key) {
+    repository.credentials.secret_access_key = expandEnv(repository.credentials.secret_access_key);
+  }
+  const rulesFile = path.join(wayDir, "rules.yaml");
+  const rules = yaml.load(fs.readFileSync(rulesFile, "utf8"));
+  if (rules.uptime_kuma?.push_url) {
+    rules.uptime_kuma.push_url = expandEnv(rules.uptime_kuma.push_url);
+  }
+  return { repository, rules };
+}
+
+// src/core/restic.ts
+import { execa } from "execa";
+function buildResticEnv(repo) {
+  const env = {};
+  switch (repo.type) {
+    case "s3":
+      env.RESTIC_REPOSITORY = `s3:https://${repo.endpoint}/${repo.bucket}`;
+      break;
+    case "local":
+      env.RESTIC_REPOSITORY = repo.path;
+      break;
+    case "sftp":
+      env.RESTIC_REPOSITORY = `sftp:${repo.host}:${repo.path}`;
+      break;
+  }
+  if (repo.credentials.password) env.RESTIC_PASSWORD = repo.credentials.password;
+  if (repo.credentials.access_key_id) env.AWS_ACCESS_KEY_ID = repo.credentials.access_key_id;
+  if (repo.credentials.secret_access_key) env.AWS_SECRET_ACCESS_KEY = repo.credentials.secret_access_key;
+  return env;
+}
+function buildBackupArgs(name, project, globalExcludes) {
+  const args = ["backup", `--tag=way:${name}`];
+  const allExcludes = [...globalExcludes, ...project.excludes || []];
+  for (const exclude of allExcludes) args.push(`--exclude=${exclude}`);
+  args.push(...project.paths);
+  return args;
+}
+function buildS3Options(repo) {
+  const options = [];
+  if (repo.options?.bucket_lookup) {
+    options.push("-o", `s3.bucket-lookup=${repo.options.bucket_lookup}`);
+  }
+  return options;
+}
+async function execRestic(args, env, s3Options = []) {
+  await execa("restic", [...s3Options, ...args], { env: { ...process.env, ...env }, stdio: "inherit" });
+}
+
+// src/commands/run.ts
+async function run(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.project ? [options.project] : 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(`=== Backing up: ${projectName} ===`);
+    try {
+      const args = buildBackupArgs(projectName, project, globalExcludes);
+      if (options.extraArgs) args.push(...options.extraArgs);
+      await execRestic(args, env, s3Options);
+      succeeded.push(projectName);
+    } catch (error) {
+      console.error(`Failed to backup ${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(", "));
+  if (config.rules.uptime_kuma?.push_url) {
+    await notifyUptimeKuma({ succeeded, failed, duration }, config.rules.uptime_kuma.push_url);
+  }
+  return { succeeded, failed, duration };
+}
+async function notifyUptimeKuma(result, pushUrl) {
+  const status = result.failed.length > 0 ? "down" : "up";
+  const msg = `Succeeded: ${result.succeeded.length}, Failed: ${result.failed.length}`;
+  const url = `${pushUrl}?status=${status}&msg=${encodeURIComponent(msg)}&ping=${result.duration}`;
+  try {
+    const response = await fetch(url);
+    if (response.ok) {
+      console.log(`Uptime Kuma notified: status=${status}, ping=${result.duration}ms`);
+    } else {
+      console.error("Uptime Kuma notification failed");
+    }
+  } catch (error) {
+    console.error("Uptime Kuma notification failed:", error);
+  }
+}
+
+// src/commands/gc.ts
+async function gc(options) {
+  const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
+  const config = loadConfig(wayDir, options.remote);
+  const keepDaily = config.rules.retention?.keep_daily || 7;
+  const keepWeekly = config.rules.retention?.keep_weekly || 4;
+  const keepMonthly = config.rules.retention?.keep_monthly || 6;
+  console.log("=== Cleaning snapshots ===");
+  console.log(`Policy: daily=${keepDaily}, weekly=${keepWeekly}, monthly=${keepMonthly}`);
+  const env = buildResticEnv(config.repository);
+  const s3Options = buildS3Options(config.repository);
+  const args = [
+    "forget",
+    "--prune",
+    `--keep-daily=${keepDaily}`,
+    `--keep-weekly=${keepWeekly}`,
+    `--keep-monthly=${keepMonthly}`
+  ];
+  if (options.extraArgs) args.push(...options.extraArgs);
+  await execRestic(args, env, s3Options);
+}
+
+// src/commands/cron.ts
+import { execSync } from "child_process";
+import fs2 from "fs";
+async function cron(options) {
+  const wayDir = process.env.WAY_DIR || `${process.env.HOME}/.way`;
+  const config = loadConfig(wayDir, options.remote);
+  const markerStart = "# === way backup schedule ===";
+  const markerEnd = "# === way backup schedule end ===";
+  const generateCron = () => {
+    const lines = [markerStart];
+    const backupSchedules = config.rules.schedule?.backup || [];
+    for (const schedule of backupSchedules) {
+      lines.push(`${schedule} /usr/local/bin/way run`);
+    }
+    if (config.rules.schedule?.prune) {
+      lines.push(`${config.rules.schedule.prune} /usr/local/bin/way gc`);
+    }
+    if (config.rules.schedule?.check) {
+      lines.push(`${config.rules.schedule.check} /usr/local/bin/way check`);
+    }
+    lines.push(markerEnd);
+    return lines.join("\n");
+  };
+  if (options.action === "show") {
+    console.log(generateCron());
+    return;
+  }
+  if (options.action === "install") {
+    if (!fs2.existsSync("/usr/local/bin/way")) {
+      throw new Error("Error: /usr/local/bin/way not found");
+    }
+    let existing = "";
+    try {
+      existing = execSync("crontab -l 2>/dev/null", { encoding: "utf8" });
+    } catch {
+    }
+    const filtered = existing.split("\n").filter((line) => {
+      return !line.includes(markerStart) && !line.includes(markerEnd);
+    }).join("\n");
+    const newCrontab = filtered + "\n" + generateCron();
+    execSync("crontab -", { input: newCrontab });
+    console.log("Crontab installed successfully");
+    execSync('crontab -l | grep -A100 "' + markerStart + '" | head -20', { stdio: "inherit", shell: "/bin/bash" });
+  }
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("way").version("0.3.0").description("\u7B56\u7565\u5907\u4EFD\u5DE5\u5177").option("--remote <name>", "\u6307\u5B9A\u4ED3\u5E93", "default");
+program.command("run [project]").description("\u6267\u884C\u5907\u4EFD").action(async (project, options, command) => {
+  const remote = command.parent.opts().remote;
+  const extraArgs = command.args.slice(1);
+  await run({ remote, project, extraArgs });
+});
+program.command("gc").description("\u6E05\u7406\u65E7\u5FEB\u7167").allowUnknownOption().allowExcessArguments().action(async function() {
+  const remote = this.parent.opts().remote;
+  const extraArgs = this.parent.args.slice(1);
+  await gc({ remote, extraArgs });
+});
+program.command("cron <action>").description("\u7BA1\u7406\u5B9A\u65F6\u4EFB\u52A1 (show|install)").action(async (action, options, command) => {
+  const remote = command.parent.opts().remote;
+  await cron({ remote, action });
+});
+program.command("env").description("\u663E\u793A\u73AF\u5883\u53D8\u91CF").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("*", { isDefault: true }).description("\u900F\u4F20\u7ED9 restic").allowUnknownOption().allowExcessArguments().action(async function(name) {
+  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);
+});
+program.parse();

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@shellus/way",
+  "version": "0.3.0",
+  "description": "将备份作为持续运营的项目，而非一次性任务。基于 restic 的策略封装。",
+  "type": "module",
+  "bin": {
+    "way": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --clean",
+    "dev": "tsup src/cli.ts --format esm --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "prepublishOnly": "npm run test:run && npm run build"
+  },
+  "files": [
+    "dist",
+    "repositories.yaml.example",
+    "rules.yaml.example"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shellus/way.git"
+  },
+  "keywords": ["backup", "restic", "snapshot", "cron"],
+  "author": "shellus",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/shellus/way/issues"
+  },
+  "homepage": "https://github.com/shellus/way#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "restic": "*"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1",
+    "execa": "^9.6.1",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/repositories.yaml.example

@@ -0,0 +1,30 @@
+# 备份目的地配置 (restic repositories)
+# 凭证支持直接填写或引用环境变量: ${ENV_VAR}
+# 复制为 repositories.yaml 并填入实际值
+
+default: local
+
+repositories:
+  local:
+    type: local
+    path: /tmp/way-backup
+    credentials:
+      password: ${RESTIC_PASSWORD}
+
+  s3:
+    type: s3
+    endpoint: s3.example.com
+    bucket: my-backup-bucket
+    options:
+      bucket_lookup: dns
+    credentials:
+      password: ${RESTIC_PASSWORD}
+      access_key_id: ${AWS_ACCESS_KEY_ID}
+      secret_access_key: ${AWS_SECRET_ACCESS_KEY}
+
+  sftp:
+    type: sftp
+    host: backup.example.com
+    path: /backup/myhost
+    credentials:
+      password: ${RESTIC_PASSWORD}

package/rules.yaml.example

@@ -0,0 +1,63 @@
+# 备份规则配置
+# 备份目的地见 repositories.yaml
+# 复制为 rules.yaml 并根据实际情况修改
+
+# Uptime Kuma 通知（备份完成后推送状态）
+uptime_kuma:
+  push_url: "${UPTIME_KUMA_PUSH_URL}"  # 支持环境变量
+
+# 备份时间 (cron格式，留空则不执行)
+schedule:
+  backup:
+    - "0 12 * * *"   # 每天中午
+    - "0 18 * * *"   # 每天傍晚
+  prune: "0 4 * * 0" # 每周日凌晨4点清理旧快照
+  check: ""          # 完整性检查，留空不执行
+
+# 快照保留策略
+retention:
+  keep_daily: 7
+  keep_weekly: 4
+  keep_monthly: 6
+
+projects:
+  data:
+    description: 数据目录
+    paths:
+      - /path/to/data
+    excludes:
+      - cache
+      - tmp
+
+  config:
+    description: 配置文件
+    paths:
+      - /home/user/.config
+      - /home/user/.ssh
+    excludes: []
+
+# 全局排除规则 - 适用于所有项目
+global_excludes:
+  # 包管理
+  - node_modules
+  - .venv
+  - venv
+  - __pycache__
+  - "*.pyc"
+  - vendor
+
+  # 缓存
+  - .cache
+
+  # 构建产物
+  - dist
+  - .next
+
+  # IDE配置
+  - .idea
+  - .vscode
+
+  # 临时文件
+  - "*.log"
+  - "*.tmp"
+  - "*.swp"