fix: expand g14 registry gc retention

docs/reference/gc.md

@@ -44,25 +44,29 @@ UniDesk 的磁盘治理入口是 `bun scripts/cli.ts gc ...`。该入口用于
 
 ## HWLAB Registry Retention
 
-G14 HWLAB registry 清理必须显式使用 `--include-hwlab-registry`，默认 `gc remote G14 plan` 不进入 registry。策略必须保守，不能只留 latest。
+G14 HWLAB registry 清理必须显式使用 `--include-hwlab-registry`，默认 `gc remote G14 plan` 不进入 registry。策略必须保守，不能只留 latest，也不能只删除 tag link 后误判已经释放空间。
 
 默认保留规则：
 
 | 保留项 | 规则 |
 |---|---|
 | 当前 workload 引用 | 保留所有当前 k3s workload 使用的 tag ref 和 digest ref |
-| 近期 tag | 保留 `--registry-min-age-hours` 内全部 tag，默认 48 小时，最小 24 小时 |
-| 每 repo 最新 tag | 每个业务 repo 至少保留 `--registry-keep-per-repo` 个最新 tag，默认 20，最小 10 |
+| digest closure | 从当前 workload、保留 tag、protected/base/非业务 repo 出发，保留 manifest config/layer/manifest-list 的 digest 闭包 |
+| 近期 tag | 保留 `--registry-min-age-hours` 内全部 tag，默认 48 小时，可显式设为 0 |
+| 每 repo 最新 tag | 每个业务 repo 至少保留 `--registry-keep-per-repo` 个最新 tag，默认 20，最小 1 |
 | cache/base/protected tag | 保留 cache repo、`latest`、基础镜像 tag 和显式 protected tag |
 | 非业务 repo | 默认不删除非 `hwlab/hwlab-*` 的 commit-like tag |
 
-删除范围只允许 commit-like tag，并且仅当对应 manifest digest 不再被任何保留 tag 引用时，才通过 registry API 删除 manifest。随后必须缩容 registry pod，运行官方 `registry garbage-collect`，再恢复 registry。`--registry-gc-only` 只用于中断恢复或人工维护窗口收尾：它不删除任何 tag，只运行官方 GC。
+删除范围包括两类：不在保留集内的 commit-like tag，以及 `hwlab/hwlab-*` / `hwlab/cache/hwlab-*` repo 内不在保留 digest closure 的 stale `_manifests/revisions/sha256/<digest>`。执行时先在 registry 在线状态下通过 API 删除 manifest，再缩容 registry pod，删除遗留 tag/revision 目录，运行官方 `registry garbage-collect`，最后恢复 registry。`--registry-gc-only` 只用于中断恢复或人工维护窗口收尾：它不删除任何 tag 或 revision，只运行官方 GC。
+
+BuildKit cache repo 的历史 `latest` 写入会留下大量 untagged manifest revision；只删除 tag 通常只能释放少量 manifest blob，无法释放旧 cache layer。需要大幅降低 `/var/lib/hwlab/registry` 时，必须以 plan 输出的 `deleteRevisions`、`protectedDigestClosure` 和 official GC 后的 `diskAfterBytes` 判断是否真正生效。
 
 Registry 执行必须以远端异步 job 完成，并具备以下维护保护：
 
 - 暂停 G14/v0.2 branch poller CronJob。
 - 等待 hwlab-ci PipelineRun、TaskRun 和 Job 空闲。
 - 通过 registry API 删除 manifest 时 registry 必须仍在线。
+- registry 下线后只能删除通过 plan 判定的 tag/revision 目录；不得直接删除 blob 目录。
 - 缩容 registry 后运行官方 `registry:2.8.3` garbage-collect pod。
 - finally 阶段删除 GC pod、恢复 registry replicas、等待 rollout、恢复 CronJob suspend 状态。
 - 状态查询使用 `gc remote G14 status --job-id <id>`，不使用长 SSH 会话等待。
@@ -93,7 +97,7 @@ G14 当前只有一个本机 k3s cluster；空间归因时不要把 `hwlab-dev`
 |---|---|---|
 | Host path | `du -x` 按 `/var/lib/*`、`/root`、`/usr` 等目录统计 | 判断根盘主要压力源 |
 | k3s namespace/PVC | `kubectl get pv,pvc,pod -A -o json` 结合 local-path PV host path | 把可归属数据映射到 namespace/workload |
-| Registry repo/tag | registry v2 repository/tag link 与 blob manifest 解析 | 判断镜像历史 tag 与共享 layer 的贡献 |
+| Registry repo/tag/revision | registry v2 repository/tag link、manifest revision 与 blob manifest 解析 | 判断镜像历史 tag、cache revision 与共享 layer 的贡献 |
 
 当前 G14 高水位的长期基线分布如下，后续诊断出现同类量级时优先按同一顺序处理：
 
@@ -140,7 +144,7 @@ bun scripts/cli.ts ssh G14 script -- 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubec
 bun scripts/cli.ts ssh G14 script -- 'find /var/lib/hwlab/registry/docker/registry/v2/repositories -path "*/_manifests/tags/*/current/link" -type f | wc -l'
 ```
 
-需要深挖 registry 时，报告字段至少包括 repo、tag count、latest tags、unique blob bytes 和 shared blob bytes。需要深挖 k3s runtime 时，报告字段至少包括 namespace/PVC、PV host path、owner workload、PVC 实占、k3s containerd snapshots/blobs 总量。不要把 `/var/lib/kubelet/pods` 与 `/var/lib/rancher/k3s/storage` 简单相加，因为 kubelet pod 目录可能包含 PVC bind mount 或 runtime 元数据，存在重复计数风险。
+需要深挖 registry 时，报告字段至少包括 repo、tag count、manifest revision count、latest tags、protected digest closure、unique blob bytes 和 shared blob bytes。需要深挖 k3s runtime 时，报告字段至少包括 namespace/PVC、PV host path、owner workload、PVC 实占、k3s containerd snapshots/blobs 总量。不要把 `/var/lib/kubelet/pods` 与 `/var/lib/rancher/k3s/storage` 简单相加，因为 kubelet pod 目录可能包含 PVC bind mount 或 runtime 元数据，存在重复计数风险。
 
 ## Validation Checklist