@shellus/way 0.3.1 → 0.4.0

package/README.md

@@ -4,6 +4,12 @@
 
 推荐在所有地方使用策略备份：开发环境、个人电脑、生产服务器。
 
+## 版本说明
+
+- **v0.4.0+**: TypeScript 版本，使用 systemd，凭证直接写在 YAML
+- **v0.3.x**: TypeScript 版本，使用 crontab，支持 .env
+- **v0.2.x**: Bash 版本
+
 ## 设计原理
 
 ### 1. 备份目的
@@ -40,6 +46,11 @@
 
 假设本机被入侵，攻击者不应能通过本机凭证定位或删除备份数据。
 
+**v0.4.0 安全增强**：
+- 使用 systemd 替代 crontab（避免在 crontab 留下痕迹）
+- 移除 .env 文件支持（避免被 `find .env` 发现）
+- 凭证直接写在 `~/.way/repositories.yaml`（权限 600）
+
 ### 9. 多层冗余原则
 
 单一备份链路存在单点故障风险。应在多个维度建立冗余：
@@ -55,52 +66,95 @@
 ## 依赖
 
 - [restic](https://restic.net/) - 备份引擎
-- Node.js >= 18（npm 安装方式）或 yq（脚本安装方式）
+- Node.js >= 18
 
-npm 安装方式会自动处理依赖，脚本安装方式的 install.sh 会自动安装 restic 和 yq。
+## 安装
+
+```bash
+npm install -g @shellus/way
+```
 
 ## 快速开始
 
-### 方式 1: npm 安装（推荐）
+### 1. 初始化配置
 
 ```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: 脚本安装
+编辑 `~/.way/repositories.yaml` 填入实际凭证，设置权限：
+
+```bash
+chmod 600 ~/.way/repositories.yaml
+```
+
+### 2. 初始化 restic 仓库
+
+```bash
+# 本地仓库
+way init
+
+# S3 仓库（指定其他仓库）
+way --remote=s3 init
+```
+
+### 3. 配置定时备份
 
 ```bash
-# 安装（way + restic + yq）
-curl -fsSL https://github.com/shellus/way/releases/latest/download/install.sh | bash
+way systemd install
+way systemd status
 ```
 
-### 使用
+### 4. 手动执行备份
 
 ```bash
+way run              # 备份所有项目
+way run data         # 只备份 data 项目
+way snapshots        # 查看快照
+```
+
+## 命令参考
 
-# way 自己的命令（不与 restic 冲突）
+```bash
+# 备份命令
 way run                 # 执行备份（读取 rules.yaml 的项目和排除规则）
 way run data            # 只备份 data 项目
 way gc                  # 按 retention 策略清理旧快照
-way cron install        # 安装定时任务
-way cron show           # 显示将要安装的 crontab
+
+# systemd 定时任务
+way systemd install     # 安装 systemd 定时任务
+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
-way prune               # → restic prune（直接透传）
 
 # 指定 repository（默认用 repositories.yaml 中的 default）
 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]
+```
+
 ---
 
 ## 配置说明
@@ -123,7 +177,7 @@ WAY_DIR=/path/to/config way snapshots
 备份规则配置，参考 [`rules.yaml`](rules.yaml)：
 
 - **projects**: 备份项目、路径、专属排除规则
-- **schedule**: 备份时间、清理任务的 cron 表达式
+- **schedule**: 备份时间（systemd timer OnCalendar 格式）
 - **retention**: 快照保留策略
 - **global_excludes**: 全局排除规则
 
@@ -142,43 +196,45 @@ restic 使用 Go 的 filepath.Match 语法：
 
 备份目的地配置，参考 [`repositories.yaml`](repositories.yaml)。
 
-### .env
+**v0.4.0 变更**：凭证直接写明文，不再支持 `${VAR}` 环境变量语法。
 
-敏感凭证通过环境变量注入，在 `.env` 中定义：
-
-```bash
-RESTIC_PASSWORD=your-restic-password
-AWS_ACCESS_KEY_ID=your-access-key
-AWS_SECRET_ACCESS_KEY=your-secret-key
+```yaml
+repositories:
+  local:
+    type: local
+    path: /backup/repo
+    credentials:
+      password: your-password  # 直接明文
 ```
 
-在 `repositories.yaml` 中使用 `${VAR}` 语法引用：
+建议设置文件权限：`chmod 600 ~/.way/repositories.yaml`
 
-```yaml
-credentials:
-  password: ${RESTIC_PASSWORD}
-  access_key_id: ${AWS_ACCESS_KEY_ID}
-```
+## 配置备份
 
-## 凭证离线备份
+`~/.way/` 目录包含所有配置和凭证，建议整体备份到安全位置：
 
-`repositories.yaml` 和 `.env` 包含 restic 仓库密码和云存储凭证。这两个文件被 `.gitignore` 排除，不会进入版本控制，也不会被 way 自身备份。
+```bash
+# 打包配置目录
+tar czf way-config-$(date +%Y%m%d).tar.gz -C ~ .way
+
+# 加密备份（推荐）
+gpg -c way-config-$(date +%Y%m%d).tar.gz
+```
 
-**如果本机不可访问且遗忘了这些凭证，所有备份数据将永久无法恢复。**
+**如果本机不可访问且遗忘了配置和凭证，所有备份数据将永久无法恢复。**
 
-必须在本机之外单独保存一份：
+必须在本机之外保存 `~/.way/` 备份：
 
 - 密码管理器（推荐）
-- 加密笔记
-- 离线存储（U 盘、纸质打印）
+- 加密云存储
+- 离线存储（U 盘、纸质打印关键凭证）
 
-需要保存的信息：
+关键信息：
 
-| 项目 | 来源 |
+| 项目 | 位置 |
 |------|------|
-| restic 仓库密码 | `.env` 中的 `RESTIC_PASSWORD` |
-| S3 访问凭证 | `.env` 中的 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` |
-| 仓库地址 | `repositories.yaml` 中的 `url` |
+| 备份规则 | `~/.way/rules.yaml` |
+| 仓库配置和凭证 | `~/.way/repositories.yaml` |
 
 ## 数据恢复
 
@@ -222,4 +278,10 @@ way --remote=oss restore <snapshot-id> --target /tmp/restore
 
 ## 开发
 
-参见 [CLAUDE.md](CLAUDE.md)。
+参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解：
+- 项目结构和技术栈
+- 开发环境搭建
+- 变更规范和测试要求
+- 发布流程
+
+内部开发参考：[CLAUDE.md](CLAUDE.md)

package/dist/cli.js

@@ -7,43 +7,14 @@ import { Command } from "commander";
 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 };
 }
 
@@ -82,7 +53,16 @@ function buildS3Options(repo) {
   return options;
 }
 async function execRestic(args, env, s3Options = []) {
-  await execa("restic", [...s3Options, ...args], { env: { ...process.env, ...env }, stdio: "inherit" });
+  try {
+    await execa("restic", [...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/");
+      process.exit(1);
+    }
+    throw error;
+  }
 }
 
 // src/commands/run.ts
@@ -161,68 +141,112 @@ async function gc(options) {
   await execRestic(args, env, s3Options);
 }
 
-// src/commands/cron.ts
+// src/commands/systemd.ts
 import { execSync } from "child_process";
 import fs2 from "fs";
-async function cron(options) {
+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 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");
-  };
+  const serviceContent = `[Unit]
+Description=Way Backup Service
+After=network.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/bin/way run
+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
+`;
   if (options.action === "show") {
-    console.log(generateCron());
+    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") {
-    if (!fs2.existsSync("/usr/local/bin/way")) {
-      throw new Error("Error: /usr/local/bin/way not found");
+    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 status way-backup.timer", { stdio: "inherit" });
+  }
+  if (options.action === "uninstall") {
+    try {
+      execSync("systemctl --user stop way-backup.timer", { stdio: "ignore" });
+    } catch {
     }
-    let existing = "";
     try {
-      existing = execSync("crontab -l 2>/dev/null", { encoding: "utf8" });
+      execSync("systemctl --user disable way-backup.timer", { stdio: "ignore" });
     } 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" });
+    if (fs2.existsSync(servicePath)) fs2.unlinkSync(servicePath);
+    if (fs2.existsSync(timerPath)) fs2.unlinkSync(timerPath);
+    execSync("systemctl --user daemon-reload");
+    console.log("Systemd timer uninstalled");
+  }
+  if (options.action === "status") {
+    execSync("systemctl --user status way-backup.timer", { stdio: "inherit" });
   }
 }
 
 // src/cli.ts
 var program = new Command();
-program.name("way").version("0.3.1").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) => {
+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", `
+\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 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
+
+\u6587\u6863: https://github.com/shellus/way
+`);
+program.command("run [project]").description("\u6267\u884C\u5907\u4EFD").allowUnknownOption().allowExcessArguments().action(async (project, options, command) => {
   const remote = command.parent.opts().remote;
-  const extraArgs = command.args.slice(1);
-  await run({ remote, project, extraArgs });
+  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 });
+  }
 });
 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) => {
+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 cron({ remote, action });
+  await systemd({ 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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellus/way",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "将备份作为持续运营的项目，而非一次性任务。基于 restic 的策略封装。",
   "type": "module",
   "bin": {
@@ -22,7 +22,12 @@
     "type": "git",
     "url": "git+https://github.com/shellus/way.git"
   },
-  "keywords": ["backup", "restic", "snapshot", "cron"],
+  "keywords": [
+    "backup",
+    "restic",
+    "snapshot",
+    "systemd"
+  ],
   "author": "shellus",
   "license": "MIT",
   "bugs": {
@@ -37,7 +42,6 @@
   },
   "dependencies": {
     "commander": "^14.0.3",
-    "dotenv": "^17.3.1",
     "execa": "^9.6.1",
     "js-yaml": "^4.1.1"
   },

package/repositories.yaml.example

@@ -1,5 +1,5 @@
 # 备份目的地配置 (restic repositories)
-# 凭证支持直接填写或引用环境变量: ${ENV_VAR}
+# 凭证直接填写明文（不再支持环境变量）
 # 复制为 repositories.yaml 并填入实际值
 
 default: local
@@ -9,7 +9,7 @@ repositories:
     type: local
     path: /tmp/way-backup
     credentials:
-      password: ${RESTIC_PASSWORD}
+      password: test123
 
   s3:
     type: s3
@@ -18,13 +18,13 @@ repositories:
     options:
       bucket_lookup: dns
     credentials:
-      password: ${RESTIC_PASSWORD}
-      access_key_id: ${AWS_ACCESS_KEY_ID}
-      secret_access_key: ${AWS_SECRET_ACCESS_KEY}
+      password: your-restic-password
+      access_key_id: your-access-key
+      secret_access_key: your-secret-key
 
   sftp:
     type: sftp
     host: backup.example.com
     path: /backup/myhost
     credentials:
-      password: ${RESTIC_PASSWORD}
+      password: your-restic-password

package/rules.yaml.example

@@ -4,14 +4,13 @@
 
 # Uptime Kuma 通知（备份完成后推送状态）
 uptime_kuma:
-  push_url: "${UPTIME_KUMA_PUSH_URL}"  # 支持环境变量
+  push_url: "https://uptime.example.com/api/push/xxxxx"
 
-# 备份时间 (cron格式，留空则不执行)
+# 备份时间（cron 格式，会自动转换为 systemd OnCalendar）
 schedule:
   backup:
-    - "0 12 * * *"   # 每天中午
-    - "0 18 * * *"   # 每天傍晚
-  prune: "0 4 * * 0" # 每周日凌晨4点清理旧快照
+    - "0 12 * * *"   # 每天中午 12:00
+  prune: "0 4 * * 0" # 每周日凌晨 4:00 清理
   check: ""          # 完整性检查，留空不执行
 
 # 快照保留策略

package/README.local.md

@@ -1,44 +0,0 @@
-# 本机环境配置
-
-## 存储后端
-
-腾讯云 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
-```