From a27389d0d0c987e869bfaeb3420eca6f1d0239df Mon Sep 17 00:00:00 2001 From: admin Date: Tue, 3 Nov 2026 23:11:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E3=80=8A=E7=BC=96=E8=AF=91?= =?UTF-8?q?=E8=86=A8=E8=83=80=E9=97=AE=E9=A2=98=E5=8F=8A=E5=A4=84=E7=90=86?= =?UTF-8?q?=E3=80=8B=E2=80=94=E2=80=94=20target/=2058G=20=E7=9A=84?= =?UTF-8?q?=E6=A0=B9=E5=9B=A0=E3=80=81=E5=A4=84=E7=BD=AE=E4=B8=8E=E8=A7=84?= =?UTF-8?q?=E7=9F=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 docs/build-bloat.md,记录 2026-11-03 这次磁盘膨胀的完整处置: - 现象:target/ 58G(deps 45G + incremental 12G + release 820M),磁盘 87% - 根因:cargo 默认传 -C incremental=…,而 sccache 遇 incremental 直接拒缓存 (server 端日志 CannotCache(incremental))⇒ 8.4G 缓存全是废的,每轮从零重编 - 处置:根 Cargo.toml 加 [profile.dev] incremental = false + cargo clean - 结果:58G → 1.2G;清空后重建 63s → 14.14s(缓存命中,命中率 86.71%); 磁盘 87% → 75%(跑完测试后 76%) - 定位方法论:发现 sccache 命中率异常时看 server 端日志 (SCCACHE_LOG=debug + SCCACHE_ERROR_LOG),client 端统计只说「没命中」 - 区分表:哪些是编译中间产物(该清)、哪些不是(node_modules / pglite 数据, 按既定约定不动) - 沉淀 6 条规矩(清前 pgrep、用 cargo clean 而非 rm -rf、sccache 缓存不在项目内、 改 profile 要重新体检 target 体积等) 索引同步:docs/README-project.md(链接区 + 目录树)、README.md(目录树)。 验证:check-citations 4/4、check-naming 3/0/1、check-arch 20/20、 check-boundary 12/12、check-contract 10/10、check-module 123/123 全绿。 --- README.md | 1 + docs/README-project.md | 2 + docs/build-bloat.md | 219 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 222 insertions(+) create mode 100644 docs/build-bloat.md diff --git a/README.md b/README.md index 7a7e1bc..4cac13b 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,7 @@ ssw-jnpf-lite-rust/ ← 仓根 = 技能根(三处软链指向这里 ├── runbook.md # 怎么起 / 怎么冒烟 / 常见故障 ├── decisions.md # 实施期逐条裁决(98 条「什么—为什么—代价」) ├── known-limitations.md # 分支级已知限制(被接受/挂起的东西) + ├── build-bloat.md # 编译膨胀问题及处理(target/ 58G → 1.2G 的根因与处置) └── ddl/ # 官方 DDL 摘录 ``` diff --git a/docs/README-project.md b/docs/README-project.md index a3268c8..91189c8 100644 --- a/docs/README-project.md +++ b/docs/README-project.md @@ -13,6 +13,7 @@ - 📘 **契约唯一真源**:[`docs/contract.md`](contract.md) —— 与本文件冲突时以契约为准。 - 🧭 **agent 指引**:[`CLAUDE.md`](../CLAUDE.md)(红线 / 踩坑 / 端点全表)· [`HANDOFF.md`](../HANDOFF.md)(交接)。 - 🛠 **怎么起 / 怎么冒烟 / 常见故障**:[`docs/runbook.md`](runbook.md)。 +- 💾 **编译膨胀问题及处理**:[`docs/build-bloat.md`](build-bloat.md)(`target/` 58G → 1.2G 的根因、处置与规矩)。 - 🧾 **实施期裁决(98 条「什么—为什么—代价」)**:[`docs/decisions.md`](decisions.md) · **分支级已知限制**:[`docs/known-limitations.md`](known-limitations.md)。 @@ -56,6 +57,7 @@ ssw-jnpf-lite-rust/ ├── scripts/smoke_backend.sh # 两把尺子的「隔离后端」自启动助手(默认自起 ⇒ CI 可跑) ├── scripts/check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端) └── docs/ # contract.md(契约)· runbook.md(运维)· decisions.md(裁决)· known-limitations.md(已知限制) + # build-bloat.md(编译膨胀问题及处理) # JNPF_SOURCE_AUDIT.md(官方源码逐行核对)· JNPF_COMPAT_SURFACE.md(面 B 规格)· MIGRATION.md(迁移指南)· ddl/ ``` diff --git a/docs/build-bloat.md b/docs/build-bloat.md new file mode 100644 index 0000000..263f6c4 --- /dev/null +++ b/docs/build-bloat.md @@ -0,0 +1,219 @@ +# 编译膨胀问题及处理(ssw-platform) + +> **一句话**:2026-11-03 发现 `target/` 涨到 **58G**(磁盘已用 87%), +> 根因不是「Rust 编译本来就大」,而是 **增量编译让 sccache 全程空转** ⇒ 缓存形同虚设、 +> 每轮构建都从零重编。处置 = 清空 `target/` + 关掉 dev 增量编译。 +> **结果:58G → 1.2G,且「清空后重建」从 63s 缩到 14s(走缓存命中)。** + +--- + +## 1. 现象 + +| 项 | 值 | +|---|---| +| `target/` 体积 | **58G**(`debug/deps` 45G + `debug/incremental` 12G + `release` 820M) | +| `target/` 文件数 | **683,476**(其中 `debug/deps` 540,833) | +| 磁盘占用 | **87%**(`/System/Volumes/Data`,可用仅剩 59 GiB) | +| 依赖规模 | `Cargo.lock` **174 个包**(本仓 17 个 crate + 外部依赖) | +| `sccache` 缓存实体 | `~/.cache/sccache` **8.4G** | +| `sccache` 命中率 | **0**(`Cache hits` 恒为 0,`Non-cacheable calls` = 请求数) | + +**同期项目内其它占用**(用来区分「什么是编译中间产物」): + +| 路径 | 体积 | 是什么 | 是否该清 | +|---|---|---|---| +| `target/` | 58G | **编译中间产物** | ✅ 清 | +| `src/frontend/node_modules` | 74M | 前端依赖(**非**编译产物) | ❌ 不清(删了下次重下,且重下更慢更占) | +| `src/backend/data/`(pglite) | 60M | **运行期数据** | ❌ 不清(是数据不是垃圾) | +| `.git/` | 19M | 版本历史 | ❌ 不清 | +| `crates/` | 3.2M | **真源代码** | ❌ 不清 | +| `scripts/__pycache__` | 124K | Python 字节码缓存 | ✅ 清(自动重建) | + +--- + +## 2. 根因:`incremental` 让 sccache 拒缓存 + +### 2.1 为什么值得深挖 + +本机 `~/.cargo/config.toml` **早就配好了** sccache: + +```toml +[build] +rustc-wrapper = "/Users/xs/.cargo/bin/sccache" + +[env] +SCCACHE_DIR = { value = ".cache/sccache", relative = true } +``` + +缓存实体也有 8.4G(20,409 个文件)。按常理,`target/` 应该是「小而精」的—— +`cargo clean` 之后重建走缓存命中,十几秒就回来了。 + +**但实测 `sccache --show-stats` 的 `Cache hits` 恒为 0。** + +### 2.2 定位过程(关键:看 server 端日志,不要只看 client 端统计) + +client 端统计只告诉你「没命中」,不告诉你「为什么」。开 server 端 debug 日志才看到真相: + +```bash +export SCCACHE_DIR="$HOME/.cache/sccache" +export SCCACHE_LOG=debug +export SCCACHE_ERROR_LOG=/tmp/scc_err.log +sccache --stop-server; sccache --start-server +touch src/lib.rs && cargo build --offline +grep -iE 'unhandled|cannotcache' /tmp/scc_err.log +``` + +**server 端日志原文**: + +``` +parse_arguments: CannotCache(incremental): + ["--crate-name", "sccprobe", "--edition=2021", "src/lib.rs", ..., + "-C", "incremental=/private/tmp/scc-probe/target/debug/incremental", ...] +``` + +### 2.3 因果链 + +``` +cargo 默认给 rustc 传 -C incremental= + │ + ▼ +sccache 遇到 incremental ⇒ 拒缓存(CannotCache(incremental)) + │ + ▼ +Cache hits 恒为 0,8.4G 缓存全是废的 + │ + ▼ +每轮构建都从零重编 ⇒ deps 堆到 45G、incremental 堆到 12G + │ + ▼ +target/ = 58G,磁盘 87% +``` + +**关键点**:增量编译与 sccache 是**互斥**的。开了增量,sccache 就完全不介入; +于是你既没有得到增量加速(因为缓存判据失效后每次都全量),又付出了磁盘代价—— +**两头落空**。 + +### 2.4 旁证:`deps` 里堆着 10 个历史 rlib + +``` +230.6 MB libssw_platform-c9e02b20408f6637.rlib +230.6 MB libssw_platform-538da23eaac2c350.rlib +215.3 MB libssw_platform-5d60b88b38c2b355.rlib +213.6 MB libssw_platform-c94ffde5df1ce787.rlib +168.1 MB libssw_platform-bc6ce2ecdfc0f0fd.rlib +...(共 10 个,每个 100–230 MB) +``` + +cargo **永远不会自动清理**这些历史产物——每次改 profile 参数、换 feature 组合、 +换 rustc 版本,都会把**整套旧产物**留在盘上。这与 `xstudio/scripts/reclaim-space.sh` +里记的同一现象(dbx 的 target 曾到 2.4 GB,依赖图只有 556 个 crate,盘上却有 863 个 rlib) +**是同一个病**。 + +--- + +## 3. 处置 + +### 3.1 修根因:关掉 dev 增量编译 + +根 `Cargo.toml` 新增(**注意:必须在 workspace 根,成员 crate 里写 `[profile.*]` cargo 会报错**): + +```toml +[profile.dev] +incremental = false +``` + +**为什么这行有效**: +- 去掉 `-C incremental=…` ⇒ sccache 不再拒缓存 ⇒ 缓存真正生效; +- 增量编译产物(`target/debug/incremental`)不再产生 ⇒ 单这一项就少涨 **12G**。 + +**代价与取舍**: +- 失去 cargo 自己的增量加速; +- 由 sccache 命中替代,且**跨 `cargo clean` 仍有效**(增量缓存一 clear 就没了,sccache 命中不); +- 「改一处重编」从「秒级(增量)」变成「秒级(缓存命中)」——实测命中率 **86.71%**。 + +### 3.2 清理动作 + +```bash +# 🔴 用 cargo clean,不要手 rm -rf target/ +# (cargo clean 会顺手清 target/ 外的残留,也避免路径写错) +cargo clean +``` + +实测输出与效果: + +``` +Removed 631330 files, 92.4GiB total +可用空间: 59 GiB → 118 GiB 磁盘占用: 87% → 75% +``` + +另删 `scripts/__pycache__`(124K,Python 字节码缓存,自动重建)。 + +> ⚠️ **「118 GiB / 75%」是清理完成那一刻的瞬时值** —— 随后跑 `cargo test --workspace` +> 会重新生成测试产物(`target/` 3.5G),磁盘回落至 **76% / 可用 110 GiB**。 +> 两个数都正常,**看趋势别看快照**。 + +> ⚠️ **清理前必须确认没有构建在跑**: +> ```bash +> pgrep -f "cargo (build|rustc|check)" && echo "有构建在跑,先别清" +> ``` +> 这条闸门与 `xstudio/scripts/reclaim-space.sh` 的做法一致(pgrep 探测活跃构建则跳过)。 + +### 3.3 验证:清空后重建走缓存命中 + +这是判断「根治了没有」的**决定性实验**: + +| 场景 | 耗时 | +|---|---| +| 全量首次编译(无缓存) | **63s** | +| `rm -rf target` 后重建(走 sccache 命中) | **14.14s** ✅ | + +命中率 **86.71%**(124 命中 / 19 未命中)。`target/debug/incremental` 不再产生 +(实测只剩 0B 空目录)。 + +--- + +## 4. 结果 + +| 指标 | 处置前 | 处置后 | +|---|---|---| +| `target/` | **58G** | **1.2G**(纯构建)/ 3.5G(含测试产物) | +| `target/debug/incremental` | 12G | **0B**(不再产生) | +| 磁盘占用 | 87% | **75%**(清理瞬时)→ 76%(跑完测试后) | +| 可用空间 | 59 GiB | **118 GiB**(清理瞬时)→ 110 GiB(含测试产物) | +| 清空后重建 | 63s(全量) | **14.14s**(缓存命中) | +| sccache 命中率 | 0% | **86.71%** | + +**无回归**(全部复跑确认): + +- `cargo test --workspace`:**695 passed / 0 failed / 2 ignored**(79 个二进制,与 M1 基线完全一致) +- `check-arch` 20/20 · `check-boundary` 12/12 · `check-contract` 10/10 +- `check-module` 123/123 · `check-citations` 4/4 + +--- + +## 5. 沉淀下来的规矩 + +1. **`target/` 现在是「随时可清」的东西** —— 清了重建只要十几秒,不必心疼。 + 真要清用 `cargo clean`,**不要手 `rm -rf target/`**。 +2. **清之前先 `pgrep`** —— 有构建在跑就跳过,别把别人的编译现场掀了。 +3. **`sccache` 缓存在 `~/.cache/sccache`,不在项目内** ⇒ 跟着 `target/` 一起删是错的。 + 它是**包缓存**(按既定约定统一放 `~/.cache//`,工具默认路径留软链)。 +4. **改 `Cargo.toml` 的 profile 参数要重新体检 target 体积** —— + profile 一变,cargo 会留一整套旧产物(本次就积累了 10 个 rlib ≈ 1.7G)。 +5. **发现 sccache 命中率异常时,看 server 端日志**(`SCCACHE_LOG=debug` + + `SCCACHE_ERROR_LOG`),client 端统计只说「没命中」,不说「为什么」。 +6. **`cargo metadata` 在本机可能失败** —— 它要拉 wasm 依赖(如 `js-sys`), + `--offline` 下报 `failed to download`。统计依赖规模用 `Cargo.lock` 的 `[[package]]` 数。 + +--- + +## 6. 相关文件 + +| 文件 | 作用 | +|---|---| +| `Cargo.toml`(根) | `[profile.dev] incremental = false` —— 修复点本体 | +| `~/.cargo/config.toml` | `rustc-wrapper = sccache` + `SCCACHE_DIR`(**不是**仓库内文件) | +| `CLAUDE.md` §9 | 「磁盘占用」小节 —— 给 agent 的速查摘要 | +| `xstudio/scripts/reclaim-space.sh` | 兄弟项目的同类回收脚本(pgrep 闸门 + 只清可再生中间产物的口径可参考) | + +**相关 tag**:`v0.1.8-target-cleanup`(本处置)