BackupTools（Unix 版）安装与使用说明 ==================================== 适用平台：Linux（unix）、macOS（macos）。作用：把本机指定目录备份到 Gitee 仓库，并在需要时增量还原到本机。 一、依赖 -------- 1. 运行依赖系统已安装 git。 2. 在线安装与更新需要 curl 或 wget。 3. 安装脚本按平台选择预编译二进制：Linux 用 unix/，macOS 用 macos/。 二、在线安装 ------------ 按平台选择一条命令执行（脚本会自动识别 CPU 架构）： # Linux curl -fsSL <基地址>/backup-tools/unix/install.sh | bash # macOS curl -fsSL <基地址>/backup-tools/macos/install.sh | bash 可选参数（管道方式需用 bash -s -- 传递）： --prefix DIR 安装前缀，默认 $HOME/.local --shell bash|zsh 指定补全与 rc 片段使用的 shell（默认自动识别） --reinstall 同版本已安装时也重新安装 --force 覆盖无安装记录的已有文件，或允许降级 --insecure 跳过 TLS 证书校验（自签/私有 CA 服务器） --base-url URL 覆盖基地址 示例： curl -fsSL <基地址>/backup-tools/unix/install.sh | bash -s -- --prefix "$HOME/.local" 自签/私有 CA 证书同时需要跳过引导下载与脚本内部下载的校验： curl -kfsSL <基地址>/backup-tools/unix/install.sh | bash -s -- --insecure 基地址优先级：--base-url > 环境变量 BACKUP_TOOLS_BASE_URL > ~/.config/backup-tools/install.conf 中的 base_url= 行 > 发布时注入的默认值。 安装内容： <前缀>/bin/backuptools 主命令 <前缀>/share/bash-completion/completions/backuptools bash 补全 <前缀>/share/zsh/site-functions/_backuptools zsh 补全 <前缀>/share/backup-tools/install-record 安装记录 <前缀>/share/backup-tools/config-templates/ 配置模板 安装脚本会幂等写入 ~/.bashrc 或 ~/.zshrc 中的受管片段（标记 "# >>> backup-tools >>>"），设置 PATH 并加载补全。重复安装不会重复追加。 三、离线安装 ------------ 下载自包含归档并在解压目录执行包内 install.sh（不联网）： wget <基地址>/backup-tools/unix/backup-tools-unix-v<版本>.tar.gz tar -xzf backup-tools-unix-v<版本>.tar.gz cd backup-tools ./install.sh --prefix "$HOME/.local" --shell bash macOS 将 unix/ 换成 macos/。归档内含各架构二进制、补全、配置模板、 install.sh、uninstall.sh、version 与使用教程。参数与在线安装一致。 四、配置 Gitee 访问 ------------------- 软件运行时只读取 auth 文件，不再提供交互式凭据录入命令。 1. 复制模板（安装时已随包安装）： mkdir -p ~/.config/backuptools cp <前缀>/share/backup-tools/config-templates/auth.example ~/.config/backuptools/auth chmod 600 ~/.config/backuptools/auth macOS 的配置目录为 ~/Library/Application Support/backuptools。 也可使用发布目录中的 config-templates.zip，解压后取 auth.example。 2. 编辑 auth（只允许 repo_url 与 token 两个属性）： repo_url=https://gitee.com/<用户名>/<仓库>.git token= 3. 保存后运行 backup / restore / check 即可。文件缺失、仍是模板占位值、 缺少属性、含多余属性或格式错误时，工具会明确报错并终止本次操作。 Gitee 私人令牌获取：Gitee「设置 → 私人令牌」，勾选仓库读写权限。 五、快速开始 ------------ 1. 配置更新地址（可选；默认取发布时注入的地址）： backuptools config update_base_url https://example.com 2. 设置需要基路径的源（如 project 源，输入包含 Project 目录的父目录）： backuptools config project /home/test 3. 备份（交互式勾选本次要备份的源，确认后推送到 Gitee）： backuptools backup 4. 还原（可选择备份版本，默认最新；覆盖前先备份本机旧文件）： backuptools restore # 交互式选择版本与源，需确认 backuptools restore -y # 跳过确认 backuptools restore -version 20261031170700 -y # 直接还原指定版本 5. 检查（只读比对本地与远端最新备份，判断是否需要还原）： backuptools check 6. 删除远端备份版本（交互式勾选，回车确认删除）： backuptools delete 7. 查看状态与版本： backuptools status # 配置、本地副本、源清单、文件位置（不显示令牌） backuptools version 六、子命令 ---------- backuptools backup 勾选源并备份到 Gitee backuptools restore [-y] [-version <时间戳>] 选择版本并增量还原（默认最新） backuptools check 只读检查本地与远端差异 backuptools delete 交互式删除远端备份版本（重写历史并强推） backuptools update [-y] [-insecure] 检查并整包更新到最新版本 backuptools status 查看配置与源清单 backuptools config [<键> <值>] 交互式或按键值修改 app config backuptools version 显示当前版本 backuptools help 显示帮助 说明：已移除 backuptools init。Gitee 凭据改由第四节的 auth 文件配置， 源基路径由 backuptools config 设置。 七、备份源（可自定义） ---------------------- 源定义唯一文件：~/.config/backuptools/sources.json （macOS 为 ~/Library/Application Support/backuptools/sources.json） 默认源： agents ~/.config/agents opencode ~/.config/opencode（排除 node_modules、.token） project <基路径>/Project 下的 .rules/ 与 AGENTS.md project 源需要先配置基路径（包含 Project 目录的父目录）： backuptools config project /home/test 未配置基路径的源显示为 (unconfigured)，不可选中。 自定义方式： 1. 直接编辑 sources.json：每个源对象含 name、path、include、exclude， 可选 requires_base_path；name 不可重复。 2. 新增源在数组中追加对象；删除源移除对应对象。 3. 删除 sources.json 即恢复默认源定义。 4. 文件不合法时会报错并指出条目位置；同级其他 .json 文件会被拒绝， 请把内容合并进 sources.json（config.json 除外）。 源定义会随每次备份上传（unix/<时间戳>/sources.json）。在新机器上执行 restore 或 check 时，若本地仍是初始默认定义且远端带自定义定义，会自动采纳； 本地已修改的定义始终优先。 备份范围只由 include / exclude 决定：源目录自带的 .gitignore 会作为普通文件 被备份，不会过滤提交内容（package.json、package-lock.json 等仍会进入仓库）。 不需要备份的目录应写入该源的 exclude；默认 opencode 源已排除 node_modules。 八、本机文件位置（Linux） ------------------------- ~/.config/backuptools/auth Gitee 地址与令牌 ~/.config/backuptools/config.json app config（update_base_url、源基路径） ~/.config/backuptools/sources.json 备份源定义（可编辑） ~/.local/share/backuptools/repo 本地仓库副本 ~/.local/state/backuptools/restore-backup/<时间戳>/ 还原前原文件备份 macOS 的配置目录为 ~/Library/Application Support/backuptools。 九、更新 -------- backuptools update # 检查新版本，展示更新说明，确认后整包更新 backuptools update -y # 跳过确认 backuptools update -insecure # 自签/私有 CA 服务器使用 更新流程：读取 <更新地址>/backup-tools/<平台>/update-manifest.json → 比较版本 → 展示更新说明 → 下载归档并校验 sha256 → 解压并执行包内安装器 → 清理旧版本废弃文件 → 提示重启生效。任一步失败即终止，当前程序保持可用。 更新地址也可持久配置： backuptools config update_base_url https://example.com 十、删除远端备份版本 -------------------- 执行 backuptools delete 后，工具先把本地副本完全同步到远端默认分支，再列出 unix/ 下的全部备份版本（新→旧）。每行显示版本时间、包含的源；最新版本标注 (latest)。 操作键位： ↑ / ↓（或 k / j） 移动光标 空格 勾选或取消当前版本 a / n 全选 / 全不选 回车 确认删除所勾选的版本（回车即最终确认） q 或 Ctrl-C 取消，不删除任何内容 说明： 1. 进入列表时默认全不选，降低误删风险。 2. 最新版本允许删除；删除后 restore 自动使用剩余的最新版本。 3. 允许删除全部版本；删除后远端无可用备份，restore / check 会提示无备份， 直至再次执行备份。 4. 非交互场景（脚本、管道、定时任务）会直接报错，不会自动删除。 5. 删除会重写当前分支的全部 Git 历史并强制推送到 Gitee，使所选版本 在分支历史中不可再访问；其他克隆必须重新克隆才能正常同步。 6. 仅处理当前分支；其他分支与 tag 不处理。Gitee 侧不可达对象可能 短期保留，直至服务端垃圾回收。 7. 若本机 last-version 指向被删除的版本，删除成功后该记录会被清除。 8. 仅操作 unix/ 平台目录，不影响仓库中的 windows/ 等其他目录。 十一、还原时选择备份版本 ------------------------ 执行 backuptools restore 后，工具先把本地副本完全同步到远端默认分支，再列出 unix/ 下的全部备份版本（新→旧）。每行显示版本时间、包含的源；最新版本标注 (latest)。 操作键位： ↑ / ↓（或 k / j） 移动光标 回车 确认还原当前光标所在版本 q 或 Ctrl-C 取消，不修改任何本机文件 选择版本后，再勾选该版本中要还原的源（空格切换、a 全选、n 全不选、 回车确认、q 取消）。版本中不存在的源显示为禁用项，不会被还原。 也可在命令行直接指定版本，跳过交互式版本选择： backuptools restore -version 20261031170700 backuptools restore -version 20261031170700 -y # 脚本场景 说明： 1. 光标默认停在最新版本，直接回车即还原最新版本。 2. 非交互场景未给 -version 时默认最新版本；未给 -y 仍会因无法确认而退出。 3. 版本号格式不合法或版本不存在时报错，并列出当前可用版本。 4. 还原成功后 last-version 记录所选版本，check 据此对比。 5. 还原仍为增量方式，覆盖前本机原文件备份到第八节所列目录。 十二、卸载 -------- 按平台执行卸载脚本： # Linux curl -fsSL <基地址>/backup-tools/unix/uninstall.sh | bash # macOS curl -fsSL <基地址>/backup-tools/macos/uninstall.sh | bash 可选参数： --prefix DIR 安装时使用的前缀，默认 $HOME/.local --shell bash|zsh 指定要清理 rc 片段的 shell（默认自动识别） --force 无安装记录时也删除已知文件 卸载按 install-record 删除文件并移除 rc 受管片段，不删除配置与备份数据。 需要时手动清理第八节所列目录。 十三、升级与清理说明 -------------------- 1. 从 v1 升级：安装 v2 会删除旧补全文件（~/.zfunc/_backuptools 与 ~/.local/share/bash-completion/completions/backuptools）和旧版专属 rc 块 "# >>> backuptools shell completion >>>"，并写入新的安装记录。 2. 旧版 ~/.zshrc 中的共享片段 "# >>> zsh user completions >>>" 可能被其他 工具复用，安装脚本只提示、不自动删除。 3. 应用内更新会自动删除新版本清单中不存在的旧文件；无法确认归属的文件 只提示，不擅自删除。 4. 每次访问 Gitee 前（backup / restore / check / delete），工具先把本地仓库 副本完全同步到远端默认分支（Gitee 为 master），并清理未跟踪及被 .gitignore 忽略的残留，使本地副本与 Gitee 完全一致。 本地副本与远端分叉时（例如另一台机器执行过 delete 重写历史），未推送的 本地提交会被丢弃，但源文件仍在本机，重新执行 backup 即可再次采集。 5. 重复执行安装命令即可修复或升级；同版本默认直接退出，需重装请加 --reinstall。 十四、注意事项 -------------- 1. 默认源的 exclude 用于避免备份敏感文件，自行放宽规则可能导致敏感文件进入备份仓库。 2. restore 为增量还原：只写有差异的文件，保留本机独有文件。 3. 令牌保存在 auth 文件中，不会进入备份数据或日志。 4. <基地址> 指发布根目录（不含项目名与平台），例如 https://example.com。