# 自动备份与可选加密（0.3.0）

在“配置保险箱”设置中选择范围与 WebDAV，开启“配置变更后自动备份”并保存。默认关闭；开启后先等待配置稳定，再创建初始快照。它只在安装了本插件的 Harness 进程运行期间工作，不注册系统启动项、不读取远端覆盖本机，也不改变离线恢复流程。

## 防止频繁上传

- 每 5 秒读取已选 profile 的 allowlist 文件；不递归扫描 home，不上传凭据、会话、缓存、自己的设置或调度状态。
- 0.4.1 起，轮询只读取内容并计算哈希，未变化时不解析 YAML、不写锁文件、不访问网络；准备上传时再持锁采集两次并完整校验。详见 [性能测量](polling-performance.md)。
- 默认等最后一次内容变化后 30 秒，连续编辑会重新计时；可设置 1–600 秒。
- 默认两次自动尝试至少间隔 5 分钟，可设置 1–1440 分钟。间隔内的变更合并，最终上传最新稳定内容。
- 指纹包含文件路径/内容哈希、profile 范围、WebDAV 目的地和加密模式，不包含每次生成的 ID/时间。未变化的已验证内容不再次上传；指纹保存在本机，正常重启后仍能去重。手动成功备份也更新指纹。
- 一个进程内与设置动作/模型工具共用互斥；同一个 home 的多个插件实例还共用 PID 锁及持久化去重记录，防止自动任务同时写入。
- 上传准确使用被检查的那份快照；上传后仍重新下载并校验。上传期间又有变化，在后续轮询中合并处理。

0.4.0 起，自动备份成功后也执行 [本设备快照保留策略](retention.md)，默认保留最近 30 份有归属记录的快照。普通的明确未上传失败按指数退避，最多一小时；上传开始后结果不确定时暂停，重启也不会自动重复 PUT。先“加载快照”检查，再点“恢复自动尝试”，此操作可能创建另一份快照。中断时遗留的 `auto.lock` 仅在原 PID 已退出时回收；若锁文件本身损坏，需在停止全部相关 Harness 后人工检查。

## 加密选择和口令

“加密备份”默认开启。手动备份/预览口令仍按次使用。自动模式可以在保存开关后输入“本次运行自动备份的加密口令”，点击解锁：口令只保留在宿主进程内，关闭自动备份、切换明文或卸载时清除引用，不写入文件、浏览器共享状态或响应。重新启动后需要再解锁；如果进程已有 `DSH_VAULT_PASSPHRASE`，可直接使用它。自动任务不借用手动输入的口令。

关闭加密后，手动和自动备份均不需要口令。保存的是可读 JSON，仍使用 `.vault` 扩展名，包含与加密模式相同的配置范围。配置中直接填写的模型 API Key 等秘密会明文暴露，内容哈希只能检查一致性，不能证明来源或阻止有存储访问权的人重写内容。HTTP 还会明文传输 WebDAV 认证信息；HTTPS 不会让存储中的明文快照自动变成密文。

读取明文快照需要明确选择明文模式，默认加密模式拒绝它，避免静默降级。明文模式也可以读取旧加密快照，但仍必须提供原口令。切换开关不会改写历史对象。

## 恢复依旧离线

设置页只有预览，不执行恢复。CLI 可显式加 `--unencrypted` 创建或读取明文快照；也会采用 `--home` 中保存的加密选项：

```sh
node src/cli.mjs backup --home /path/to/source-home --unencrypted
node src/cli.mjs preview --home /path/to/target-home --id SNAPSHOT_ID --unencrypted
# 停止使用目标 home 的所有 Harness，设置用于保护本地回滚日志的 DSH_VAULT_PASSPHRASE 后：
node src/cli.mjs restore --home /path/to/target-home --id SNAPSHOT_ID --unencrypted --confirm PLAN_TOKEN --offline
```

即使远端快照选择明文，本地回滚日志仍然加密，因此确认恢复和 recover 需要口令。`--offline`、最新计划 token、路径/大小/哈希/配置格式检查、运行时及本地依赖阻塞都保留。自动开关、解锁口令和去重记录不在恢复范围内；恢复不会给另一台设备自动启用后台上传。

## 本机文件和生命周期

`config-vault/settings.json` 保存非秘密开关、等待期和最小间隔；旧 v1 文件不含新字段时自动视为关闭自动备份、开启加密，不需要修改既有配置。`auto-state.json` 只记录指纹、时间、快照 ID 与未确认尝试，不保存配置正文或口令。`auto.lock` 只记录 PID 和随机所有权标记。

卸载时停止定时器、取消并等待正在运行的操作，再丢弃会话口令。关闭页面不停止宿主任务。关闭开关阻止后续自动上传；已经进行中的操作先完成或在卸载时取消。CLI 不启动后台调度器。