# 使用与维护

0.10新增format4/5恢复写出续作与显式format5原生元数据归档/恢复。创建、运行、精确死租约续作、权限同意、便携有损策略及窄崩溃窗口拒绝见 [0.10指南](RELIABILITY_0_10.md)。旧目录不自动升级，日志丢失不接管暂存区；首次使用先用合成资料练习。

0.9分页续作、工作台、部分恢复、双确认保留、追加副本/新密钥重建、WAL/后台/通知及未支持项见 [0.9指南](RELIABILITY_0_9.md)。旧格式沿用旧入口，不自动升级；旧专用清理/修复命令不能当成通用分页能力。

报告/演练、加密、独立副本和保留清理见 [RECOVERY](RECOVERY.md)；任务与本机工作台见 [WORKBENCH](WORKBENCH.md)。0.3 的多选、取消、密钥和属性边界见 [PRACTICAL_0_3](PRACTICAL_0_3.md)，桌面安装/回退见 [DESKTOP](DESKTOP.md)。以下日常备份与故障保护规则继续有效。旧工具不能打开未知仓库标识，升级前保留旧版本与原仓库，不原地变更格式。

## 日常流程

1. 关闭正在改写资料的程序，或先导出一致性数据；数据库不要直接备份其运行中数据目录。
2. 在独立盘创建仓库，运行 `plan` 核对排除规则和大小预算。
3. 执行 `backup`，保存返回的快照 ID；重要 ID 可另存可信渠道。
4. 运行 `verify <repo> all`；定期恢复到新目录，检查内容。`list/status` 不能替代完整校验。

仓库最多允许一个操作持有锁，包括读取和恢复。为避免跨主机错误抢锁，网络盘上的外地主机锁不自动回收。NAS 场景需先验证同步、原子重命名和故障行为，不能仅凭目录能读写就视为可靠备份。

## 错误处理

| 现象 | 处理 |
|---|---|
| `Repository locked` | 确认本机其他操作已停止，再执行 `recover <repo>` |
| 外地主机/无法识别的锁 | 先协调该主机；不支持强制破锁，保留原目录并人工确认 |
| 对象缺失/损坏或清单 SHA 不符 | 保留证据；从另一份可信备份恢复，不编辑清单或覆盖对象掩盖问题 |
| 源文件/目录发生变化 | 暂停写入，再执行备份；已存的合法分块可复用 |
| 磁盘满/写入失败 | 释放其他空间，保留原始资料；`recover` 清理未提交临时文件后重试 |
| 目标目录已存在 | 选新的目标，工具不提供 `--force` 覆盖选项 |
| Linux/macOS 缺少排他重命名辅助程序 | 在完整源码目录运行 `npm run build`；不降级为可能覆盖的普通 rename |
| 超出预算/特殊文件/不兼容名称 | 拆分资料集或精确排除；不静默跳过，不修改原文件 |

`recover` 删除的仅是未提交的 `.part/.manifest` 文件；这些不是可用快照，其源资料应仍在原目录。已提交但尚未被任何快照引用的对象保留，可在重试中复用；`status` 会报告它们。本版没有自动删除历史数据的命令。

## 中断恢复

备份进程终止后，可能留下死锁、临时文件和未引用对象；不会发布半个清单。执行 `recover` 后重新备份，原对象可复用，但仍会重新扫描源文件，这不是保存了每个扫描游标的断点续跑。

恢复失败的暂存目录位于目标父目录，名称 `.moonrestore-<uuid>.partial`。正常捕获错误会打印其位置。进程被强制终止时，请查看目标父目录中的这个目录；正式目标尚未提交。`recover` 不自动删除仓库之外的目录，重试应重新验证并创建新的暂存目录。

文件写入进行同步；Linux/macOS 尽力同步目录，Windows 没有可移植的目录同步接口。重命名后若元数据同步失败，命令可能报告失败但完整目标已经出现：不要直接删目标，应核对内容与另一份备份。未进行真实断电测试。

## 权限与容量

恢复保留文件内容和目录结构；0.3 对带有效扩展的条目默认恢复修改时间，基础 POSIX 权限需明确选择（CLI 环境变量 `MOONRESTORE_RESTORE_MODES=1`）。默认 POSIX 文件 `0600`、目录 `0700`；Windows 权限取决于父目录 ACL。不恢复 ACL、所有者、稀疏属性、ADS/xattrs 或特殊权限位；旧快照没有属性则继续使用默认值。恢复容量需预留目标完整逻辑大小及文件系统开销；备份容量至少容纳新增分块、清单及临时文件。目录名称仍可被本机有权限的用户看到。

升级前保留旧版本和另一份可用仓库副本，先运行测试和全量校验。默认格式保持 v1；显式加密/大文件 profile 见 FORMAT，不提供原地自动格式迁移。