【win备份还原工具开发日记】30：P5缺件与V系列#38验收结清、门禁修复分级、wimlib覆盖式还原端到端（v2.6.21→v2.6.27）

对应文档（同日 16 篇）：docs/20261022-0615-P5缺件还原端到端进度与交接-Step-5-Preview.md、docs/20261022-0655-P5缺件还原端到端实机通过-Step-5-Preview.md、docs/20261022-0715-门禁参数修复v2.6.22与缺件镜像硬拒验证-Step-5-Preview.md、docs/20261022-0745-V4默认菜单名验收与门禁快速通道v2.6.23-Step-5-Preview.md、docs/20261022-0845-V1-A入口还原C盘实机验收与D4修复验证-Step-5-Preview.md、docs/20261022-0915-V5-图形用户界面弹窗钉住项实机验收-Step-5-Preview.md、docs/20261022-1200-38全链复跑AB入口备份预安装环境安装实机验收-Step-5-Preview.md、docs/20261022-1427-wimlib-no-acls覆盖式还原概念验证与DISM对照-Step-5-Preview.md、docs/20261022-1433-接手AI交接-wimlib覆盖式还原集成与项目铁律-Hy3.md、docs/20261022-1719-wimlib覆盖式还原通道集成任务110-Step-5-Preview.md、docs/20261022-1719-下一步待实现-Step-5-Preview.md、docs/20261022-1719-当前开发进度-Step-5-Preview.md、docs/20261022-2030-wimlib覆盖式还原端到端实机通过-Step-5-Preview.md、docs/20261022-2030-下一步待实现-Step-5-Preview.md、docs/20261022-2030-当前开发进度-Step-5-Preview.md、docs/20261022-2308-wimlib保留访问控制列表覆盖式还原概念验证-Step-5-Preview.md

今天做了什么

P5 缺件还原交接阻塞与缺件镜像构造（06:15，Step-5-Preview）：#41 tasks 清理收尾（18→2，归档 zip 18/18 验证）。缺件镜像 br-2619-noRE.wim（32,452,239,435 B 逐字节副本）构造成功：挂载 RW 后 del 对 TrustedInstaller（Windows 服务的信任安装方）属主文件报拒绝访问且失败仍返回 0，须 takeown /f → icacls /grant *S-1-5-18:(F) → del，只读回挂验证 VERIFY-AFTER-COMMIT=ABSENT。prepare 任务 f785b473 成功（stage=prepared）但 resume 报 os error 3——载荷镜像离奇消失（H:\BackupRestoreRE\f785b473\ 目录在、0 文件），端到端阻塞；已排除程序（remove_staging 仅 boot_entry.rs:799 终态一处）、GUI、空间（H: 剩 132GB）、探针四方。三个环境/代码发现：①挂载门禁参数缺陷出生即错（wim_mount_markers 用 /ImageFile: 调 /Mount-Wim，恒报 87，自 v2.4.2 commit 50ab69f 起静默降级为镜像名启发式）；②F: 空盘之谜（10-20 10:18–12:38 无人值守窗口被格式化，成因未知待求证）；③本机 grep 交替、UTF-16/GBK 编码等探针纪律。

P5 缺件还原端到端实机通过 + 载荷消失反证（06:55，Step-5-Preview）：任务 6aaa9528 stage=success/progress=100。关键在 prepare→resume 只隔 5 秒（上轮隔 3 分钟载荷即消失）；每 3.1 秒监控证实载荷 714,894,729 B 全程稳定，任务成功后 PAYLOAD_GONE 是 remove_staging 终态清理——反证程序不会在任务存活期删载荷，上轮「离奇消失」更可能为外部因素，USN（更新序列号）日志排查降为最低优先级。判据：恢复日志 WinRE registration skipped（winre_registration.rs:598）、目标卷序列号 E4D3-9C23→1C85-1445、已用 70.8 GB 与镜像 capturedUsedBytes 76.9 GB 同量级、当前系统 reagentc 命令不存在、实机进桌面且 EventID 1000（应用错误事件）零新增。两处日志落点订正：预安装环境主日志在镜像同目录 Recovery.log（75,805,556 B 累积，任务目录 recovery.log 仅 262 B）；recovery_fault::checkpoint 默认空操作（仅 --test-fault 落 marker），上轮交接把「checkpoint registration-skipped」当判据表述不准，真判据是 preflight 两行日志。坑：abandon-task/resume 的 root 参数是工作区根（传 \tasks 拼成 tasks\tasks）；%time% 在 for /L 体内静态展开须 !time!；恢复环境内盘符与 Windows 侧不同（WORKSPACE=E:/IMAGE=C:/TARGET=F: 对应 Windows 侧 H:/H:/F:）；按键注入只认 vmkey.sh（n=57、esc=9）。

门禁参数修复 v2.6.22 与双组对照（07:15，Step-5-Preview）：commit 1ef5e2e。/Mount-Wim 参数 /ImageFile:→/WimFile:，抽纯函数 wim_mount_args + 单测锁死，通过/降级都留痕（「只读挂载已确认完整 Windows…」/「…已按镜像名启发式放行…」两条文案）。实机双组：缺件镜像准备期硬拒 EXITCODE=1（8 分 17 秒，任务目录数 4 不变零写入零残留）、完整镜像通过（8 分 44 秒，任务 a2e4372a）；prepare-bootstrap.log 同一文件留有修复前后对照（22:27:33 ImageFile 错 → 22:49:34 WimFile: 对）。代价实测 8 分钟量级（挂载 6–7 分钟+卸载 1–2 分钟），旧预估 2–3 分钟差一个数量级；门禁日志权威位置是 H:\brwork\logs\prepare-bootstrap.log 而非任务目录 prepare.log；prlctl exec 的 cmd 会话里 if 括号块会整块不执行（两次栽坑）。产物 2,855,936 B / SHA256 731b1724。

V4 默认菜单名验收 + 门禁快速通道 v2.6.23 + P5 回归（07:45，Step-5-Preview）：V4（C 入口还原到非 C 卷、未起名）任务 189e0b2d success/100——新条目 description=Windows Backup（=镜像索引名）、default={6280fead} 指向新系统、哨兵全 absent、F: 6014-FBCE→4866-9770；已知缺口：CLI 默认名与索引名恰好同为「Windows Backup」，两条路径无法区分，需索引名≠默认值的镜像。v2.6.23（commit a85bb9f）性能分级：先 /Get-WimInfo 约 2 秒取名，name_looks_like_full_windows()（单测 5 正例 7 负例）判级，可疑才挂载——三组对照：完整 8 分 44 秒→29 秒、纯 PE（预安装环境）镜像 10 秒挂载后硬拒、缺件镜像 29 秒放行（行为变化：不再准备期硬拒，改由恢复期 P5 降级兜底，符合 10-16 用户裁定，代价是「提前 8 分钟发现」消失）。P5 回归（08:00 追加）：任务 be4352e8 走 QuickPass 28 秒 prepare，success/100，新系统 C: 4C8D-5E27（P5Regress）缺 reagentc，哨兵全消失；清理后 F: 38E7-CC30。产物 2,859,520 B / 21a371f1。

V1（A 入口还原 C: 活动系统盘）+ D4 修复首验（08:45，Step-5-Preview）：任务 b4cec607 success/100；快照 936c5f2f 全程唯一、验证通过即删。判据：哨兵 SENTINEL_GONE、序列号 48D5196E→8E2F-5FC1、已用 70.8 GiB ↔ capturedUsedBytes 76,903,538,688 B、default={2ef03cd4}={current}、菜单名「本次还原的 Windows」、恢复环境 Enabled @ partition6、EventID 1000 零新增。D4 修复（恢复环境独立恢复分区重接）首次实机验证：10-19 曾因 reconnect 把「恢复环境在独立恢复分区」当异常拒接致任务 failed；本轮按设备路径核对 partition6 的 winre.wim+boot.sdi 原件齐备后走独立分区重接，recoverysequence {264caa29}（与 10-19 手工 /enable 补回同一对象），双启动配置数据（BCD，Boot Configuration Data）存储补 recoverysequence/recoveryenabled，终检哈希不变。镜像「带回旧状态」效应：还原后 C: 回到镜像拍摄时刻（10-18 17:49）——包目录是 v2.6.19、任务 02138f14 复活弹待续跑框；还原后必须重部署当前版二进制（补部署 v2.6.24 CD401F92）+ abandon-task 收口。

V5（图形用户界面弹窗钉住项）实机验收，V 系列结清（09:15，Step-5-Preview）：任务 742cfd28 success/100，还原目标 V5Test，F: 38E7-CC30→387A-0D37。恢复环境进度窗按 M 开引导修复编辑器：对「当前默认启动项·不可取消」主系统按空格 → √ 保持（boot_menu.rs::toggle 对 is_pinned 直接返回 false），对还原中系统同样被拒；终态 default={75a727f5}（V5Test）、老系统 {2ef03cd4} 留在 displayorder、菜单名保持不变——零静默篡改。两层防护：交互层 toggle + 持久层 BootMenuPlan::validate（防绕过图形用户界面直接改 boot-menu-plan.json，freeze() 失败）；A4 裁定的静态说明与行尾标注到位。V1–V6 按新 default 规则全部实机结清；清理后 F: 3452-FE6C。

#38 A/B 入口+备份+预安装环境安装全链复跑六步通过（12:00，Step-5-Preview，v2.6.24）：零缺陷收口；快照 pre-38-A-restore {72ea9997}（④ 前拍覆盖④⑤，⑥ 已删）。②a 系统备份任务 0ee37f85：索引名「Windows 11 26200.9550 20261022」（31,957,169,494 B / capturedUsedBytes 77,348,761,600 / 674 秒 / imageSha256 974246c2）；命令行索引名默认「Windows Backup」（online_operation.rs:1259 与 main.rs:3233，与图形用户界面算法不同属既定设计），显式 --image-name 重捕闭环；在线备份必须显式 --compress fast|none。②b 数据备份「Windows (T:) 20261022」。③ B 入口在线还原 T:：镜像外 marker-pre/file1/nested 留存、镜像内 marker-post/sentinel-post 消失（精确覆盖），序列号 08835EE0→E880494B。④ A 入口还原 C: 任务 62c4902d：哨兵消失、序列号 8E2F5FC1→BCD4EAAB、default 指向新系统、三道确认链真实点击（提权 TCP agent 端口 9124）。⑤ 预安装环境双模式：内存 H:\BackupRestorePE + 硬盘 F:（D47D8E54），双启动项 winpe Yes，boot.sdi 取自 C:\WinPE_arm64\media\boot\boot.sdi。⑥ EventID 1000=28 条零新增、WerFault=0。工具层 5 坑：TaskStore root 语义、PowerShell 5.1 .Add ( 带空格全报错、@($null).Count=1 假阳性、常驻 TCP agent 旧版无 exec op、dir /b | head 管道提前关误判目录空。

wimlib --no-acls 概念验证与 DISM 对照（14:27，Step-5-Preview）：用户针对「覆盖式应用（取消格式化）打到已含 Windows 的卷被 DISM（部署映像服务与管理）拒绝 RestoreDirMetadata 0x80070005」指示**「换 wimlib --no-acls」。五实验闭环：E1 金丝雀 icacls 退出码 5（复现条件成立）；E2 DISM 覆盖应用意外成功**——完整 Windows 里 wimgapi 自行提权，合成访问控制列表（ACL，Access Control List）挡不住它；E3 wimlib apply --no-acls 71GiB/634,091 条目退出码 0（约 22 分钟）；E4 小镜像双点直接证明（文件逐字节落盘 + 安全描述符 sddlMatch=True 原样不动）；E5 禁用提权父进程下 wimlib 仍退出码 0（自带 SeRestore/SeBackup 提权——恢复环境路径的决定性性质）。三大发现：F1 10-16 的 DISM 失败需两条件同时成立（预安装环境/恢复环境上下文 + 原生 Setup 商店应用 ACL），在线态优先级 2 闸门可能过严但勿凭推论拆闸门；F2 本机原生商店应用保护已被「镜像回滚效应」洗掉（186 个 WindowsApps 子目录全变 SYSTEM 属主）——镜像回滚效应新副作用；F3 --no-acls 对 0x80070005 结构性免疫。工具坑：cmd 的 "F:\" 反斜杠转义引号吞 --no-acls、无 BOM 脚本按 GBK 解析、AdjustTokenPrivileges Pack=1 错位假成功、whoami /priv 状态列不可信（判权限只用 icacls 子进程探针）、同进程 .NET Set-Acl 与子进程行为不一致。wimlib 1.14.5 ARM64 官方二进制，GPLv3+/LGPLv2.1+ 独立进程调用属合法聚合。

#110 wimlib 覆盖式还原通道集成 v2.6.25（17:19，Step-5-Preview）：commit adfb298。11 个文件 + 2 个二进制入库（windows/wimlib-aarch64/：wimlib-imagex.exe 125,440 B sha fddb8c21、libwim-15.dll 432,640 B sha b34549c6；.gitignore 反否定防宽通配静默忽略）。TargetSpec.overlay_no_acl（serde default false 兜底）；新模块 wimlib_apply.rs（参数形态/二进制定位/执行封装 + 3 单测，缺失明确报错绝不静默回退 DISM）；三处硬拒改路由/确认（prepare 落盘标记、在线路由、图形用户界面 MB_OK→MB_YESNO 确认框明示「目录权限不还原、商店应用权限可能异常」）；OPTIONAL_RUNTIME_FILES 加两文件复用 sha256 注入链；build-win.sh 八联 SHA 校验。接手交接文档只列三处闸门，漏了第四处 apply 点（main.rs 恢复环境任务链，A 入口主链）——只改三处则 A 入口会在恢复环境撞 DISM 退出码 5，已补。实现期发现：概念验证的 "F:\" 引号坑在 run_program 通道不存在（windows_command::quote 标准 MSVCRT 转义，单测锁定）；pe_operation 三入口恒格式化，Request.overlay_no_acl 防御性预留 false。验证：macOS 单测 255 过（cli 211+core 44）、交叉编译产物 2,869,248 B / 1423beba、strings 13 处命中新代码；实机验收未跑。

#110 端到端实机通过收口 + 部署口径勘误（20:30，Step-5-Preview）：任务 ab95a79a success/100，prepare→resume 间隙 <1 秒；task.json 落盘 formatTarget:false + overlayNoAcl:true；恢复日志第 2,162,589 行 wimlib 行 apply E:\BRImages\br-2619-cur.wim 1 F:\ --no-acls、本会话零 DISM /Apply-Image 行；覆盖式判据与格式化路径相反：哨兵存活 + hosts 标记被镜像覆写（GONE_OVERWRITTEN）+ 序列号 D47D-8E54 不变；约 8 分钟、宿主磁盘零增长；恢复环境内 wimlib 哈希 = 仓库基线 fddb8c21（载荷注入链通）；三项判据零新增。环境恢复：bcdedit /default {077a3904} 重启验证 C:=BCD4-EAAB 原系统正常。口径勘误：实机部署唯一路径 = 虚拟机内 build-windows.ps1 -Deploy（虚拟机构建哈希 87ad04d6）；1423beba 是 macOS 交叉编译件不得用于发布验收。新坑：PowerShell 5.1 -Command 遇 && ParserError 且引号被剥离（统一走 cmd /d /c）；宿主空间靠停机优雅触发 TRIM 回收（102→68.8GiB，空闲 70→112GiB）；pe_safety.rs 旧硬拒文案成死代码。边界诚实声明：原生商店应用保护场景本机已无法构造、未复跑确认非偶发。

陈旧条目勘误 + pe_safety 死文案重构 v2.6.26 + 测试卷清理（21:16–22:30，Step-5-Preview）：21:16 源码核对证实 1719 文档把门禁缺陷列为「当前唯一大块」属陈旧条目——v2.6.22 已修并实机双组验证，v2.6.23 快速通道又把「noRE 将被硬拒」预期改为放行+P5 兜底（有意取代，非待验证）；windows_prepare.rs:1372 的 /ImageFile: 是 /Mount-Image 的合法参数非缺陷。v2.6.26（commit f051f3d）：overlay_restore_on_windows_volume_error（旧硬拒双语文案，发布件里从未输出、被优化器 GC）收敛为谓词 overlay_restore_on_windows_volume，四象限单测保留。22:2x 测试卷清理：BR-e2e-110 启动项 {b8d4ca6f} 及 recoverysequence {bc360467}/resumeobject {b8d4ca6e} 子对象已删（resumeobject 被 /delete /f 连带删、显式删报「找不到」属预期）；format F: 序列号 D47D-8E54→6A2D-BA03 释放 350GB，重启验证启动链正常；清理前 bcd-pre-cleanup-110.bcd 双保险。

wimlib「保留访问控制列表」概念验证（23:08，Step-5-Preview）：起因用户问「wimlib 完全替换 DISM 是否可行」。T1/T3 对照：特权禁用上下文（金丝雀 icacls 退出码 5）下 wimlib 不加 --no-acls 把 TrustedInstaller 保护目录安全描述符完整还原（小型镜像 SDDL 逐字节一致；加 --no-acls 则预设不动）。全量轮（23:29–23:55）：71GiB/634,091 条目退出码 0 零警告，判据样本 Clipchamp 包目录 + AppxManifest.xml 与 C: 参考逐字节一致（含 WIN://SYSAPPID 条件 ACE + S-1-15-3-* app package SID + TrustedInstaller FA 的原生商店应用 ACL）；pass1（--no-acls 基线）安全描述符=裸默认 O:BA，两遍结果可区分。G1：wimlib 自带提权同时覆盖写入与安全描述符还原——DISM 失败的本质就是恢复环境里 wimgapi 不提权；G2：--no-acls 从「功能必需」重定位为「双保险+行为确定」；G3：4 条未测边界覆盖 3 条，剩「恢复环境内实机」一道（属端到端范畴）。T3 首轮取证伪影：取证时父进程仍在禁用态，SYSTEM 列不了无 SYSTEM ACE 的目录致 Test-Path 假阴——早间 poc-final-proof.ps1 已处理过该坑、本轮新脚本漏改，教训复犯。用户随即拍板「保留访问控制列表」产品化（v2.6.27，23:55 启动、跨夜端到端通过）。

教训与经验

• prepare 后要秒级 resume：载荷消失只在 prepare 后约 3 分钟的窗口出现过一次；5 秒内 resume + 每 3.1 秒监控即可拿到「载荷全程稳定」的反证，把「离奇消失」从代码缺陷降级为外部因素——阻塞排查时先做对照实验再深挖。
• 出生即缺陷靠实机对照暴露：/ImageFile: 参数错让权威门禁自 v2.4.2 起静默失效且降级无痕，10-13「VHD 致 87」归因被推翻；修复必须同时补「通过/降级都留痕」+ 纯函数单测锁参数，并在同一日志文件里留下前后对照。
• 权威判据的耗时先实测再定方案：32GB 只读挂载实测 6–7 分钟（旧预估 2–3 分钟差一个数量级）→ 催生性能分级：/Get-WimInfo 2 秒取名、可疑才挂载，8 分 44 秒→29 秒（18 倍），代价（改名镜像绕过准备期）由恢复期注册前置检查兜底。
• DISM 覆盖式失败需两条件同时成立：预安装环境/恢复环境上下文（wimgapi 提权不生效）+ 原生 Setup 商店应用 ACL；完整 Windows 里连合成限制性 ACL 都能被 wimgapi 提权改写——勿在完整 Windows 里复现成功就拆在线态闸门。
• wimlib 自带 SeRestore/SeBackup 提权是覆盖式通道成立的第一性原因：禁用提权父进程下写入与安全描述符还原双双成功；--no-acls 只是双保险+行为确定，并非功能必需——据此才有 v2.6.27「保留访问控制列表」演进。
• 覆盖式与格式化路径的判据相反：覆盖式铁证 = 哨兵存活 + 序列号不变 + 镜像内文件被覆写；照搬「哨兵消失+序列号变化」会把对的判成错的（该口径已写进 1719/2030 文档勘误）。
• 镜像回滚效应有两个副作用：①还原系统盘连程序部署位一起回滚（v2.6.19 复活、可续跑任务复活弹框）——还原后必须重部署当前版二进制并 abandon 收口；②format+apply 把原生 TrustedInstaller 商店应用保护永久洗掉（186 个目录变 SYSTEM 属主）——本机已无法构造原生 ACL 场景。
• 判据侧陷阱清单：recovery_fault::checkpoint 默认不落日志不能当判据；恢复环境主日志在镜像同目录 Recovery.log 而非任务目录；提权自测只用 icacls 子进程探针（whoami /priv 与同进程 Set-Acl 都不可信）；取证本身要在解除禁用态后做，否则 Test-Path 假阴（T3 教训复犯说明教训要进脚本模板，只写文档会再踩）。
• 交接/待办清单必须经源码核对：Hy3 交接漏了第四处 apply 点（main.rs 恢复环境链），1719 待办把已修的门禁缺陷当「唯一大块」——集成与排期以源码现状为准，文档清单会过时或遗漏。

下次接手的注意

• v2.6.27「保留访问控制列表」产品化已在当晚 23:55 拍板启动（wimlib_args 去 --no-acls、apply_no_acl 改名 apply_overlay、确认框文案改「镜像目录访问控制列表/属主完整还原」），跨夜（10-23 02:21）端到端通过：任务 356f0b55 success/100，ACL 8/8 逐字节一致。
• 待用户拍板：#110 是否复跑一次确认非偶发；32GB 副本 br-2619-noRE.wim 删除（已符合条件未删）；H:\brwork\tasks 证据目录（771b3ee2/79445787/ab95a79a）保留边界；TaskStore 任务目录是否搬离程序目录 C:（10-18 问过，动前先问）；包目录 3 个解析失败任务清理。
• 零星缺口：B 键在恢复环境/预安装环境内整链未跑（在线/离线 UI 层已双路径）；wimlib 安全描述符还原失败行为未构造（本机无法造，失败即整体退出码非 0、不静默降级）；启动配置数据历史恢复环境/预安装环境 osloader 条目备案待清理。
• V4 已知物料缺口：需一个索引名 ≠「Windows Backup」的镜像，才能严格区分「用默认名」与「读索引名」两条路径。
• 铁律提醒：实机部署唯一路径 = 虚拟机内 build-windows.ps1 -Deploy（macOS 侧 build-win.sh --deploy 只部署交叉编译件）；恢复环境主日志在镜像同目录 Recovery.log；门禁日志在 prepare-bootstrap.log。