pikasTech-unidesk/docs/reference/gc.md

Disk GC And Retention Reference

UniDesk 的磁盘治理入口是 bun scripts/cli.ts gc ...。该入口用于短期一次性止血和低风险防膨胀策略，所有清理动作都必须先有结构化 plan，再通过显式确认执行。GC 不是通用 rm -rf 或原生命令集合；当目标磁盘水位无法在保护边界内下降到阈值以下时，应停止并升级为 retention/capacity 决策，而不是扩大清理范围。

Command Boundary

• gc plan：只读生成主 server 清理候选、估算收益、风险等级、保护对象和数据库诊断摘要。
• gc run --confirm：只执行当前 plan 可见候选页，默认不执行分页隐藏候选；用 --limit、--result-limit、--full|--raw 控制披露和执行范围。
• gc policy plan|install：渲染或安装低风险长期策略，例如 journald cap 和每日 allowlisted 文件/tmp 清理 timer。
• gc db-trace plan|run --confirm --before-date YYYY-MM-DD --vacuum-full：显式 trace 遥测留存入口；涉及数据库重写时按维护窗口处理。
• gc remote <providerId> plan|run --confirm|status --job-id <id>：通过 UniDesk SSH 透传在 provider host 上执行受控 GC。远端长任务必须使用异步 job 和 status 短查询，不应让单次 SSH 等待完整 registry GC 或其他长清理。

所有成功和失败输出都必须是 JSON。plan 必须标记 dryRun=true、mutation=false；run 必须要求 --confirm 并报告 diskBefore、diskAfter、summary、results 和 protected。远端 GC 可用 --target-use-percent N 显式表达目标根盘水位；summary.target 必须给出目标所需释放量、候选估算、预计水位、缺口和 safeStop 决策，避免靠人工心算判断是否应该继续扩大清理范围。

Protected Data

默认 GC 不得删除或 prune 以下对象：

对象	保护原因
PostgreSQL PGDATA	数据库权威状态，必须走备份、留存或迁移流程
Docker image/container/volume	运行面和发布真相可能依赖旧镜像或 volume
Baidu Netdisk staging/backups	备份链路状态和可重建缓存边界需单独判定
D601 registry storage	artifact registry retention 需使用专门入口
/var/lib/rancher/k3s 与 /var/lib/rancher/k3s/storage	k3s 控制面、containerd 状态和 local-path PVC 数据
/var/lib/kubelet、/var/lib/containerd	kubelet/runtime 状态和可能被 workload 复用的 image cache
HWLAB 固定 workspaces	/root/hwlab、/root/hwlab-v02、/root/agentrun 是 source/runtime 约束的一部分
Kubernetes workload、Secret、PVC、PV、Argo、Tekton 对象	必须通过对应运行面 retention 子命令或 GitOps/CI 控制入口处理

如果需要触碰上表对象，必须先补高层 UniDesk CLI 子命令、dry-run 计划、保护对象、验证命令和失败分类；不能把原生 kubectl、docker prune、crictl rmi 或手写 registry shell 作为长期流程。

Remote G14 Policy

gc remote G14 ... 必须先确认目标是 G14 原生 k3s 节点，且 preflight 中节点名包含 ubuntu-rog-zephyrus-g14-ga401iv-ga401iv。G14 默认候选只允许：

• systemd journal vacuum 到目标上限。
• Docker json-file 日志截断。
• Docker BuildKit cache prune，默认只清理超过 --build-cache-until 的 cache。
• apt archive clean。
• allowlisted /tmp 诊断目录删除。
• 受限 core dump 删除。

受限 core dump 只匹配 /root/unidesk/core.<pid> 普通文件。执行前必须重新校验路径 allowlist、Git 未跟踪、非 symlink、无 fuser 活跃引用。估算收益必须按实际分配块数计算，并可另行披露 apparentSizeBytes；不能把 sparse core dump 的表观大小当成可回收磁盘空间。

HWLAB Registry Retention

G14 HWLAB registry 清理必须显式使用 --include-hwlab-registry，默认 gc remote G14 plan 不进入 registry。策略必须保守，不能只留 latest，也不能只删除 tag link 后误判已经释放空间。

默认保留规则：

保留项	规则
当前 workload 引用	保留所有当前 k3s workload 使用的 tag ref 和 digest ref
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，以及 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；目标集群中某条 lane 暂无 CronJob 时记录为 absent，不视为失败。
• 暂停 poller 后再等待 hwlab-ci PipelineRun、TaskRun 和 Job 空闲；不能在暂停前因为 active CI 直接拒绝，否则 poller 竞态会导致 maintenance 反复失败。
• 通过 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 会话等待。
• gc remote 的 stdout 是有界 JSON：当 --full 或大量候选导致结果过大时，完整结果会写入远端 /tmp/unidesk-gc-remote/jobs/<job>.json，stdout 只返回摘要、jobId、statePath 和 statusCommand，再用 gc remote G14 status --job-id <job> 渐进查询，避免输出爆炸被误判为 JSON 失败。

G14 CI Workspace Retention

G14 的 Tekton workspace retention 不能通过原生 kubectl delete、直接删除 /var/lib/rancher/k3s/storage 或手工清 PV host path 完成。所有完成态 PipelineRun workspace 清理都必须走对应高层 UniDesk CLI，先 dry-run 输出候选和保护对象，再 confirm 执行。

AgentRun v0.1 使用 agentrun-ci namespace：

bun scripts/cli.ts agentrun v01 control-plane cleanup-runs --min-age-minutes 30 --limit 200 --dry-run
bun scripts/cli.ts agentrun v01 control-plane cleanup-runs --min-age-minutes 30 --limit 200 --confirm
bun scripts/cli.ts agentrun v01 control-plane cleanup-released-pvs --limit 200 --dry-run
bun scripts/cli.ts agentrun v01 control-plane cleanup-released-pvs --limit 200 --confirm

HWLAB 使用 hwlab-ci namespace：

bun scripts/cli.ts hwlab g14 control-plane cleanup-runs --lane v02 --min-age-minutes 30 --limit 200 --dry-run
bun scripts/cli.ts hwlab g14 control-plane cleanup-runs --lane v02 --min-age-minutes 30 --limit 200 --confirm
bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs --lane all --limit 200 --dry-run
bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs --lane all --limit 200 --confirm

Retention 入口的长期合同：

• 默认只选择 Succeeded/Failed 的完成态 PipelineRun，且必须达到 --min-age-minutes。
• 默认保护每条 lane 或前缀下最新完成的 PipelineRun，保留当前 CI/CD 状态证据；只有显式定点目标才允许清理最新证据。
• dry-run 必须披露候选 PipelineRun、owned PVC、active mount 保护、预估可回收空间或可回收对象数，以及 confirm 命令。
• confirm 首先删除 PipelineRun，让 Tekton ownerRef 释放临时 PVC；随后用 cleanup-released-pvs 处理 local-path 未自动删除的 Released PV。
• cleanup-released-pvs 只能选择 local-path、Delete reclaim policy、目标 CI namespace 的 Released PV；不得触碰业务 namespace、runtime PVC、Secret、registry storage 或 GitOps desired state。

CI workspace retention 是 registry retention 之前的低风险步骤。若它清不出足够空间，不能扩大到 raw PV/path 删除；应继续进入 registry retention plan，或进入 safe-stop 决策。

Safe Stop Line

磁盘目标可以设为 <70% 或维护窗口临时目标如 <50%，但安全边界优先级高于目标百分比。目标必须直接传给 CLI，使输出带有可机读缺口：

bun scripts/cli.ts gc remote G14 plan --target-use-percent 50 --limit 20
bun scripts/cli.ts gc remote G14 plan --target-use-percent 50 --include-hwlab-registry --limit 20

当 summary.target.safeStop=true、state 为 shortfall 或 safe-stop-no-meaningful-candidates 时，应停止自动清理并提交决策表。若默认 plan 和 registry plan 都无法覆盖目标缺口，剩余空间通常位于 registry 保留集、k3s runtime、containerd image cache 或 PVC 数据中。继续下降需要显式选择以下更高风险方案之一：

方案	风险	需要的前置决策
降低 registry 每 repo 保留数或缩短近期 tag 窗口	可能影响切旧 tag 回滚	明确旧 tag 回滚窗口和服务 owner 接受标准
containerd/k3s image cache prune	可能触发 workload 重新拉镜像或旧镜像缺失	registry 健康、镜像可拉取性和维护窗口
PVC/runtime 数据 retention	可能删除业务状态或 CI 证据	业务 owner 确认数据类别和留存期限
rsyslog 文件日志压缩/截断	可能丢失一线故障证据	明确日志留存窗口，先补受控 CLI/logrotate 策略
source worktree/cache TTL	可能删除并行任务上下文或本地依赖缓存	worktree owner、分支状态、dirty 状态和可重建性判定
扩容磁盘	低运行风险	节点容量预算和停机/在线扩容方式

G14 进入 50% 这类维护窗口目标时，标准顺序是：

1. gc remote G14 plan --target-use-percent <N> 取得默认低风险候选和缺口。
2. 运行 AgentRun/HWLAB CI workspace retention，并二次处理 Released PV。
3. 使用 --include-hwlab-registry 规划 registry retention；默认保守保留，维护窗口内可显式把 --registry-keep-per-repo 降到 1，但必须保留当前 workload refs 和 digest closure。
4. 再次运行 gc remote G14 plan --target-use-percent <N> --include-hwlab-registry ...。
5. 若只剩 KiB 级低风险候选且 safeStop=true，停止自动清理，不得为了命中百分比目标手工删除受保护目录。

G14 Space Attribution Baseline

G14 当前只有一个本机 k3s cluster；空间归因时不要把 hwlab-dev、hwlab-prod、hwlab-v02 理解成独立 cluster，它们是同一 k3s 上的 namespace/runtime slice。长期诊断应按三层归因：

层级	归因方式	判读口径
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/revision	registry v2 repository/tag link、manifest revision 与 blob manifest 解析	判断镜像历史 tag、cache revision 与共享 layer 的贡献

G14 高水位的长期基线分布如下，后续诊断出现同类量级时优先按同一顺序处理。registry 和 CI workspace retention 后，空间压力通常从 /var/lib/hwlab/registry 转移到 k3s containerd snapshot/content、local-path PVC、host containerd、rsyslog 文件日志和 source worktree/cache；这些都属于受保护或需策略化处理的运行面，不能为了达到百分比目标直接删除目录。

类别	路径	典型量级	归因说明
HWLAB local registry	/var/lib/hwlab/registry	高水位约 60GiB；强 retention 后约十几 GiB	最大头；按 repo/tag/revision retention 管理，不能直接删 blob
k3s runtime	/var/lib/rancher/k3s	高水位约 45-55GiB；清理后约 28-35GiB	embedded containerd、local-path PVC 和 k3s server/db
k3s containerd snapshots	/var/lib/rancher/k3s/agent/containerd/.../snapshots	高水位约 30-40GiB；清理后约十几 GiB	workload image layer/snapshot cache，共享占用，不能直接按单 pod 删除
k3s containerd blobs	/var/lib/rancher/k3s/agent/containerd/.../blobs	高水位约 8-12GiB；清理后约数 GiB	k3s image content store，共享占用
k3s local-path PVC	/var/lib/rancher/k3s/storage	高水位约 8-10GiB；CI retention 后约 6-8GiB	可按 namespace/PVC 归因，只能通过运行面 retention 入口清理
host containerd	/var/lib/containerd	约 9-12GiB	k3s 外的 host/containerd cache，默认不由 remote GC prune
root workspaces/cache	/root	约 2-8GiB	HWLAB/v0.2 worktree、npm/bun/cache 等；worktree TTL 需 owner/dirty 判定
logs	/var/log	约 1-3GiB	journald 可由 GC cap，rsyslog 文件需受控 logrotate/压缩策略，pod logs 通常较小

PVC 的长期判读口径：

Namespace	典型占用	主要来源
hwlab-ci	约 2GiB	完成态 Tekton TaskRun workspace PVC；单个 PVC 通常约 0.24GiB
hwlab-dev	数百 MiB	hwlab-code-agent-workspace 与 dev Postgres
hwlab-prod	数百 MiB	hwlab-code-agent-workspace
hwlab-v02	数百 MiB	hwlab-code-agent-workspace 与 v0.2 Postgres

Registry 的长期判读口径：

Repo 类型	典型形态	说明
hwlab/hwlab-cloud-api	tag 数可超过 20，unique blob 数 GiB	最大业务 repo，优先观察 tag 增长
hwlab/hwlab-agent-*、hwlab/hwlab-cloud-web、hwlab/hwlab-gateway*	每 repo 保留约 20 tag 时通常各占数 GiB	多服务并行构建导致 registry 线性增长
hwlab/cache/*	tag 少但共享 layer 多	不能按 expanded size 简单相加
base/protected image	tag 少，占用低到中等	保留用于构建和运行回滚

Registry 报告必须区分 uniqueBlobBytes 和 sharedBlobBytes。多个 repo/tag 复用同一 layer 时，expanded tag size 会重复计算；判断可回收空间应以 official registry GC 后的根目录变化为准。

Diagnosis Commands

G14 空间审计默认只读。需要报告时优先采集以下摘要，避免全量 dump 大 JSON：

trans G14 script -- 'df -h / | tail -1'
trans G14 script -- 'du -xh -d 1 / /var /var/lib /root 2>/dev/null | sort -h | tail -40'
trans G14 script -- 'du -xh -d 2 /var/lib/rancher/k3s /var/lib/containerd /var/log 2>/dev/null | sort -h | tail -80'
trans G14 script -- 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get pv,pvc,pod -A -o wide'
trans G14 script -- 'find /var/lib/hwlab/registry/docker/registry/v2/repositories -path "*/_manifests/tags/*/current/link" -type f | wc -l'

需要深挖 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 元数据，存在重复计数风险。

需要深挖日志和 worktree 时，默认只读报告，不直接清理：

trans G14 script -- 'du -xh -d 1 /var/log 2>/dev/null | sort -h | tail -40'
trans G14 script -- 'du -xh -d 2 /root/hwlab-v02/.worktree 2>/dev/null | sort -h | tail -60'

rsyslog 文件日志不属于当前 gc remote 默认可变更对象。若 /var/log/syslog*、/var/log/kern.log* 或同类文件成为 50% 目标的最后缺口，应先新增受控 logrotate/压缩/截断 CLI，并在输出中披露保留 tail、压缩对象、释放估算和失败恢复；禁止直接 truncate 或删除日志文件作为长期流程。/root/hwlab-v02/.worktree 只能在明确 owner、branch、dirty 状态和可重建性后清理，不能按目录大小直接删除。

Validation Checklist

G14 GC 后必须验证：

trans G14 script -- 'df -h / | tail -1'
trans G14 script -- 'curl -fsS http://127.0.0.1:5000/v2/ >/dev/null && echo ok'
trans G14 script -- 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-ci get deploy hwlab-registry'
trans G14 script -- 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-ci get cronjob hwlab-g14-branch-poller -o custom-columns=NAME:.metadata.name,SUSPEND:.spec.suspend --no-headers && ! KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-ci get cronjob hwlab-v02-branch-poller >/dev/null 2>&1'

DEV workload 验证应检查非零副本 workload 是否 ready；0/0 的显式停用 deployment 不应误报为事故。registry tag 数只作为辅证，不能替代 workload ref 保护和 registry API 健康。

同时必须用高层 CLI 验证受影响运行面仍对齐：

bun scripts/cli.ts agentrun v01 control-plane status
bun scripts/cli.ts hwlab g14 control-plane status --lane v02
bun scripts/cli.ts agentrun v01 control-plane cleanup-runs --min-age-minutes 30 --limit 200 --dry-run
bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs --lane all --limit 200 --dry-run

验收结论至少包含：根盘水位、DiskPressure=False、registry readiness/API、AgentRun aligned=true、HWLAB v0.2 state=aligned、active PipelineRun 数，以及 remaining low-risk candidates / safe-stop 决策。若目标百分比未达到但 safeStop=true，必须写清剩余缺口和下一类策略选择，不得把未执行的高风险清理伪装成已完成。

Long-Term Anti-Bloat Plan

措施	默认策略	预期收益
Registry conservative retention	workload refs + 48h tag + 每 repo 20 tag + official GC	高构建频率下通常是主要收益，可释放十几到几十 GiB
CI tag growth cap	每个 service 对 commit tag 增长设置上限并进入 GC plan	防止 registry 每周持续膨胀
Tekton/Pipeline retention	完成态 PipelineRun/TaskRun/Job 按留存期清理	释放少量空间，降低 API 噪声
Log/journal cap	journald 上限、文件日志轮转、Docker json log truncate	稳定防止日志膨胀，收益通常为数百 MiB 到数 GiB
Core dump limits	限制 dump 大小或按 allowlist 删除实际分配块	防止 crash dump 污染观测；sparse dump 不应被高估
Containerd image audit	定期只读报告 runtime image cache 构成	为维护窗口 prune 提供证据，不默认删除
Worktree TTL audit	报告 .worktree owner、branch、dirty 和 node_modules/cache 占用	为安全清理并行任务 scratch 提供证据
Capacity trigger	达到高水位时输出 safe-stop 决策表	避免为了百分比目标破坏运行面