# 本设备快照保留策略（0.4.0）

设置页“本设备保留的最近快照数”默认 30，范围 1–10000。新备份上传、下载并与采集内容比对成功后，才登记归属和执行清理。手动、自动、模型工具和 CLI 走同一引擎；CLI 可用 `backup --keep-last COUNT` 覆盖该次设置。

## 归属边界

- 每个 Harness home 首次成功备份时生成一个随机设备标识，保存在 `config-vault/retention-device.json`；不是机器名，也不读取硬件标识。一个 home 下多个 profile 共用该设备标识。
- 每个成功对象登记本机上传凭据，包含快照 ID、上传字节 SHA-256、成功登记时间和设备/目的地分区。保存在 `config-vault/retention/<目的地哈希>/<设备ID>/<快照ID>.json`，不含配置内容、密码或加密口令。
- 目的地按规范化目录 URL 和账号隔离，密码轮换不影响归属。切换 URL 别名或账号会进入另一个保留分区，不猜测两个地址是否实际指向同一目录。
- **只有本机凭据中的 ID 才能成为删除候选。** 不枚举并接管全部远端文件，不依据文件名、远端设备标签或明文快照中的声明判定归属。
- 设备 ID 和凭据都不在备份 allowlist 中。恢复到新 home 会生成新标识；不要手工复制这些本机元数据来“认领”其他设备。删除本机元数据后，旧对象失去可证明归属，会保留而非自动接管。

升级前没有本机凭据的历史快照会保留，因此整个远端目录不保证总共只有 30 个对象；策略约束的是当前设备、当前目的地有凭据的快照。其他设备可独立配置自己的数量。

## 清理顺序与条件

1. 新对象上传并下载校验成功，写入该对象的原子本机凭据。
2. 获取目的地/设备清理锁，读取并完整校验凭据。按本机成功登记时间排序保留最近 N 个，并始终保护刚验证的新对象。
3. 下载旧候选，要求字节哈希与原上传凭据相同。文件已被替换时跳过。
4. 要求服务器返回强 ETag，并使用 `If-Match` 条件 DELETE。GET 后若被其他写入者替换，服务器应以 412 拒绝删除。没有强 ETag、缺少删除权限或不符合预期的响应时保留文件并提示。
5. 确认删除成功或对象已不存在后，才移除本机凭据。断线后状态不确定时留着凭据，下次成功备份再检查。

只删除单个已验证 ID 对应的 `.vault` 文件，不删除远端目录，不处理凭据以外的对象。加密和明文模式使用相同策略；通过字节哈希判断归属，所以清理旧密文不需要旧口令。条件删除安全依赖 WebDAV 服务器正确实现 If-Match，与条件上传同样需要服务端遵守协议。

单次最多处理 50 个旧候选，远端清理受 30 秒总时限约束，防止长时间拖住宿主。降低数量、积压、并发保护、缺少 ETag 或删除失败时可暂时超限；下一次成功备份继续处理。修改保留数量本身不立即删除，也不会为了清理而生成重复自动快照。无内容变更时可以手动备份以触发一次清理。

## 失败和界面

备份与清理是两个结果。清理失败仍返回 `verified: true`，另附 `retention.status`、删除数、待清理数和固定原因码；不返回原始服务端正文或异常文本。设置页显示“备份成功、清理未完成”，保留当前可恢复的新对象。自动任务仍更新内容指纹，避免因为清理失败重复上传相同配置。

本地清理状态和锁不纳入快照。锁按 PID 检查，只回收已退出进程的锁；同 home 并发成功备份先独立登记凭据，未获得清理锁的操作报告延后，下次再处理。损坏或无法读取的归属记录会阻止清理，不能通过猜测继续删除。

本地回滚日志不受这个数量设置影响，恢复依旧需要停止目标 Harness、离线预览和确认 token。