docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md

@@ -16,7 +16,7 @@
 
 1. 构建产物目录统一使用 `build/<版本号>/`。
 2. 默认使用 Jenkins `BUILD_NUMBER` 作为版本号，避免依赖时间戳；如有需要也允许显式传 `BUILD_VERSION`。
-3. `构建` 与 `构建并部署` 在 `checkout scm` 后、实际构建前必须执行 `git reset --hard HEAD` 与 `git clean -fd`，避免固定源码目录内的 Git 变更和未跟踪文件影响发布包；不使用 `-x`，避免删除 `node_modules/` 等忽略目录后与 `RUN_NPM_CI=false` 冲突。
+3. 所有使用仓库源码的 Jenkins 流水线在实际执行脚本前必须先执行 `git reset --hard HEAD`，避免固定源码目录内的 Git 变更影响本次构建、部署或迁移操作；其中 `构建` 与 `构建并部署` 在实际构建前还必须执行 `git clean -fd` 清理未跟踪文件，不使用 `-x`，避免删除 `node_modules/` 等忽略目录后与 `RUN_NPM_CI=false` 冲突。
 4. `构建并部署` 可选填写 `COMMIT_HASH`。留空时使用 Jenkins SCM 当前检出的提交；填写时只能是 7 到 40 位十六进制 commit hash，流水线会先按 SCM checkout 得到仓库，再尽量拉取 `origin` 全部分支引用、解析该 hash 并 detached checkout 到对应 commit 后构建。
 5. `部署` 流水线允许人工启动；没有上游触发 cause 时按人工部署处理，不再直接失败。
 6. `部署` 流水线仅在存在上游触发 cause 时校验上游作业名与传入的 `EXPECTED_UPSTREAM_JOB` 一致；如配置了环境变量 `GENARRATIVE_ALLOWED_UPSTREAM_JOB`，还必须与该值一致。
@@ -84,7 +84,8 @@ jenkins/Jenkinsfile.deploy
 
 1. 读取触发原因；人工启动时跳过上游门禁，上游触发时同时兼容 `BuildUpstreamCause` 与经典 `UpstreamCause` 并继续校验上游作业名。
 2. 校验 `BUILD_VERSION`、`SOURCE_WORKSPACE_ROOT`、`DEPLOY_DIRECTORY` 非空。
-3. 执行：
+3. 在 `SOURCE_WORKSPACE_ROOT` 内执行 `git reset --hard HEAD`，确保部署脚本和构建产物选择不受本地改动影响。
+4. 执行：
 
 ```bash
 scripts/jenkins-deploy-release.sh \

docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md

@@ -86,7 +86,8 @@ Genarrative-Database-Import
 2. `INCREMENTAL` 与 `REPLACE_EXISTING` 互斥，Jenkinsfile 会在执行前阻止同时启用。
 3. Jenkinsfile 不打印 token；生产环境应通过 Jenkins 凭据或目标机器环境变量传入敏感值。
 4. 如果不传 `TOKEN`，导入脚本会创建临时 Web API identity，并调用迁移授权/撤销 procedure 收敛权限窗口。
-5. 如果日志出现 `SpacetimeDB HTTP 413: Failed to buffer the request body: length limit exceeded`，优先把 `CHUNK_SIZE` 调低到 `262144` 或更小后重跑。该参数只降低单次 HTTP body，不改变导入表范围。
+5. 导入导出流水线在调用仓库内迁移脚本前都会执行 `git reset --hard HEAD`，确保固定源码目录中的本地改动不会影响本次迁移操作。
+6. 如果日志出现 `SpacetimeDB HTTP 413: Failed to buffer the request body: length limit exceeded`，优先把 `CHUNK_SIZE` 调低到 `262144` 或更小后重跑。该参数只降低单次 HTTP body，不改变导入表范围。
 
 ## 5. 本地部署测试参数
 

jenkins/Jenkinsfile.build-and-deploy

@@ -113,6 +113,8 @@ pipeline {
           sh '''
             bash -lc '
               set -euo pipefail
+              # 每条流水线开头先强制回到 SCM 检出的干净提交，避免固定源码目录残留改动影响本次执行。
+              git reset --hard HEAD
               requested_commit="${COMMIT_HASH:-}"
               if [[ -n "${requested_commit}" ]]; then
                 # Jenkins 先按 SCM 配置完成 checkout；如指定 commit，再拉取远端引用并切到该提交构建。

jenkins/Jenkinsfile.database-export

@@ -56,6 +56,8 @@ pipeline {
           sh """
             bash -lc '
               set -euo pipefail
+              # 导出流水线复用固定源码目录时，先清掉本地改动，确保执行的是 Jenkins SCM 检出的脚本。
+              git reset --hard HEAD
               export_dir="${params.OUTPUT_DIRECTORY}"
               if [[ -z "\${export_dir}" ]]; then
                 export_dir="database-exports"

jenkins/Jenkinsfile.database-import

@@ -70,6 +70,8 @@ pipeline {
           sh """
             bash -lc '
               set -euo pipefail
+              # 导入流水线复用固定源码目录时，先清掉本地改动，确保迁移脚本来自 Jenkins SCM 检出的版本。
+              git reset --hard HEAD
               args=(scripts/spacetime-import-migration-json.mjs --in "${params.INPUT_FILE}")
               if [[ -n "${params.DATABASE}" ]]; then
                 args+=(--database "${params.DATABASE}")

jenkins/Jenkinsfile.deploy

@@ -115,6 +115,8 @@ pipeline {
           sh """
             bash -lc '
               set -euo pipefail
+              # 部署流水线也先清回上游工作区的当前提交，避免复用目录中的本地改动影响部署脚本或产物选择。
+              git reset --hard HEAD
               test -d "build/${params.BUILD_VERSION}"
               deploy_script="${env.DEPLOY_SCRIPT_PATH}"
               chmod +x "\${deploy_script}"