From f14ce36019fa30752afed1805e73f67d2d77610e Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 29 May 2026 01:54:57 +0000 Subject: [PATCH] docs: add disk gc retention reference --- AGENTS.md | 3 +- docs/reference/cli.md | 2 +- docs/reference/gc.md | 112 ++++++++++++++++++++++++++++++++++++++++++ scripts/src/help.ts | 2 +- 4 files changed, 116 insertions(+), 3 deletions(-) create mode 100644 docs/reference/gc.md diff --git a/AGENTS.md b/AGENTS.md index 1774739b..fc92d764 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -146,7 +146,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `bun scripts/cli.ts server swap status|ensure [--path /swapfile] [--size 2GiB] [--dry-run]`：以 JSON 查看或幂等创建主 server swapfile，`ensure` 输出 before/after、动作、持久化状态和 degraded/failed 详情，规则见 `docs/reference/deployment.md`。 - `bun scripts/cli.ts server logs [--tail-bytes N]`：分页返回文件日志与 Docker 日志尾部并带截断元数据，日志规则见 `docs/reference/observability.md`。 - `bun scripts/cli.ts server cleanup plan [--min-age-hours N] [--limit N]`：只读/干跑生成主 server Docker 镜像清理计划，默认只列出至少 24 小时前创建的非保护镜像，输出 active/protected images、stale candidates、预计释放空间、风险等级和必须人工确认的 `docker image rm` 命令；禁止默认删除、禁止 prune、禁止触碰 database volume、registry storage 或 Baidu Netdisk 状态。 -- `bun scripts/cli.ts gc plan|run|db-trace|policy|remote`：主 server 或受控 provider 磁盘高水位一次性缓解和低风险防膨胀入口，覆盖日志、journald、Docker BuildKit cache、allowlisted `/tmp` 诊断目录、受限 core dump、显式 trace 遥测留存和 systemd 定时策略；`gc run`、`gc remote ... run` 和 `gc db-trace run` 需要显式确认，规则见 `docs/reference/cli.md`。 +- `bun scripts/cli.ts gc plan|run|db-trace|policy|remote`：主 server 或受控 provider 磁盘高水位一次性缓解和低风险防膨胀入口，覆盖日志、journald、Docker BuildKit cache、allowlisted `/tmp` 诊断目录、受限 core dump、显式 trace 遥测留存和 systemd 定时策略；规则见 `docs/reference/gc.md`。 - `bun scripts/cli.ts server rebuild `：以 build-first、Compose lock、no-deps force-recreate 和 post-up validation 的异步 job 重建主 server Compose 内单个服务；对 database、File Browser、Code Queue 执行面、k3sctl-adapter 或未知对象返回结构化 `unsupported-server-rebuild`，规则见 `docs/reference/deployment.md` 与 `docs/reference/cicd-standardization.md`。 - `bun scripts/cli.ts provider attach [--master-server URL] [--up] [--force]` / `bun scripts/cli.ts provider triage [--observed-error text] [--observed-scope scope] [--microservice id ...] [--full|--raw]`：前者在新增计算节点上生成两项配置的 provider-gateway 挂载包；后者是只读多信号健康裁决入口，默认低噪声输出 `decision`、`healthyScopes`、`failedScopes`、`retryable` 和异常信号摘要，用来把单路径 `provider is not online`、SSH 超时、registry 失败或 proxy 失败归类为 `retryable-transient`、`service-degraded` 或 `global-offline`，完整 evidence 需显式 `--full|--raw`，规则见 `docs/reference/provider-gateway.md` 和 `docs/reference/code-queue-supervision.md`。 - `bun scripts/cli.ts ssh [operation args...]` / `tran [operation args...]`：通过 provider-gateway 的 Host SSH / WSL SSH 维护桥进入 provider、host workspace、Windows cmd route、k3s 控制面或 pod workspace，并提供带 SHA-256 校验的 `upload`/`download` 文件传输；主 server 人工/Codex 分布式操作必须用本机 `tran` wrapper，CLI 参考和可移植脚本可保留完整命令，细则见 `docs/reference/cli.md`、`docs/reference/windows-passthrough.md` 和 `docs/reference/provider-gateway.md`。 @@ -198,6 +198,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `docs/reference/code-queue-supervision.md`：Code Queue 居中调度、并发队列拆分、运行中监控、基础设施缺陷分流和验收收口规则。 - `docs/reference/hwlab.md`：HWLAB 指挥侧固定 workspace、G14 主运行面、D601 legacy/硬件桥接边界、最小 device-agent/gateway 桥接模型和受控发布边界。 - `docs/reference/g14.md`：G14 provider 节点、k3s 控制桥、当前 HWLAB DEV/PROD source/runtime truth、device-agent 手动实验边界、Code Queue/CI 候选目标和节点本地 VPN proxy bootstrap 边界。 +- `docs/reference/gc.md`：UniDesk 主 server 和 provider 磁盘 GC、G14/HWLAB registry retention、safe-stop 线和长期防膨胀收益规则。 - `docs/reference/observability.md`：服务日志、任务活性、通用性能指标 API 和性能面板的可观测性规则。 - `docs/reference/microservices.md`：用户服务（兼容命名 `microservice`）的配置、代理、安全边界、unidesk-direct/k3sctl-managed 部署模式、Todo Note/Baidu Netdisk on main-server、k3s Control/Code Queue/MDTODO/Decision Center/FindJob/Pipeline/MET Nonlinear on D601 和验证规则。 - `docs/reference/windows-passthrough.md`：WSL provider 通过 SSH 透传调用 Windows cmd/PowerShell、Keil、COM 串口和 Windows 侧 skill 的长期规则。 diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 13841a60..ddf0b3b6 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -25,7 +25,7 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 DEV/PROD 滚动、P - `server swap status|ensure [--path /swapfile] [--size 2GiB] [--dry-run]` 是主 server swap 管理入口。`status` 仅读 `/proc/meminfo`、`/proc/swaps` 和 `/etc/fstab` 并返回 JSON；`ensure` 在已有任何 active swap 时只报告 no-op，在无 active swap 时创建固定 swapfile、`chmod 600`、`mkswap`、`swapon` 并尽量写入 `/etc/fstab`。输出必须包含 `before`、`after`、total memory、active swap、持久化状态、关键动作和错误详情；若 swap 已启用但 fstab 写入失败，状态为 `degraded`，调用者需按返回的 detail 修复持久化。 - `server logs` 返回 `logs/` 文件日志和 Docker 容器日志的尾部，默认限制输出大小，避免日志爆炸。实现必须只读取文件末尾字节，不得为了 tail 先把巨大日志完整读入 CLI 内存。 - `server cleanup plan [--min-age-hours N] [--limit N]` 只生成主 server Docker 镜像清理 dry-run 计划，不执行删除；默认 `--min-age-hours 24`，避免把刚发布或刚验证的镜像列为 stale。输出必须包含 `dryRun=true`、`mutation=false`、`policy.deletionExecuted=false`、active containers/images、受保护镜像、candidate stale images、估算释放空间、风险等级、`commandsToReview` 和人工审批清单。计划必须保守白名单：保留 running containers 使用的 image ID，保留 stopped containers 引用的 image ID 直到人工先复核容器，保留 `deploy.json`/`CI.json` 当前 commit-pinned artifact、Compose stable image、上游 digest pin 和 provider-gateway runner image；`protectedStorage` 必须显式列出 PostgreSQL named volume、Baidu Netdisk `.state`、D601 registry storage 和 Docker volumes/host data policy。该入口禁止生成或执行 `docker system prune`、`docker image prune`、`docker builder prune`、`docker volume rm`、`docker compose down -v`、数据库清理或 host data `rm` 命令；未来若增加真实删除，必须另设显式审批参数并先复核 dry-run 输出。 -- `gc plan|run --confirm` 是主 server 磁盘高水位的一次性短期缓解入口，覆盖 UniDesk 文件日志、Docker `json-file` 容器日志、systemd journal、Docker BuildKit cache 和 allowlisted `/tmp` 诊断目录。`gc plan` 默认只读并返回候选、风险、估算释放空间、受保护对象和数据库只读摘要；候选列表默认按释放空间排序限制为 50 条，`--limit N` 调整页大小，`--full|--raw` 才展开全部候选。输出中的 `estimatedReclaim` 表示全量候选估算，`returnedEstimatedReclaim` 表示当前输出页估算；`gc run` 默认只返回前 50 条结果，`--result-limit N` 调整结果页大小，避免 GC 自身输出膨胀。`gc run` 必须显式 `--confirm`，只执行当前输出候选中的短期清理动作，因此默认不会执行被分页隐藏的候选。`gc` 不删除 Docker image/container/volume，不触碰 PostgreSQL PGDATA，不删除 Baidu Netdisk staging/backups 或 D601 registry storage；默认路径中数据库只做诊断摘要。`gc remote plan|run --confirm|status --job-id ` 通过 UniDesk SSH 透传在 provider host 上执行同类低风险 GC；G14 路径会先确认原生 k3s node 身份，并显式保护 `/var/lib/rancher/k3s`、`/var/lib/rancher/k3s/storage`、`/var/lib/kubelet`、`/var/lib/containerd`、HWLAB 固定 workspaces、Kubernetes workload/Secret/PVC/PV/Argo/Tekton 对象以及 Docker image/container/volume，默认只允许 journal vacuum、Docker json log truncate、Docker BuildKit cache prune、apt archive clean、allowlisted `/tmp` 临时目录删除，以及受限 core dump 清理；core dump 仅匹配 `/root/unidesk/core.` 这类普通文件，并在执行前重新校验路径 allowlist、Git 未跟踪和无 `fuser` 活跃引用。HWLAB registry 清理必须显式加 `--include-hwlab-registry` 才会进入，策略不是只留 latest：默认保留当前 workload 引用的 tag/digest、cache/latest、基础镜像 tag、48 小时内所有 tag，以及每个业务 repo 至少 20 个最新 tag；执行时会以远端异步 job 暂停 G14/v0.2 branch poller CronJob、等待 hwlab-ci PipelineRun/TaskRun/Job 空闲、通过 registry API 删除不再被保留 tag 引用的 manifest，再缩容 registry pod 后运行官方 `registry garbage-collect`，最后恢复 registry 和 CronJob；中断恢复可显式使用 `--registry-gc-only` 生成只跑官方 GC 的收尾候选，该候选不删除任何 tag。长任务状态通过 `gc remote status --job-id ` 查询。`gc policy plan|install` 渲染或安装低风险长期策略：journald 512MiB 上限和每日 `unidesk-gc.timer`，该 timer 只运行文件日志与 allowlisted `/tmp` 低风险 GC，不主动 vacuum journal，不触碰数据库、Docker image/volume 或 Baidu staging，输出写入 `.state/gc/`。`gc db-trace plan|run --confirm --before-date YYYY-MM-DD --vacuum-full` 是显式数据库 trace 遥测留存入口，只删除 `oa_events` 中默认 trace 高频事件类型在指定日期前的数据，并在 `--vacuum-full` 下重写 `public.oa_events` 让 `df` 真正回收磁盘；执行前必须确认近期 PostgreSQL basebackup，且应视为维护窗口操作。常用参数包括 `--logs-keep-days N`、`--file-log-max-bytes SIZE`、`--file-log-tail-bytes SIZE`、`--docker-log-max-bytes SIZE`、`--journal-target-size SIZE`、`--build-cache-until 24h`、显式清空全部 BuildKit cache 的 `--build-cache-all`、`--tmp-min-age-hours N`、显式 `--include-browser-cache`、远端 registry 的 `--registry-keep-per-repo N`、`--registry-min-age-hours N`、`--registry-gc-only` 与 `--job-id ID`。 +- `gc plan|run --confirm|db-trace|policy|remote` 是主 server 和受控 provider 的磁盘高水位一次性缓解与长期防膨胀入口。`plan` 只读输出候选、风险、估算收益和保护对象；`run` 必须显式 `--confirm`；`gc remote ...` 通过 UniDesk SSH 透传执行远端 GC，G14/HWLAB registry retention、受限 core dump、保护对象、safe-stop 线和长期收益表的权威规则见 `docs/reference/gc.md`。 - `server rebuild ` 创建异步 job，先构建目标服务镜像，随后在 `.state/locks/server-compose.lock` 串行保护下用 `--no-deps --force-recreate` 替换目标 service 并等待容器 `healthy/running`；该命令用于替代手工删除容器的兜底流程，其中 `dev-frontend-proxy` 只更新主 server dev 入口薄代理，`todo-note`、`code-queue-mgr`、`project-manager`、`baidu-netdisk` 和 `oa-event-flow` 只重建主 server 承载的对应后端，不会重建或删除 database 命名卷。D601 Code Queue 执行面不由 `server rebuild` 管理，Rust backend-core 迭代不得用 `server rebuild backend-core` 在 master server 编译，规则见 `docs/reference/dev-environment.md`。 - `provider attach [--master-server URL] [--up] [--force]` 在新计算节点生成两项配置的 provider-gateway 挂载包：`.state/provider-.env` 默认只包含 `UNIDESK_MASTER_SERVER` 与 `PROVIDER_ID`，`provider-.yml` 固定 Docker socket、`pid: "host"`、`restart: always`、只读 `/workspace` 和 SSH 维护私钥挂载；`--up` 会立即执行生成的 `docker compose up -d --build`。`provider triage [--observed-error text] [--observed-scope scope] [--microservice id ...] [--full|--raw]` 是只读多信号健康裁决入口，会把单路径 `provider is not online`、SSH 超时、registry 失败和 service proxy 失败归类成 `runner-local-observation-gap`、`service-degraded`、`provider-degraded` 或 `global-blocker`。默认输出只返回裁决、scope、失败/降级/未知信号和有界 evidence 摘要，完整 evidence 必须显式加 `--full` 或 `--raw`；推荐交叉验证命令仍包含 `debug health`、`debug dispatch host.ssh --wait-ms 15000`、`ssh argv true`、`artifact-registry health --provider-id `、`microservice health k3sctl-adapter`、`microservice health code-queue` 和 `codex tasks --view supervisor --limit 20`。 - `ssh [operation args...]` / `tran [operation args...]` 通过 backend-core 内网 WebSocket broker 和 provider-gateway 的 Host SSH / WSL SSH 维护桥连接目标节点；`route` 基础形态是 provider id，例如 `D601` 或 `G14`，也可以扩展为纯定位路径 `provider:plane[:namespace:resource[:container]]`，例如 `D601:win`、`D601:win/c/test`、`G14:k3s`、`D601:k3s` 或 `G14:k3s::`。WSL provider 的 Windows cmd 入口固定写 `tran D601:win cmd `，需要 Windows cwd 时用 `tran D601:win/c/test cmd cd`，由 CLI 自动设置 `chcp 65001`、`PYTHONUTF8=1` 和 `PYTHONIOENCODING=utf-8`；命名只允许 `win`，不得使用 `win32`。非交互远端命令优先使用 `ssh argv ...`；需要 shell 脚本、管道、变量或循环时优先使用 quoted heredoc 单步传输，例如 `tran G14 script <<'SCRIPT'`、`tran G14:k3s script <<'SCRIPT'` 或 `tran G14:k3s:: script <<'SCRIPT'`，把脚本走 stdin。`script -- '<单个字符串>'` 是无需 stdin 的远端 shell one-liner，例如 `tran G14:/root/hwlab script -- 'cd /root/hwlab && git status --short --branch'`；`script -- <多个 argv>` 才是 direct argv，适合 `tran D601:/path script -- sed -n '1,20p' file` 这类带短横线的单进程命令。顶层 remote option parser 必须保留命令已经开始后的 `--`，不得把它吞成全局选项结束符。需要远端改文本文件时默认优先使用 ` apply-patch < patch.diff`；需要可靠传输非文本或整文件时使用 ` upload ` 和 ` download `，CLI 会按字节数与 SHA-256 自动校验并在 provider-gateway stdin/argv 限制下切换客户端分块策略；需要旧 helper 时显式使用 `:k3s:: apply-patch-v1` 或 ` apply-patch-v1`。ssh-like 命令遇到 timeout/kex/255 类失败时，CLI 会在 stderr 追加一行 `UNIDESK_SSH_HINT` JSON，提示 stdin script/argv 重试和 provider triage 交叉验证。 diff --git a/docs/reference/gc.md b/docs/reference/gc.md new file mode 100644 index 00000000..c2144ecb --- /dev/null +++ b/docs/reference/gc.md @@ -0,0 +1,112 @@ +# 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 plan|run --confirm|status --job-id `：通过 UniDesk SSH 透传在 provider host 上执行受控 GC。远端长任务必须使用异步 job 和 `status` 短查询，不应让单次 SSH 等待完整 registry GC 或其他长清理。 + +所有成功和失败输出都必须是 JSON。`plan` 必须标记 `dryRun=true`、`mutation=false`；`run` 必须要求 `--confirm` 并报告 `diskBefore`、`diskAfter`、`summary`、`results` 和 `protected`。 + +## 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.` 普通文件。执行前必须重新校验路径 allowlist、Git 未跟踪、非 symlink、无 `fuser` 活跃引用。估算收益必须按实际分配块数计算，并可另行披露 `apparentSizeBytes`；不能把 sparse core dump 的表观大小当成可回收磁盘空间。 + +## HWLAB Registry Retention + +G14 HWLAB registry 清理必须显式使用 `--include-hwlab-registry`，默认 `gc remote G14 plan` 不进入 registry。策略必须保守，不能只留 latest。 + +默认保留规则： + +| 保留项 | 规则 | +|---|---| +| 当前 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 | +| 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。 + +Registry 执行必须以远端异步 job 完成，并具备以下维护保护： + +- 暂停 G14/v0.2 branch poller CronJob。 +- 等待 hwlab-ci PipelineRun、TaskRun 和 Job 空闲。 +- 通过 registry API 删除 manifest 时 registry 必须仍在线。 +- 缩容 registry 后运行官方 `registry:2.8.3` garbage-collect pod。 +- finally 阶段删除 GC pod、恢复 registry replicas、等待 rollout、恢复 CronJob suspend 状态。 +- 状态查询使用 `gc remote G14 status --job-id `，不使用长 SSH 会话等待。 + +## Safe Stop Line + +磁盘目标可以设为 `<70%`，但安全边界优先级高于目标百分比。当执行以下命令后仍高于目标时，应停止自动清理并提交决策表： + +```bash +bun scripts/cli.ts gc remote G14 plan --limit 20 +bun scripts/cli.ts gc remote G14 plan --include-hwlab-registry --limit 20 +``` + +若两个 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 确认数据类别和留存期限 | +| 扩容磁盘 | 低运行风险 | 节点容量预算和停机/在线扩容方式 | + +## Validation Checklist + +G14 GC 后必须验证： + +```bash +bun scripts/cli.ts ssh G14 script -- 'df -h / | tail -1' +bun scripts/cli.ts ssh G14 script -- 'curl -fsS http://127.0.0.1:5000/v2/ >/dev/null && echo ok' +bun scripts/cli.ts ssh G14 script -- 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-ci get deploy hwlab-registry' +bun scripts/cli.ts ssh G14 script -- 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-ci get cronjob hwlab-g14-branch-poller hwlab-v02-branch-poller -o custom-columns=NAME:.metadata.name,SUSPEND:.spec.suspend --no-headers' +``` + +DEV workload 验证应检查非零副本 workload 是否 ready；`0/0` 的显式停用 deployment 不应误报为事故。registry tag 数只作为辅证，不能替代 workload ref 保护和 registry API 健康。 + +## 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 提供证据，不默认删除 | +| Capacity trigger | 达到高水位时输出 safe-stop 决策表 | 避免为了百分比目标破坏运行面 | + diff --git a/scripts/src/help.ts b/scripts/src/help.ts index cc56bcc4..a1c7d5f9 100644 --- a/scripts/src/help.ts +++ b/scripts/src/help.ts @@ -313,7 +313,7 @@ function gcHelp(): unknown { "remote plan|run": "run bounded GC through UniDesk SSH passthrough on a provider host; G14 protects HWLAB k3s/runtime/PVC/workspace paths, and HWLAB registry retention is explicit opt-in with workload-ref, recent-tag and per-repo tag protection", "--no-file-logs|--no-docker-logs|--no-journal|--no-build-cache|--no-tmp|--no-db-summary": "disable one collector", }, - reference: "docs/reference/cli.md", + reference: "docs/reference/gc.md", }; }