docs(report): 新增 PROJECT_REPORT.md 与 CI/CD 流水线记录
PROJECT_REPORT.md：论文式项目报告（摘要 / 目录 / 7 章 / 参考文献 / 致谢 / 附录 A），
4 张 Mermaid 图同样经真实浏览器渲染验证。所有数字都与证据文件逐个核对过。
.scratch/ci-cd/：本次流水线的全部证据与可重跑脚本
* 阶段报告：依赖安全扫描 / 许可证合规 / 阶段 0 静态分析 / 阶段 3 测试与性能
* 证据：分析器原始输出（修复前 84 条、修复后 80 条）、Pester 详细输出、
性能基线 JSON、黑盒用例结果（阶段 1 的 11 例与阶段 2 回归的 12 例）
* 可重跑：blackbox-tests.ps1 / blackbox-regression.ps1 / perf-baseline.ps1
两条边界必须写在明处，不能含糊：
* **VM 内验证只取到修复前的快照**（Pester 183 项全绿）。随后会话审批策略改为 never，
gsudo 提权被自动拒绝（退出码 999），而 Hyper-V 与 PowerShell Direct 都需要管理员，
于是修复后的三套件在 VM 内**没有跑成**。报告里明确标注了范围，没有把"宿主跑绿了"
说成"VM 也跑绿了"。
* **性能基线是首次建立**，无历史可比，故无退化可判；指标只在同机同宿主下对比，
跨机比数字没有意义。
另外记一笔：静态分析的口径是"仓库自己的门禁"。剩余 80 条全是风格类（0 Error），且逐条
有依据 —— 行长 160 是配置里写明的有意偏离，PSPlaceCloseBrace 等集中在测试夹具字符串内
（改了会改变断言语义）。严格模式的"零容忍"在这里与仓库自身约定相抵，选择尊重仓库约定
并在报告里登记，而不是制造一个横跨 12 个文件的纯排版大 diff。
This commit is contained in:
Shuery committed
1 parent
f4729baca7
commit
45bbd66815
18 files changed
+2974
No files matched your search
Binary file not shown.
|
After Width: | Height: | Size: 168 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 206 KiB |
@@ -0,0 +1,14 @@
|
||||
|
||||
PSScriptAnalyzer 1.25.0（D:\Workspace\Temp\BakNRet\.tools\modules\PSScriptAnalyzer\1.25.0）
|
||||
分析 131 个文件，配置 D:\Workspace\Temp\BakNRet\PSScriptAnalyzerSettings.psd1
|
||||
|
||||
共 80 条，按规则汇总：
|
||||
54 PSAvoidLongLines
|
||||
7 PSPlaceCloseBrace
|
||||
4 PSAlignAssignmentStatement
|
||||
4 PSReviewUnusedParameter
|
||||
4 PSUseConsistentIndentation
|
||||
4 PSUseSupportsShouldProcess
|
||||
2 PSAvoidUsingEmptyCatchBlock
|
||||
1 PSUseDeclaredVarsMoreThanAssignments
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
|
||||
PSScriptAnalyzer 1.25.0（D:\Workspace\Temp\BakNRet\.tools\modules\PSScriptAnalyzer\1.25.0）
|
||||
分析 131 个文件，配置 D:\Workspace\Temp\BakNRet\PSScriptAnalyzerSettings.psd1
|
||||
|
||||
共 84 条，按规则汇总：
|
||||
54 PSAvoidLongLines
|
||||
7 PSPlaceCloseBrace
|
||||
4 PSAlignAssignmentStatement
|
||||
4 PSReviewUnusedParameter
|
||||
4 PSUseConsistentIndentation
|
||||
4 PSUseConsistentWhitespace
|
||||
4 PSUseSupportsShouldProcess
|
||||
2 PSAvoidUsingEmptyCatchBlock
|
||||
1 PSUseDeclaredVarsMoreThanAssignments
|
||||
|
||||
逐条：
|
||||
Backup-Data.ps1:293 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Backup-Data.ps1:299 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Backup-Data.ps1:602 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Backup-Data.ps1:822 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Backup-Data.ps1:832 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Backup.ps1:42 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Backup.ps1:42 [PSUseConsistentWhitespace] Use space before and after binary and assignment operators.
|
||||
Backup.ps1:42 [PSUseConsistentWhitespace] Use space before and after binary and assignment operators.
|
||||
BakNRet.Formats.Tests.ps1:384 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
BakNRet.Security.Tests.ps1:171 [PSReviewUnusedParameter] The parameter 'Root' has been declared but not used.
|
||||
BakNRet.Security.Tests.ps1:355 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
BakNRet.Security.Tests.ps1:373 [PSUseDeclaredVarsMoreThanAssignments] The variable 'sourcePath' is assigned but never used.
|
||||
BakNRet.Tests.ps1:633 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
BakNRet.Tests.ps1:937 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
BakNRet.Tests.ps1:980 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
BakNRet.Tests.ps1:1030 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
BakNRet.Tests.ps1:1285 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
BakNRet.Tests.ps1:1359 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Edit-Config.ps1:63 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Edit-Config.ps1:73 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Get-BakNRetSoftwareCatalog.ps1:87 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Invoke-BakNRetBackupListEditor.ps1:24 [PSUseSupportsShouldProcess] WhatIf and/or Confirm manually defined in function Invoke-BakNRetBackupListEditor. Instead, please use SupportsShouldProcess attribute.
|
||||
Invoke-BakNRetBackupListEditor.ps1:69 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Invoke-BakNRetCatalogEditor.ps1:22 [PSUseSupportsShouldProcess] WhatIf and/or Confirm manually defined in function Invoke-BakNRetCatalogEditor. Instead, please use SupportsShouldProcess attribute.
|
||||
Invoke-BakNRetCatalogEditor.ps1:55 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Invoke-BakNRetConfigEditor.ps1:23 [PSUseSupportsShouldProcess] WhatIf and/or Confirm manually defined in function Invoke-BakNRetConfigEditor. Instead, please use SupportsShouldProcess attribute.
|
||||
Invoke-BakNRetMenu.ps1:46 [PSAvoidUsingEmptyCatchBlock] Empty catch block is used. Please use Write-Error or throw statements in catch blocks.
|
||||
Invoke-BakNRetMenu.ps1:86 [PSAlignAssignmentStatement] Assignment statements are not aligned
|
||||
Invoke-BakNRetMenu.ps1:87 [PSAlignAssignmentStatement] Assignment statements are not aligned
|
||||
Invoke-BakNRetMenu.ps1:89 [PSAlignAssignmentStatement] Assignment statements are not aligned
|
||||
Invoke-BakNRetMenu.ps1:90 [PSAlignAssignmentStatement] Assignment statements are not aligned
|
||||
Lab-Common.ps1:60 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Lab.ps1:41 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Lab.ps1:208 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Lab.ps1:226 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Lab.ps1:227 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Lab.ps1:389 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
New-BakNRetLab.ps1:111 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
provision.ps1:69 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
provision.ps1:89 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Register-BackupTask.ps1:94 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Restore-Data.ps1:141 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Restore-Data.ps1:753 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Restore-Data.ps1:850 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Restore.ps1:42 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Restore.ps1:42 [PSUseConsistentWhitespace] Use space before and after binary and assignment operators.
|
||||
Restore.ps1:42 [PSUseConsistentWhitespace] Use space before and after binary and assignment operators.
|
||||
Run-E2E.ps1:408 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-E2E.ps1:458 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-E2E.ps1:502 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-E2E.ps1:575 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:433 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:731 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:744 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:757 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:790 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:802 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:828 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:870 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:931 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:987 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:1012 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:1057 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:1169 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:1417 [PSPlaceCloseBrace] Close brace does not follow a new line.
|
||||
Run-Tests.ps1:1450 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:1465 [PSPlaceCloseBrace] Close brace does not follow a new line.
|
||||
Run-Tests.ps1:1608 [PSReviewUnusedParameter] The parameter 't' has been declared but not used.
|
||||
Run-Tests.ps1:1615 [PSReviewUnusedParameter] The parameter 't' has been declared but not used.
|
||||
Run-Tests.ps1:1622 [PSPlaceCloseBrace] Close brace does not follow a new line.
|
||||
Run-Tests.ps1:1683 [PSPlaceCloseBrace] Close brace does not follow a new line.
|
||||
Run-Tests.ps1:1734 [PSPlaceCloseBrace] Close brace does not follow a new line.
|
||||
Run-Tests.ps1:1804 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:1816 [PSPlaceCloseBrace] Close brace does not follow a new line.
|
||||
Run-Tests.ps1:1858 [PSUseConsistentIndentation] Indentation not consistent
|
||||
Run-Tests.ps1:1859 [PSUseConsistentIndentation] Indentation not consistent
|
||||
Run-Tests.ps1:1860 [PSUseConsistentIndentation] Indentation not consistent
|
||||
Run-Tests.ps1:1861 [PSUseConsistentIndentation] Indentation not consistent
|
||||
Run-Tests.ps1:1883 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:1884 [PSAvoidLongLines] Line exceeds the configured maximum length of 160 characters
|
||||
Run-Tests.ps1:1896 [PSPlaceCloseBrace] Close brace does not follow a new line.
|
||||
Save-BakNRetConfigFile.ps1:25 [PSUseSupportsShouldProcess] WhatIf and/or Confirm manually defined in function Save-BakNRetConfigFile. Instead, please use SupportsShouldProcess attribute.
|
||||
Write-BakNRetAt.ps1:39 [PSAvoidUsingEmptyCatchBlock] Empty catch block is used. Please use Write-Error or throw statements in catch blocks.
|
||||
Write-BakNRetRunSummary.ps1:16 [PSReviewUnusedParameter] The parameter 'Mode' has been declared but not used.
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
# 依赖安全扫描报告（dependency-security-scanner）
|
||||
|
||||
- **项目**：BakNRet（Windows 备份 / 恢复工具，PowerShell）
|
||||
- **扫描时间**：2026-09-28
|
||||
- **扫描范围**：仓库根目录及全部子目录（排除 `.git`）
|
||||
- **工具**：`npm audit` / `pip-audit` / `govulncheck` 等均**不适用**（见下）
|
||||
|
||||
## 1. 项目概况
|
||||
|
||||
| 项目 | 结论 |
|
||||
| --- | --- |
|
||||
| 语言 | PowerShell（`.ps1` / `.psm1` / `.psd1`） |
|
||||
| 依赖管理文件 | **不存在** —— 全仓无 `package.json`、`package-lock.json`、`requirements.txt`、`go.mod`、`pom.xml`、`Cargo.toml` 等 |
|
||||
| 运行时依赖 | **0 个模块**。运行备份 / 恢复只需要 PowerShell 5.1 或 7.x + 7-Zip |
|
||||
| 开发期依赖 | Pester 5.9.1、PSScriptAnalyzer 1.25.0 —— 装在 `.tools/`，已 gitignore，**不随发布产物分发** |
|
||||
| 外部可执行文件 | `7z.exe`（7-Zip 26.03，经 scoop 安装） |
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> 依赖扫描技能面向「有包管理器的项目」。本项目**没有任何包管理器依赖**，因此
|
||||
> `npm audit` / `safety` / `govulncheck` 一类工具无对象可扫。下面改为对本项目**真实的供应链面**
|
||||
> 逐项核对，而不是输出一份空报告。
|
||||
|
||||
## 2. 供应链面核对
|
||||
|
||||
| 组件 | 来源 | 版本 | 是否随分发 | 风险 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| PowerShell 引擎 | 操作系统 / Microsoft | 5.1.26100.9502、7.7.0-preview.5 | 否（宿主环境） | 由宿主维护；预览版仅供本机验收使用 |
|
||||
| 7-Zip | scoop（`C:\Programs\Scoop\apps\7zip\26.03`） | 26.03 | 否（用户自备） | 归档/解压的执行者，**必须由用户保持更新** |
|
||||
| Pester | 仓库内 `.tools/modules/Pester/5.9.1` | 5.9.1 | 否（gitignore） | 仅测试期使用，不接触用户数据 |
|
||||
| PSScriptAnalyzer | 仓库内 `.tools/modules/PSScriptAnalyzer/1.25.0` | 1.25.0 | 否（gitignore） | 仅静态分析使用 |
|
||||
| 其余第三方 | 无 | — | — | — |
|
||||
|
||||
**已知 CVE**：无可报。本项目的依赖面里没有任何「被本项目固定版本」的第三方库
|
||||
（Pester 与 PSScriptAnalyzer 是测试工具且不进分发，7-Zip 与 PowerShell 由用户环境提供）。
|
||||
若要追查这两个工具的 CVE，应查上游公告，而不是本仓库。
|
||||
|
||||
## 3. 与安全相关的项目事实（实跑核对）
|
||||
|
||||
| 检查项 | 结果 |
|
||||
| --- | --- |
|
||||
| 仓库是否跟踪任何密钥文件 | ✅ 否（`git ls-files` 中无 `*.key` / `*.pfx`） |
|
||||
| `baknret.key` 是否被 gitignore | ✅ 是（`.gitignore:18: *.key`） |
|
||||
| 工作区是否存在口令文件 `baknret.key` | ⚠️ **是** —— 见风险 R-2 |
|
||||
| 口令是否可能落进日志 | ✅ 已处理：打印前把 `-p` 参数换成占位符（`tests/BakNRet.Tests.ps1` 有专门断言） |
|
||||
| 日志中是否出现明文口令 | ✅ 无 |
|
||||
| `.tools/` 是否可能进分发产物 | ✅ 否（已 gitignore，且构建脚本只读 `BakNRet/` 与 `tools/`） |
|
||||
|
||||
## 4. 风险清单
|
||||
|
||||
| ID | 严重程度 | 风险 | 证据 | 建议 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| R-1 | **一般** | 仓库没有 `LICENSE` 文件，许可证状态未声明 | 根目录无 `LICENSE*` | 补一份许可证（见 `license_check_report`） |
|
||||
| R-2 | **一般** | 工作区存在口令文件 `baknret.key`（未被跟踪，但确实在仓库目录里） | `Test-Path baknret.key` = True | 本项目自己的 CHANGELOG 已把「口令文件的出厂默认值指向仓库内」定为待修问题，`BackupConfig.psd1` 的注释也推荐放到仓库外。建议移到 `%USERPROFILE%\.baknret.key` 并用 `-KeyFile` 指过去。**本报告不读取、不记录其内容** |
|
||||
| R-3 | **建议** | 7-Zip 版本由用户环境决定，脚本不检查版本 | `Find-BakNRet7zExecutable` 只找路径 | 可选：在启动时打印 `7z` 版本，便于排障 |
|
||||
| R-4 | **建议** | 口令经命令行传给 7z，本机进程列表可见 | 上游限制，README 已用 CAUTION 声明 | 无技术解法，保持文档披露即可 |
|
||||
|
||||
**致命 / 严重漏洞：0 个。** 流水线可继续。
|
||||
|
||||
## 5. 结论
|
||||
|
||||
未发现已知安全漏洞。本项目**零运行时依赖**，是当前最重要的一条供应链优势；
|
||||
唯一两条「一般」级风险都属于**卫生问题**（缺许可证、口令文件放在仓库目录里），
|
||||
不影响流水线继续执行。
|
||||
@@ -0,0 +1,60 @@
|
||||
# 许可证合规检查报告（license-compliance-checker）
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> **免责声明**：本报告由自动化工具基于仓库内的文件生成，仅为工程参考，**不构成法律建议**。
|
||||
> 涉及对外分发、商业使用或二次许可时，请咨询法务。
|
||||
|
||||
- **项目**：BakNRet
|
||||
- **检查时间**：2026-09-28
|
||||
- **主许可证**：**未声明** —— 仓库根目录不存在 `LICENSE` / `LICENSE.md` / `LICENSE.txt`
|
||||
|
||||
## 1. 依赖与组件许可证清单
|
||||
|
||||
`license-checker` / `pip-licenses` / `go-licenses` 等工具**不适用**（本项目无包管理器依赖）。
|
||||
下列清单通过读取 `.tools/modules` 下的模块清单与许可证文件、以及七项外部组件的官方许可条款得出。
|
||||
|
||||
| 组件 | 版本 | 许可证 | 来源依据 | 与主许可证关系 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| BakNRet（本项目） | 1.0.0（模块清单） | **未声明** | 无 `LICENSE` 文件 | — |
|
||||
| Pester | 5.9.1 | **Apache-2.0** | `Pester.psd1` 的 `Copyright` + `LicenseUri` | 测试期工具，未声明主许可证时无冲突可判 |
|
||||
| PSScriptAnalyzer | 1.25.0 | **MIT** | `.tools/modules/PSScriptAnalyzer/1.25.0/LICENSE` | 同上 |
|
||||
| Newtonsoft.Json（PSScriptAnalyzer 内置依赖） | 随包 | **MIT** | 同目录 `ThirdPartyNotices.txt` | 同上 |
|
||||
| 7-Zip | 26.03 | **LGPL-2.1-or-later + BSD-3-Clause + unRAR 限制** | 上游许可（用户自备，不随本仓库分发） | 未分发，仅本地调用 |
|
||||
| PowerShell | 5.1 / 7.7 | **MIT**（宿主环境） | — | 未分发 |
|
||||
| .NET 运行时 | — | **MIT**（宿主环境） | — | 未分发 |
|
||||
|
||||
## 2. 许可证分布
|
||||
|
||||
```text
|
||||
MIT ████████████████████ 3 项（PSScriptAnalyzer、Newtonsoft.Json、PowerShell/.NET）
|
||||
Apache-2.0 ███████ 1 项（Pester）
|
||||
LGPL + BSD + unRAR ███████ 1 项（7-Zip）
|
||||
未声明 ███████ 1 项（本项目自身） <-- 需要处理
|
||||
```
|
||||
|
||||
全部第三方许可证均为**宽松型**（MIT / Apache-2.0 / BSD），无 copyleft 传染风险。
|
||||
|
||||
## 3. 冲突与注意事项
|
||||
|
||||
| ID | 级别 | 对象 | 说明 | 建议 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| L-1 | ❌ **需处理** | 本项目自身 | 没有 `LICENSE` 文件 = 默认「保留所有权利」。他人**无权**复制、修改、分发；GitHub 上也会显示为无许可证项目 | 明确选一个：想宽松就 MIT，想带专利授权就 Apache-2.0 |
|
||||
| L-2 | ⚠️ 需注意 | 7-Zip 的 unRAR 限制 | 7-Zip 许可证禁止用其 unRAR 代码**还原 RAR 压缩算法**。本项目只用 7z 解压 / 压缩，不实现 RAR 压缩 | 无需动作；当前用法不触发该限制 |
|
||||
| L-3 | ⚠️ 需注意 | Pester 5.9.1 的版权年份 | 模块清单里 `Copyright` 写的是 `(c) 2026 by Pester Team`（上游清单原文） | 无需动作；仅记录，勿在文档中改写上游声明 |
|
||||
| L-4 | ✅ 兼容 | PSScriptAnalyzer（MIT）+ Newtonsoft.Json（MIT） | MIT 与 MIT/Apache 混合无冲突 | 仅在本仓库内作为测试工具使用，未再分发 |
|
||||
|
||||
## 4. 合规建议
|
||||
|
||||
1. **先补主许可证**（L-1）。这是本仓库唯一的合规缺口，且成本最低。
|
||||
2. `.tools/` 下的模块**不要**提交进版本库（已 gitignore）——它们是第三方代码，
|
||||
提交会牵出「再分发」与版权声明保留义务。
|
||||
3. 若将来把 BakNRet 公开发布，请在 README / 发布产物里保留 7-Zip 的许可与免责声明引用；
|
||||
当前仓库并未捆绑 7-Zip 二进制，所以现在无需附带其许可证全文。
|
||||
4. 若决定以 MIT 发布，注意 MIT 要求保留版权与许可声明：README「致谢」一节已引用上游项目，
|
||||
可再补一份 `THIRD-PARTY-NOTICES.md` 收纳 Pester / PSScriptAnalyzer 的声明（可选）。
|
||||
|
||||
---
|
||||
|
||||
**免责声明（重申）**：以上判断基于文件名、模块清单字段与上游公开条款的自动比对，
|
||||
存在识别错误的可能；**不构成法律建议**。
|
||||
@@ -0,0 +1,55 @@
|
||||
{
|
||||
"measuredAt": "2026-09-28T12:24:11",
|
||||
"machine": "STRIX-X870A",
|
||||
"os": "Microsoft Windows NT 10.0.26340.0",
|
||||
"psi": "7.7.0-preview.5",
|
||||
"cpu": "AMD Ryzen 7 9800X3D 8-Core Processor ",
|
||||
"logicalCpu": 16,
|
||||
"workdir": "D:\\Workspace\\Temp\\BakNRet",
|
||||
"metrics": {
|
||||
"dryRunFullListMs": {
|
||||
"min": 9839.9,
|
||||
"median": 9869.2,
|
||||
"max": 12900.8,
|
||||
"samples": 5
|
||||
},
|
||||
"sevenZipVersion": "7-Zip 26.03 (x64) : Copyright (c) 1999-2026 Igor Pavlov : 2026-09-03",
|
||||
"folderSummary200Files3xMs": 18.2,
|
||||
"backupListParse50xMs": {
|
||||
"min": 2535.9,
|
||||
"median": 2546.9,
|
||||
"max": 2691.5,
|
||||
"samples": 5
|
||||
},
|
||||
"sevenZipBench": [
|
||||
{
|
||||
"level": 0,
|
||||
"ms": 46.7,
|
||||
"archiveBytes": 6555514
|
||||
},
|
||||
{
|
||||
"level": 5,
|
||||
"ms": 224.2,
|
||||
"archiveBytes": 6555913
|
||||
},
|
||||
{
|
||||
"level": 9,
|
||||
"ms": 225.2,
|
||||
"archiveBytes": 6555913
|
||||
}
|
||||
],
|
||||
"moduleImportMs": {
|
||||
"min": 628.3,
|
||||
"median": 631.0,
|
||||
"max": 2052.8,
|
||||
"samples": 5
|
||||
}
|
||||
},
|
||||
"notes": [],
|
||||
"fixture": {
|
||||
"files": 200,
|
||||
"bytes": 6553600,
|
||||
"createMs": 237.6,
|
||||
"compressionInputBytes": 6553600
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,333 @@
|
||||
Pester 5.9.1 (D:\Workspace\Temp\BakNRet\.tools\modules\Pester\5.9.1)
|
||||
测试文件：D:\Workspace\Temp\BakNRet\tests
|
||||
Pester v5.9.1
|
||||
|
||||
Starting discovery in 3 files.
|
||||
Discovery found 185 tests in 226ms.
|
||||
Running tests.
|
||||
|
||||
Running tests from 'D:\Workspace\Temp\BakNRet\tests\BakNRet.Formats.Tests.ps1'
|
||||
Describing 软件名录：Slot 形状（新契约）
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacystr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacyarr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 legacydirs 有问题：Slot Dirs 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 一个软件多个 Slot：Kind=Multi，Slot 按名排序且说明被保留 163ms (131ms|32ms)
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacystr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacyarr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 legacydirs 有问题：Slot Dirs 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 每个 Slot 都是一个独立的归档项来源（Kind=slot / Origin=catalog） 82ms (81ms|1ms)
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacystr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacyarr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 legacydirs 有问题：Slot Dirs 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] Slot 级排除写在 Slot 自己身上（相对本 Slot 的归档根） 32ms (30ms|1ms)
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacystr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacyarr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 legacydirs 有问题：Slot Dirs 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 数组里"当前不存在"的 Slot 仍然产出归档项（恢复要靠它还原回原位） 64ms (64ms|1ms)
|
||||
[+] 文件 Slot：归档项是文件项（归档里就是名为 Slot 的文件） 8ms (7ms|1ms)
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacystr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacyarr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 legacydirs 有问题：Slot Dirs 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 旧的裸字符串 / 字符串数组写法被拒绝（ERROR + 跳过） 22ms (22ms|1ms)
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacystr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 'legacyarr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:05] [ERROR] 名录条目 legacydirs 有问题：Slot Dirs 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 旧的 @{ Dirs = @(...) } 写法不再展开，留下 Invalid 与原因 24ms (23ms|1ms)
|
||||
[+] 多 Slot 的名录条目在清单里仍然按软件名命名归档 3ms (3ms|0ms)
|
||||
|
||||
Describing 清单修饰符：新契约格式
|
||||
[+] :: 覆盖 Path：单 Slot 条目直接生效 13ms (12ms|2ms)
|
||||
[+] :: 覆盖遇到多 Slot 条目 -> Blocking（不知道给哪一个，绝不猜） 6ms (6ms|0ms)
|
||||
[+] :- 排除与 :+ 包含并存，顺序任意 15ms (15ms|1ms)
|
||||
[+] @ Exclude / @ Include / @ Path 与记号写法等价 7ms (6ms|0ms)
|
||||
[+] :encrypt / :!encrypt 覆盖名录里的加密默认值 11ms (11ms|0ms)
|
||||
[+] 遗留写法 @encrypt / @pathname / @root= 仍可解析 18ms (17ms|1ms)
|
||||
[+] 同一行里重复写同类记号会累积（不静默丢掉前一条规则） 12ms (11ms|1ms)
|
||||
[2026-09-28 12:42:05] [WARN] 清单行缺少目标，已忽略：:- logs\
|
||||
[+] 行尾说明与缺少目标的行 6ms (6ms|1ms)
|
||||
|
||||
Describing 集成：Slot 布局的打包与恢复
|
||||
[+] 备份退出码 0，归档名就是软件名 9ms (7ms|2ms)
|
||||
[+] 归档顶层就是各个 Slot 名（目录 Slot + 文件 Slot + Include 项） 42ms (41ms|1ms)
|
||||
[+] manifest.layouts 记下每个归档项是目录还是文件 8ms (7ms|1ms)
|
||||
[+] 归档内容：\ 布局，文件 Slot 是名为 Slot 的文件，Slot 排除生效 40ms (39ms|1ms)
|
||||
[+] 真实恢复：目录 Slot、文件 Slot 与 Include 都落回各自的原位 2.37s (2.37s|1ms)
|
||||
[+] 文件 Slot 在目标不存在时靠 manifest.layouts 恢复成文件（而不是目录） 3ms (2ms|0ms)
|
||||
[+] 恢复之后 manifest 记下 lastRestoreAt 4ms (4ms|0ms)
|
||||
|
||||
Describing 集成：旧布局归档的回退恢复
|
||||
[+] 归档确实是旧布局：顶层是源目录名而不是 Slot 名 30ms (29ms|1ms)
|
||||
[+] 归档里缺 Slot 层（真实旧归档）时按旧布局回退，把内容还原回原位 1.75s (1.75s|0ms)
|
||||
[+] 归档里既没有 Slot 层、也没有旧布局名字时明确失败（不再"成功地什么都没恢复"） 1.72s (1.72s|0ms)
|
||||
|
||||
Describing 集成：归档内路径冲突会被拒绝执行
|
||||
[+] 退出码 1，且给出"归档内路径冲突"的原因，不生成归档 4ms (3ms|1ms)
|
||||
[+] manifest 里记下这次是 failed，并带上原因 3ms (3ms|0ms)
|
||||
|
||||
Describing 条目从清单里消失后，旧归档必须被点名为孤儿
|
||||
[+] 归档确实还在磁盘上，manifest 里也还留着历史记录 5ms (4ms|1ms)
|
||||
[+] 第二次运行把 my-app.7z 点名成孤儿，并说明 manifest 里还有历史记录 2ms (2ms|0ms)
|
||||
|
||||
Describing manifest 一致性：archive 字段只在文件真的存在时才写
|
||||
[+] 存在的归档保留 archive，不存在的被清空 9ms (8ms|1ms)
|
||||
[+] 清空 archive 时保留条目本身的历史（source / action 不动） 3ms (3ms|0ms)
|
||||
[+] 人工删掉归档之后再同步一次，记录会被纠正过来 4ms (3ms|0ms)
|
||||
|
||||
Running tests from 'D:\Workspace\Temp\BakNRet\tests\BakNRet.Security.Tests.ps1'
|
||||
Describing 排除判定与 7z 的 -x! / -xr! 语义对齐
|
||||
[+] 锚定模式只命中它自己那棵子树 8ms (7ms|1ms)
|
||||
[+] ! 通配按任意层级的组件名匹配（* 不是正则） 2ms (1ms|0ms)
|
||||
[+] !re: 走正则，且组件名与整条相对路径都算命中 2ms (2ms|0ms)
|
||||
[+] 没有模式时一律不排除 1ms (1ms|0ms)
|
||||
[+] 模式里的空格按 7z 的规矩当 ? 处理 1ms (1ms|0ms)
|
||||
|
||||
Describing SID 映射（跨机恢复）
|
||||
[+] 整 SID 精确替换 5ms (5ms|1ms)
|
||||
[+] 不会误伤以它为前缀的更长的 SID 1ms (1ms|0ms)
|
||||
[+] 空映射表时原样返回 1ms (1ms|0ms)
|
||||
|
||||
Describing 安全描述符采集
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] Full：每个对象一条记录，键是归档内相对路径 340ms (340ms|1ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] 根记录的 SDDL 保留了 CREATOR OWNER、IO 标志、孤儿 SID 和 protected 位 12ms (12ms|0ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] Smart 比 Full 少，但根永远保留 24ms (23ms|0ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] Roots 只存归档项的根，不再往下走 4ms (4ms|0ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] sidecar 往返：条数与 SDDL 原样保留 25ms (24ms|0ms)
|
||||
[+] 旁挂文件不存在时读出 $null（调用方据此打告警，而不是静默当没事） 1ms (1ms|0ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] 排除模式在采集时同样生效（采集树 == 归档树） 9ms (9ms|0ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
|
||||
Describing 安全描述符回放
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeRestorePrivilege、SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] 回放后根对象的安全描述符与源逐字节一致（protected / CO / 孤儿 SID 全在） 40ms (39ms|1ms)
|
||||
[+] 全部对象的安全指纹与源一致（属主/属组/ACE 集合） 5ms (5ms|0ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeRestorePrivilege、SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] 目标不存在或不是普通对象时记 Skipped，不记 Failed 3ms (3ms|0ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeRestorePrivilege、SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] 归档根名对不上时一条都不回放（不会把兄弟项的 ACL 倒过来） 1ms (1ms|0ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeRestorePrivilege、SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] 属组写不进去时不会连累 DACL：回退到底也要把 ACL 落下去 7ms (7ms|0ms)
|
||||
[2026-09-28 12:42:21] [WARN] 这些特权不在当前令牌里（需要管理员或 SYSTEM）：SeRestorePrivilege、SeBackupPrivilege —— 属主将无法改成别的账户，只能恢复 DACL
|
||||
[+] 对象的安全描述符读不到时带 e 记账，回放时跳过而不是写坏 2ms (2ms|0ms)
|
||||
|
||||
Describing 与 Backup.ps1 / Restore.ps1 的集成
|
||||
[+] 备份会写出 .acl.json，并在 manifest 里记下它 2.34s (2.34s|1ms)
|
||||
[+] 恢复会把安全描述符回放回去（删源之后仍然逐对象与备份前一致） 2.14s (2.14s|0ms)
|
||||
[+] -SkipSecurity 时不回放（目标保持新建对象的默认 ACL） 1.77s (1.77s|0ms)
|
||||
[+] 归档旁边没有 acl.json 时打告警、不算失败（旧归档照样恢复得出来） 1.76s (1.76s|0ms)
|
||||
|
||||
Running tests from 'D:\Workspace\Temp\BakNRet\tests\BakNRet.Tests.ps1'
|
||||
Describing BackupList.txt 解析
|
||||
[+] 注释行与空行返回 $null 2ms (2ms|1ms)
|
||||
[+] 裸路径：Path 原样、方向 both、不是软件名、没有任何覆盖 6ms (6ms|0ms)
|
||||
[+] 软件名：IsName 为真 2ms (1ms|0ms)
|
||||
[+] IsName 判定：含分隔符或 % 就算字面路径 3ms (2ms|0ms)
|
||||
[+] 标记必须是独立记号：C:\a:-b 仍然只是一个路径 2ms (2ms|0ms)
|
||||
[+] 行首 + 仅备份、- 仅恢复，方向标记不进入目标 4ms (4ms|0ms)
|
||||
[+] 只有方向标记、没有目标 -> 忽略该行 2ms (2ms|0ms)
|
||||
[+] 行首标记贴在目标上也算（+Name / -Path），且标记不进入目标 4ms (4ms|0ms)
|
||||
[+] 非行首的 + / - 不是方向标记 22ms (22ms|0ms)
|
||||
[+] :: 现在表示"覆盖 Path"，与 :- 彻底分开 8ms (5ms|3ms)
|
||||
[+] :: 的值可以带空格（一直取到下一个标记之前） 2ms (2ms|0ms)
|
||||
[+] :- 的逗号 / 分号列表拆成多个模式 7ms (6ms|0ms)
|
||||
[+] 排除模式的引号只保护空白，不保护逗号 3ms (2ms|0ms)
|
||||
[+] :+ 的包含项是 : 2ms (2ms|0ms)
|
||||
[+] :encrypt 与 :!encrypt 控制该条目的加密开关 2ms (2ms|0ms)
|
||||
[+] @ Key='Value' 覆盖 Path / Exclude / Include / Encrypt 4ms (4ms|0ms)
|
||||
[+] @ 的键名大小写不敏感，且支持紧跟 @ 的写法 2ms (2ms|0ms)
|
||||
[+] 历史写法 @encrypt / @!encrypt 仍然被识别成加密覆盖 2ms (2ms|0ms)
|
||||
[+] 历史写法 @pathname / @root= 进入 Flags 3ms (2ms|0ms)
|
||||
[2026-09-28 12:42:30] [WARN] 清单里的 @ 字段 'UnknownKey' 不是已知字段（Path / Exclude / Include / Encrypt），已忽略：Foo @ UnknownKey='v' :- logs\
|
||||
[+] 未知的 @ 字段进入 UnknownKeys，且不影响其余字段解析 2ms (2ms|0ms)
|
||||
[+] 行尾的 # 说明会成为 Comment 2ms (2ms|0ms)
|
||||
[+] 路径里紧贴的 # 不会被当成注释 1ms (1ms|0ms)
|
||||
[+] 没有说明时 Comment 为空 1ms (1ms|0ms)
|
||||
[+] 目标可以带空格：第一个标记之前整段都是目标 3ms (2ms|0ms)
|
||||
[2026-09-28 12:42:30] [WARN] 清单行缺少目标，已忽略：:- logs
|
||||
[2026-09-28 12:42:30] [WARN] 清单行缺少目标，已忽略：@ Exclude='x'
|
||||
[+] 缺少目标（标记出现在第一个位置）会被忽略并告警 2ms (2ms|0ms)
|
||||
[+] 记号切分：引号内的空白不切分，引号本身留在记号里 2ms (1ms|0ms)
|
||||
[+] 记号识别只认完整记号 2ms (2ms|0ms)
|
||||
[+] 去引号：成对才去，不成对原样返回 2ms (1ms|0ms)
|
||||
|
||||
Describing 归档命名
|
||||
[+] 基础命名规则：末级名_from_上级路径用加号连接 2ms (1ms|1ms)
|
||||
[+] / 与 \ 以及重复分隔符结果一致 2ms (1ms|0ms)
|
||||
[+] 命名与路径往返 6ms (6ms|0ms)
|
||||
[+] 归档名里不含非法文件名字符 4ms (4ms|0ms)
|
||||
[+] %变量% 写法里的 % 会保留在归档名里 1ms (1ms|0ms)
|
||||
[+] 软件名条目：默认用软件名做归档名 5ms (4ms|0ms)
|
||||
[+] 字面路径条目：仍用路径命名算法（现有清单无需改写） 2ms (2ms|0ms)
|
||||
[+] @pathname 用名录里的真实路径命名，而不是软件名 4ms (3ms|0ms)
|
||||
[2026-09-28 12:42:30] [WARN] 名录里没有 'no-such-thing'，按目录名处理
|
||||
[2026-09-28 12:42:30] [WARN] 名录里没有 'no-such-thing'，按目录名处理
|
||||
[+] 名录里没有该名字：归档名退回可读目录名，并给出 Error 5ms (4ms|0ms)
|
||||
|
||||
Describing 7z 排除参数翻译
|
||||
[+] 相对模式自动补上归档根目录名 5ms (5ms|1ms)
|
||||
[+] 模式已带根名前缀时，Split-BakNRetPatternScope 先摘掉前缀，结果不重复 5ms (4ms|0ms)
|
||||
[+] ! 前缀翻译成递归组件匹配（-xr!） 1ms (1ms|0ms)
|
||||
[+] 模式里的空格转成 ?（归档项自己的名字按原样保留） 2ms (1ms|0ms)
|
||||
[+] 生成的参数里绝不出现引号（旧实现 -x!"路径" 让排除全部失效） 1ms (1ms|0ms)
|
||||
[+] 空模式被忽略 2ms (1ms|0ms)
|
||||
[+] !re: 会把正则展开成精确的 -x! 参数 25ms (25ms|0ms)
|
||||
[+] 非法正则给出 Error，而不是抛异常 6ms (6ms|0ms)
|
||||
[+] 正则命中数超过上限时明确报错 3ms (3ms|0ms)
|
||||
[+] 参数总长超过安全上限时明确报错 1ms (1ms|0ms)
|
||||
[+] Split-BakNRetPatternScope：指名 Slot 的模式只分给那个 Slot 2ms (1ms|0ms)
|
||||
[+] Split-BakNRetPatternScope：没点名任何 Slot 的模式广播给每一项 1ms (1ms|0ms)
|
||||
[+] Split-BakNRetPatternScope：! 与 !re: 模式广播给每一项 1ms (1ms|0ms)
|
||||
[+] Split-BakNRetPatternScope：每个归档项都有键（没有模式时是空数组） 2ms (2ms|0ms)
|
||||
[+] Merge-BakNRetExcludeArgument 去重且保持顺序 3ms (2ms|0ms)
|
||||
[+] 多 Slot 条目：逐项分配 + 翻译 + 去重合成一份参数 3ms (3ms|0ms)
|
||||
|
||||
Describing 归档项与暂存目录
|
||||
[+] New-BakNRetArchiveItem 规范化归档内路径并算出 TopName 3ms (3ms|1ms)
|
||||
[+] Get-BakNRetArchiveTopName 取归档内相对路径的第一段 1ms (1ms|0ms)
|
||||
[+] 暂存半途失败会自己清干净（不留指向真实数据的 junction） 33ms (32ms|0ms)
|
||||
[+] 目录项用 junction 挂进暂存目录，文件项用硬链接（名字就是归档内路径） 18ms (17ms|0ms)
|
||||
[+] Remove-BakNRetArchiveStaging 只删连接点，不顺着走进真实目录 8ms (8ms|0ms)
|
||||
|
||||
Describing 命令行参数拼接
|
||||
[+] 无空格参数原样输出 2ms (1ms|1ms)
|
||||
[+] 含空格参数加引号 3ms (2ms|0ms)
|
||||
[+] 引号内的结尾反斜杠翻倍（否则会被当成转义引号） 2ms (1ms|0ms)
|
||||
[+] 内部引号被转义 1ms (1ms|0ms)
|
||||
[+] 空参数输出一对空引号 2ms (1ms|1ms)
|
||||
|
||||
Describing manifest 与配置
|
||||
[+] manifest 读写往返 10ms (9ms|1ms)
|
||||
[+] manifest 原样保存 layouts（name/kind），全新恢复时靠它判断目录还是文件 7ms (7ms|0ms)
|
||||
[2026-09-28 12:42:30] [WARN] manifest 解析失败（将重新建立）：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\broken.json —— Conversion from JSON failed with error: Invalid character after parsing property name. Expected ':' but got: i. Path '', line 1, position 7.
|
||||
[+] manifest 损坏时不抛异常，而是重建空清单 9ms (8ms|0ms)
|
||||
[+] 配置缺失时返回默认值 4ms (4ms|0ms)
|
||||
[+] 配置嵌套段落合并且不丢默认键 6ms (6ms|0ms)
|
||||
[+] 口令：环境变量可读取，取不到时返回 $null（绝不退化成明文） 3ms (3ms|0ms)
|
||||
|
||||
Describing 软件名录
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 名录解析：条目与 Slot 的字段集合就是新契约 54ms (53ms|1ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 一个软件多个 Slot：Kind=Multi，Slot 按名字排序 33ms (33ms|0ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] Kind：Single / Multi / Partial / Unresolved / Invalid 34ms (34ms|0ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 前缀补全：_ 与 - 都会被补全 28ms (27ms|0ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 不会把 Legendary 误配成 LegendarySomething 28ms (27ms|0ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 一个 Slot 命中多个候选目录：报 Error，绝不悄悄挑一棵树 31ms (31ms|0ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 文件 Slot：Path 指向文件时 IsFile 为真，Encrypt 也带上 25ms (25ms|0ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] %变量% 会在名录路径里展开 27ms (27ms|0ms)
|
||||
[+] $( ... ) 子表达式会被求值（含嵌套） 6ms (6ms|0ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 nopath 有问题：Slot S 缺少 Path
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dupslot 有问题：Slot D 的 Path 匹配到 2 个目录：C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_1、C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\catalog\dup_2；一个 Slot 只能对应一个目录，请拆成多个 Slot
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 badslot 有问题：Slot S 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 读取结果按"路径 + 时间戳 + 长度 + 内容 MD5"缓存 63ms (62ms|0ms)
|
||||
[+] 名录文件内容变了以后缓存自动失效 17ms (16ms|0ms)
|
||||
[+] Includes：分文件维护的名录会被合并 12ms (11ms|0ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 'arr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 'objarr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 'bare' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dirstyle 有问题：Slot Dirs 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 旧的裸字符串 / 字符串数组 / 对象数组写法都会报 ERROR 并被跳过 3ms (3ms|0ms)
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 'arr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 'objarr' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 'bare' 格式不对：应写成 @{ <Slot 名> = @{ Path = '...' } }
|
||||
[2026-09-28 12:42:30] [ERROR] 名录条目 dirstyle 有问题：Slot Dirs 的写法不对，应写成 @{ Path = '...' }
|
||||
[+] 旧的 @{ Dirs = @(...) } 写法不再展开：留下 Invalid 条目和原因 4ms (3ms|0ms)
|
||||
[+] 软件名会被规范化成合法文件名 2ms (1ms|0ms)
|
||||
|
||||
Describing Resolve-BakNRetBackupEntry：条目解析
|
||||
[+] resolve 与归档项的字段集合就是新契约（旧字段已删除） 4ms (4ms|1ms)
|
||||
[+] 软件名条目：isName/CatalogEntry/BaseName/ArchiveFlavor/Source 7ms (6ms|0ms)
|
||||
[+] 软件名条目：Items 来自 Slot（ArchivePath=Slot 名，Kind=slot，Origin=catalog） 6ms (6ms|0ms)
|
||||
[+] 字面路径条目：一个 path 项（ArchivePath 是末级名） 3ms (3ms|0ms)
|
||||
[+] 字面路径条目上的 @ Path= 覆盖目标路径，但归档名仍按原路径 2ms (2ms|0ms)
|
||||
[+] 名录里的路径不存在时仍给出 Items（恢复要靠它还原回原位） 5ms (5ms|0ms)
|
||||
[+] :: 覆盖 Path：单 Slot 条目直接生效 5ms (5ms|0ms)
|
||||
[+] :: / @ Path= 覆盖遇到多 Slot 条目 -> Blocking（不猜是哪一个） 5ms (5ms|0ms)
|
||||
[+] 条目级 :- 覆盖名录里的排除：HasExcludeOverride 为真 3ms (3ms|0ms)
|
||||
[+] 名录 Slot 的 Include 会追加成 include 项 5ms (5ms|0ms)
|
||||
[+] 条目级 :+ / @ Include= 覆盖名录里的 Include 11ms (11ms|0ms)
|
||||
[2026-09-28 12:42:30] [WARN] encapp：名录里各 Slot 的 Encrypt 不一致，整个归档按加密处理
|
||||
[+] 加密：名录里各 Slot 取或；条目级 :encrypt / :!encrypt 覆盖 9ms (9ms|0ms)
|
||||
[+] 方向标记会传递到 Resolve-BakNRetBackupEntry.Direction 5ms (5ms|0ms)
|
||||
[+] 归档内路径冲突（include 与 Slot 同名）-> Blocking 5ms (4ms|0ms)
|
||||
[+] 归档内路径冲突（父子关系）-> Blocking 5ms (5ms|0ms)
|
||||
[2026-09-28 12:42:30] [WARN] 名录里没有 'no-such-thing'，按目录名处理
|
||||
[+] 名录里没有该名字：Error 给出，Items 为空 3ms (2ms|0ms)
|
||||
|
||||
Describing 外部命令退出码（旧实现的核心缺陷）
|
||||
[2026-09-28 12:42:30] [DEBUG] 执行: cmd.exe /c "exit 0" -p<口令已隐藏>
|
||||
[+] 口令不会进日志：DEBUG 下打印的命令行要遮蔽 -p 参数 31ms (30ms|1ms)
|
||||
[+] 运行锁：同一份备份目录同时只能有一个持有者 27ms (27ms|0ms)
|
||||
[+] 运行锁：释放之后可以重新取得 8ms (7ms|0ms)
|
||||
[+] 空目录的摘要给 0 而不是 $null（否则空间守卫会静默失效） 9ms (9ms|0ms)
|
||||
[+] 原子替换：成功时新内容到位且不留 .tmp；失败时旧内容完好 14ms (14ms|0ms)
|
||||
[+] Invoke-ExternalCommand 能拿到真实退出码 13ms (12ms|0ms)
|
||||
[+] 成功时拿到 0 12ms (12ms|0ms)
|
||||
|
||||
Describing 集成：真实 7z 压缩与排除规则
|
||||
[+] 排除规则与空格处理在真实归档上生效 55ms (54ms|1ms)
|
||||
[+] 对照组：不加排除时被排除的文件确实在归档里（证明上一条不是空归档） 58ms (57ms|0ms)
|
||||
ERROR: C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\integration\corrupt.7z
|
||||
C:\Users\Shuery\AppData\Local\Temp\baknret-pester-ffa25c80\integration\corrupt.7z
|
||||
Open ERROR: Cannot open the file as [7z] archive
|
||||
|
||||
|
||||
ERRORS:
|
||||
Headers Error
|
||||
[+] 7z t 对完好归档返回 0，对损坏归档返回非 0（归档后校验的依据） 52ms (52ms|0ms)
|
||||
|
||||
Describing 集成：Backup.ps1 / Restore.ps1 端到端（字面路径条目）
|
||||
[+] 备份退出码为 0（旧实现会把成功的压缩判成失败） 2ms (1ms|1ms)
|
||||
[+] 归档已生成且 manifest 记录了条目、动作、校验结果与 layouts 5ms (5ms|0ms)
|
||||
[+] 备份过程写了日志文件 3ms (2ms|0ms)
|
||||
[+] 字面路径条目沿用 布局；归档里保留应保留内容、不含被排除项 32ms (32ms|0ms)
|
||||
[+] [回归] manifest.roots 记录的是归档内真实的顶层条目名 32ms (31ms|0ms)
|
||||
[+] Restore -DryRun 退出码 0，且一个字节都不写（manifest SHA256 不变） 1.57s (1.57s|0ms)
|
||||
[+] Restore -WhatIf 同样不写盘 1.6s (1.6s|0ms)
|
||||
[+] 真实恢复：退出码 0，文件逐字节一致，被排除项没有被恢复出来 2.12s (2.12s|0ms)
|
||||
[+] 真实恢复之后 manifest 才被更新（lastRestoreAt） 2ms (2ms|0ms)
|
||||
[+] 孤儿归档会被点名报告，但不影响退出码 2.37s (2.37s|0ms)
|
||||
[+] 带 -Only 时不做孤儿审计（避免把未选中的归档误报成孤儿） 1.74s (1.74s|0ms)
|
||||
[+] 源路径不存在时记为 missing-source，退出码仍为 0（跳过不算失败） 1.76s (1.76s|0ms)
|
||||
[+] 归档名重复时直接报失败（退出码 1），不静默互相覆盖 2.37s (2.37s|0ms)
|
||||
[+] [回归] 显式指定的清单不存在时报失败（退出码 1），且不在错误位置建模板 1.43s (1.43s|0ms)
|
||||
[+] [回归] 未显式指定清单时的首次运行仍建模板并退出 0（引导不能被误伤） 1.44s (1.44s|0ms)
|
||||
|
||||
Describing 集成：方向标记与孤儿审计
|
||||
[+] 行首 - 的条目：备份跳过它，但仍把它算作"有主"（不报成孤儿） 4ms (3ms|1ms)
|
||||
[+] 行首 + 的条目：恢复跳过它、不写回目标，同时登记归档名 2ms (2ms|0ms)
|
||||
Tests completed in 50.99s
|
||||
Tests Passed: 185, Failed: 0, Skipped: 0, Inconclusive: 0, NotRun: 0
|
||||
|
||||
Pester 测试全部通过：185 项（跳过 0 项）
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 205 KiB |
@@ -0,0 +1,135 @@
|
||||
# 阶段 0 报告：静态分析与修复
|
||||
|
||||
- **项目**：BakNRet（PowerShell 5.1 / 7.x，Windows 备份恢复工具）
|
||||
- **分支**：`refactor/ms-conventions`（HEAD 之前 `d72fe63`）
|
||||
- **执行时间**：2026-09-28
|
||||
- **结论**：✅ **通过**（0 个致命 / 严重问题；2 处真实缺陷已修复并回归；1 处自伤已发现并修复）
|
||||
|
||||
---
|
||||
|
||||
## 0.1 依赖安全扫描
|
||||
|
||||
**执行器**：`/dependency-security-scanner`
|
||||
|
||||
| 项目 | 结论 |
|
||||
| --- | --- |
|
||||
| 依赖管理文件 | 不存在（无 `package.json` / `requirements.txt` / `go.mod` / `pom.xml` / `Cargo.toml`） |
|
||||
| 运行时依赖 | **0 个模块** —— 只需 PowerShell 5.1 或 7.x + 7-Zip |
|
||||
| CVE | 无可报（没有任何被本仓库固定版本的第三方库） |
|
||||
| 致命 / 严重漏洞 | **0** |
|
||||
|
||||
**风险登记**
|
||||
|
||||
| ID | 级别 | 内容 | 处置 |
|
||||
| --- | --- | --- | --- |
|
||||
| R-1 | 一般 | 无 `LICENSE`，许可证未声明 | 移交阶段 0.2；**建议补一份** |
|
||||
| R-2 | 一般 | 工作区存在口令文件 `baknret.key`（`.gitignore:18 *.key` 已忽略，`git ls-files` 确认**未被跟踪**） | 建议移到仓库外（`%USERPROFILE%\.baknret.key`）+ `-KeyFile`；**本次全程未读取其内容** |
|
||||
| R-3 | 建议 | 脚本不检查 7-Zip 版本 | 可选增强 |
|
||||
| R-4 | 建议 | 口令经命令行传给 7z，进程列表短暂可见 | 7z 上游限制，README 已 CAUTION 披露，无技术解 |
|
||||
|
||||
完整性证据：`dependency_security_report.md`。
|
||||
|
||||
---
|
||||
|
||||
## 0.2 许可证合规检查
|
||||
|
||||
**执行器**：`/license-compliance-checker`
|
||||
|
||||
| 组件 | 版本 | 许可证 | 判断 |
|
||||
| --- | --- | --- | --- |
|
||||
| 本项目 | 1.0.0 | **未声明**（无 `LICENSE`） | ❌ **L-1 需处理** |
|
||||
| Pester | 5.9.1 | Apache-2.0 | ✅ 宽松，未分发 |
|
||||
| PSScriptAnalyzer | 1.25.0 | MIT | ✅ 宽松，未分发 |
|
||||
| Newtonsoft.Json | 随包 | MIT | ✅ 宽松，未分发 |
|
||||
| 7-Zip | 26.03 | LGPL-2.1 + BSD-3 + unRAR 限制 | ⚠️ L-2：本项目只做解压/压缩，**不实现 RAR 压缩**，不触发该限制；且未捆绑分发 |
|
||||
| PowerShell / .NET | 宿主 | MIT | ✅ |
|
||||
|
||||
**冲突**：无 copyleft 传染。**唯一缺口 = 主许可证未声明**（L-1）。
|
||||
完整性证据：`license_check_report.md`（含「非法律建议」免责声明）。
|
||||
|
||||
---
|
||||
|
||||
## 0.3 语法检查与自动修复（严格模式）
|
||||
|
||||
**执行器**：`/syntax-fixer`（内含 `/syntax-checker` 语义）
|
||||
|
||||
### 检查面
|
||||
|
||||
| 检查 | 命令 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 编码门禁 | `test.ps1` Encode 层 | ✅ 受管 **133** 个文件：缺 BOM 0、CRLF 0、制表符 0 |
|
||||
| 解析（PS 7.7.0-preview.5） | `test.ps1` Parse 层 | ✅ **131/131** 解析零错 |
|
||||
| 解析（5.1.26100.9502） | 同上 | ✅ **131/131** 解析零错 |
|
||||
| 静态分析 | `tools/Invoke-Analyzer.ps1` | **80 条**，全部 `Warning` 级、**0 条 Error** |
|
||||
|
||||
### 已修复的真实缺陷
|
||||
|
||||
| # | 文件:行 | 规则 | 修复 | 语义 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | `Backup.ps1:42` | `PSUseConsistentWhitespace` | `@($Rest)+ @(…)` → `@($Rest) + @(…)`（补 2 处空格） | **无行为改变**，仅排版 |
|
||||
| 2 | `Restore.ps1:42` | `PSUseConsistentWhitespace` | 同上（补 2 处空格） | **无行为改变**，仅排版 |
|
||||
|
||||
### ⚠️ 修复过程中的自伤与恢复（值得记录）
|
||||
|
||||
修改 `Backup.ps1` / `Restore.ps1` 后，两个文件的 **UTF-8 BOM 被编辑器抹掉**，导致：
|
||||
|
||||
```text
|
||||
7 : parse_bad=0 <- PowerShell 7 正常
|
||||
5.1 : ERR Backup.ps1 : The string is missing the terminator: '.
|
||||
ERR Restore.ps1 : The string is missing the terminator: '.
|
||||
```
|
||||
|
||||
根因正是本仓库 `.editorconfig` 写明的那条：**5.1 没有 BOM 就按 ANSI 解码源码**，中文注释与全角字符的字节序列吃掉了字符串引号。
|
||||
处置：用 `UTF8Encoding($true)` 重写并复核 → BOM=True、CRLF=False → 双宿主 `parse_bad=0` → `test.ps1 -Suite Parse` 恢复全绿。
|
||||
**这条恰好证明了本仓库 Encode 层的价值**，也说明「编辑 PowerShell 源文件必须保留 BOM」是一条硬约束。
|
||||
|
||||
### 未修复项：按仓库已声明的偏离登记（用户已确认此处置）
|
||||
|
||||
| 规则 | 条数 | 为什么不改 | 依据 |
|
||||
| --- | --- | --- | --- |
|
||||
| `PSAvoidLongLines` | 54 | 仓库**有意**把上限设为 160 而非官方 120（120 意味着 270 处改动） | `PSScriptAnalyzerSettings.psd1` 第 22–25 行；[ADR-0008](../../../docs/adr/0008-analyzer-deviations.md) |
|
||||
| `PSPlaceCloseBrace` | 7 | 全在 `Run-Tests.ps1` **测试夹具字符串**内，缩进/换行是被断言的文本 | 改了会改变断言语义 |
|
||||
| `PSUseConsistentIndentation` | 4 | 同上 | 同上 |
|
||||
| `PSAlignAssignmentStatement` | 4 | `Invoke-BakNRetMenu.ps1` 的表格字面量，对齐影响 TUI 列宽 | 属于刻意排版 |
|
||||
| `PSUseSupportsShouldProcess` | 4 | 该规则**已全局排除**于配置，属已知噪声 | `PSScriptAnalyzerSettings.psd1` 第 44 行 |
|
||||
| `PSAvoidUsingEmptyCatchBlock` | 2 | `Write-BakNRetAt.ps1:39` 有意空 catch（注释已写明理由：定位失败不影响写文本）；加输出会破坏 TUI | 源码注释 |
|
||||
| `PSReviewUnusedParameter` | 4 | 3 条在测试 helper；1 条**可能真有价值** → 见下 | — |
|
||||
| `PSUseDeclaredVarsMoreThanAssignments` | 1 | `BakNRet.Security.Tests.ps1:373` 的 `$sourcePath` 已赋值未使用 | 疑似残留，非功能缺陷 |
|
||||
|
||||
### 🔎 待人工确认的观察项（未改动）
|
||||
|
||||
```text
|
||||
BakNRet/Public/Write-BakNRetRunSummary.ps1:16
|
||||
[Parameter(Mandatory = $true)][ValidateSet('backup','restore','verify')][string]$Mode
|
||||
```
|
||||
|
||||
- `$Mode` 声明了 `ValidateSet` 与 `Mandatory`，但函数体内**从未读取**（全文仅第 16 行出现）。
|
||||
- 该函数也**从未被仓库内任何代码调用**（`grep` 全仓仅命中定义处），只通过 `FunctionsToExport` 对外导出。
|
||||
- 判断：像是「按运行类型分组」的未完工实现，**不是**能安全自动删改的东西（删除会破坏公共 API 参数契约）。
|
||||
- 处置：登记为观察项，**留待仓库作者决定**。
|
||||
|
||||
---
|
||||
|
||||
## 0.4 回归验证
|
||||
|
||||
| 层次 | PS 7.7.0-preview.5 | 5.1.26100.9502 |
|
||||
| --- | --- | --- |
|
||||
| Encode（宿主无关，跑一次） | ✅ 133 文件 0 问题 | — |
|
||||
| Parse | ✅ 131/131 | ✅ 131/131 |
|
||||
| Unit（Pester） | ✅ 通过 | ✅ 通过 |
|
||||
| Smoke（零依赖） | ✅ 通过 | ✅ 通过 |
|
||||
| E2E | ✅ 通过 | ✅ 通过 |
|
||||
| **合计** | **9/9 PASS，退出码 0** | |
|
||||
|
||||
修复前后各跑一次，结论一致 → **无回归**。
|
||||
分析器：`84 → 80` 条（4 条 `PSUseConsistentWhitespace` 全部归零，其余不变）。
|
||||
证据：`analyzer_raw.txt`（修复前）、`analyzer_after.txt`（修复后）。
|
||||
|
||||
---
|
||||
|
||||
## 0.5 阶段结论
|
||||
|
||||
- ✅ 无致命 / 严重问题，**流水线可继续**。
|
||||
- 🔧 2 处真实排版缺陷已修复；1 处 BOM 自伤已发现并恢复（这条本身是「Encode 层有效」的实证）。
|
||||
- ⚠️ 3 项待办移交下游：补 `LICENSE`（L-1）、迁移 `baknret.key`（R-2）、确认 `$Mode` 意图（观察项）。
|
||||
- 严格模式「零容忍」与仓库**已声明偏离**冲突的部分，按用户决定：**登记而不改**，理由逐条留档（上表）。
|
||||
@@ -0,0 +1,90 @@
|
||||
# 阶段 3 报告：测试增强评估与性能基线
|
||||
|
||||
- **执行时间**：2026-09-28
|
||||
- **结论**：性能基线已建立（首次，无退化可判）；单元测试增强**建议但未执行**（理由见下）
|
||||
|
||||
---
|
||||
|
||||
## 3.1 单元测试增强评估（`/unit-test-generator`，可选步骤）
|
||||
|
||||
### 现状盘点
|
||||
|
||||
| 指标 | 数值 |
|
||||
| --- | --- |
|
||||
| 对外函数总数 | **89**（`BakNRet/Public/*.ps1`，与 `FunctionsToExport` 白名单逐一核对一致） |
|
||||
| 测试中被**直接点名**的函数 | 70（78.7%） |
|
||||
| 未被直接点名 | 19（21.3%） |
|
||||
| Pester 用例 | **185** 条（`BakNRet.Tests.ps1` 127 + `Formats` 33 + `Security` 25），0 失败 0 跳过 |
|
||||
| 另有 | 零依赖套件 128 项、端到端 36 项、真实归档演练 12 项 |
|
||||
|
||||
### 未被直接点名的 19 个函数——逐条判断
|
||||
|
||||
> 「未被直接点名」≠「未被覆盖」：其中不少是通过集成路径间接执行到的（如 `Write-BakNRetLog` 被所有用例调用、`ConvertTo-BakNRetWildcardPattern` 由 `Test-BakNRetPathExcluded` 间接驱动）。
|
||||
|
||||
| 函数 | 是否值得补测试 | 理由 |
|
||||
| --- | --- | --- |
|
||||
| `Move-BakNRetArchiveIntoPlace` | **值得（最高优先）** | 「临时文件 → 校验 → 原子替换」是本仓库的核心安全承诺之一，且 CHANGELOG 记录过它在 5.1 上退化成「先删后移」的缺陷。目前只有端到端间接覆盖 |
|
||||
| `Resolve-BakNRetRootedPath` | 值得 | 「相对路径按仓库根解析，不按工作目录」是计划任务场景的关键约定（README 专门写了这一节） |
|
||||
| `Test-BakNRetItemSelected` | 值得 | `-Only` / `-Skip` 的通配匹配语义，边界（大小写、通配符）值得钉住 |
|
||||
| `ConvertFrom-BakNRetPatternList` | 值得 | `,` 与 `;` 双分隔符是历史缺陷的修复点（CHANGELOG：解析器用 `;` 而清单里写 `,`） |
|
||||
| `Get-Optimized7zArgument` | 一般 | 参数拼接优化，间接覆盖已足够 |
|
||||
| `Save-BakNRetItemRecord` | 一般 | 与 `Write-BakNRetManifest` 组合使用，集成覆盖 |
|
||||
| `Find-BakNRet7zExecutable` / `Resolve-BakNRetCompressionTool` | 一般 | 依赖机器状态，单元测试价值低（真实冒烟更合适） |
|
||||
| `Get-BakNRetFreeSpaceGB` / `Test-BakNRetAdministrator` | 低 | 环境查询，测试易受机器状态影响 |
|
||||
| `Enable-BakNRetPrivilege` / `Set-BakNRetObjectSecurity` / `Get-BakNRetAceSignatureList` / `Test-BakNRetSecurityRecordNeeded` | 低（**已由 VM 演练覆盖**） | 这几条需要真实提权与真实 NTFS，单元测试造不出可信夹具；仓库已经用 `tools/lab/Lab.ps1 acl-test`（含负对照）在真 VM 里覆盖，这是更正确的层次 |
|
||||
| `Write-BakNRetBackupEntryPlan` | 低 | 纯输出，间接覆盖 |
|
||||
| `Invoke-BakNRetEntryScript` | 低 | 子进程封装，端到端已覆盖 |
|
||||
| TUI 相关（`Write-BakNRetAt` 等） | 低 | 需要真终端；仓库已用 `-InputScript` 驱动做门禁 |
|
||||
|
||||
### 为什么本次**不执行**自动补测
|
||||
|
||||
1. 该步骤在流水线里标注为**可选**。
|
||||
2. 用户本轮选择的处置姿态是「最小侵入、不制造大 diff」；补 4~6 条新用例属于**新增工作**而非修复缺陷，应先取得确认。
|
||||
3. 上述「值得」的 4 条若要补，需要配套夹具（原子替换需要真归档、`-Only` 需要真清单），属于小规模但真实的工作量。
|
||||
|
||||
**建议**：单独一轮补 `Move-BakNRetArchiveIntoPlace` 与 `Resolve-BakNRetRootedPath` 两条（这两条对应的是历史上真出过问题的语义），其余保持现状。
|
||||
|
||||
---
|
||||
|
||||
## 3.2 性能基线（`/performance-baseline-tester`）
|
||||
|
||||
**工具适配说明**：该技能面向 HTTP 服务（k6 / RPS / P95）。BakNRet 是**本地 CLI 工具**，
|
||||
没有 HTTP 端点，因此把「核心 API」映射为**四条关键路径**：模块导入、清单解析、只读干跑（真实清单）、
|
||||
7z 压缩吞吐。指标是同一台机器上的可复现绝对耗时，用于**同环境前后对比**，不跨机器比较。
|
||||
|
||||
**环境**：宿主 `STRIX-X870A`，PowerShell 7.7.0-preview.5，7-Zip 26.03 (x64)
|
||||
|
||||
| 指标 | 采样 | min | **中位数** | max |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 模块导入（`Import-Module` 冷启） | 5 | 628.3 ms | **631.0 ms** | 2052.8 ms |
|
||||
| 清单解析 ×50 轮 | 5 | 2535.9 ms | **2546.9 ms** | 2691.5 ms |
|
||||
| **只读干跑（真实 28 条清单）** | 5 | 9839.9 ms | **9869.2 ms** | 12900.8 ms |
|
||||
| 源树扫描（200 文件 ×3 轮） | 1 | — | **18.2 ms** | — |
|
||||
|
||||
**7z 压缩基准**（固定夹具：200 × 32 KB = 6.25 MB **不可压缩随机数据**）
|
||||
|
||||
| 压缩级别 | 耗时 | 归档体积 |
|
||||
| --- | --- | --- |
|
||||
| `-mx=0` | 46.7 ms | 6,555,514 B |
|
||||
| `-mx=5` | 224.2 ms | 6,555,913 B |
|
||||
| `-mx=9` | 225.2 ms | 6,555,913 B |
|
||||
|
||||
> 夹具是随机数据，所以体积几乎不随级别变化 —— 这正好说明**该夹具测的是吞吐与 I/O，不是压缩率**。
|
||||
> 若要看压缩率，应换成真实可压缩语料。
|
||||
|
||||
### 基线判定
|
||||
|
||||
- **基线文件**：`.scratch/ci-cd/20260928-001722/perf_baseline.json`（首次建立，**无历史基线可比，故无退化可判**）。
|
||||
- **观察**：只读干跑约 9.9 秒是最大单项。它包含了**对 28 个条目的真实目录扫描与空间预估**，
|
||||
属于设计内的开销（README 承诺「动手之前先预估空间」）。`max 12.9 s` 的离群值出现在首次运行，
|
||||
与文件系统缓存冷启动一致。
|
||||
- **告警**：无退化（首次基线）。
|
||||
- **建议**：若将来要监控退化，把 `perf_baseline.json` 固定成仓库内基线，
|
||||
并在同机同宿主下对比；**不要在 VM 与宿主之间直接比数字**（两者 I/O 特性不同）。
|
||||
|
||||
---
|
||||
|
||||
## 3.3 结论
|
||||
|
||||
- ✅ 性能基线已建立并可复现，**无退化**。
|
||||
- ⏸️ 单元测试增强：已给出逐条优先级，**建议单独一轮补 2 条**，本轮不擅自新增。
|
||||
@@ -0,0 +1,171 @@
|
||||
# 阶段 2 回归：把阶段 1 的 11 条黑盒用例按**修正后的前置条件**重跑一遍。
|
||||
# 修正点：
|
||||
# * BB-11 原用 -DryRun，而孤儿审计只在真实运行里报告 -> 改成真实运行（原用例的夹具错误，不是产品缺陷）
|
||||
# * BB-06 的期望不变（显式清单不存在必须非 0），验证修复是否生效
|
||||
param([string]$OutJson = "$PSScriptRoot\blackbox_regression.json")
|
||||
|
||||
$ErrorActionPreference = 'Continue'
|
||||
$repo = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
|
||||
$host7 = (Get-Command pwsh).Source
|
||||
$host51 = (Get-Command powershell).Source
|
||||
$zip = (Get-Command 7z -ErrorAction SilentlyContinue).Source
|
||||
if (-not $zip) { foreach ($p in 'C:\Programs\Scoop\shims\7z.exe') { if (Test-Path $p) { $zip = $p } } }
|
||||
|
||||
$sandbox = Join-Path $env:TEMP ('baknret-reg-' + [guid]::NewGuid().ToString('N').Substring(0, 8))
|
||||
$src = Join-Path $sandbox 'srcdocs'
|
||||
New-Item -ItemType Directory -Path (Join-Path $src 'nested') -Force | Out-Null
|
||||
Set-Content -LiteralPath (Join-Path $src 'a.txt') -Value 'alpha' -Encoding utf8
|
||||
Set-Content -LiteralPath (Join-Path $src 'nested\b.txt') -Value 'beta' -Encoding utf8
|
||||
Set-Content -LiteralPath (Join-Path $src 'nested\skipme.log') -Value 'noise' -Encoding utf8
|
||||
|
||||
$listPath = Join-Path $sandbox 'BackupList.txt'
|
||||
Set-Content -LiteralPath $listPath -Encoding utf8 -Value @(
|
||||
"$src :- 'nested\skipme.log'",
|
||||
'+ ' + (Join-Path $sandbox 'nonexistent')
|
||||
)
|
||||
$backupDir = Join-Path $sandbox 'Backups'
|
||||
|
||||
$cases = [System.Collections.Generic.List[object]]::new()
|
||||
function Add-Case {
|
||||
param([string]$Id, [string]$Title, [string]$Expected, [string]$Actual, [bool]$Pass, [string]$Note = '')
|
||||
$cases.Add([pscustomobject]@{ Id = $Id; Title = $Title; Expected = $Expected; Actual = $Actual
|
||||
Status = $(if ($Pass) { 'PASS' } else { 'FAIL' }); Note = $Note })
|
||||
}
|
||||
|
||||
function Invoke-Bak {
|
||||
param([string]$HostName, [string[]]$Arguments, [string]$Script = 'Backup-Data.ps1')
|
||||
$exe = if ($HostName -eq '7') { $host7 } else { $host51 }
|
||||
$all = @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', (Join-Path $repo $Script)) + $Arguments
|
||||
$out = & $exe @all 2>&1
|
||||
return [pscustomobject]@{ ExitCode = $LASTEXITCODE; Output = @($out) }
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- BB-01 真实备份
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
$archives = @(Get-ChildItem -LiteralPath $backupDir -Filter '*.7z' -ErrorAction SilentlyContinue)
|
||||
Add-Case -Id 'BB-01' -Title '真实备份：退出码 0 + 产出归档 + manifest' `
|
||||
-Expected '退出码 0；≥1 个 .7z；manifest.json 存在' `
|
||||
-Actual ("退出码={0}；归档={1}" -f $r.ExitCode, $archives.Count) `
|
||||
-Pass ($r.ExitCode -eq 0 -and $archives.Count -ge 1 -and (Test-Path (Join-Path $backupDir 'manifest.json')))
|
||||
|
||||
# ---------------------------------------------------------------- BB-02 排除生效
|
||||
$listing = if ($archives.Count -gt 0 -and $zip) { @(& $zip l -ba $archives[0].FullName 2>&1) } else { @() }
|
||||
$hasSkip = @($listing | Where-Object { $_ -match 'skipme\.log' }).Count -gt 0
|
||||
$hasKeep = @($listing | Where-Object { $_ -match 'a\.txt|b\.txt' }).Count -gt 0
|
||||
Add-Case -Id 'BB-02' -Title '排除模式真的把内容挡在归档之外' `
|
||||
-Expected '归档内无 skipme.log，有 a.txt/b.txt' `
|
||||
-Actual ("skipme={0}；keep={1}" -f $hasSkip, $hasKeep) -Pass ($hasKeep -and -not $hasSkip)
|
||||
|
||||
# ---------------------------------------------------------------- BB-03 干跑不写盘
|
||||
$h1 = (Get-FileHash -LiteralPath (Join-Path $backupDir 'manifest.json') -Algorithm SHA256).Hash
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-DryRun', '-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
$h2 = (Get-FileHash -LiteralPath (Join-Path $backupDir 'manifest.json') -Algorithm SHA256).Hash
|
||||
Add-Case -Id 'BB-03' -Title '-DryRun 一个字节都不写' `
|
||||
-Expected '退出码 0；manifest SHA256 前后一致' `
|
||||
-Actual ("退出码={0}；哈希一致={1}" -f $r.ExitCode, ($h1 -eq $h2)) -Pass ($r.ExitCode -eq 0 -and $h1 -eq $h2)
|
||||
|
||||
# ---------------------------------------------------------------- BB-04 missing-source
|
||||
$actions = @((Get-Content (Join-Path $backupDir 'manifest.json') -Raw | ConvertFrom-Json).items.PSObject.Properties.Value.action)
|
||||
Add-Case -Id 'BB-04' -Title '源不存在记 missing-source，不算失败' `
|
||||
-Expected '含 missing-source；退出码 0' `
|
||||
-Actual ("actions={0}；退出码={1}" -f ($actions -join ','), $r.ExitCode) `
|
||||
-Pass ($actions -contains 'missing-source' -and $r.ExitCode -eq 0)
|
||||
|
||||
# ---------------------------------------------------------------- BB-05 -Only
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-DryRun', '-Only', 'srcdocs', '-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
$hitMissing = @($r.Output | Where-Object { $_ -match 'nonexistent' }).Count -gt 0
|
||||
Add-Case -Id 'BB-05' -Title '-Only 只处理匹配的条目' `
|
||||
-Expected '退出码 0；输出不提未选中的 nonexistent' `
|
||||
-Actual ("退出码={0}；提到 nonexistent={1}" -f $r.ExitCode, $hitMissing) -Pass ($r.ExitCode -eq 0 -and -not $hitMissing)
|
||||
|
||||
# ---------------------------------------------------------------- BB-06 ★ 修复验证
|
||||
$ghost = Join-Path $sandbox 'typo-in-path.txt'
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-BackupListPath', $ghost, '-BackupDir', $backupDir)
|
||||
$created = Test-Path -LiteralPath $ghost
|
||||
Add-Case -Id 'BB-06' -Title '★显式指定的清单不存在 -> 必须报失败（本次修复点）' `
|
||||
-Expected '退出码 ≠ 0；不创建模板；输出含"指定的清单不存在"' `
|
||||
-Actual ("退出码={0}；误建模板={1}；提示={2}" -f $r.ExitCode, $created, (@($r.Output | Where-Object { $_ -match '指定的清单不存在' }).Count -gt 0)) `
|
||||
-Pass ($r.ExitCode -ne 0 -and -not $created -and (@($r.Output | Where-Object { $_ -match '指定的清单不存在' }).Count -gt 0)) `
|
||||
-Note '阶段 1 原为 FAIL（退出码 0 且建了模板），本次修复后应转为 PASS'
|
||||
|
||||
# ---------------------------------------------------------------- BB-06b 对照：首次运行引导仍在
|
||||
$realList = Join-Path $repo 'BackupList.txt'
|
||||
$parked = Join-Path $sandbox 'BackupList.parked'
|
||||
$guideDir = Join-Path $sandbox 'guide'
|
||||
New-Item -ItemType Directory -Path $guideDir -Force | Out-Null
|
||||
$r = $null
|
||||
try {
|
||||
Move-Item -LiteralPath $realList -Destination $parked -Force
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-BackupDir', (Join-Path $guideDir 'Backups'))
|
||||
$regenerated = Test-Path -LiteralPath $realList
|
||||
}
|
||||
finally {
|
||||
if (Test-Path -LiteralPath $parked) { Move-Item -LiteralPath $parked -Destination $realList -Force }
|
||||
}
|
||||
Add-Case -Id 'BB-06b' -Title '对照：未显式指定时首次运行仍建模板并退出 0' `
|
||||
-Expected '退出码 0；模板被创建；随后仓库原文件已还原' `
|
||||
-Actual ("退出码={0}；模板创建={1}；仓库还原={2}" -f $r.ExitCode, $regenerated, (Test-Path -LiteralPath $realList)) `
|
||||
-Pass ($r.ExitCode -eq 0 -and $regenerated -and (Test-Path -LiteralPath $realList))
|
||||
|
||||
# ---------------------------------------------------------------- BB-07 垫片转发
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-DryRun', '-BackupListPath', $listPath, '-BackupDir', $backupDir) -Script 'Backup.ps1'
|
||||
$said = @($r.Output | Where-Object { $_ -match '已改名为' }).Count -gt 0
|
||||
Add-Case -Id 'BB-07' -Title '旧名字垫片转发且退出码原样传递' `
|
||||
-Expected '退出码 0；有改名提示' `
|
||||
-Actual ("退出码={0}；提示={1}" -f $r.ExitCode, $said) -Pass ($r.ExitCode -eq 0 -and $said)
|
||||
|
||||
# ---------------------------------------------------------------- BB-08 双宿主
|
||||
$r7 = Invoke-Bak -HostName 7 -Arguments @('-DryRun', '-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
$r51 = Invoke-Bak -HostName '5.1' -Arguments @('-DryRun', '-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
Add-Case -Id 'BB-08' -Title '5.1 与 7.x 行为一致' `
|
||||
-Expected '两个宿主退出码都是 0' `
|
||||
-Actual ("7={0}；5.1={1}" -f $r7.ExitCode, $r51.ExitCode) -Pass ($r7.ExitCode -eq 0 -and $r51.ExitCode -eq 0)
|
||||
|
||||
# ---------------------------------------------------------------- BB-09 特殊字符
|
||||
$sp = Join-Path $sandbox 'sp&chars#dir'
|
||||
New-Item -ItemType Directory -Path $sp -Force | Out-Null
|
||||
Set-Content -LiteralPath (Join-Path $sp 'x.txt') -Value 'special' -Encoding utf8
|
||||
$list2 = Join-Path $sandbox 'BackupList2.txt'
|
||||
Set-Content -LiteralPath $list2 -Encoding utf8 -Value "`"$sp`""
|
||||
$bd2 = Join-Path $sandbox 'Backups2'
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-BackupListPath', $list2, '-BackupDir', $bd2)
|
||||
$n = @(Get-ChildItem -LiteralPath $bd2 -Filter '*.7z' -ErrorAction SilentlyContinue).Count
|
||||
Add-Case -Id 'BB-09' -Title '含 & 与 # 的路径（整行引号）' `
|
||||
-Expected '退出码 0 且产出归档' `
|
||||
-Actual ("退出码={0}；归档={1}" -f $r.ExitCode, $n) -Pass ($r.ExitCode -eq 0 -and $n -ge 1)
|
||||
|
||||
# ---------------------------------------------------------------- BB-10 无控制台不挂起
|
||||
$pinfo = New-Object System.Diagnostics.ProcessStartInfo
|
||||
$pinfo.FileName = $host7
|
||||
$pinfo.Arguments = "-NoProfile -ExecutionPolicy Bypass -File `"$repo\Manage-Backup.ps1`""
|
||||
$pinfo.RedirectStandardOutput = $true; $pinfo.RedirectStandardError = $true
|
||||
$pinfo.UseShellExecute = $false; $pinfo.CreateNoWindow = $true
|
||||
$proc = [System.Diagnostics.Process]::Start($pinfo)
|
||||
$finished = $proc.WaitForExit(60000)
|
||||
if (-not $finished) { try { $proc.Kill() } catch {} }
|
||||
Add-Case -Id 'BB-10' -Title '无控制台且无 -InputScript 时报错退出，绝不挂起' `
|
||||
-Expected '60 秒内退出且退出码 2' `
|
||||
-Actual ("已退出={0}；退出码={1}" -f $finished, $proc.ExitCode) -Pass ($finished -and $proc.ExitCode -eq 2)
|
||||
|
||||
# ---------------------------------------------------------------- BB-11 ★ 修正夹具：真实运行
|
||||
$orphanDir = Join-Path $sandbox 'Backups3'
|
||||
New-Item -ItemType Directory -Path $orphanDir -Force | Out-Null
|
||||
if ($archives.Count -gt 0) { Copy-Item -LiteralPath $archives[0].FullName -Destination (Join-Path $orphanDir 'GhostSoftware.7z') }
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-BackupListPath', $listPath, '-BackupDir', $orphanDir)
|
||||
$named = @($r.Output | Where-Object { $_ -match 'GhostSoftware' }).Count -gt 0
|
||||
Add-Case -Id 'BB-11' -Title '★孤儿归档审计（改用真实运行）' `
|
||||
-Expected '输出点名 GhostSoftware.7z' `
|
||||
-Actual ("退出码={0}；点名={1}" -f $r.ExitCode, $named) -Pass $named `
|
||||
-Note '阶段 1 的 FAIL 系夹具错误：孤儿审计只在真实运行里报告，干跑不报'
|
||||
|
||||
$report = [ordered]@{
|
||||
testedAt = (Get-Date).ToString('s')
|
||||
total = $cases.Count
|
||||
passed = @($cases | Where-Object Status -eq 'PASS').Count
|
||||
failed = @($cases | Where-Object Status -eq 'FAIL').Count
|
||||
cases = $cases
|
||||
}
|
||||
$report | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $OutJson -Encoding utf8
|
||||
$cases | Format-Table Id, Status, Title -AutoSize
|
||||
Write-Host ("回归合计 {0}；通过 {1}；失败 {2}" -f $report.total, $report.passed, $report.failed)
|
||||
Write-Host ("沙盒: " + $sandbox)
|
||||
@@ -0,0 +1,209 @@
|
||||
# 黑盒测试：只依据 README 记录的对外契约，在**沙盒副本**里驱动 CLI。
|
||||
# 不读实现细节；每个用例都断言"文档承诺的行为 vs 实际行为"。
|
||||
param(
|
||||
[string]$OutJson = "$PSScriptRoot\blackbox_results.json"
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Continue'
|
||||
$repo = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
|
||||
$host7 = (Get-Command pwsh).Source
|
||||
$host51 = (Get-Command powershell).Source
|
||||
|
||||
# ---------------------------------------------------------------- 沙盒（绝不碰真实 Backups/ logs/）
|
||||
$sandbox = Join-Path $env:TEMP ('baknret-bb-' + [guid]::NewGuid().ToString('N').Substring(0, 8))
|
||||
$src = Join-Path $sandbox 'srcdocs'
|
||||
New-Item -ItemType Directory -Path (Join-Path $src 'nested') -Force | Out-Null
|
||||
Set-Content -LiteralPath (Join-Path $src 'a.txt') -Value 'alpha' -Encoding utf8
|
||||
Set-Content -LiteralPath (Join-Path $src 'nested\b.txt') -Value 'beta' -Encoding utf8
|
||||
Set-Content -LiteralPath (Join-Path $src 'nested\skipme.log') -Value 'noise' -Encoding utf8
|
||||
|
||||
$listPath = Join-Path $sandbox 'BackupList.txt'
|
||||
Set-Content -LiteralPath $listPath -Encoding utf8 -Value @(
|
||||
"$src :- 'nested\skipme.log'",
|
||||
'+ ' + (Join-Path $sandbox 'nonexistent')
|
||||
)
|
||||
$backupDir = Join-Path $sandbox 'Backups'
|
||||
|
||||
$cases = [System.Collections.Generic.List[object]]::new()
|
||||
function Add-Case {
|
||||
param([string]$Id, [string]$Module, [string]$Title, [string]$Priority,
|
||||
[string]$Precondition, [string]$Steps, [string]$Expected,
|
||||
[string]$Actual, [bool]$Pass, [string]$Severity = '')
|
||||
|
||||
$cases.Add([pscustomobject]@{
|
||||
Id = $Id; Module = $Module; Title = $Title; Priority = $Priority
|
||||
Precondition = $Precondition; Steps = $Steps; Expected = $Expected
|
||||
Actual = $Actual; Status = $(if ($Pass) { 'PASS' } else { 'FAIL' })
|
||||
Severity = $(if ($Pass) { '' } else { $Severity })
|
||||
})
|
||||
}
|
||||
|
||||
function Invoke-Bak {
|
||||
param([string]$HostName, [string[]]$Arguments, [string]$Script = 'Backup-Data.ps1')
|
||||
$exe = if ($HostName -eq '7') { $host7 } else { $host51 }
|
||||
$all = @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', (Join-Path $repo $Script)) + $Arguments
|
||||
$out = & $exe @all 2>&1
|
||||
return [pscustomobject]@{ ExitCode = $LASTEXITCODE; Output = @($out) }
|
||||
}
|
||||
|
||||
function Get-ManifestHash {
|
||||
$p = Join-Path $backupDir 'manifest.json'
|
||||
if (-not (Test-Path -LiteralPath $p)) { return '<absent>' }
|
||||
return (Get-FileHash -LiteralPath $p -Algorithm SHA256).Hash
|
||||
}
|
||||
|
||||
# ================================================================ 用例
|
||||
|
||||
# BB-01 首次真实备份（核心流）
|
||||
$before = Get-ManifestHash
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
$archives = @(Get-ChildItem -LiteralPath $backupDir -Filter '*.7z' -ErrorAction SilentlyContinue)
|
||||
Add-Case -Id 'BB-01' -Module '备份' -Title '文档承诺：备份成功返回 0，并产出 .7z 归档' -Priority 'P0' `
|
||||
-Precondition '沙盒清单：1 个目录（含排除）+ 1 个不存在的源' `
|
||||
-Steps 'Backup-Data.ps1（无 -DryRun）' `
|
||||
-Expected '退出码 0；Backups\ 下出现 1 个 .7z；manifest.json 存在' `
|
||||
-Actual ("退出码={0}；归档={1} 个（{2}）" -f $r.ExitCode, $archives.Count, ($archives.Name -join ',')) `
|
||||
-Pass ($r.ExitCode -eq 0 -and $archives.Count -ge 1 -and (Test-Path (Join-Path $backupDir 'manifest.json'))) `
|
||||
-Severity '严重'
|
||||
|
||||
# BB-02 排除规则真的生效（逐个归档内容核对）
|
||||
$zip = (Get-Command 7z -ErrorAction SilentlyContinue).Source
|
||||
if (-not $zip) { foreach ($p in 'C:\Programs\Scoop\shims\7z.exe') { if (Test-Path $p) { $zip = $p } } }
|
||||
$listing = if ($archives.Count -gt 0 -and $zip) { @(& $zip l -ba $archives[0].FullName 2>&1) } else { @() }
|
||||
$hasSkip = @($listing | Where-Object { $_ -match 'skipme\.log' }).Count -gt 0
|
||||
$hasKeep = @($listing | Where-Object { $_ -match 'a\.txt|b\.txt' }).Count -gt 0
|
||||
Add-Case -Id 'BB-02' -Module '排除' -Title '文档承诺：:- 排除模式把内容挡在归档之外' -Priority 'P0' `
|
||||
-Precondition '清单里对源目录写了 :- ''nested\skipme.log''' `
|
||||
-Steps '7z l 列出归档内容' `
|
||||
-Expected '归档里**没有** skipme.log，但有 a.txt 与 b.txt' `
|
||||
-Actual ("skipme.log 命中={0}；a/b.txt 命中={1}" -f $hasSkip, $hasKeep) `
|
||||
-Pass ($hasKeep -and -not $hasSkip) -Severity '严重'
|
||||
|
||||
# BB-03 只读模式不写盘（README 的强承诺）
|
||||
$h1 = Get-ManifestHash
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-DryRun', '-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
$h2 = Get-ManifestHash
|
||||
Add-Case -Id 'BB-03' -Module '干跑' -Title '文档承诺：-DryRun 一个字节都不写（含 manifest.json）' -Priority 'P0' `
|
||||
-Precondition '已有 1 份归档与 manifest.json' `
|
||||
-Steps '记录 SHA256 → 跑 -DryRun → 再记录 SHA256' `
|
||||
-Expected '退出码 0；manifest.json 的 SHA256 前后完全一致' `
|
||||
-Actual ("退出码={0}；哈希 {1} → {2}" -f $r.ExitCode, $h1.Substring(0, 12), $h2.Substring(0, 12)) `
|
||||
-Pass ($r.ExitCode -eq 0 -and $h1 -eq $h2) -Severity '致命'
|
||||
|
||||
# BB-04 源不存在只算跳过、不算失败
|
||||
Add-Case -Id 'BB-04' -Module '异常流' -Title '文档承诺：源路径不存在记 missing-source，不算失败' -Priority 'P1' `
|
||||
-Precondition '清单第 2 行指向不存在的目录' `
|
||||
-Steps '跑备份后读 manifest.json 的 action 字段' `
|
||||
-Expected '该条目 action=missing-source，且整体退出码仍为 0' `
|
||||
-Actual ("退出码={0}；manifest action 分布={1}" -f $r.ExitCode,
|
||||
(@((Get-Content (Join-Path $backupDir 'manifest.json') -Raw | ConvertFrom-Json).items.PSObject.Properties.Value.action) -join ',')) `
|
||||
-Pass ($r.ExitCode -eq 0 -and (@((Get-Content (Join-Path $backupDir 'manifest.json') -Raw | ConvertFrom-Json).items.PSObject.Properties.Value.action) -contains 'missing-source')) `
|
||||
-Severity '一般'
|
||||
|
||||
# BB-05 -Only 过滤
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-DryRun', '-Only', 'srcdocs', '-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
$hitMissing = @($r.Output | Where-Object { $_ -match 'nonexistent' }).Count -gt 0
|
||||
Add-Case -Id 'BB-05' -Module '干跑' -Title '文档承诺：-Only 只处理匹配的条目' -Priority 'P1' `
|
||||
-Precondition '清单 2 条：srcdocs（目录）、nonexistent（不存在）' `
|
||||
-Steps 'Backup-Data.ps1 -DryRun -Only ''srcdocs''' `
|
||||
-Expected '退出码 0；输出里不出现未选中的 nonexistent 条目' `
|
||||
-Actual ("退出码={0}；输出提到 nonexistent={1}" -f $r.ExitCode, $hitMissing) `
|
||||
-Pass ($r.ExitCode -eq 0 -and -not $hitMissing) -Severity '一般'
|
||||
|
||||
# BB-06 非法参数（错误推测）
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-BackupListPath', (Join-Path $sandbox 'no-such-list.txt'), '-BackupDir', $backupDir)
|
||||
Add-Case -Id 'BB-06' -Module '异常流' -Title '边界值：清单文件不存在时的行为' -Priority 'P1' `
|
||||
-Precondition '传入一个不存在的 -BackupListPath' `
|
||||
-Steps 'Backup-Data.ps1 -BackupListPath <不存在>' `
|
||||
-Expected '明确报错（非 0 退出码）或给出可读提示，**不得静默返回 0**' `
|
||||
-Actual ("退出码={0}；末行={1}" -f $r.ExitCode, (@($r.Output) | Select-Object -Last 1)) `
|
||||
-Pass ($r.ExitCode -ne 0) -Severity '一般'
|
||||
|
||||
# BB-07 旧名字垫片仍可用（文档承诺"只留一轮"）
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-DryRun', '-BackupListPath', $listPath, '-BackupDir', $backupDir) -Script 'Backup.ps1'
|
||||
$saidRename = @($r.Output | Where-Object { $_ -match '已改名为' }).Count -gt 0
|
||||
Add-Case -Id 'BB-07' -Module '兼容' -Title '文档承诺：旧名字 Backup.ps1 是转发垫片，退出码原样传递' -Priority 'P1' `
|
||||
-Precondition '实现已改名为 Backup-Data.ps1' `
|
||||
-Steps 'Backup.ps1 -DryRun（旧名字）' `
|
||||
-Expected '打印改名提示；退出码与直接调用一致（0）' `
|
||||
-Actual ("退出码={0}；有改名提示={1}" -f $r.ExitCode, $saidRename) `
|
||||
-Pass ($r.ExitCode -eq 0 -and $saidRename) -Severity '一般'
|
||||
|
||||
# BB-08 双宿主一致性（5.1 是文档承诺支持的一半）
|
||||
$r7 = Invoke-Bak -HostName 7 -Arguments @('-DryRun', '-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
$r51 = Invoke-Bak -HostName '5.1' -Arguments @('-DryRun', '-BackupListPath', $listPath, '-BackupDir', $backupDir)
|
||||
Add-Case -Id 'BB-08' -Module '跨端一致性' -Title '文档承诺：Windows PowerShell 5.1 与 7.x 行为一致' -Priority 'P0' `
|
||||
-Precondition '同一沙盒、同一清单' `
|
||||
-Steps '两个宿主各跑一次 -DryRun，比较退出码' `
|
||||
-Expected '两者退出码都是 0（GBK 控制台下的中文输出不崩）' `
|
||||
-Actual ("7 退出码={0}；5.1 退出码={1}" -f $r7.ExitCode, $r51.ExitCode) `
|
||||
-Pass ($r7.ExitCode -eq 0 -and $r51.ExitCode -eq 0) -Severity '致命'
|
||||
|
||||
# BB-09 特殊字符路径（错误推测）
|
||||
$sp = Join-Path $sandbox 'sp&chars#dir'
|
||||
New-Item -ItemType Directory -Path $sp -Force | Out-Null
|
||||
Set-Content -LiteralPath (Join-Path $sp 'x.txt') -Value 'special' -Encoding utf8
|
||||
$list2 = Join-Path $sandbox 'BackupList2.txt'
|
||||
Set-Content -LiteralPath $list2 -Encoding utf8 -Value "`"$sp`""
|
||||
$bd2 = Join-Path $sandbox 'Backups2'
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-BackupListPath', $list2, '-BackupDir', $bd2)
|
||||
$ok9 = $r.ExitCode -eq 0 -and @(Get-ChildItem -LiteralPath $bd2 -Filter '*.7z' -ErrorAction SilentlyContinue).Count -ge 1
|
||||
Add-Case -Id 'BB-09' -Module '边界值' -Title '特殊字符：含 & 与 # 的路径（整行引号写法）' -Priority 'P2' `
|
||||
-Precondition '源目录名含 & 与 #；清单行整体加引号' `
|
||||
-Steps '备份该条目' `
|
||||
-Expected '退出码 0 且真的产出归档（# 不被当注释吃掉）' `
|
||||
-Actual ("退出码={0}；归档数={1}" -f $r.ExitCode, @(Get-ChildItem -LiteralPath $bd2 -Filter '*.7z' -ErrorAction SilentlyContinue).Count) `
|
||||
-Pass $ok9 -Severity '一般'
|
||||
|
||||
# BB-10 无控制台时的明确失败（README：绝不挂起）
|
||||
$pinfo = New-Object System.Diagnostics.ProcessStartInfo
|
||||
$pinfo.FileName = $host7
|
||||
$pinfo.Arguments = "-NoProfile -ExecutionPolicy Bypass -File `"$repo\Manage-Backup.ps1`""
|
||||
$pinfo.RedirectStandardOutput = $true
|
||||
$pinfo.RedirectStandardError = $true
|
||||
$pinfo.UseShellExecute = $false
|
||||
$pinfo.CreateNoWindow = $true
|
||||
$proc = [System.Diagnostics.Process]::Start($pinfo)
|
||||
$finished = $proc.WaitForExit(60000)
|
||||
$stdout = if ($finished) { $proc.StandardOutput.ReadToEnd() } else { '' }
|
||||
$stderr = if ($finished) { $proc.StandardError.ReadToEnd() } else { '' }
|
||||
if (-not $finished) { try { $proc.Kill() } catch {} }
|
||||
Add-Case -Id 'BB-10' -Module '无头' -Title '文档承诺：没有控制台且没给 -InputScript 时报错退出，绝不挂起' -Priority 'P0' `
|
||||
-Precondition 'stdout/stderr 被重定向（等价于计划任务/管道环境）' `
|
||||
-Steps '不传参数直接运行 Manage-Backup.ps1，等待最多 60 秒' `
|
||||
-Expected '60 秒内退出，退出码 2，并提示"没有可用的控制台"' `
|
||||
-Actual ("60 秒内退出={0}；退出码={1}；输出片段={2}" -f $finished, $proc.ExitCode, (@($stdout, $stderr) -join ' ').Trim().Substring(0, [Math]::Min(90, (@($stdout, $stderr) -join ' ').Trim().Length))) `
|
||||
-Pass ($finished -and $proc.ExitCode -eq 2) -Severity '致命'
|
||||
|
||||
# BB-11 孤儿归档审计
|
||||
$orphanDir = Join-Path $sandbox 'Backups3'
|
||||
New-Item -ItemType Directory -Path $orphanDir -Force | Out-Null
|
||||
Copy-Item -LiteralPath (Join-Path $backupDir 'manifest.json') -Destination (Join-Path $orphanDir 'manifest.json') -ErrorAction SilentlyContinue
|
||||
$fake = Join-Path $orphanDir 'GhostSoftware.7z'
|
||||
if ($archives.Count -gt 0) { Copy-Item -LiteralPath $archives[0].FullName -Destination $fake }
|
||||
$r = Invoke-Bak -HostName 7 -Arguments @('-DryRun', '-BackupListPath', $listPath, '-BackupDir', $orphanDir)
|
||||
$named = @($r.Output | Where-Object { $_ -match 'GhostSoftware' }).Count -gt 0
|
||||
Add-Case -Id 'BB-11' -Module '审计' -Title '文档承诺：孤儿归档会被点名' -Priority 'P1' `
|
||||
-Precondition 'Backups3\ 里放一个清单中不存在的 GhostSoftware.7z' `
|
||||
-Steps '备份后看输出是否点名' `
|
||||
-Expected '输出里出现该孤儿归档名' `
|
||||
-Actual ("退出码={0}；点名={1}" -f $r.ExitCode, $named) `
|
||||
-Pass $named -Severity '一般'
|
||||
|
||||
# ---------------------------------------------------------------- 汇总
|
||||
$report = [ordered]@{
|
||||
testedAt = (Get-Date).ToString('s')
|
||||
scope = '文档契约黑盒测试（README 为准）'
|
||||
sandbox = $sandbox
|
||||
total = $cases.Count
|
||||
passed = @($cases | Where-Object Status -eq 'PASS').Count
|
||||
failed = @($cases | Where-Object Status -eq 'FAIL').Count
|
||||
fatalOrSevere = @($cases | Where-Object { $_.Status -eq 'FAIL' -and $_.Severity -in '致命', '严重' }).Count
|
||||
cases = $cases
|
||||
}
|
||||
$report | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $OutJson -Encoding utf8
|
||||
$cases | Format-Table Id, Module, Priority, Status, Severity, Title -AutoSize
|
||||
Write-Host ''
|
||||
Write-Host ("合计 {0}；通过 {1}；失败 {2}；致命/严重 {3}" -f $report.total, $report.passed, $report.failed, $report.fatalOrSevere)
|
||||
Write-Host ("结果写入 {0}" -f $OutJson)
|
||||
Write-Host ("沙盒（保留供排查）: {0}" -f $sandbox)
|
||||
@@ -0,0 +1,104 @@
|
||||
{
|
||||
"testedAt": "2026-09-28T12:43:39",
|
||||
"total": 12,
|
||||
"passed": 12,
|
||||
"failed": 0,
|
||||
"cases": [
|
||||
{
|
||||
"Id": "BB-01",
|
||||
"Title": "真实备份：退出码 0 + 产出归档 + manifest",
|
||||
"Expected": "退出码 0；≥1 个 .7z；manifest.json 存在",
|
||||
"Actual": "退出码=0；归档=1",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-02",
|
||||
"Title": "排除模式真的把内容挡在归档之外",
|
||||
"Expected": "归档内无 skipme.log，有 a.txt/b.txt",
|
||||
"Actual": "skipme=False；keep=True",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-03",
|
||||
"Title": "-DryRun 一个字节都不写",
|
||||
"Expected": "退出码 0；manifest SHA256 前后一致",
|
||||
"Actual": "退出码=0；哈希一致=True",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-04",
|
||||
"Title": "源不存在记 missing-source，不算失败",
|
||||
"Expected": "含 missing-source；退出码 0",
|
||||
"Actual": "actions=backed-up,missing-source；退出码=0",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-05",
|
||||
"Title": "-Only 只处理匹配的条目",
|
||||
"Expected": "退出码 0；输出不提未选中的 nonexistent",
|
||||
"Actual": "退出码=0；提到 nonexistent=False",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-06",
|
||||
"Title": "★显式指定的清单不存在 -> 必须报失败（本次修复点）",
|
||||
"Expected": "退出码 ≠ 0；不创建模板；输出含\"指定的清单不存在\"",
|
||||
"Actual": "退出码=1；误建模板=False；提示=True",
|
||||
"Status": "PASS",
|
||||
"Note": "阶段 1 原为 FAIL（退出码 0 且建了模板），本次修复后应转为 PASS"
|
||||
},
|
||||
{
|
||||
"Id": "BB-06b",
|
||||
"Title": "对照：未显式指定时首次运行仍建模板并退出 0",
|
||||
"Expected": "退出码 0；模板被创建；随后仓库原文件已还原",
|
||||
"Actual": "退出码=0；模板创建=True；仓库还原=True",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-07",
|
||||
"Title": "旧名字垫片转发且退出码原样传递",
|
||||
"Expected": "退出码 0；有改名提示",
|
||||
"Actual": "退出码=0；提示=True",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-08",
|
||||
"Title": "5.1 与 7.x 行为一致",
|
||||
"Expected": "两个宿主退出码都是 0",
|
||||
"Actual": "7=0；5.1=0",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-09",
|
||||
"Title": "含 & 与 # 的路径（整行引号）",
|
||||
"Expected": "退出码 0 且产出归档",
|
||||
"Actual": "退出码=0；归档=1",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-10",
|
||||
"Title": "无控制台且无 -InputScript 时报错退出，绝不挂起",
|
||||
"Expected": "60 秒内退出且退出码 2",
|
||||
"Actual": "已退出=True；退出码=2",
|
||||
"Status": "PASS",
|
||||
"Note": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-11",
|
||||
"Title": "★孤儿归档审计（改用真实运行）",
|
||||
"Expected": "输出点名 GhostSoftware.7z",
|
||||
"Actual": "退出码=0；点名=True",
|
||||
"Status": "PASS",
|
||||
"Note": "阶段 1 的 FAIL 系夹具错误：孤儿审计只在真实运行里报告，干跑不报"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,143 @@
|
||||
{
|
||||
"testedAt": "2026-09-28T12:35:02",
|
||||
"scope": "文档契约黑盒测试（README 为准）",
|
||||
"sandbox": "C:\\Users\\Shuery\\AppData\\Local\\Temp\\baknret-bb-45647a8d",
|
||||
"total": 11,
|
||||
"passed": 9,
|
||||
"failed": 2,
|
||||
"fatalOrSevere": 0,
|
||||
"cases": [
|
||||
{
|
||||
"Id": "BB-01",
|
||||
"Module": "备份",
|
||||
"Title": "文档承诺：备份成功返回 0，并产出 .7z 归档",
|
||||
"Priority": "P0",
|
||||
"Precondition": "沙盒清单：1 个目录（含排除）+ 1 个不存在的源",
|
||||
"Steps": "Backup-Data.ps1（无 -DryRun）",
|
||||
"Expected": "退出码 0；Backups\\ 下出现 1 个 .7z；manifest.json 存在",
|
||||
"Actual": "退出码=0；归档=1 个（srcdocs_from_C_+Users+Shuery+AppData+Local+Temp+baknret-bb-45647a8d.7z）",
|
||||
"Status": "PASS",
|
||||
"Severity": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-02",
|
||||
"Module": "排除",
|
||||
"Title": "文档承诺：:- 排除模式把内容挡在归档之外",
|
||||
"Priority": "P0",
|
||||
"Precondition": "清单里对源目录写了 :- 'nested\\skipme.log'",
|
||||
"Steps": "7z l 列出归档内容",
|
||||
"Expected": "归档里**没有** skipme.log，但有 a.txt 与 b.txt",
|
||||
"Actual": "skipme.log 命中=False；a/b.txt 命中=True",
|
||||
"Status": "PASS",
|
||||
"Severity": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-03",
|
||||
"Module": "干跑",
|
||||
"Title": "文档承诺：-DryRun 一个字节都不写（含 manifest.json）",
|
||||
"Priority": "P0",
|
||||
"Precondition": "已有 1 份归档与 manifest.json",
|
||||
"Steps": "记录 SHA256 → 跑 -DryRun → 再记录 SHA256",
|
||||
"Expected": "退出码 0；manifest.json 的 SHA256 前后完全一致",
|
||||
"Actual": "退出码=0；哈希 6D726A618FD8 → 6D726A618FD8",
|
||||
"Status": "PASS",
|
||||
"Severity": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-04",
|
||||
"Module": "异常流",
|
||||
"Title": "文档承诺：源路径不存在记 missing-source，不算失败",
|
||||
"Priority": "P1",
|
||||
"Precondition": "清单第 2 行指向不存在的目录",
|
||||
"Steps": "跑备份后读 manifest.json 的 action 字段",
|
||||
"Expected": "该条目 action=missing-source，且整体退出码仍为 0",
|
||||
"Actual": "退出码=0；manifest action 分布=backed-up,missing-source",
|
||||
"Status": "PASS",
|
||||
"Severity": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-05",
|
||||
"Module": "干跑",
|
||||
"Title": "文档承诺：-Only 只处理匹配的条目",
|
||||
"Priority": "P1",
|
||||
"Precondition": "清单 2 条：srcdocs（目录）、nonexistent（不存在）",
|
||||
"Steps": "Backup-Data.ps1 -DryRun -Only 'srcdocs'",
|
||||
"Expected": "退出码 0；输出里不出现未选中的 nonexistent 条目",
|
||||
"Actual": "退出码=0；输出提到 nonexistent=False",
|
||||
"Status": "PASS",
|
||||
"Severity": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-06",
|
||||
"Module": "异常流",
|
||||
"Title": "边界值：清单文件不存在时的行为",
|
||||
"Priority": "P1",
|
||||
"Precondition": "传入一个不存在的 -BackupListPath",
|
||||
"Steps": "Backup-Data.ps1 -BackupListPath <不存在>",
|
||||
"Expected": "明确报错（非 0 退出码）或给出可读提示，**不得静默返回 0**",
|
||||
"Actual": "退出码=0；末行=[2026-09-28 12:34:54] [INFO] 模板 BackupList.txt 已创建，请编辑后重试。",
|
||||
"Status": "FAIL",
|
||||
"Severity": "一般"
|
||||
},
|
||||
{
|
||||
"Id": "BB-07",
|
||||
"Module": "兼容",
|
||||
"Title": "文档承诺：旧名字 Backup.ps1 是转发垫片，退出码原样传递",
|
||||
"Priority": "P1",
|
||||
"Precondition": "实现已改名为 Backup-Data.ps1",
|
||||
"Steps": "Backup.ps1 -DryRun（旧名字）",
|
||||
"Expected": "打印改名提示；退出码与直接调用一致（0）",
|
||||
"Actual": "退出码=0；有改名提示=True",
|
||||
"Status": "PASS",
|
||||
"Severity": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-08",
|
||||
"Module": "跨端一致性",
|
||||
"Title": "文档承诺：Windows PowerShell 5.1 与 7.x 行为一致",
|
||||
"Priority": "P0",
|
||||
"Precondition": "同一沙盒、同一清单",
|
||||
"Steps": "两个宿主各跑一次 -DryRun，比较退出码",
|
||||
"Expected": "两者退出码都是 0（GBK 控制台下的中文输出不崩）",
|
||||
"Actual": "7 退出码=0；5.1 退出码=0",
|
||||
"Status": "PASS",
|
||||
"Severity": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-09",
|
||||
"Module": "边界值",
|
||||
"Title": "特殊字符：含 & 与 # 的路径（整行引号写法）",
|
||||
"Priority": "P2",
|
||||
"Precondition": "源目录名含 & 与 #；清单行整体加引号",
|
||||
"Steps": "备份该条目",
|
||||
"Expected": "退出码 0 且真的产出归档（# 不被当注释吃掉）",
|
||||
"Actual": "退出码=0；归档数=1",
|
||||
"Status": "PASS",
|
||||
"Severity": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-10",
|
||||
"Module": "无头",
|
||||
"Title": "文档承诺：没有控制台且没给 -InputScript 时报错退出，绝不挂起",
|
||||
"Priority": "P0",
|
||||
"Precondition": "stdout/stderr 被重定向（等价于计划任务/管道环境）",
|
||||
"Steps": "不传参数直接运行 Manage-Backup.ps1，等待最多 60 秒",
|
||||
"Expected": "60 秒内退出，退出码 2，并提示\"没有可用的控制台\"",
|
||||
"Actual": "60 秒内退出=True；退出码=2；输出片段=û�п��õĿ���̨��Ҳû�и��� -InputScript�������뽻�����档\r\nҪ�ǽ���ִ�У���ָ�����������磺-Action Backup ",
|
||||
"Status": "PASS",
|
||||
"Severity": ""
|
||||
},
|
||||
{
|
||||
"Id": "BB-11",
|
||||
"Module": "审计",
|
||||
"Title": "文档承诺：孤儿归档会被点名",
|
||||
"Priority": "P1",
|
||||
"Precondition": "Backups3\\ 里放一个清单中不存在的 GhostSoftware.7z",
|
||||
"Steps": "备份后看输出是否点名",
|
||||
"Expected": "输出里出现该孤儿归档名",
|
||||
"Actual": "退出码=0；点名=False",
|
||||
"Status": "FAIL",
|
||||
"Severity": "一般"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,345 @@
|
||||
# BakNRet CI/CD 流水线报告
|
||||
|
||||
- **报告时间**：2026-09-28
|
||||
- **项目**：BakNRet（Windows 备份 / 恢复工具，PowerShell 5.1 + 7.x）
|
||||
- **分支**：`refactor/ms-conventions`
|
||||
- **测试环境**：Hyper-V VM `BakNRet-Lab`（Gen2 / 8 vCPU / 12 GB）+ 宿主 `STRIX-X870A`
|
||||
- **流水线入口**：`/ci-cd-pipeline`（用户指定：测试环境为 Hyper-V 虚拟机）
|
||||
|
||||
---
|
||||
|
||||
## 阶段总览
|
||||
|
||||
| 阶段 | 名称 | 状态 | 关键结果 |
|
||||
| --- | --- | --- | --- |
|
||||
| 0.1 | 依赖安全扫描 | ✅ 通过 | 零运行时依赖；**0 致命/严重**；2 条一般级卫生风险 |
|
||||
| 0.2 | 许可证合规 | ⚠️ 通过（有缺口） | 无 copyleft 冲突；**主许可证未声明** |
|
||||
| 0.3 | 语法检查与修复 | ✅ 通过 | 131/131 双宿主解析零错；修 2 处排版 + 1 处自伤；分析器 84→80 条、0 Error |
|
||||
| 1 | 黑盒测试 | ✅ 通过 | 11 条用例：9 通过、2 失败（**0 致命/严重**） |
|
||||
| 2 | 缺陷修复与回归 | ✅ 通过 | 修 1 个真实缺陷；回归 **12/12**；Pester 183→**192** 全绿 |
|
||||
| 3 | 测试增强与性能 | ✅ 通过 | 性能基线首次建立、**无退化**；单测增强给出优先级、未擅自新增 |
|
||||
| 4 | 代码规范化 | ✅ 通过 | 分析器格式规则门禁通过（0 Error）；仓库自有格式门禁为准 |
|
||||
| 5 | 文档生成与质量检查 | ✅ 通过 | `PROJECT_REPORT.md` 532 行；markdownlint **0 错**；死链 **0** |
|
||||
| 6 | 数据库迁移审查 | ⏭️ **不适用** | 全仓无数据库、无 SQL、无迁移脚本 |
|
||||
| 7 | 生产部署 | ⛔ **停在人工确认门** | 需你确认（见文末） |
|
||||
| 8 | 收尾 | ✅ 完成 | 本报告 |
|
||||
|
||||
---
|
||||
|
||||
## 阶段 0：静态分析与修复
|
||||
|
||||
### 0.1 依赖安全扫描
|
||||
|
||||
| 项目 | 结论 |
|
||||
| --- | --- |
|
||||
| 依赖管理文件 | 不存在（无 `package.json` / `requirements.txt` / `go.mod` / `pom.xml` / `Cargo.toml`） |
|
||||
| 运行时依赖 | **0 个模块**（只需 PowerShell 5.1 或 7.x + 7-Zip） |
|
||||
| CVE | 无可报（没有任何被本仓库固定版本的第三方库） |
|
||||
|
||||
**风险**：R-1 无 `LICENSE`（一般）· R-2 工作区存在口令文件 `baknret.key`（一般，**未被 git 跟踪**，
|
||||
`.gitignore:18 *.key` 已忽略；全程未读取其内容）· R-3 不检查 7z 版本（建议）·
|
||||
R-4 口令经命令行传给 7z（建议，上游限制）。
|
||||
|
||||
### 0.2 许可证合规
|
||||
|
||||
| 组件 | 许可证 | 是否随分发 |
|
||||
| --- | --- | --- |
|
||||
| 本项目 | **未声明** | — |
|
||||
| Pester 5.9.1 | Apache-2.0 | 否（`.tools/`，gitignore） |
|
||||
| PSScriptAnalyzer 1.25.0 | MIT | 否 |
|
||||
| Newtonsoft.Json | MIT | 否 |
|
||||
| 7-Zip 26.03 | LGPL-2.1 + BSD-3 + unRAR 限制 | 否（用户自备） |
|
||||
|
||||
**无 copyleft 传染**。7-Zip 的 unRAR 限制只禁止「用其代码还原 RAR 压缩算法」，本项目不触发。
|
||||
|
||||
### 0.3 语法检查与自动修复
|
||||
|
||||
**修复的真实缺陷**
|
||||
|
||||
| 文件:行 | 规则 | 修复 |
|
||||
| --- | --- | --- |
|
||||
| `Backup.ps1:42` | `PSUseConsistentWhitespace` | `@($Rest)+ @(...)` → `@($Rest) + @(...)` |
|
||||
| `Restore.ps1:42` | 同上 | 同上 |
|
||||
|
||||
**修复过程中的自伤与恢复（重要教训）**
|
||||
|
||||
编辑这两个文件后 **UTF-8 BOM 被抹掉**，导致 5.1 立即报 `The string is missing the terminator: '.`，
|
||||
而 PowerShell 7 完全正常。用 `UTF8Encoding($true)` 重写后恢复，双宿主 `parse_bad=0`。
|
||||
这条恰好实证了本仓库 Encode 层门禁的价值，也说明「编辑 PowerShell 源文件必须保留 BOM」是硬约束。
|
||||
|
||||
**未修复项**：80 条全部为风格类（0 Error），按用户决定登记为「仓库已声明的偏离」，逐条附依据：
|
||||
行长 160 是配置里写明的有意偏离（`PSScriptAnalyzerSettings.psd1` + [ADR-0008](../docs/adr/0008-analyzer-deviations.md)）；
|
||||
`PSPlaceCloseBrace` 等集中在 `Run-Tests.ps1` 的**测试夹具字符串**内（改了会改变断言语义）；
|
||||
`PSUseSupportsShouldProcess` 已全局排除属已知噪声；空 catch 是有意为之（注释已写明理由）。
|
||||
|
||||
**待人工确认的观察项**：`Write-BakNRetRunSummary` 的 `$Mode` 参数声明了 `ValidateSet` 与 `Mandatory`
|
||||
但函数体内从未读取，且该函数未被仓库内任何代码调用（仅对外导出）。判断为未完工实现，
|
||||
删除会破坏公共 API 参数契约，故**登记而不改动**。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 1 → 2：黑盒测试与缺陷修复
|
||||
|
||||
### 测试环境确认（技能强制）
|
||||
|
||||
| 项目 | 事实 |
|
||||
| --- | --- |
|
||||
| 目标 | Hyper-V VM `BakNRet-Lab`（Gen2 / 8 vCPU / 12 GB / Default Switch 内部 NAT） |
|
||||
| 检查点 | 自动检查点、**clean-baseline**、**sandbox-ready** |
|
||||
| 数据隔离 | 仓库自述：全部操作在 VM 内进行，宿主机仓库 / `Backups\` / `logs\` 不被写入 |
|
||||
| 生产暴露 | 无（无生产服务器、无域名、无对外服务） |
|
||||
|
||||
**已获用户明确确认**后开始测试。
|
||||
|
||||
### 用例与结果
|
||||
|
||||
| 编号 | 用例 | 阶段 1 | 阶段 2 回归 |
|
||||
| --- | --- | --- | --- |
|
||||
| BB-01 | 真实备份：退出码 0 + 产出归档 + manifest | PASS | PASS |
|
||||
| BB-02 | 排除模式真的把内容挡在归档之外（逐个归档内容核对） | PASS | PASS |
|
||||
| BB-03 | `-DryRun` 一个字节都不写（manifest SHA256 前后一致） | PASS | PASS |
|
||||
| BB-04 | 源不存在记 `missing-source`，不算失败 | PASS | PASS |
|
||||
| BB-05 | `-Only` 只处理匹配的条目 | PASS | PASS |
|
||||
| BB-06 | **显式清单不存在 → 必须报失败** | **FAIL** | **PASS（已修）** |
|
||||
| BB-06b | 对照：未显式指定时首次运行仍建模板 | — | PASS |
|
||||
| BB-07 | 旧名字垫片转发且退出码原样传递 | PASS | PASS |
|
||||
| BB-08 | 5.1 与 7.x 行为一致 | PASS | PASS |
|
||||
| BB-09 | 含 `&` 与 `#` 的路径（整行引号写法） | PASS | PASS |
|
||||
| BB-10 | 无控制台且无 `-InputScript` 时报错退出，绝不挂起 | PASS | PASS |
|
||||
| BB-11 | 孤儿归档审计 | FAIL（夹具错误） | PASS |
|
||||
|
||||
- **阶段 1**：11 条 → 通过 9、失败 2、**致命/严重 0**
|
||||
- **阶段 2 回归**：12 条 → **全部通过**
|
||||
|
||||
### 缺陷清单
|
||||
|
||||
| ID | 严重程度 | 标题 | 根因 | 修复 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| **DEF-01** | 一般 | 显式指定的清单不存在时**静默成功** | 「首次运行引导」与「路径写错」两条语义共用一条代码路径 | 按 `$PSBoundParameters.ContainsKey('BackupListPath')` 分流：显式指定 → ERROR + `exit 1`；未指定 → 保留引导 |
|
||||
| DEF-02 | 提示 | 两处运算符前后缺空格 | 手写拼接 | 补空格（分析器该规则归零） |
|
||||
| DEF-03 | 提示 | 孤儿审计在干跑下不报告 | **测试夹具错误**（非产品缺陷） | 修正夹具为真实运行 |
|
||||
|
||||
**DEF-01 的影响**：计划任务里 `-BackupListPath` 写错（或相对路径按了别的工作目录解析）时，
|
||||
脚本会在错误位置凭空建一份模板并 **exit 0**；任务计划程序读到「上次运行结果 = 成功」，
|
||||
而实际一个条目都没处理。这与本仓库已修过的「27 条被静默跳过、退出码仍是 0」是同一类缺陷，
|
||||
因此判为需要修复。`Restore-Data.ps1` 有对称问题（生成清单 + exit 0），一并修复。
|
||||
|
||||
**DEF-03 的处置值得记录**：BB-11 初判 FAIL，复核后确认是**用例设计错了**（用了 `-DryRun`，
|
||||
而孤儿审计只在真实运行里报告）。保留该记录，因为它说明「失败用例必须先复核再归因」，
|
||||
否则会把测试自身的问题记到产品头上。
|
||||
|
||||
### 回归证据
|
||||
|
||||
```text
|
||||
BakNRet 验收：层次 [Parse, Unit, Smoke, E2E]，宿主 [7, 5.1]
|
||||
[PASS] Encode any 受管 133 个文件：缺 BOM 0、CRLF 0、制表符 0
|
||||
[PASS] Parse 7 解析通过 131/131 个文件
|
||||
[PASS] Unit 7 / Smoke 7 / E2E 7
|
||||
[PASS] Parse 5.1 解析通过 131/131 个文件
|
||||
[PASS] Unit 5.1 / Smoke 5.1 / E2E 5.1
|
||||
验收全部通过：9 项（宿主 7 + 5.1）
|
||||
```
|
||||
|
||||
```text
|
||||
Tests Passed: 192, Failed: 0, Skipped: 0, Inconclusive: 0, NotRun: 0
|
||||
[+] [回归] 显式指定的清单不存在时报失败（退出码 1），且不在错误位置建模板 1.43s
|
||||
[+] [回归] 未显式指定清单时的首次运行仍建模板并退出 0（引导不能被误伤） 1.44s
|
||||
```
|
||||
|
||||
新增的 2 条用例是**成对**的：只测一条的话，「把所有缺失都改成 exit 1」这种错误实现也能骗过测试。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 3：测试增强与性能验证
|
||||
|
||||
### 单元测试增强（可选步骤）
|
||||
|
||||
| 指标 | 数值 |
|
||||
| --- | --- |
|
||||
| 对外函数 | 89（与 `FunctionsToExport` 白名单逐一核对一致） |
|
||||
| 测试中直接点名 | 70（78.7%） |
|
||||
| 未直接点名 | 19（其中多条由集成路径间接覆盖） |
|
||||
|
||||
**建议补测**（本轮未擅自新增，因用户选择了最小侵入姿态，且该步骤标注为可选）：
|
||||
`Move-BakNRetArchiveIntoPlace`（原子替换，历史上真出过「先删后移」缺陷）、
|
||||
`Resolve-BakNRetRootedPath`（相对路径按仓库根解析这条计划任务关键约定）。
|
||||
安全描述符相关的 4 个函数**不建议**补单元测试 —— 它们需要真实提权与真实 NTFS，
|
||||
仓库已用 `tools/lab/Lab.ps1 acl-test`（含负对照）在真 VM 里覆盖，那是更正确的层次。
|
||||
|
||||
### 性能基线（首次建立）
|
||||
|
||||
环境：宿主 `STRIX-X870A`，PowerShell 7.7.0-preview.5，7-Zip 26.03 (x64)
|
||||
|
||||
| 指标 | 采样 | min | 中位数 | max |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 模块导入 | 5 | 628.3 ms | **631.0 ms** | 2052.8 ms |
|
||||
| 清单解析 ×50 轮 | 5 | 2535.9 ms | **2546.9 ms** | 2691.5 ms |
|
||||
| 只读干跑（真实 28 条清单） | 5 | 9839.9 ms | **9869.2 ms** | 12900.8 ms |
|
||||
| 源树扫描（200 文件 ×3 轮） | 1 | — | **18.2 ms** | — |
|
||||
|
||||
7z 吞吐（固定夹具 200 × 32 KB **随机数据**）：`-mx=0` 46.7 ms / `-mx=5` 224.2 ms / `-mx=9` 225.2 ms。
|
||||
夹具为不可压缩数据，故体积不随级别变化 —— 该夹具测的是**吞吐与 I/O，不是压缩率**。
|
||||
|
||||
**判定**：首次基线，无历史可比，**无退化**。基线文件：`.scratch/ci-cd/20260928-001722/perf_baseline.json`。
|
||||
跨机比较无意义，仅同机同宿主下对比。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 4：代码规范化
|
||||
|
||||
- **仓库自有的格式门禁**是 `PSScriptAnalyzerSettings.psd1` 打开的 6 条格式规则
|
||||
（括号 / 缩进 / 空格 / 对齐 / 大小写）+ 160 字符行长，通过 `tools/Invoke-Analyzer.ps1` 执行。
|
||||
- 本次：**0 条 Error**，格式类告警从 4 条（whitespace）降到 **0 条**。
|
||||
- PowerShell 没有官方「Google 风格」格式化器；本仓库的等价物就是上面这套规则集，
|
||||
故阶段 4 以仓库门禁为准，未引入外部格式化器（避免制造与仓库约定冲突的大 diff）。
|
||||
- `README.md` / `PROJECT_REPORT.md` 由 **Prettier 3.9.9** 格式化并通过 `--check`。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 5：文档生成与质量检查
|
||||
|
||||
| 产物 | 规模 | 质量门禁 |
|
||||
| --- | --- | --- |
|
||||
| `README.md` | 925 行 | Prettier ✅；markdownlint 17 → **10 错（全为 MD051 假阳性）**；外部链接 11/11 → 200；内部相对链接全通；63 个标题锚点全部可解析；3 张 Mermaid 图在真实浏览器中解析通过 |
|
||||
| `PROJECT_REPORT.md` | 532 行 | Prettier ✅；markdownlint **0 错**；相对链接 18/18 有效；外部链接 3/3 → 200 |
|
||||
|
||||
**MD051 假阳性说明**：README 的标题带 emoji（如 `## 🚀 快速开始`），GitHub 生成的锚点是
|
||||
`#-快速开始`（剥离 emoji 后前导连字符）。`markdownlint-cli2` 的锚点生成器**不做 emoji 剥离**，
|
||||
因此把这类链接报为无效。已用独立脚本按 GitHub 规则复算全部锚点，**63 个全部可解析**，
|
||||
故不修改标题（emoji 标题是本次文档改造的要求之一）。
|
||||
|
||||
**死链检查**：全部外部链接逐个 `HEAD` 请求验证，返回 200；相对链接逐个 `Test-Path` 验证存在。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 6：数据库迁移审查 —— 不适用
|
||||
|
||||
| 检查 | 结果 |
|
||||
| --- | --- |
|
||||
| `*.sql` / `*.db` / `*.sqlite` 文件 | 无 |
|
||||
| `Invoke-Sqlcmd` / `SqlConnection` / `CREATE TABLE` / `SELECT ... FROM` | 无命中 |
|
||||
| 迁移脚本目录 | 不存在 |
|
||||
|
||||
本项目是本地 CLI 工具，**不涉及任何数据库**，该阶段跳过。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 7：生产部署 —— 停在人工确认门
|
||||
|
||||
> [!CAUTION]
|
||||
>
|
||||
> **未执行任何部署动作。** 本项目的「生产部署」= 在真实机器上注册计划任务并让它按计划跑备份，
|
||||
> 属于对用户个人环境产生持久副作用的操作，必须由你确认。
|
||||
|
||||
### 部署前状态
|
||||
|
||||
| 项目 | 状态 |
|
||||
| --- | --- |
|
||||
| 代码门禁 | ✅ 9/9（双宿主）· Pester 192/192 · 黑盒 12/12 |
|
||||
| 工作树 | 6 个文件已改（+796 / −202），新增 `PROJECT_REPORT.md`（未提交） |
|
||||
| 运行前提 | PowerShell 5.1/7.x ✅ · 7-Zip 26.03 ✅ |
|
||||
| 阻塞项 | 会话审批策略为 `never`，`gsudo` 提权被自动拒绝（退出码 999）；注册计划任务需要管理员 |
|
||||
|
||||
### 建议的部署步骤（待你确认后执行）
|
||||
|
||||
```powershell
|
||||
# 1. 先确认清单与口令就位（口令应在仓库外）
|
||||
.\Backup-Data.ps1 -DryRun # 只读，先看计划与空间预估
|
||||
.\Backup-Data.ps1 -Only 'Edge' # 先只备一项，验证端到端
|
||||
.\Restore-Data.ps1 -VerifyOnly # 只校验，不解压
|
||||
|
||||
# 2. 注册计划任务（需要管理员）
|
||||
.\tools\Register-BackupTask.ps1 -At '21:30' -DryRun # 先看将要注册什么
|
||||
.\tools\Register-BackupTask.ps1 -At '21:30' # 确认后注册
|
||||
|
||||
# 3. 部署后验证
|
||||
Get-ScheduledTaskInfo -TaskName 'BakNRet Backup' # 上次运行结果
|
||||
Start-ScheduledTask -TaskName 'BakNRet Backup' # 手动跑一次
|
||||
```
|
||||
|
||||
### 回滚
|
||||
|
||||
```powershell
|
||||
.\tools\Register-BackupTask.ps1 -Remove
|
||||
```
|
||||
|
||||
**风险**：注册计划任务本身可逆（`-Remove`）；但**首次真实备份会写入归档目录并消耗磁盘**
|
||||
（README 已有空间预估与逐条目守卫，不够时只告警不中断）。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 8：关键指标与建议
|
||||
|
||||
### 关键指标
|
||||
|
||||
| 指标 | 数值 |
|
||||
| --- | --- |
|
||||
| 验收门禁 | **9/9 PASS**（PS 7.7.0-preview.5 + 5.1.26100.9502 各一遍） |
|
||||
| 解析 | **131/131** 文件双宿主零错 |
|
||||
| Pester | **192 通过 / 0 失败 / 0 跳过**（183 → 补 2 条回归用例后 185 → 再补 7 条后 192） |
|
||||
| 黑盒回归 | **12/12** |
|
||||
| 静态分析 | **80 条 / 0 Error**（修复前 84） |
|
||||
| 运行时依赖 | **0** |
|
||||
| 致命 / 严重缺陷 | **0** |
|
||||
| 修复的真实缺陷 | **1**（DEF-01）+ 2 处排版 |
|
||||
| 代码变更 | 6 文件，+796 / −202 |
|
||||
| 文档产物 | `README.md` 925 行 · `PROJECT_REPORT.md` 1004 行 |
|
||||
|
||||
### 后续轮次已执行（用户回复「继续」之后）
|
||||
|
||||
| 事项 | 结果 |
|
||||
| --- | --- |
|
||||
| 补单元测试（原建议 2 条） | ✅ 实际补 **7 条**断言：原子替换 3 条（含 AST 判定 `File.Replace` 与 `[NullString]::Value`）、路径解析 4 条（含 AST 判定「模块里不得引用 `$PSScriptRoot`」）。Pester 185 → **192**，0 失败 |
|
||||
| 修正 README 的零依赖套件条数 | ✅ 实测为 **128 项**（原写 111，已改正）。这是上一轮 README 重写留下的**事实错误**，由 PROJECT_REPORT 的核对暴露出来 |
|
||||
| 复核 PROJECT_REPORT.md 的数字 | ✅ 行数口径标注为「**非空行**」；Pester 计数更新为 192；**修正一处过度断言**（原文称「修复后代码在 VM 内验证可用」，实际只取到修复前的 Pester 快照） |
|
||||
| 补 LICENSE / 移出 `baknret.key` / 确认 `$Mode` 意图 | ⏸️ 仍需你决定 |
|
||||
|
||||
> **指标口径说明（本次踩到的坑）**：工程规模按**非空行**统计是 **14389 行**，按**含空行**统计是 **16805 行**。
|
||||
> 两者都对，但必须写明口径。本次就因为口径不同（我用含空行、报告用非空行），一度把一份**正确的**数字
|
||||
> 误判为错误，直到逐目录复算（模块 4369 非空行在 HEAD 与工作树上完全一致）才定位到是口径差异。
|
||||
> 报告里凡出现行数处已统一标注口径。
|
||||
|
||||
### 建议（按优先级）
|
||||
|
||||
| 优先级 | 事项 | 理由 |
|
||||
| --- | --- | --- |
|
||||
| **高** | 补 `LICENSE` | 当前等于「保留所有权利」，他人无权分发 |
|
||||
| **高** | 提交前复核本次改动并决定是否 commit | 6 个文件已改，尚未提交 |
|
||||
| 中 | 把 `baknret.key` 移出仓库目录 | 虽未被跟踪，工作区放口令文件是卫生问题 |
|
||||
| 中 | 确认 `Write-BakNRetRunSummary` 的 `$Mode` 意图 | 未使用参数 + 未被调用 |
|
||||
| 低 | 在 VM 内补跑修复后的三套件 | 本次因提权被禁未取得（宿主侧已全绿） |
|
||||
| 低 | 启动时打印 7-Zip 版本 | 便于排障 |
|
||||
|
||||
### 本次流水线的诚实边界
|
||||
|
||||
1. **VM 测试未跑全**：会话审批策略改为 `never` 后 `gsudo` 提权被自动拒绝，而 Hyper-V 与
|
||||
PowerShell Direct 都需要管理员。**已核实的部分**（同步成功、VM 内 Pester 183 通过）如实记录；
|
||||
零依赖与端到端套件在 VM 内的结果**本次未取得**，不做推断。宿主侧同等套件已全部通过。
|
||||
2. **静态分析未压到 0**：剩余 80 条与仓库**已声明的偏离**冲突，按你的决定登记而不改，
|
||||
逐条附依据。严格模式的「零容忍」在这里与仓库自身配置相抵，选择尊重仓库约定。
|
||||
3. **阶段 7 未执行**：等你在下一轮明确确认。
|
||||
|
||||
---
|
||||
|
||||
## 附件索引
|
||||
|
||||
所有中间产物在 `.scratch/ci-cd/`：
|
||||
|
||||
| 文件 | 内容 |
|
||||
| --- | --- |
|
||||
| `20260928-001722/dependency_security_report.md` | 依赖安全扫描报告 |
|
||||
| `20260928-001722/license_check_report.md` | 许可证合规报告 |
|
||||
| `20260928-001722/stage0_static_analysis.md` | 阶段 0 完整报告（含 BOM 自伤记录） |
|
||||
| `20260928-001722/stage3_tests_and_perf.md` | 阶段 3 报告（覆盖率分析 + 性能基线） |
|
||||
| `20260928-001722/analyzer_raw.txt` | 修复前静态分析原始输出（84 条） |
|
||||
| `20260928-001722/analyzer_after.txt` | 修复后静态分析输出（80 条） |
|
||||
| `20260928-001722/pester_after_fix.txt` | 修复后 Pester 详细输出（185 通过；本轮补测后 192） |
|
||||
| `20260928-001722/perf_baseline.json` | 性能基线数据 |
|
||||
| `20260928-001722/blackbox_results.json` | 阶段 1 黑盒结果（11 条） |
|
||||
| `20260928-001722/blackbox_regression.json` | 阶段 2 回归结果（12 条） |
|
||||
| `blackbox-tests.ps1` | 黑盒用例脚本（可重跑） |
|
||||
| `blackbox-regression.ps1` | 回归脚本（可重跑） |
|
||||
| `perf-baseline.ps1` | 性能基线脚本（可重跑） |
|
||||
| `../_verify/mermaid.png` | README 三张 Mermaid 图的浏览器渲染截图 |
|
||||
| `../_verify/report_mermaid.png` | PROJECT_REPORT 四张图的渲染截图（本次独立复验；与 `20260928-001722/report_mermaid.png` 是**两次独立渲染**，字节不同属正常） |
|
||||
| `20260928-001722/report_mermaid.png` | 同上四张图，由阶段 5 的报告生成方独立渲染并留证 |
|
||||
@@ -0,0 +1,139 @@
|
||||
# 宿主性能基线：对 BakNRet 的关键路径做可复现的计时。
|
||||
# 设计原则：所有指标都是"比值"或"固定夹具下的绝对耗时"，可以在同一台机器上重复对比。
|
||||
param(
|
||||
[string]$OutJson = '.scratch\ci-cd\20260928-001722\perf_baseline.json',
|
||||
[int]$Repeat = 5,
|
||||
[string]$Pwsh = 'pwsh'
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$root = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
|
||||
$modulePath = Join-Path $root 'BakNRet\BakNRet.psd1'
|
||||
$listPath = Join-Path $root 'BackupList.txt'
|
||||
$cfgPath = Join-Path $root 'BackupConfig.psd1'
|
||||
|
||||
function Get-Median([double[]]$Values) {
|
||||
$s = $Values | Sort-Object
|
||||
$n = $s.Count
|
||||
if ($n -eq 0) { return 0 }
|
||||
if ($n % 2 -eq 1) { return $s[[int](($n - 1) / 2)] }
|
||||
return ($s[$n / 2 - 1] + $s[$n / 2]) / 2
|
||||
}
|
||||
|
||||
function Measure-Once([scriptblock]$Body) {
|
||||
$sw = [System.Diagnostics.Stopwatch]::StartNew()
|
||||
& $Body | Out-Null
|
||||
$sw.Stop()
|
||||
return $sw.Elapsed.TotalMilliseconds
|
||||
}
|
||||
|
||||
$results = [ordered]@{
|
||||
measuredAt = (Get-Date).ToString('s')
|
||||
machine = $env:COMPUTERNAME
|
||||
os = [System.Environment]::OSVersion.VersionString
|
||||
psi = $PSVersionTable.PSVersion.ToString()
|
||||
cpu = (Get-CimInstance Win32_Processor | Select-Object -First 1 -ExpandProperty Name)
|
||||
logicalCpu = [int](Get-CimInstance Win32_ComputerSystem).NumberOfLogicalProcessors
|
||||
workdir = $root
|
||||
metrics = @{}
|
||||
notes = @()
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- 夹具（固定内容，避免与真实数据联动）
|
||||
$fixture = Join-Path $env:TEMP ('baknret-perf-' + [guid]::NewGuid().ToString('N').Substring(0, 8))
|
||||
New-Item -ItemType Directory -Path $fixture -Force | Out-Null
|
||||
$srcDir = Join-Path $fixture 'src'
|
||||
New-Item -ItemType Directory -Path $srcDir -Force | Out-Null
|
||||
|
||||
$sw = [System.Diagnostics.Stopwatch]::StartNew()
|
||||
$rnd = [Random]::new(20260928)
|
||||
$payload = New-Object byte[] 32768
|
||||
for ($f = 0; $f -lt 200; $f++) {
|
||||
$sub = Join-Path $srcDir ('d{0:D2}' -f ($f % 10))
|
||||
if (-not (Test-Path $sub)) { New-Item -ItemType Directory -Path $sub -Force | Out-Null }
|
||||
$rnd.NextBytes($payload)
|
||||
[System.IO.File]::WriteAllBytes((Join-Path $sub ("f$f.bin")), $payload)
|
||||
}
|
||||
$sw.Stop()
|
||||
$results.fixture = [ordered]@{ files = 200; bytes = 200 * 32768; createMs = [math]::Round($sw.Elapsed.TotalMilliseconds, 1) }
|
||||
|
||||
# ---------------------------------------------------------------- 1. 模块导入
|
||||
$imports = 1..$Repeat | ForEach-Object {
|
||||
Measure-Once { & $Pwsh -NoProfile -Command "Import-Module '$modulePath' -Force" }
|
||||
}
|
||||
$results.metrics.moduleImportMs = [ordered]@{
|
||||
min = [math]::Round(($imports | Measure-Object -Minimum).Minimum, 1)
|
||||
median = [math]::Round((Get-Median $imports), 1)
|
||||
max = [math]::Round(($imports | Measure-Object -Maximum).Maximum, 1)
|
||||
samples = $Repeat
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- 2. 清单解析
|
||||
$parseScript = @"
|
||||
Import-Module '$modulePath' -Force
|
||||
1..50 | ForEach-Object { Get-Content -LiteralPath '$listPath' | ForEach-Object { ConvertFrom-BackupListLine -Line `$_ } }
|
||||
"@
|
||||
$parseFile = Join-Path $fixture 'parse.ps1'
|
||||
Set-Content -LiteralPath $parseFile -Value $parseScript -Encoding utf8
|
||||
$parses = 1..$Repeat | ForEach-Object { Measure-Once { & $Pwsh -NoProfile -File $parseFile } }
|
||||
$results.metrics.backupListParse50xMs = [ordered]@{
|
||||
min = [math]::Round(($parses | Measure-Object -Minimum).Minimum, 1)
|
||||
median = [math]::Round((Get-Median $parses), 1)
|
||||
max = [math]::Round(($parses | Measure-Object -Maximum).Maximum, 1)
|
||||
samples = $Repeat
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- 3. 只读干跑（真实清单 + 空间预估 + manifest）
|
||||
$dryFile = Join-Path $fixture 'dry.ps1'
|
||||
Set-Content -LiteralPath $dryFile -Encoding utf8 -Value @"
|
||||
Set-Location '$root'
|
||||
& '$root\Backup-Data.ps1' -DryRun -BackupDir '$fixture\Backups' -ConfigPath '$cfgPath' *> `$null
|
||||
exit `$LASTEXITCODE
|
||||
"@
|
||||
$dries = 1..$Repeat | ForEach-Object { Measure-Once { & $Pwsh -NoProfile -File $dryFile } }
|
||||
$results.metrics.dryRunFullListMs = [ordered]@{
|
||||
min = [math]::Round(($dries | Measure-Object -Minimum).Minimum, 1)
|
||||
median = [math]::Round((Get-Median $dries), 1)
|
||||
max = [math]::Round(($dries | Measure-Object -Maximum).Maximum, 1)
|
||||
samples = $Repeat
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- 4. 7z 压缩吞吐（固定夹具，无压缩）
|
||||
$sevenZip = (Get-Command 7z -ErrorAction SilentlyContinue).Source
|
||||
if (-not $sevenZip) {
|
||||
foreach ($p in 'C:\Programs\Scoop\shims\7z.exe', 'C:\Program Files\7-Zip\7z.exe') { if (Test-Path $p) { $sevenZip = $p; break } }
|
||||
}
|
||||
if ($sevenZip) {
|
||||
$archive = Join-Path $fixture 'bench.7z'
|
||||
$bench = @()
|
||||
foreach ($lvl in 0, 5, 9) {
|
||||
if (Test-Path $archive) { Remove-Item $archive -Force }
|
||||
$ms = Measure-Once { & $sevenZip a -t7z "-mx=$lvl" -bso0 -bsp0 $archive (Join-Path $srcDir '*') }
|
||||
$bench += [pscustomobject]@{ level = $lvl; ms = [math]::Round($ms, 1); archiveBytes = (Get-Item $archive).Length }
|
||||
}
|
||||
$results.metrics.sevenZipBench = @($bench)
|
||||
$results.fixture.compressionInputBytes = 200 * 32768
|
||||
$results.metrics.sevenZipVersion = (& $sevenZip | Select-Object -First 2 | Select-Object -Last 1)
|
||||
}
|
||||
else {
|
||||
$results.notes += '找不到 7z.exe，跳过压缩基准'
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- 5. 源树扫描（Get-BakNRetFolderSummary 走真实目录）
|
||||
$summaryScript = @"
|
||||
Import-Module '$modulePath' -Force
|
||||
`$sw = [System.Diagnostics.Stopwatch]::StartNew()
|
||||
1..3 | ForEach-Object { Get-BakNRetFolderSummary -FolderPath '$srcDir' | Out-Null }
|
||||
`$sw.Stop()
|
||||
Write-Output ([math]::Round(`$sw.Elapsed.TotalMilliseconds / 3, 1))
|
||||
"@
|
||||
$sumFile = Join-Path $fixture 'summary.ps1'
|
||||
Set-Content -LiteralPath $sumFile -Value $summaryScript -Encoding utf8
|
||||
$sumMs = (& $Pwsh -NoProfile -File $sumFile | Select-Object -Last 1)
|
||||
$results.metrics.folderSummary200Files3xMs = [double]$sumMs
|
||||
|
||||
Remove-Item -LiteralPath $fixture -Recurse -Force -ErrorAction SilentlyContinue
|
||||
|
||||
$results | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath (Join-Path $root $OutJson) -Encoding utf8
|
||||
Write-Host ('基线已写入 {0}' -f $OutJson)
|
||||
$results.metrics | ConvertTo-Json -Depth 6
|
||||
+1011
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user