From 4d39d727f07500e4bf10e9ab9f67efb337bcb3f8 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 6 Jun 2026 09:35:31 +0000 Subject: [PATCH] docs: document G14 disk retention state --- AGENTS.md | 2 +- docs/reference/agentrun.md | 6 +++ docs/reference/gc.md | 83 +++++++++++++++++++++++++++++++++----- 3 files changed, 80 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 55f5a3f4..e53c518b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -228,7 +228,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `bun scripts/cli.ts gh preflight|auth status|issue ...|pr list|files|diff --stat|read|view|preflight|closeout|create|edit|update|comment|merge` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、分页 issue list、inactive issue stale-close、脱敏 auth/status 诊断、heredoc/stdin Markdown 写入、当日滚动简报时间线 ClaudeQQ 通知、escape 扫描、只读 cleanup-plan 和 #20 board-audit、PR changed-file/stat summary、PR 创建/评论 dry-run、REST-only 低噪声 PR title/body 编辑、PR 收口元数据观察（含 merged/closed 区分与 merge commit）、低噪声 PR 收口 preflight、guarded PR merge 与 runner PR preflight；`gh issue/pr read|view` 支持 `owner/repo#number` shorthand，`--raw|--full` 是显式完整披露别名，`gh pr diff` 仅支持 `--stat` 紧凑 JSON，`gh pr merge` 会先执行 closeout 预检并拒绝非 open、draft、冲突、非 CLEAN、失败或 pending checks 的 PR，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 - `bun scripts/cli.ts commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run|prompt-lint --kind gpt55-pr`：查看 host Codex 指挥官直管微服务 skeleton 的 source/contract、无 daemon smoke 验证计划、.state/commander/ 状态模型、trace summary 聚合、ClaudeQQ 高风险请示草案和 GPT-5.5 PR prompt 边界辅助 lint；当前只返回 dry-run 计划和 backend-core `microservice proxy claudeqq` 授权后候选命令，不接 live bridge、不接管人工指挥官，不发送消息，`prompt-lint` 不作为业务 PR 门禁也不改变 `codex submit` 默认行为，规则见 `docs/reference/host-codex-commander.md`。 - `bun scripts/cli.ts hwlab g14 monitor-prs [--lane g14|v02]`：一行启动异步监控 HWLAB PR；默认 base=G14 合并后滚动 G14 DEV 并写每日简报，`--lane v02` 监控 base=v0.2，CI/preflight 通过后自动合并、触发 v0.2 CD，并在 PR 下评论 pending/冲突/成功/失败/超时状态，规则见 `docs/reference/g14.md` 与 `docs/reference/cli.md`。 -- `bun scripts/cli.ts agentrun v01 control-plane status|trigger-current [--dry-run|--confirm]`：通过 G14 route 只读观察或手动触发 AgentRun `v0.1` commit-pinned Tekton/Argo PipelineRun，规则见 `docs/reference/agentrun.md` 与 `docs/reference/cli.md`。 +- `bun scripts/cli.ts agentrun v01 control-plane status|trigger-current|refresh|cleanup-runs|cleanup-released-pvs [--dry-run|--confirm]`：通过 G14 route 只读观察、手动触发、刷新 Argo 或清理 AgentRun `v0.1` completed CI workspace retention，规则见 `docs/reference/agentrun.md`、`docs/reference/gc.md` 与 `docs/reference/cli.md`。 - `bun scripts/cli.ts hwlab cd audit --env dev` / `status|preflight|apply --dry-run`：旧 D601 HWLAB DEV CD 指挥侧 wrapper，仅用于显式 legacy 诊断和迁移对照；当前 HWLAB DEV/PROD source/runtime truth 已迁到 G14 `/root/hwlab` 与 G14 k3s/GitOps，规则见 `docs/reference/hwlab.md`。 - `bun scripts/cli.ts ci install/status/run/publish-backend-core/publish-user-service/run-dev-e2e/logs`：在 D601 原生 k3s 上安装和运行 Tekton CI，支持每 commit 检查、Code Queue 只读性能门禁、`CI.json` catalog 驱动的 backend-core 与 user-service commit-pinned 镜像发布和手动触发的 `origin/master:deploy.json#environments.dev` 临时 namespace e2e；catalog/producer/consumer 分工见 `docs/reference/cicd-standardization.md`，`run-dev-e2e` 的 Git 控制 runner、短 launcher 和 no-CD 边界见 `docs/reference/dev-ci-runner.md`，Tekton 规则见 `docs/reference/ci.md`。 - `bun scripts/cli.ts codex deploy `：旧 Code Queue 兼容部署入口已禁用，原因是它会绕过受控部署边界直连 D601 部署 Code Queue；规则见 `docs/reference/codex-deploy.md`。 diff --git a/docs/reference/agentrun.md b/docs/reference/agentrun.md index dd3e64d6..5f29abd1 100644 --- a/docs/reference/agentrun.md +++ b/docs/reference/agentrun.md @@ -71,10 +71,16 @@ bun scripts/cli.ts agentrun v01 control-plane trigger-current --dry-run bun scripts/cli.ts agentrun v01 control-plane trigger-current --confirm bun scripts/cli.ts agentrun v01 control-plane refresh --dry-run bun scripts/cli.ts agentrun v01 control-plane refresh --confirm +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 ``` `status` 只读观察 `G14:/root/agentrun-v01` 当前 commit、对应 PipelineRun、GitOps latest、Argo Application、`agentrun-v01` workload、manager source commit 和 git mirror 摘要，并报告 Argo revision 是否对齐 `v0.1-gitops` latest。默认输出是 compact commander 视图，只保留 `summary`、阶段耗时、对齐状态和 drill-down 命令；需要远端 stdout/stderr tail 时显式加 `--full`，需要原始 git mirror cache 输出时显式加 `--raw`。`status` 会向 stderr 输出 `agentrun.control-plane.status.progress` 阶段事件，覆盖 `source`、`runtime` 和 `git-mirror`，避免长时间聚合时无可见进展。`trigger-current` 会先把固定 source worktree 快进到 `origin/v0.1`，再以当前 commit 创建 commit-pinned PipelineRun；同名 PipelineRun 正在运行或已经成功时必须拒绝重复触发，只允许在失败态或不存在时创建。该命令只提交 CI/CD 工作，不等待完整 PipelineRun 或 rollout 完成，后续用 `status` 轮询。`refresh` 只对 `argocd/agentrun-g14-v01` 执行 hard refresh，用于 GitOps promotion 已完成但 Argo 仍停留旧 revision 时的受控同步入口；它不直接 patch runtime workload。 +`cleanup-runs` 是 AgentRun `v0.1` 完成态 CI workspace retention 入口，只清理 `agentrun-ci` namespace 中超过 `--min-age-minutes` 的 `agentrun-v01-ci-*` PipelineRun，通过 Tekton ownerRef 释放临时 workspace PVC。dry-run 必须披露候选 PipelineRun、owned PVC、active mount 保护、local-path 实际估算 bytes 和 confirm 命令。默认保护最新完成的 PipelineRun，保留当前 CI/CD 状态证据。`cleanup-released-pvs` 是二次回收入口，只处理 `agentrun-ci`、`local-path`、`Delete` reclaim policy 的 `Released` PV；它不触碰 `agentrun-v01` runtime namespace、业务 PVC、Secret、registry storage 或 GitOps desired state。磁盘治理和 G14 safe-stop 规则见 `docs/reference/gc.md`。 + ## UniDesk 边界 UniDesk 是 AgentRun 的综合分布式开发和运维中心。UniDesk 可以记录： diff --git a/docs/reference/gc.md b/docs/reference/gc.md index 0018ceea..711f52e9 100644 --- a/docs/reference/gc.md +++ b/docs/reference/gc.md @@ -63,8 +63,8 @@ BuildKit cache repo 的历史 `latest` 写入会留下大量 untagged manifest r Registry 执行必须以远端异步 job 完成，并具备以下维护保护： -- 暂停 G14 branch poller CronJob；`v0.2` 不设 branch poller，只需确认不存在 v02 CronJob 残留。 -- 等待 hwlab-ci PipelineRun、TaskRun 和 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。 @@ -72,6 +72,38 @@ Registry 执行必须以远端异步 job 完成，并具备以下维护保护： - 状态查询使用 `gc remote G14 status --job-id `，不使用长 SSH 会话等待。 - `gc remote` 的 stdout 是有界 JSON：当 `--full` 或大量候选导致结果过大时，完整结果会写入远端 `/tmp/unidesk-gc-remote/jobs/.json`，stdout 只返回摘要、`jobId`、`statePath` 和 `statusCommand`，再用 `gc remote G14 status --job-id ` 渐进查询，避免输出爆炸被误判为 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： + +```bash +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： + +```bash +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，使输出带有可机读缺口： @@ -88,8 +120,18 @@ bun scripts/cli.ts gc remote G14 plan --target-use-percent 50 --include-hwlab-re | 降低 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 ` 取得默认低风险候选和缺口。 +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 --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。长期诊断应按三层归因： @@ -100,18 +142,18 @@ G14 当前只有一个本机 k3s cluster；空间归因时不要把 `hwlab-dev` | 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 retention 后，空间压力可能从 `/var/lib/hwlab/registry` 转移到 k3s containerd snapshot/content、local-path PVC 和 host containerd；这些都属于受保护运行面，不能为了达到百分比目标直接删除目录。 +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 | embedded containerd、local-path PVC 和 k3s server/db | -| k3s containerd snapshots | `/var/lib/rancher/k3s/agent/containerd/.../snapshots` | 约 30-40GiB | workload image layer/snapshot cache，共享占用，不能直接按单 pod 删除 | -| k3s containerd blobs | `/var/lib/rancher/k3s/agent/containerd/.../blobs` | 约 8-12GiB | k3s image content store，共享占用 | -| k3s local-path PVC | `/var/lib/rancher/k3s/storage` | 约 8-10GiB | 可按 namespace/PVC 归因，只能通过运行面 retention 入口清理 | +| 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` | 约 2GiB | HWLAB/v0.2 worktree、npm/bun/cache 等 | -| logs | `/var/log` | 约 1GiB | journald 约占一半，pod logs 很小 | +| 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 的长期判读口径： @@ -147,6 +189,15 @@ trans G14 script -- 'find /var/lib/hwlab/registry/docker/registry/v2/repositorie 需要深挖 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 时，默认只读报告，不直接清理： + +```bash +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 后必须验证： @@ -160,6 +211,17 @@ trans G14 script -- 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-ci ge DEV workload 验证应检查非零副本 workload 是否 ready；`0/0` 的显式停用 deployment 不应误报为事故。registry tag 数只作为辅证，不能替代 workload ref 保护和 registry API 健康。 +同时必须用高层 CLI 验证受影响运行面仍对齐： + +```bash +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 | 措施 | 默认策略 | 预期收益 | @@ -170,4 +232,5 @@ DEV workload 验证应检查非零副本 workload 是否 ready；`0/0` 的显式 | 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 决策表 | 避免为了百分比目标破坏运行面 |