@shellus/way 0.4.2 → 0.5.0

package/README.md

@@ -6,7 +6,8 @@
 
 ## 版本说明
 
-- **v0.4.0+**: TypeScript 版本，使用 systemd，凭证直接写在 YAML
+- **v0.5.0+**: daemon 模式，支持项目级调度配置
+- **v0.4.0**: TypeScript 版本，使用 systemd timer，凭证直接写在 YAML
 - **v0.3.x**: TypeScript 版本，使用 crontab，支持 .env
 - **v0.2.x**: Bash 版本
 
@@ -46,10 +47,11 @@
 
 假设本机被入侵，攻击者不应能通过本机凭证定位或删除备份数据。
 
-**v0.4.0 安全增强**：
-- 使用 systemd 替代 crontab（避免在 crontab 留下痕迹）
-- 移除 .env 文件支持（避免被 `find .env` 发现）
-- 凭证直接写在 `~/.way/repositories.yaml`（权限 600）
+**v0.5.0 架构升级**：
+- 使用 daemon 模式替代 systemd timer
+- 支持项目级 schedule 配置（不同项目不同频率）
+- 使用 node-cron 实现精确到分钟的调度
+- systemd service 管理常驻进程（自动重启）
 
 ### 9. 多层冗余原则
 
@@ -119,15 +121,20 @@ way snapshots        # 查看快照
 
 ```bash
 # 备份命令
-way run                 # 执行备份（读取 rules.yaml 的项目和排除规则）
+way run                 # 执行所有项目备份
 way run data            # 只备份 data 项目
+way run data config     # 备份多个项目
 way gc                  # 按 retention 策略清理旧快照
+way gc --dry-run        # 模拟清理（不实际删除）
 
-# systemd 定时任务
-way systemd install     # 安装 systemd 定时任务
+# daemon 模式（推荐）
+way daemon              # 启动常驻进程，按配置定时执行
+
+# systemd 管理
+way systemd install     # 安装 systemd service（运行 daemon）
 way systemd show        # 显示 systemd 配置
-way systemd status      # 查看定时任务状态
-way systemd uninstall   # 卸载定时任务
+way systemd status      # 查看服务状态
+way systemd uninstall   # 卸载服务
 
 # 透传 restic（way 只设置环境变量）
 way snapshots           # → restic snapshots
@@ -143,16 +150,14 @@ way --remote=oss snapshots
 
 ```mermaid
 graph LR
-    A[way run] --> B[读取配置]
-    B --> C[遍历项目]
-    C --> D[执行 restic backup]
-    D --> E[推送 Uptime Kuma]
-
-    F[systemd timer] --> G[定时触发]
-    G --> A
-
-    H[way gc] --> I[restic forget]
-    I --> J[restic prune]
+    A[way daemon] --> B[读取配置]
+    B --> C[为每个项目创建 cron 任务]
+    C --> D[node-cron 定时触发]
+    D --> E[执行 restic backup]
+    E --> F[推送 Uptime Kuma]
+
+    G[systemd service] --> H[启动 daemon]
+    H --> I[进程崩溃自动重启]
 ```
 
 ---
@@ -174,13 +179,36 @@ WAY_DIR=/path/to/config way snapshots
 
 ### rules.yaml
 
-备份规则配置，参考 [`rules.yaml`](rules.yaml)：
+备份规则配置，参考 [`rules.yaml.example`](rules.yaml.example)：
 
-- **projects**: 备份项目、路径、专属排除规则
-- **schedule**: 备份时间（systemd timer OnCalendar 格式）
-- **retention**: 快照保留策略
+- **defaults**: 全局默认配置（schedule、retention）
+- **projects**: 备份项目配置，可覆盖默认 schedule 和 retention
+- **maintenance**: 维护任务配置（prune、check）
 - **global_excludes**: 全局排除规则
 
+**项目级调度示例**：
+
+```yaml
+defaults:
+  schedule: "0 */2 * * *"  # 默认每 2 小时
+
+projects:
+  data:
+    paths: [/data]
+    # 继承默认 schedule
+
+  logs:
+    paths: [/var/log]
+    schedule: "0 3 * * *"  # 覆盖为每天凌晨 3 点
+
+  archive:
+    paths: [/archive]
+    schedule: "0 2 * * 0"  # 每周日凌晨 2 点
+    retention:
+      keep_weekly: 8
+      keep_monthly: 12
+```
+
 #### 排除规则通配符语法
 
 restic 使用 Go 的 filepath.Match 语法：

package/dist/cli.js

@@ -15,6 +15,9 @@ function loadConfig(wayDir, remoteName) {
   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 || {})) {
+    throw new Error("\u65E7\u914D\u7F6E\u683C\u5F0F\u4E0D\u518D\u652F\u6301\uFF0C\u8BF7\u53C2\u8003 rules.yaml.example \u66F4\u65B0\u914D\u7F6E");
+  }
   return { repository, rules };
 }
 
@@ -72,7 +75,7 @@ async function run(options) {
   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 projects = options.projects && options.projects.length > 0 ? options.projects : Object.keys(config.rules.projects);
   const succeeded = [];
   const failed = [];
   const startTime = Date.now();
@@ -123,11 +126,13 @@ async function notifyUptimeKuma(result, pushUrl) {
 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;
+  const retention = config.rules.defaults?.retention || {};
+  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}`);
+  console.log(`Policy: daily=${keepDaily}, weekly=${keepWeekly}, monthly=${keepMonthly}${keepYearly ? `, yearly=${keepYearly}` : ""}`);
   const env = buildResticEnv(config.repository);
   const s3Options = buildS3Options(config.repository);
   const args = [
@@ -137,7 +142,8 @@ async function gc(options) {
     `--keep-weekly=${keepWeekly}`,
     `--keep-monthly=${keepMonthly}`
   ];
-  if (options.extraArgs) args.push(...options.extraArgs);
+  if (keepYearly) args.push(`--keep-yearly=${keepYearly}`);
+  if (options.dryRun) args.push("--dry-run");
   await execRestic(args, env, s3Options);
 }
 
@@ -145,80 +151,122 @@ async function gc(options) {
 import { execSync } from "child_process";
 import fs2 from "fs";
 import path2 from "path";
-function cronToSystemd(cron) {
-  const parts = cron.trim().split(/\s+/);
-  if (parts.length !== 5) return "daily";
-  const [minute, hour, day, month, weekday] = parts;
-  if (day === "*" && month === "*" && weekday === "*") {
-    return `*-*-* ${hour.padStart(2, "0")}:${minute.padStart(2, "0")}:00`;
-  }
-  return "daily";
-}
 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 serviceContent = `[Unit]
-Description=Way Backup Service
+Description=Way Backup Daemon
 After=network.target
 
 [Service]
-Type=oneshot
-ExecStart=${wayPath} run
+Type=simple
+ExecStart=${wayPath} daemon
+Restart=always
+RestartSec=10
 Environment="WAY_DIR=${wayDir}"
-`;
-  const timerContent = `[Unit]
-Description=Way Backup Timer
-
-[Timer]
-OnCalendar=${cronToSystemd(config.rules.schedule?.backup?.[0] || "daily")}
-Persistent=true
 
 [Install]
-WantedBy=timers.target
+WantedBy=default.target
 `;
   if (options.action === "show") {
     console.log("=== way-backup.service ===");
     console.log(serviceContent);
-    console.log("\n=== way-backup.timer ===");
-    console.log(timerContent);
     return;
   }
   const systemdDir = `${process.env.HOME}/.config/systemd/user`;
   const servicePath = path2.join(systemdDir, "way-backup.service");
-  const timerPath = path2.join(systemdDir, "way-backup.timer");
   if (options.action === "install") {
     fs2.mkdirSync(systemdDir, { recursive: true });
     fs2.writeFileSync(servicePath, serviceContent);
-    fs2.writeFileSync(timerPath, timerContent);
     execSync("systemctl --user daemon-reload");
-    execSync("systemctl --user enable way-backup.timer");
-    execSync("systemctl --user start way-backup.timer");
-    console.log("Systemd timer installed and started");
-    execSync("systemctl --user --no-pager status way-backup.timer", { stdio: "inherit" });
+    execSync("systemctl --user enable way-backup.service");
+    execSync("systemctl --user start way-backup.service");
+    console.log("Systemd service installed and started");
+    execSync("systemctl --user --no-pager status way-backup.service", { stdio: "inherit" });
   }
   if (options.action === "uninstall") {
     try {
-      execSync("systemctl --user stop way-backup.timer", { stdio: "ignore" });
+      execSync("systemctl --user stop way-backup.service", { stdio: "ignore" });
     } catch {
     }
     try {
-      execSync("systemctl --user disable way-backup.timer", { stdio: "ignore" });
+      execSync("systemctl --user disable way-backup.service", { stdio: "ignore" });
     } catch {
     }
     if (fs2.existsSync(servicePath)) fs2.unlinkSync(servicePath);
-    if (fs2.existsSync(timerPath)) fs2.unlinkSync(timerPath);
     execSync("systemctl --user daemon-reload");
-    console.log("Systemd timer uninstalled");
+    console.log("Systemd service uninstalled");
   }
   if (options.action === "status") {
-    execSync("systemctl --user --no-pager status way-backup.timer", { stdio: "inherit" });
+    execSync("systemctl --user --no-pager status way-backup.service", { stdio: "inherit" });
+  }
+}
+
+// src/commands/daemon.ts
+import cron from "node-cron";
+var isRunning = false;
+var taskQueue = [];
+async function executeTask(task) {
+  taskQueue.push(task);
+  if (isRunning) return;
+  while (taskQueue.length > 0) {
+    isRunning = true;
+    const nextTask = taskQueue.shift();
+    try {
+      await nextTask();
+    } catch (error) {
+      console.error("Task failed:", error);
+    }
+  }
+  isRunning = false;
+}
+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");
+  for (const [name, project] of Object.entries(config.rules.projects)) {
+    const schedule = project.schedule || config.rules.defaults?.schedule || "0 */2 * * *";
+    cron.schedule(schedule, () => {
+      executeTask(async () => {
+        console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running backup: ${name}`);
+        await run({ remote: options.remote, projects: [name] });
+      });
+    });
+    console.log(`Scheduled backup for ${name}: ${schedule}`);
   }
+  const pruneSchedule = config.rules.maintenance?.prune?.schedule;
+  if (pruneSchedule) {
+    cron.schedule(pruneSchedule, () => {
+      executeTask(async () => {
+        console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running prune`);
+        await gc({ remote: options.remote, dryRun: false });
+      });
+    });
+    console.log(`Scheduled prune: ${pruneSchedule}`);
+  }
+  const checkSchedule = config.rules.maintenance?.check?.schedule;
+  if (checkSchedule) {
+    cron.schedule(checkSchedule, () => {
+      executeTask(async () => {
+        console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] Running check`);
+      });
+    });
+    console.log(`Scheduled check: ${checkSchedule}`);
+  }
+  process.on("SIGTERM", () => {
+    console.log("Received SIGTERM, shutting down gracefully");
+    process.exit(0);
+  });
+  process.on("SIGINT", () => {
+    console.log("Received SIGINT, shutting down gracefully");
+    process.exit(0);
+  });
 }
 
 // src/cli.ts
 var program = new Command();
-program.name("way").version("0.4.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", `
+program.name("way").version("0.5.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
@@ -230,25 +278,22 @@ program.name("way").version("0.4.0").description("\u7B56\u7565\u5907\u4EFD\u5DE5
 
 \u6587\u6863: https://github.com/shellus/way
 `);
-program.command("run [project]").description("\u6267\u884C\u5907\u4EFD").allowUnknownOption().allowExcessArguments().action(async (project, options, command) => {
+program.command("run [projects...]").description("\u6267\u884C\u5907\u4EFD").allowUnknownOption().allowExcessArguments().action(async (projects, options, command) => {
   const remote = command.parent.opts().remote;
-  const allArgs = command.parent.args.slice(1);
-  if (project?.startsWith("--")) {
-    await run({ remote, project: void 0, extraArgs: allArgs });
-  } else {
-    const extraArgs = project ? allArgs.slice(1) : allArgs;
-    await run({ remote, project, extraArgs });
-  }
+  await run({ remote, projects });
 });
-program.command("gc").description("\u6E05\u7406\u65E7\u5FEB\u7167").allowUnknownOption().allowExcessArguments().action(async function() {
+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;
-  const extraArgs = this.parent.args.slice(1);
-  await gc({ remote, extraArgs });
+  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) => {
   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) => {
+  const remote = command.parent.opts().remote;
+  await daemon({ remote });
+});
 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) {

package/migrate-to-v0.5.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# 迁移脚本：v0.4.x -> v0.5.0
+# 将旧配置格式转换为新格式
+
+set -e
+
+WAY_DIR="${WAY_DIR:-$HOME/.way}"
+RULES_FILE="$WAY_DIR/rules.yaml"
+BACKUP_FILE="$WAY_DIR/rules.yaml.v0.4.backup"
+
+if [ ! -f "$RULES_FILE" ]; then
+  echo "错误: 未找到 $RULES_FILE"
+  exit 1
+fi
+
+# 备份原配置
+cp "$RULES_FILE" "$BACKUP_FILE"
+echo "已备份原配置到: $BACKUP_FILE"
+
+# 检查是否是旧格式
+if ! grep -q "^schedule:" "$RULES_FILE"; then
+  echo "配置已是新格式，无需迁移"
+  exit 0
+fi
+
+# 提取旧配置的值
+OLD_SCHEDULE=$(grep -A2 "^schedule:" "$BACKUP_FILE" | grep -A1 "backup:" | tail -1 | sed 's/.*"\(.*\)".*/\1/')
+OLD_PRUNE=$(grep -A3 "^schedule:" "$BACKUP_FILE" | grep "prune:" | sed 's/.*"\(.*\)".*/\1/')
+OLD_CHECK=$(grep -A4 "^schedule:" "$BACKUP_FILE" | grep "check:" | sed 's/.*"\(.*\)".*/\1/')
+
+KEEP_DAILY=$(grep "keep_daily:" "$BACKUP_FILE" | sed 's/.*: \(.*\)/\1/')
+KEEP_WEEKLY=$(grep "keep_weekly:" "$BACKUP_FILE" | sed 's/.*: \(.*\)/\1/')
+KEEP_MONTHLY=$(grep "keep_monthly:" "$BACKUP_FILE" | sed 's/.*: \(.*\)/\1/')
+
+# 生成新配置
+cat > "$RULES_FILE" << EOF
+# 备份规则配置 (v0.5.0)
+# 旧配置已备份到: $(basename $BACKUP_FILE)
+
+# 全局默认配置
+defaults:
+  schedule: "${OLD_SCHEDULE:-0 */2 * * *}"
+  retention:
+    keep_daily: ${KEEP_DAILY:-7}
+    keep_weekly: ${KEEP_WEEKLY:-4}
+    keep_monthly: ${KEEP_MONTHLY:-6}
+
+EOF
+
+# 复制 uptime_kuma 配置
+if grep -q "^uptime_kuma:" "$BACKUP_FILE"; then
+  echo "# Uptime Kuma 通知" >> "$RULES_FILE"
+  grep -A1 "^uptime_kuma:" "$BACKUP_FILE" >> "$RULES_FILE"
+  echo "" >> "$RULES_FILE"
+fi
+
+# 复制 projects 配置
+echo "# 备份项目" >> "$RULES_FILE"
+sed -n '/^projects:/,/^global_excludes:/p' "$BACKUP_FILE" | sed '$d' >> "$RULES_FILE"
+echo "" >> "$RULES_FILE"
+
+# 复制 global_excludes
+sed -n '/^global_excludes:/,$p' "$BACKUP_FILE" >> "$RULES_FILE"
+
+# 添加 maintenance 配置
+if [ -n "$OLD_PRUNE" ] || [ -n "$OLD_CHECK" ]; then
+  echo "" >> "$RULES_FILE"
+  echo "# 维护任务" >> "$RULES_FILE"
+  echo "maintenance:" >> "$RULES_FILE"
+  if [ -n "$OLD_PRUNE" ]; then
+    echo "  prune:" >> "$RULES_FILE"
+    echo "    schedule: \"$OLD_PRUNE\"" >> "$RULES_FILE"
+  fi
+  if [ -n "$OLD_CHECK" ]; then
+    echo "  check:" >> "$RULES_FILE"
+    echo "    schedule: \"$OLD_CHECK\"" >> "$RULES_FILE"
+  fi
+fi
+
+echo "✓ 配置迁移完成"
+
+# 检测并升级 systemd 服务
+TIMER_FILE="$HOME/.config/systemd/user/way-backup.timer"
+SERVICE_FILE="$HOME/.config/systemd/user/way-backup.service"
+
+if systemctl --user is-active way-backup.timer &>/dev/null || [ -f "$TIMER_FILE" ]; then
+  echo ""
+  echo "检测到旧版 systemd timer，正在升级为 daemon service..."
+
+  # 停止并禁用旧 timer
+  systemctl --user stop way-backup.timer 2>/dev/null || true
+  systemctl --user disable way-backup.timer 2>/dev/null || true
+  rm -f "$TIMER_FILE"
+
+  # 停止旧 service（如果在运行）
+  systemctl --user stop way-backup.service 2>/dev/null || true
+
+  # 重新安装新版 service
+  way systemd install
+
+  echo "✓ systemd 服务已从 timer 升级为 daemon"
+elif systemctl --user is-active way-backup.service &>/dev/null || [ -f "$SERVICE_FILE" ]; then
+  echo ""
+  echo "检测到 systemd service，正在重新安装..."
+
+  # 重新安装以更新配置
+  way systemd uninstall
+  way systemd install
+
+  echo "✓ systemd 服务已更新"
+else
+  echo ""
+  echo "未检测到 systemd 服务，如需安装: way systemd install"
+fi
+
+echo ""
+echo "如需回滚配置: mv $BACKUP_FILE $RULES_FILE"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellus/way",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "将备份作为持续运营的项目，而非一次性任务。基于 restic 的策略封装。",
   "type": "module",
   "bin": {
@@ -16,7 +16,8 @@
   "files": [
     "dist",
     "repositories.yaml.example",
-    "rules.yaml.example"
+    "rules.yaml.example",
+    "migrate-to-v0.5.sh"
   ],
   "repository": {
     "type": "git",
@@ -43,11 +44,13 @@
   "dependencies": {
     "commander": "^14.0.3",
     "execa": "^9.6.1",
-    "js-yaml": "^4.1.1"
+    "js-yaml": "^4.1.1",
+    "node-cron": "^4.2.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.5.0",
+    "@types/node-cron": "^3.0.11",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"

package/rules.yaml.example

@@ -2,23 +2,19 @@
 # 备份目的地见 repositories.yaml
 # 复制为 rules.yaml 并根据实际情况修改
 
+# 全局默认配置
+defaults:
+  schedule: "0 */2 * * *"  # 默认每 2 小时
+  retention:
+    keep_daily: 7
+    keep_weekly: 4
+    keep_monthly: 6
+
 # Uptime Kuma 通知（备份完成后推送状态）
 uptime_kuma:
   push_url: "https://uptime.example.com/api/push/xxxxx"
 
-# 备份时间（cron 格式，会自动转换为 systemd OnCalendar）
-schedule:
-  backup:
-    - "0 12 * * *"   # 每天中午 12:00
-  prune: "0 4 * * 0" # 每周日凌晨 4:00 清理
-  check: ""          # 完整性检查，留空不执行
-
-# 快照保留策略
-retention:
-  keep_daily: 7
-  keep_weekly: 4
-  keep_monthly: 6
-
+# 备份项目
 projects:
   data:
     description: 数据目录
@@ -33,6 +29,18 @@ projects:
     paths:
       - /home/user/.config
       - /home/user/.ssh
+    schedule: "0 3 * * *"  # 覆盖默认，每天凌晨 3 点
+    excludes: []
+
+  archive:
+    description: 历史归档
+    paths:
+      - /archive
+    schedule: "0 2 * * 0"  # 每周日凌晨 2 点
+    retention:
+      keep_weekly: 8
+      keep_monthly: 12
+      keep_yearly: 3
     excludes: []
 
 # 全局排除规则 - 适用于所有项目
@@ -60,3 +68,10 @@ global_excludes:
   - "*.log"
   - "*.tmp"
   - "*.swp"
+
+# 维护任务（可选）
+maintenance:
+  prune:
+    schedule: "0 4 * * 0"  # 每周日凌晨 4 点清理
+  check:
+    schedule: ""           # 留空不执行