Shuery/BakNRet
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d72fe63c02e02f3c9b62ebde3d5d6ccc27156ea1
BakNRet/README.md
T
Shuery d72fe63c02 docs: 跟上 TUI 与入口重组（README 入口名 + TUI 一节 + CHANGELOG + CONTEXT 模块与入口） 
README 里 24 处过期入口名（13 处 Backup.ps1、11 处 Restore.ps1）全部更新为新名字 —— 这正是 ADR-0012 里垫片存在的理由：内部实现改名断了会当场报错，而 README 里的入口名过期是**静默没用**，所以垫片留一轮等文档跟上。现在文档跟上了，删垫片的时机也就到了。

README 新增「交互界面（TUI）」一节：怎么进三个编辑器、每个编辑器能改什么（以及为什么有些字段刻意不列 —— 值跨行或本身是集合时"改一行"没有明确含义）、-Quiet 与 -InputScript 的用途、以及"只有真终端才画界面，否则明确报错并给退出码 2"。入口表从"两个入口"扩成四个（主入口 / 动作 / 配置 / 垫片）。

CHANGELOG 增加「新增：交互界面与入口重组」一节，含三项编辑器共用的外科式改写保证与那条往返断言；并写明旧命令照旧可用。

CONTEXT.md 增加「模块与入口」一节：BakNRet/ 四层的分工与规矩（清单是显式白名单、加载器是唯一点源顺序声明处、Public 一个函数一个文件、Private 放内部实现与 State），以及四个入口脚本的职责与"编排尚未下沉"这个已知的下一步。

验收：test.ps1 9/9 全绿（5.1 与 7）。
2026-09-27 22:40:54 +08:00

409 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# BakNRet
把 `BackupList.txt` 里列出的软件 / 目录用 **7-Zip** 打包进 `Backups/`，并且能用 `Restore-Data.ps1` 原样恢复的 Windows 备份工具。
- 清单里**直接写软件名**即可（如 `Edge`），目录映射维护在 `SoftwareCatalog.psd1` 里。
- 一个软件一个归档：**归档名 = 软件名**（`Edge.7z`），归档内按名录里的 **Slot 分层**
（`<Slot>\<该路径的内容>`），所以同一个软件里两个都叫 `persist` 的目录不会再撞在一起。
- 清单行首 `+` = 仅备份、`-` = 仅恢复；两条路径共用同一份清单。
- 排除 / 追加 / 加密都能写在 `SoftwareCatalog.psd1` 的 Slot 上，清单行里可以按条目覆盖。
- 只依赖 PowerShell（5.1 或 7.x）与 7-Zip，**运行备份/恢复不需要任何模块**（只有跑 Pester 测试才需要 Pester 5）。
- 每个归档写完后做 `7z t` 内容校验，**先写临时文件、校验通过再原子替换**。
- 每次运行产出可核对的 `Backups/manifest.json` 与 `logs/*.log`。
- 归档之外还保存 **NTFS 安全描述符**（属主 / 属组 / DACL）：每个归档旁边一份
`<归档名>.acl.json`，恢复时按它回放。这是"恢复之后原程序还能不能读写"的关键
（`C:\ProgramData` 下那些靠 `CREATOR OWNER` 授权的目录，见「安全描述符」一节）。
- 退出码可靠：有失败就返回 `1`，计划任务能正确判断成败。
- 备份结束做**孤儿归档审计**：磁盘上有、但没有任何清单条目指向的归档会被点名（它们恢复不到，别误删）。
- 恢复支持 `-WhatIf` / `-DryRun` / `-VerifyOnly` / `-Only` / `-Skip`；其中三种"只看不写"的模式（`-WhatIf` / `-DryRun` / `-VerifyOnly`）**一个字节都不写**。
- 动手之前先**预估本次所需空间**并直接判断目标卷够不够（不够只告警、不中断）。
---
## 快速开始
```powershell
# 1. 先试运行：只打印计划，不写任何文件
.\Backup-Data.ps1 -DryRun
# 2. 正式备份
.\Backup-Data.ps1
# 3. 强制重打（忽略"源未更新"判断）
.\Backup-Data.ps1 -Force
# 3b. 确认可以接受"有文件被占用而没打进归档"时，允许覆盖完整归档
.\Backup-Data.ps1 -Force -AcceptWarnings
# 4. 只备份 / 只恢复某几项（通配符匹配清单条目或归档名）
.\Backup-Data.ps1 -Only 'Edge','OpenSSH'
.\Restore-Data.ps1 -Only 'Edge' -Force
# 5. 恢复前先看计划（恢复会覆盖真实目录，务必先看一眼）
.\Restore-Data.ps1 -DryRun
# 6. 只校验所有归档完整性，不解压（只读，安全）
.\Restore-Data.ps1 -VerifyOnly
```
## 文件说明
| 路径 | 作用 |
| --- | --- |
| `SoftwareCatalog.psd1` | **软件名 → Slot 组**的映射：每个 Slot 是一个目录/文件，以及它的排除、追加、加密、说明 |
| `BackupList.txt` | 备份 / 恢复共用的清单，唯一的"要处理什么"来源 |
| `BackupConfig.psd1` | 目录、空间阈值、校验、加密等配置 |
| `Manage-Backup.ps1` | **主入口**：不带参数进 TUI 菜单；带 `-Action Backup\|Restore\|Config` 直接做该动作（配 `-Quiet` 走无头） |
| `Backup-Data.ps1` / `Restore-Data.ps1` | 备份 / 恢复动作本身（无头，可在计划任务里直接调） |
| `Edit-Config.ps1` | 配置管理：清单 / 设置 / 名录三个界面（见下节） |
| `Backup.ps1` / `Restore.ps1` | **旧名字，转发用的垫片**：内部实现已改名为上面两个，这层只留一轮，删它的时机是大家都改用新名字之后 |
| `BakNRet/` | 模块：`BakNRet.psd1`（清单，`FunctionsToExport` 是显式白名单）+ `BakNRet.psm1`（薄加载器，点源顺序只在这里出现一次）+ `Public/`（62 个对外函数，一函数一文件）+ `Private/`（内部函数与模块级状态） |
| `test.ps1` | **唯一验收入口**：Encode + Parse + Unit + Smoke + E2E，在 7 与 5.1 上各跑一遍 |
| `PSScriptAnalyzerSettings.psd1` | 静态分析配置（三条有意排除与 160 字符行长，理由见 `docs/adr/0008`） |
| `CONTEXT.md` | 术语表（本项目里每个概念只有一个叫法） |
| `CHANGELOG.md` | 变更日志 |
| `docs/adr/` | 决策记录（8 条：为什么这么设计、拒绝了什么） |
| `docs/*.md` | 主题文档：软件名录、清单语法、归档布局、安全描述符（从本文件拆出，便于单独引用与评审） |
| `tools/Build-BakNRetModule.ps1` | 把模块的多个源文件按加载器顺序合回单文件（发布形态、代码签名时需要） |
| `tools/Invoke-Analyzer.ps1` | 静态分析门禁（默认规则 + 格式规则） |
| `Backups/` | 归档与 `manifest.json`（已 gitignore） |
| `logs/` | 每次运行的日志（已 gitignore） |
| `tests/` | 测试：Pester 套件（`*.Tests.ps1`）、零依赖套件、端到端验收、真实归档恢复演练 |
| `tools/Register-BackupTask.ps1` | 注册 / 移除计划任务 |
| `tools/Rename-Archives.ps1` | 把归档名对齐到当前清单规则（默认试运行） |
| `tools/Install-TestDependencies.ps1` | 把 Pester 与 PSScriptAnalyzer 装到仓库内的 `.tools/`（不动机器上的全局模块） |
## SoftwareCatalog.psd1 —— 软件名 → Slot 组
软件名录的语法：一个软件由若干 Slot 组成，每个 Slot 能写路径、排除、追加、加密与说明。详见 [software-catalog.md](./docs/software-catalog.md)。
## BackupList.txt 语法
清单每一行的完整语法：方向标记、修饰符、引号与记号边界。详见 [backup-list-syntax.md](./docs/backup-list-syntax.md)。
## 归档布局、命名与迁移
归档内的层级、归档名怎么来、以及改名与迁移时要注意什么。详见 [archive-layout.md](./docs/archive-layout.md)。
## 安全描述符（属主 / ACL）
属主与 ACL 为什么不是放进归档、而是旁挂一份 sidecar，以及恢复时怎么回放。详见 [security-descriptor.md](./docs/security-descriptor.md)。
## 恢复语义
- 每一项只解出**它自己那棵子树**（`<Slot>` / `<末级名>`），不会把兄弟项也复制到别的父目录下。
- **目录项**：在目标的父目录下建一个指向目标目录的 junction，让 7z 直接写穿它落地（零拷贝），
解完立刻拆掉连接点。建不出连接点（父目录里已有同名实体、目标卷不支持等）时，
退回"先解到临时目录再逐项合并"——只慢不错。
- **文件项**：解到临时目录后把文件搬到 `Path` 指定的位置（恢复原名）。
- **旧布局兜底**：归档里没有该 Slot 时（重构前的归档）会打印告警，退回到旧布局
（把目标的末级名直接解到目标的父目录），与重构前的恢复语义一致。
- **不做镜像同步**：目标目录里多出来的文件不会被删除。想得到"完全等于归档"的目录，请先清空目标。
- 行首 `+`（仅备份）的条目不恢复；行首 `-`（仅恢复）的条目照常恢复。
- 目标目录比归档新时**默认跳过**，需要覆盖就加 `-Force`。
- `-WhatIf` / `-DryRun` 只打印计划；`-VerifyOnly` 只跑 `7z t`。
这三种模式**一个字节都不写**（`manifest.json` 也不会被碰）。
- 加密归档取不到口令时**直接失败**，不会让 7z 停在控制台等输入（在计划任务里那会静默挂起）。
- **排除规则只在下一份归档里生效**：已经生成的归档不会因为改了排除表而"变干净"。
## manifest.json
以归档基础名为键记录每个条目：
| 字段 | 含义 |
| --- | --- |
| `source` | 清单里的原始写法（软件名或路径） |
| `resolvedSource` | 展开后的路径 |
| `roots` | 归档内**真实**的顶层条目名（就是 Slot 名 / 源目录名 / 追加项的归档内路径；只统计真实存在的项）。每次重新处理该条目时刷新 |
| `layouts` | 每个归档项的 `{ name, kind }`（`dir` / `file`），恢复端在目标还不存在时靠它判断"该还原成目录还是文件" |
| `catalog` | 名录里记录的路径（便于追溯软件名到底指向哪） |
| `archive` | 归档文件名 |
| `action` | `backed-up` / `skip-unchanged` / `missing-source` / `invalid-path` / `failed` / `planned` |
| `reason` | 跳过或失败的原因 |
| `exitCode` / `verified` / `warnings` | 压缩工具退出码、是否通过 `7z t`、**当前在位归档**是否有警告 |
| `attemptWarnings` | **本次尝试**是否报了警告（与 `warnings` 区分：保留旧归档时前者为 true、后者仍为 false） |
| `sourceFiles` / `sourceBytes` / `archiveBytes` | 源文件数、源大小、归档大小 |
| `lastSuccessAt` / `successCount` / `failCount` / `lastRestoreAt` / `encrypted` | 历史与安全标记 |
`Restore-Data.ps1` **优先用 manifest 定位归档**，查不到才退回"从文件名反推路径"。
如果 `BackupList.txt` 丢了，`Restore-Data.ps1` 会优先用 manifest 里的 `source` 自动重建。
## 备份前空间预估
每次备份在**动手之前**先按清单顺序模拟一遍，把"这次要写多少、盘够不够"直接打出来：
```text
[INFO] ==== 备份前空间预估（只读）====
[INFO] 目标卷可用空间：7.37 GB
[INFO] 本次要重打 8 个条目（另有 7 个源未更新会跳过、9 个源不存在）
[INFO] 新归档合计约 2.44 GB；其中会替换掉的旧归档 1.89 GB
[INFO] - Edge 源 2,303.8 MB / 11354 文件 现有 1,781.3 MB 预估 2,303.8 MB
[INFO] - MiFlash_Unlock 源 231.3 MB / 153 文件 现有 70.0 MB 预估 91.0 MB
[INFO] ...
[INFO] 预计峰值新增占用：2.25 GB（全程净增量 0.55 GB）
[INFO] 结论：空间足够（预计用 2.25 GB / 可用 7.37 GB）
[INFO] ============================
```
- **估算模型**：临时归档写完时旧归档还在，那一刻占用"当前累计净增量 + 本次预估"，
原子替换之后本次净增量 = 预估 − 旧归档大小。峰值取整个过程的最大值。
- **预估归档大小**：有历史归档时取 `min(源大小, 旧归档 × 1.3)`；没有历史归档时按
"完全不压缩"的悲观值估 —— 宁可报多不报少。
- **结论只有两种**：空间足够，或者"空间可能不够！预计需要 X GB，可用 Y GB，差 Z GB"。
不够时**只告警、不中断** —— 真正放不下的条目会被逐条目守卫跳过；想稳妥就腾空间或加 `-Only` / `-Skip` 分批。
- 这一步是只读的，不改任何文件；`-DryRun` 也照跑。
## 日志
`logs/backup-<时间戳>.log` / `logs/restore-<时间戳>.log`，与控制台内容一致。
压缩工具自身的实时输出直接进控制台，不进日志（见「设计取舍」）。
## 配置（BackupConfig.psd1）
```powershell
@{
BackupDir = 'Backups' # 相对路径按脚本所在目录解析
LogDir = 'logs'
SnapshotDir = 'Backups\snapshots'
SoftwareCatalog = 'SoftwareCatalog.psd1'
MinFreeSpaceGB = 5
VerifyArchive = $true # 归档后跑 7z t
ComputeHash = $false # 是否额外算 SHA256（大归档很慢）
CompressionLevel = 9
ToolOutput = 'live' # live | quiet
Snapshot = @{ Enabled = $false; KeepCount = 3; KeepDays = 30 }
Encryption = @{ Enabled = $false; PasswordFile = 'baknret.key'; EncryptHeaders = $true }
DefaultExcludes = @('!Thumbs.db', '!desktop.ini')
}
```
优先级：**命令行参数 > `BackupConfig.psd1` > 代码内置默认值**，也可以用 `-ConfigPath` 指定其它配置文件。
## 加密
默认关闭 —— 一旦开启而口令丢失，备份就再也解不开。
```powershell
# 方式一：给某个 Slot 加密（私钥、浏览器数据这类最典型）
# SoftwareCatalog.psd1:
# OpenSSH = @{ DefaultData = @{ Path = '%UserProfile%\.ssh'; Encrypt = $true } }
# 或在 BackupList.txt 的条目上写：
# Edge :encrypt
# PowerShell @ Encrypt='$false' # 反过来，关掉名录里的默认加密
# 方式二：全部加密，改配置
# Encryption = @{ Enabled = $true; PasswordFile = 'D:\secret\baknret.key' }
# 口令来源（二者取其一）
$env:BAKNRET_PASSWORD = '...' # 或
.\Backup-Data.ps1 -KeyFile 'D:\secret\baknret.key' # 文件首行即口令
```
一个软件一个归档：名录里各 Slot 的 `Encrypt` 不一致时，**整个归档按加密处理**（宁可多加密，不可漏加密），
并打印告警。要求加密但取不到口令时，该条目会**明确失败**，绝不会退化成明文归档。
恢复加密归档时同理：取不到口令就直接失败，不会让 7z 停在控制台等待输入（在计划任务里那会静默挂起）。
> ⚠️ 7-Zip 只接受命令行口令，口令在本机进程列表里会短暂可见。这是 7z 本身的限制，请自行权衡。
## 口令放在哪里
口令文件的出厂默认值是**仓库根的 `baknret.key`**，靠 `.gitignore` 的 `*.key` 兜住"不被提交"。
这是一次取舍：留在仓库根最省事（口令与配置在一起，搬家时不会丢），代价是"不提交"这件事
依赖一个规则文件 —— 谁写了 `git add -f`、或把整个目录复制到别处再 `git init`，口令就会跟着走。
**相对路径按仓库根解析，不按当前工作目录。** 计划任务的工作目录通常是 `C:\Windows\System32`，
在那里 `Test-Path baknret.key` 为假 —— 如果按工作目录解析，加密条目会以"拿不到口令"失败，
而配置看上去毫无问题。
三种给它口令的方式（优先级见上一节）：
```powershell
# A. 环境变量（计划任务用这个最省事，也最不怕仓库被整体复制）
$env:BAKNRET_PASSWORD = '...'
# B. 配置文件里指到一个仓库外的文件 —— 想更稳就走这条
Encryption = @{ Enabled = $false; PasswordFile = (Join-Path $env:USERPROFILE '.baknret.key'); EncryptHeaders = $true }
# C. 单次指定
.\Backup-Data.ps1 -KeyFile (Join-Path $env:USERPROFILE '.baknret.key')
```
取不到口令时，加密条目**明确失败**，绝不退化成明文归档 —— 这条行为没有放宽。
> 从旧版本迁移：如果你的口令文件已经在仓库根（`baknret.key`），**什么都不用做**。
> 想改用仓库外的位置，把它移走后按上面 B 或 C 指过去，并先用
> `pwsh -File .\Restore-Data.ps1 -VerifyOnly -Only "WindowsTerminal" -KeyFile <新路径>` 验一下
> 口令对不对（那份归档是加密的，口令不对会报错）。
## 计划任务
```powershell
.\tools\Register-BackupTask.ps1 -At '21:30' -DryRun # 先看将要注册什么
.\tools\Register-BackupTask.ps1 -At '21:30' # 注册
.\tools\Register-BackupTask.ps1 -Remove # 移除
```
任务调用 `Backup-Data.ps1`，脚本自身写日志并按失败数返回退出码，所以「上次运行结果」在任务计划程序里可读。
## 测试
四套，按"需要多少依赖"分层：
| 套件 | 命令 | 需要什么 | 覆盖 |
| --- | --- | --- | --- |
| **Pester 套件**（推荐） | `.\tests\Run-Pester.ps1` | Pester 5.0+ 与 7z | 183 项（含安全描述符套件）：清单语法（方向 / `::` / `:-` / `:+` / `:encrypt` / `@ Key='值'` / 整行引号与记号边界）、Slot 结构名录、归档命名、排除翻译（`-x!` / `-xr!` / `!re:`）、Slot 前缀分配、暂存、manifest / 配置 / 名录，外加**用子进程真正跑 `Backup-Data.ps1` / `Restore-Data.ps1`** 的端到端与回归 |
| 零依赖套件 | `.\tests\Run-Tests.ps1` | 只要 PowerShell + 7z | 111 项：同样的单元面，适合没装 Pester 的机器 |
| 端到端验收 | `.\tests\Run-E2E.ps1` | 只要 PowerShell + 7z | 36 项：备份 → 确认排除生效 → 删源 → 恢复 → 逐字节对拍，含 `<Slot>\` 布局、文件 Slot、方向标记与旧布局回退 |
| **真实归档恢复演练** | `.\tests\Restore-Drill.ps1` | 只要 PowerShell + 7z | 12 个真实归档：解到临时目录再和活源逐字节对拍（全程不碰真实目录） |
| **安全描述符套件** | `.\tests\Run-Pester.ps1`（内含 `BakNRet.Security.Tests.ps1`） | Pester 5 + 7z | 含在上面 183 项里：排除判定与 7z `-x!/-xr!` 语义对齐、SID 映射边界（前缀 SID 不被误伤）、采集与 sidecar 往返、回放（`CREATOR OWNER` + 孤儿 SID + `protected` 逐字节一致）、以及真的用子进程跑 `Backup-Data.ps1`/`Restore-Data.ps1` 做端到端 |
演练会把"源在备份之后变过"和"归档/解压有问题"分开：内容不一致时看活源文件的修改时间，
晚于归档时间就算"源变了"（只提示），不晚于归档时间却内容不同才算失败。真实机器上的归档
常常是几周前的，不这样区分就天天报假失败。
Pester 套件要求 **5.0+**。系统自带的是 3.4.0，没有 `Should -Be`，套件会直接语法错误，
所以 `Run-Pester.ps1` 会先查版本，查不到就以退出码 2 结束并打印安装命令。两种装法：
```powershell
.\tools\Install-TestDependencies.ps1 # 只装进仓库内的 .tools/（推荐，不动机器上的全局模块）
# 或者
Install-Module Pester -Scope CurrentUser -MinimumVersion 5.0.0
```
`Run-Pester.ps1` 优先使用 `.tools/` 里的本地副本，其次是机器上已装的 5.x；
`.tools/` 已进 `.gitignore`。
Pester 套件里的端到端用例是**用子进程**跑 `Backup-Data.ps1` / `Restore-Data.ps1` 的，原因有二：
两个脚本结尾都会 `exit`，同进程 `&` 调用会把 Pester 宿主一起带走；而且子进程给出的是
真正的进程退出码，正好独立验证"退出码取法"这条修复。
## 相对旧版修了什么
见 [CHANGELOG.md](./CHANGELOG.md)。本次改造（2026-09）的修复、结构变化与规范落地都在那里。
## 验收与静态分析
一条命令跑完全部验收层次，**两个 PowerShell 版本各跑一遍**：
```
powershell
.\test.ps1 # Encode + Parse + Unit + Smoke + E2E
.\test.ps1 -Suite Parse # 只跑一层
.\test.ps1 -Suite E2E -PSVersion 5.1
.\tests\Run-RealSmoke.ps1 # 拿真实清单与真实归档做只读冒烟
```
| 层次 | 内容 | 依赖 |
| --- | --- | --- |
| Encode | 受管文件的 BOM / 行尾 / 制表符 —— 丢了 BOM 只在 5.1 上出错，所以这条必须单独检查 | 无 |
| Parse | 全仓 `.ps1` / `.psm1` / `.psd1` 在 5.1 与 7 上解析零错 | 无 |
| Unit | Pester 套件（单元面） | Pester 5+ |
| Smoke | 零依赖套件（关键冒烟） | PowerShell + 7z |
| E2E | 真的调用 7z 打包 → 删源 → 恢复 → 逐字节对拍 | 7z |
| Drill | 真实归档恢复演练（只读，要显式点名） | 本机真实归档 |
`Run-RealSmoke.ps1` 刻意独立于上面几层：其它套件都在临时目录里自造夹具，跑得快、可重复；
它专门跑真实清单，用来挡住"夹具全绿、真实数据全废"。它检查四件事：方向标记全部被剥掉、
没有软件名退化成"名录里没有"、两个只读模式退出 0、`manifest.json` 的 SHA256 前后不变。
静态分析是**独立门禁**，不塞进上面几层（套件跑一次二十多秒，混进去会让"测试红了"这句话
失去分辨力）：
```
powershell
.\tools\Invoke-Analyzer.ps1 # 默认规则 + 格式规则
.\tools\Invoke-Analyzer.ps1 -Quiet # 只看按规则汇总
```
那 6 条格式规则（括号、缩进、空格、对齐、大小写）在 PSScriptAnalyzer 里**默认是 Disabled** ——
不带 `-Settings` 的 `Invoke-ScriptAnalyzer -Severity Warning,Error` 会静默漏掉全部排版问题。
三条有意排除与 160 字符行长上限的理由见 [docs/adr/0008](./docs/adr/0008-analyzer-deviations.md)。
### 在 Hyper-V 虚拟机里验证
上面几层都在本机跑。真正值得单独跑一遍的是 `tools/lab/`：它把仓库同步进一台**干净系统**的
Hyper-V 虚拟机（`gsudo pwsh -File .\tools\lab\Lab.ps1 ...`），在那里跑完整流程。本机跑不到的
路径只有它能覆盖 —— 最典型的是**安全描述符回放**：需要把某个目录的属主改成 `NT AUTHORITY\SYSTEM`、
再靠 `CREATOR OWNER` 的继承规则判断恢复后归谁，而这件事只有在真 VM 里才敢做。
| 步骤 | 它验证什么 | 最近一次结果 |
| --- | --- | --- |
| `Lab.ps1 test -Suite all` | 三套仓库测试在干净系统上能不能跑 | Pester 183 / 零依赖 111 / 端到端 36，全部通过 |
| `Lab.ps1 backup` | 在 VM 内真跑 `Backup-Data.ps1`（沙盒清单 + 配置） | 退出码 0 |
| `Lab.ps1 restore` | 用真实归档做恢复演练，**逐字节对拍** | 通过 6 / 失败 0（含连接点场景 4/4） |
| `Lab.ps1 acl-test` | 安全描述符：属主 / `CREATOR OWNER` / 安全指纹 | 全部通过 19 项（含负对照） |
`acl-test` 里有一个**负对照**值得留意：只搬文件不回放安全描述符时，属主会变成"跑脚本的账户"
而不是原账户 —— 那条用例能证明这个演练分辨得出对错，而不是一路绿灯。
## 设计取舍（有意为之，不是遗漏）
- **放弃 7z 的更新模式（`u`）。** 7z 默认固实压缩，`u` 本来就要重压大部分数据，收益很小，却让"排除规则改动"和"源里删掉的文件"永远进不了归档。
- **包内用 Slot 分层，靠暂存目录改名。** 7z 没有"入库时改名"的能力，所以打包前建一个暂存目录，
把每个归档项按包内名字挂进去（目录走 junction、文件走硬链接/复制），打完立刻拆掉。
代价是每份归档多一次 junction 开销；收益是**一个软件可以有多个目录而不怕重名**
（scoop 的用户 `persist` 与全局 `persist` 就属于这种），恢复时也能精确地"只解这一棵子树"。
建不出连接点时**明确报错**，不悄悄退化成另一种布局。顺带一提，7z 的 `-spf` 不是干这个的
（它是 *use fully qualified file paths*）。
- **恢复用 junction 零拷贝落地。** 目标父目录下建一个指向目标的 junction，让 7z 直接写穿它，
解完立刻拆掉；建不出来就退回"先解到临时目录再合并"。这样不必把大归档整体搬两遍。
- **不捕获压缩工具的输出。** 结构化记录交给日志与 `manifest.json`；捕获子进程 stdio 需要额外管道，在受限环境里会直接失败。
- **有警告（退出码 1）时不覆盖完整的归档。** 被占用的文件会让 7z 返回 1，此时新归档是**不完整**的。实测 Edge 运行时打包，118 个文件读不到，其中包含 `Login Data`（密码）、`Cookies`、`History`、`Web Data`。所以在位归档完整时脚本**保留它、报失败、退出码 1**，确认可以接受再显式加 `-AcceptWarnings`。
- **名录里的路径不存在时，恢复仍然可用。** 源被删掉正是要恢复的场景，所以解析器照旧给出 `Items`，备份端则据此跳过。
- **源路径不存在只算"跳过"，不算失败。** 会以 `missing-source` 记进 manifest。失败只统计真正打不开的条目。
- **`@ Path=` 覆盖只允许单 Slot 条目。** 多 Slot 时"覆盖"根本没有唯一含义，直接报错比猜一个 Slot 好。
- **旧归档用"旧布局兜底"而不是拒绝恢复。** 重构前的归档包内没有 Slot 层，
恢复时按 Slot 解会失败，脚本捕获后按旧布局（目标的末级名）再试一次，
并在日志里说清楚——旧备份仍然救得回来。
## 已知限制
- **改软件名 / 改 Slot 名等于换归档结构。** 改名后旧归档不会被自动迁移，用 `tools/Rename-Archives.ps1` 或手动改名，
并注意 manifest 里会留下旧键；Slot 名变了则需要重打（`-Force`）。
- 路径里本来就含 `+` 或 `_from_` 时，仅靠文件名无法可靠反推路径，此时依赖 `manifest.json`。
- `-Snapshot` 目前是"复制一份带时间戳的副本"，不做自动轮转清理（`KeepCount` / `KeepDays` 尚未实现）。
- 加密归档的常规备份/恢复不依赖 `RAR`；`RAR` 与内置 `ZIP` 分支仅作降级，未做加密支持（ZIP 明确拒绝加密请求）。
内置 ZIP 分支也不支持排除规则（`Compress-Archive` 没有对应开关），只保证内容完整。
- **暂存改名需要能建目录连接点（junction）。** 暂存目录在 `%TEMP%`（NTFS 即可），目标源目录跨盘也没问题；
建不出连接点时该条目会明确失败，而不会静默换成别的布局。恢复时的 junction 建不出来会自动退回"临时目录 + 合并"。
- **一个 Slot 只能对应一个目录。** 前缀补全命中多个候选（同一个父目录下既有 `X` 又有 `X_后缀`）时会报错并让你拆成多个 Slot，
而不是任选一个。
- **`!re:` 有量级上限。** 正则命中的路径超过 300 条、或排除参数超过命令行安全长度时会明确失败；
这种场景应改用更粗的通配模式。
- **`root=<名>` 标记已废弃。** 包内的一层目录现在由 Slot 决定；写了该标记只会打印告警。
- **空间只做"预估 + 提示"，不做全局拦截。** 备份前会打印预计峰值新增和"够不够"的结论；
不够时**只告警不中断**，真正放不下的条目交给逐条目守卫跳过。`MinFreeSpaceGB` 是告警阈值。
想稳妥跑完就先腾空间，或用 `-Only` / `-Skip` 分批。
- **恢复安全描述符需要管理员（或 SYSTEM）。** 非提权时属主写不进去（`SeRestorePrivilege`
不在令牌里），脚本会退化到"只恢复 DACL"并明确告警 —— 那不是失败，但 `CREATOR OWNER`
会判给"当前属主"，所以依赖它的程序可能仍然没权限。
- **`acl.json` 要跟归档一起搬。** 它不在归档里（7z 装不下），改名 / 迁移归档时要用
`tools\Rename-Archives.ps1` 或手工把同名旁挂文件一起改。
- **7z 会跟随 junction**（不是存成链接，因为 `-snl` 只对 WIM/TAR 生效）：所以 scoop 那种
`apps\<app>\current` 的连接点，备份时会把目标内容一并收进归档（体积翻倍），恢复后
`current` 变成**真实目录**。功能上仍然可用（`current\bin\...` 路径还在），但要心里有数。
- **跨机恢复要配 `Security.SidMap`**：本机不存在的 SID 写进 DACL 是安全的（那条 ACE 只是
永不匹配），但写进**属主**会让谁都没有合理所有权 —— 换域 / 换机时请给映射，或接受
"属主未恢复"的告警。服务账户（`NT SERVICE\X`）的 SID 是按名字算出来的，跨机一致。
## 交互界面（TUI）
不带参数运行主入口就会进菜单：
```powershell
.\Manage-Backup.ps1 # 主菜单：备份 / 恢复 / 配置
.\Edit-Config.ps1 # 配置菜单：清单 / 设置 / 名录
.\Edit-Config.ps1 -Target List # 直接进某个编辑器
```
三个编辑器改配置的方式是**外科式改写**：只动你改的那一行（注释、对齐、`$( )` 表达式、跨行拼接一字节不动），
先校验再落盘，落盘前把原文件按时间戳复制到 `logs\config-backups\`。所以改坏了随时能翻回去。
| 界面 | 改什么 | 说明 |
| --- | --- | --- |
| 清单 | `BackupList.txt` | 改方向（`both` / `backup` / `restore`），保留你原来的写法风格（贴着写与留空格都原样） |
| 设置 | `BackupConfig.psd1` | 单行标量设置；值跨行或本身是集合的（如 `SidMap`、`DefaultExcludes`）**不列出**，因为"改一行"对它们没有明确含义 |
| 名录 | `SoftwareCatalog.psd1` | 只有单行的 `Encrypt` 与 `Description` 可改；`Path` 常带动态表达式、`Exclude` 可能是跨行拼接，一律只读 |
### 无头与自动化
- `-Quiet`：不画界面，把被调动作的输出捕获后原样转发出来（计划任务与管道用这个）。
- `-InputScript`：用按键序列驱动界面，门禁就是靠它把"打开菜单 → 选一项 → 改一个值 → 保存"整条流程跑通的。
序列用尽而界面还在等输入时会**报错退出**，绝不退回去读真终端 —— 挂起比失败糟得多。
- 只有真终端才画界面：检测到输出被重定向且没给按键序列时，明确报错并给退出码 2，不会卡住。
设计取舍（为什么零依赖、为什么不做全屏、为什么异常不改退出码）见 `docs/adr/0010` ~ `0013`。
Reference in new issue View Git Blame Copy Permalink