docs: capture JD01 GC post-task lessons
This commit is contained in:
Codex
@@ -11,6 +11,7 @@ UniDesk 的磁盘治理入口是 `bun scripts/cli.ts gc ...`。该入口用于
|
||||
- `gc policy plan|install`：从 `config/unidesk-cli.yaml#gc.policyTimer` 渲染或安装低风险长期策略，例如 journald cap、每日 allowlisted 文件/tmp 清理 timer、VPN 诊断 pcap retention、`.state` artifact retention 和 VS Code CachedExtensionVSIXs 下载缓存 retention。
|
||||
- `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 或其他长清理。
|
||||
- `--include-tool-caches`：本机和远端都必须是显式 opt-in，只清理固定 allowlist 的可重建 npm/npx/Bun 缓存；不得扩大成清理 `~/.npm`、`~/.bun`、`node_modules`、auth/config 或运行面依赖。
|
||||
|
||||
所有成功和失败输出都必须是 JSON。`plan` 必须标记 `dryRun=true`、`mutation=false`；`run` 必须要求 `--confirm` 并报告 `diskBefore`、`diskAfter`、`summary`、`results` 和 `protected`。远端 GC 可用 `--target-use-percent N` 显式表达目标根盘水位；`summary.target` 必须给出目标所需释放量、候选估算、预计水位、缺口和 `safeStop` 决策，避免靠人工心算判断是否应该继续扩大清理范围。
|
||||
|
||||
@@ -98,6 +99,10 @@ JD01 Chrome 内存治理应优先管理 observer runner 生命周期，而不是
|
||||
|
||||
JD01 plan 和 status 应同时披露内存压力摘要：active observer 数、Chrome process 数、Chrome RSS、stale observer 数、state root artifact bytes、last cleanup、last stop failure 和 drill-down 命令。GC run 只能执行 plan 中明确标记 safe 的低风险动作，例如 apt/journal/tmp allowlist、dead web-observe raw artifact retention，以及通过受控 observe stop 处理 stale observer；对 PVC、k3s runtime、containerd、Docker volume、Secret 和 auth/config 状态一律保持 protected 或转交专用 retention 入口。
|
||||
|
||||
JD01 的 npm/npx/Bun 缓存可作为中低风险边界候选，但必须通过 `gc remote JD01 plan|run --include-tool-caches` 显式启用。该入口只允许固定 allowlist 的可重建缓存目录，并在执行前重新校验路径、非 symlink 和 allowlist；它不清理 `node_modules`、用户配置、认证状态、k3s/containerd、PVC、Docker image/container/volume 或 GitOps 运行面对象。
|
||||
|
||||
Web probe sentinel 的 `quick-verify`、Playwright 或浏览器验证不得作为 CI/CD 发布 gate 自动周期触发。若某个 sentinel 需要周期 quick-verify，必须在 YAML 中显式 opt-in cadence scheduler；默认发布验证只看配置的 health endpoint，quick-verify 只作为人工或独立 post-deploy evidence 入口。这样避免 CI/CD 周期性重启 observer/Chrome 并重新制造内存和 artifact 增长。
|
||||
|
||||
## HWLAB Registry Retention
|
||||
|
||||
G14 HWLAB registry 清理必须显式使用 `--include-hwlab-registry`，默认 `gc remote G14 plan` 不进入 registry。策略必须保守，不能只留 latest，也不能只删除 tag link 后误判已经释放空间。
|
||||
@@ -188,6 +193,8 @@ G14 进入 50% 这类维护窗口目标时，标准顺序是：
|
||||
4. 再次运行 `gc remote G14 plan --target-use-percent <N> --include-hwlab-registry ...`。
|
||||
5. 若只剩 KiB 级低风险候选且 `safeStop=true`，停止自动清理，不得为了命中百分比目标手工删除受保护目录。
|
||||
|
||||
维护窗口目标接近整数边界时，验收必须同时报告 `df -h /` 和 `df -B1 /`。`summary.target` 使用字节计算，`df` 使用整数展示，二者在 49/50 这类边界可能看起来不一致；收口时以最终 `diskAfter.usePercent`、`df -h` 展示和字节视图共同说明，不得因为四舍五入差异绕过 protected boundary。
|
||||
|
||||
## G14 Space Attribution Baseline
|
||||
|
||||
G14 当前只有一个本机 k3s cluster；空间归因时不要把 `hwlab-dev`、`hwlab-prod`、`hwlab-v02` 理解成独立 cluster，它们是同一 k3s 上的 namespace/runtime slice。长期诊断应按三层归因：
|
||||
@@ -280,6 +287,16 @@ bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs --lane all --lim
|
||||
|
||||
验收结论至少包含：根盘水位、`DiskPressure=False`、registry readiness/API、AgentRun `aligned=true`、HWLAB v0.2 `state=aligned`、active PipelineRun 数，以及 remaining low-risk candidates / safe-stop 决策。若目标百分比未达到但 `safeStop=true`，必须写清剩余缺口和下一类策略选择，不得把未执行的高风险清理伪装成已完成。
|
||||
|
||||
JD01 GC 或 Chrome/observer 压力收口还必须补充：
|
||||
|
||||
```bash
|
||||
trans JD01 sh -- 'df -h /; df -B1 /; free -h'
|
||||
trans JD01 sh -- 'ps -eo pid,rss,comm,args | awk '\''BEGIN{IGNORECASE=1} /chrome|chromium|web-probe observe/ && !/awk/ {print}'\'' || true'
|
||||
bun scripts/cli.ts web-probe sentinel control-plane status --node JD01 --lane v03 --sentinel <id>
|
||||
```
|
||||
|
||||
若本次变更涉及关闭 cadence scheduler，还应确认 GitOps objects 不再包含 quick-verify CronJob，并确认 runtime/Argo/health endpoint 仍为 ready。
|
||||
|
||||
## Long-Term Anti-Bloat Plan
|
||||
|
||||
| 措施 | 默认策略 | 预期收益 |
|
||||
@@ -288,6 +305,7 @@ bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs --lane all --lim
|
||||
| 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 |
|
||||
| Remote tool cache opt-in | `gc remote ... --include-tool-caches` 只清理固定 allowlist 的 npm/npx/Bun 可重建缓存 | 在不触碰运行面状态的前提下释放数百 MiB 级边界空间 |
|
||||
| VS Code CachedExtensionVSIXs retention | 只清理可重建 extension VSIX 下载缓存，不触碰已安装扩展/server/user data | 防止远程 VS Code 扩展升级缓存长期堆积，收益通常为数百 MiB |
|
||||
| Core dump limits | 限制 dump 大小或按 allowlist 删除实际分配块 | 防止 crash dump 污染观测；sparse dump 不应被高估 |
|
||||
| Containerd image audit | 定期只读报告 runtime image cache 构成 | 为维护窗口 prune 提供证据，不默认删除 |
|
||||
|
||||
Reference in New Issue
Block a user