docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md

@@ -319,6 +319,10 @@ environment {
 
 其中 `<component>` 使用 `api-server` 或 `stdb-module`。API 与 Stdb module 并行构建时不能共享同一个 `CARGO_HOME` 或 `CARGO_TARGET_DIR`，否则容易在 Cargo package cache 或 target 目录上出现 `Blocking waiting for file lock on package cache` 等锁等待。
 
+Rust 构建流水线还必须在真正执行 `cargo` 前 source `scripts/jenkins-prepare-cargo-env.sh`。该脚本会把 `HOME` 临时切到组件级缓存目录，显式导出组件级 `CARGO_HOME`、`CARGO_TARGET_DIR`、`SCCACHE_DIR`，并在 `${CARGO_HOME}/config.toml` 写入可用的 Cargo sparse registry 配置。这样可以避免构建 agent 使用 `root` 账户时继续读取 `/root/.cargo/config` 中失效的全局镜像配置，例如错误的 `replace-with = "tuna"` 导致 `config.json not found in registry`。
+
+`server-rs/.cargo/config.toml` 只保留 Linux release 目标的 linker/rustflags 等仓库级构建配置，不在仓库级 `config.toml` 里重定义 agent 全局镜像源。不要把这些约束写到单个 crate 的 `Cargo.toml`，因为 Cargo 不会从 crate manifest 的 `[target.x86_64-unknown-linux-gnu]` 读取构建器配置。
+
 `scripts/build-production-release.sh` 必须尊重 `CARGO_TARGET_DIR`，不能硬编码从 `server-rs/target/` 拷贝 Rust 产物。脚本中的产物路径应按以下口径计算：
 
 ```bash

jenkins/Jenkinsfile.production-api-build

@@ -62,7 +62,8 @@ pipeline {
         sh '''
           bash -lc '
             set -euo pipefail
-            mkdir -p "${CARGO_HOME}" "${CARGO_TARGET_DIR}" "${SCCACHE_DIR}"
+            chmod +x scripts/jenkins-prepare-cargo-env.sh
+            source scripts/jenkins-prepare-cargo-env.sh
             if ! command -v sccache >/dev/null 2>&1; then
               echo "[api-build] 未找到 sccache，改用 rustc 直接构建。"
               unset RUSTC_WRAPPER

jenkins/Jenkinsfile.production-stdb-module-build

@@ -63,7 +63,8 @@ pipeline {
         sh '''
           bash -lc '
             set -euo pipefail
-            mkdir -p "${CARGO_HOME}" "${CARGO_TARGET_DIR}" "${SCCACHE_DIR}"
+            chmod +x scripts/jenkins-prepare-cargo-env.sh
+            source scripts/jenkins-prepare-cargo-env.sh
             if ! command -v sccache >/dev/null 2>&1; then
               echo "[stdb-build] 未找到 sccache，改用 rustc 直接构建。"
               unset RUSTC_WRAPPER

scripts/jenkins-prepare-cargo-env.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+: "${CARGO_HOME:?需要设置 CARGO_HOME}"
+: "${CARGO_TARGET_DIR:?需要设置 CARGO_TARGET_DIR}"
+: "${SCCACHE_DIR:?需要设置 SCCACHE_DIR}"
+
+ORIGINAL_HOME="${HOME:-}"
+CARGO_BUILD_HOME="${CARGO_BUILD_HOME:-$(dirname "${CARGO_HOME}")/home}"
+
+mkdir -p "${CARGO_HOME}" "${CARGO_TARGET_DIR}" "${SCCACHE_DIR}" "${CARGO_BUILD_HOME}"
+
+# Jenkins agent 当前以 root 运行时，/root/.cargo/config 可能带有失效镜像配置。
+# 生产构建使用组件级 HOME 与 CARGO_HOME，避免被全局 Cargo 配置污染。
+if [[ -z "${RUSTUP_HOME:-}" && -n "${ORIGINAL_HOME}" && -d "${ORIGINAL_HOME}/.rustup" ]]; then
+  export RUSTUP_HOME="${ORIGINAL_HOME}/.rustup"
+fi
+
+export HOME="${CARGO_BUILD_HOME}"
+export CARGO_HOME
+export CARGO_TARGET_DIR
+export SCCACHE_DIR
+
+cat >"${CARGO_HOME}/config.toml" <<'CARGO_CONFIG'
+[registries.crates-io]
+protocol = "sparse"
+CARGO_CONFIG
+
+echo "[cargo-env] HOME=${HOME}"
+echo "[cargo-env] CARGO_HOME=${CARGO_HOME}"
+echo "[cargo-env] CARGO_TARGET_DIR=${CARGO_TARGET_DIR}"
+echo "[cargo-env] SCCACHE_DIR=${SCCACHE_DIR}"
+if [[ -n "${RUSTUP_HOME:-}" ]]; then
+  echo "[cargo-env] RUSTUP_HOME=${RUSTUP_HOME}"
+fi