docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md

@@ -330,7 +330,7 @@ Rust 构建流水线还必须在真正执行 `cargo` 前 source `scripts/jenkins
 
 `server-rs/.cargo/config.toml` 只保留 Linux release 目标的 linker/rustflags 等仓库级构建配置，不在仓库级 `config.toml` 里重定义 agent 全局镜像源。不要把这些约束写到单个 crate 的 `Cargo.toml`，因为 Cargo 不会从 crate manifest 的 `[target.x86_64-unknown-linux-gnu]` 读取构建器配置。
 
-由于 `server-rs/.cargo/config.toml` 使用 `clang` 与 `-fuse-ld=lld` 构建 Linux release 目标，构建 agent 必须安装 `clang` 和 `lld`。`Genarrative-Server-Provision` 负责通过 `apt-get`、`dnf` 或 `yum` 安装 `clang`、`lld`、`pkg-config/pkgconf-pkg-config`、OpenSSL headers 与 CA 证书；API/Stdb 构建流水线在执行 Cargo 前必须检查 `clang` 与 `lld`，缺失时直接失败并提示先运行 Server-Provision。
+由于 `server-rs/.cargo/config.toml` 使用 `clang` 与 `-fuse-ld=lld` 构建 Linux release 目标，构建 agent 必须安装 `clang` 和 `lld`。`Genarrative-Server-Provision` 负责通过 `apt-get`、`dnf` 或 `yum` 安装 `clang`、`lld`、`pkg-config/pkgconf-pkg-config`、OpenSSL headers 与 CA 证书；同时负责在缺失时通过 `cargo install sccache --locked` 补齐 `sccache`，让 API/Stdb 构建流水线的 `RUSTC_WRAPPER=sccache` 真正生效。API/Stdb 构建流水线在执行 Cargo 前必须检查 `clang` 与 `lld`，缺失时直接失败并提示先运行 Server-Provision。
 
 `scripts/build-production-release.sh` 必须尊重 `CARGO_TARGET_DIR`，不能硬编码从 `server-rs/target/` 拷贝 Rust 产物。脚本中的产物路径应按以下口径计算：
 
@@ -343,7 +343,7 @@ WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module
 并发与清理规则：
 
 - 同一个 Rust 构建 Job 建议使用 `disableConcurrentBuilds()`，避免同一组件的多个 release 构建同时写入同一最终产物路径。
-- 如果 Linux agent 未安装 `sccache`，Rust 构建流水线必须自动取消 `RUSTC_WRAPPER`，回退到直接使用 `rustc`，不能因为缺少可选缓存工具阻断真实构建。
+- 如果 Linux agent 未安装 `sccache`，应先运行 `Genarrative-Server-Provision` 补齐缓存工具；Rust 构建流水线仍必须自动取消 `RUSTC_WRAPPER`，回退到直接使用 `rustc`，不能因为缺少可选缓存工具阻断真实构建。
 - 生产发布流水线只能消费 `build/<version>/` 或 Jenkins 归档产物，不允许从共享 `cargo-target` 目录直接发布。
 - `SCCACHE_CACHE_SIZE` 必须设置上限，避免编译缓存无限增长。
 - 对 `/var/cache/genarrative-build/*/cargo-target` 或数据盘对应目录配置定期清理，建议保留最近 14 到 30 天。

jenkins/Jenkinsfile.production-server-provision

@@ -139,6 +139,41 @@ pipeline {
               fi
             }
 
+            install_sccache() {
+              for tool_dir in "${HOME:-}/.cargo/bin" /root/.cargo/bin /usr/local/cargo/bin; do
+                if [[ -d "${tool_dir}" && ":${PATH}:" != *":${tool_dir}:"* ]]; then
+                  export PATH="${tool_dir}:${PATH}"
+                fi
+              done
+
+              if command -v sccache >/dev/null 2>&1; then
+                echo "[server-provision] sccache 已存在: $(command -v sccache)"
+                return
+              fi
+
+              if [[ -x /root/.cargo/bin/sccache ]]; then
+                echo "[server-provision] sccache 已存在: /root/.cargo/bin/sccache"
+                return
+              fi
+
+              echo "[server-provision] 未找到 sccache，准备通过 cargo install sccache 安装。"
+              if ! command -v cargo >/dev/null 2>&1; then
+                echo "[server-provision] 未找到 cargo，无法自动安装 sccache。请先安装 Rust 工具链后重跑 Server-Provision。" >&2
+                exit 1
+              fi
+
+              if [[ "${DRY_RUN}" == "true" ]]; then
+                echo "+ cargo install sccache --locked"
+                return
+              fi
+
+              cargo install sccache --locked
+              if ! command -v sccache >/dev/null 2>&1 && [[ ! -x /root/.cargo/bin/sccache ]]; then
+                echo "[server-provision] sccache 安装后仍不可用，请检查 cargo bin 目录是否在 PATH 中。" >&2
+                exit 1
+              fi
+            }
+
             render_nginx_https_config() {
               sed "s/genarrative.example.com/${SERVER_NAME}/g" deploy/nginx/genarrative.conf
             }
@@ -302,6 +337,7 @@ pipeline {
 
             run_cmd id
             install_build_dependencies
+            install_sccache
             run_cmd mkdir -p "${SPACETIME_ROOT}" "${RELEASE_ROOT}" "$(dirname "${CURRENT_LINK}")" "$(dirname "${WEB_LINK}")" /etc/genarrative /var/lib/genarrative/maintenance /var/lib/genarrative/auth
 
             if ! id spacetimedb >/dev/null 2>&1; then

scripts/jenkins-prepare-cargo-env.sh

@@ -17,6 +17,14 @@ if [[ -z "${RUSTUP_HOME:-}" && -n "${ORIGINAL_HOME}" && -d "${ORIGINAL_HOME}/.ru
   export RUSTUP_HOME="${ORIGINAL_HOME}/.rustup"
 fi
 
+# HOME 会在下面切到组件级缓存目录，因此这里先把真实用户的 Rust 工具链目录补进 PATH。
+# Server-Provision 通过 cargo install 安装的 sccache 通常会落在 /root/.cargo/bin。
+for tool_dir in "${ORIGINAL_HOME}/.cargo/bin" /root/.cargo/bin /usr/local/cargo/bin; do
+  if [[ -d "${tool_dir}" && ":${PATH}:" != *":${tool_dir}:"* ]]; then
+    export PATH="${tool_dir}:${PATH}"
+  fi
+done
+
 export HOME="${CARGO_BUILD_HOME}"
 export CARGO_HOME
 export CARGO_TARGET_DIR