# 使用与维护

## 日常流程

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 没有可移植的目录同步接口。重命名后若元数据同步失败，命令可能报告失败但完整目标已经出现：不要直接删目标，应核对内容与另一份备份。未进行真实断电测试。

## 权限与容量

恢复保留文件内容和目录结构，不保留权限、ACL、所有者、时间戳、稀疏属性。POSIX 文件默认 `0600`、目录 `0700`；Windows 权限取决于父目录 ACL。恢复容量需预留目标完整逻辑大小；备份容量至少容纳新增分块、清单及临时文件。目录名称仍可被本机有权限的用户看到。

升级前保留旧版本和另一份可用仓库副本，先运行测试和全量校验。本版格式为 v1，不提供自动格式迁移。