From ea4706daa656e134810b90b81b136554c7855709 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Sun, 7 Jun 2026 17:34:17 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=AD=A3=20Jenkins=20=E5=8F=91?=
 =?UTF-8?q?=E5=B8=83=E6=BA=90=E7=A0=81=E6=A0=A1=E9=AA=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

API 发布流水线保留上游构建 commit

Jenkins 二次 checkout 改为浅拉优先并按需逐步加深

同步生产运维文档和团队排障记忆
---
 .hermes/shared-memory/pitfalls.md             |  4 +-
 ...发运维】本地开发验证与生产运维-2026-05-15.md |  2 +
 jenkins/Jenkinsfile.production-api-deploy     |  7 +-
 scripts/jenkins-checkout-source.sh            | 74 ++++++++++++++++---
 4 files changed, 69 insertions(+), 18 deletions(-)

diff --git a/.hermes/shared-memory/pitfalls.md b/.hermes/shared-memory/pitfalls.md
index 5f628f58..a6d8516b 100644
--- a/.hermes/shared-memory/pitfalls.md
+++ b/.hermes/shared-memory/pitfalls.md
@@ -1254,8 +1254,8 @@
 - 后续更新：该条仍适用于常规构建 / 发布流水线；`Genarrative-Server-Provision` 已在 2026-06-05 改为服务器初始化专用口径，不允许公网 Git fallback，Job 的 `Pipeline script from SCM` 和 Jenkinsfile 内部 checkout 都必须使用本机路径或目标 agent 可访问的内网 Git 源。
 - 现象：生产发布、数据库导入导出、服务器配置、构建或 `Genarrative-Full-Build-And-Deploy` 流水线执行 `GitSCM checkout` 时，如果 Jenkins 生成的 fetch 是 `+refs/heads/*:refs/remotes/origin/*`，公网 Git 链路可能在收包阶段以 `git-remote-https died of signal 15`、`curl 56 GnuTLS recv error (-9)`、`early EOF`、`invalid index-pack output` 失败；发布类流水线还可能先遇到 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git` 不可达。
 - 原因：`127.0.0.1` 只代表当前执行阶段的 agent 自身；当 release agent 与 Git 服务不在同一台机器，或本机 Git/Web 服务临时不可用时，固定写死 localhost 会阻断 Jenkinsfile 内部源码/脚本 checkout。即使只使用域名 Git，如果 `GitSCM` 没有显式 refspec 并开启 `CloneOption honorRefspec=true`，Jenkins Git 插件也会拉取所有分支。
-- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 `linux && genarrative-build` 的 `Genarrative-Full-Build-And-Deploy` 源码解析阶段、`Genarrative-Web-Build` checkout 阶段，以及部署/发布类 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；这些首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，只有指定 commit 时才允许加深历史做分支归属校验。
-- 验证：扫描本地 Jenkins live job `config.xml`，确认 SCM `<url>` 都是 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；扫描所有生产 Jenkinsfile 的首次 `GitSCM checkout`，确认 `userRemoteConfigs` 带 `+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}`，`CloneOption` 带 `honorRefspec: true`；运行 `bash -n scripts/jenkins-checkout-source.sh`。
+- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 `linux && genarrative-build` 的 `Genarrative-Full-Build-And-Deploy` 源码解析阶段、`Genarrative-Web-Build` checkout 阶段，以及部署/发布类 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；这些首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，指定 commit 时也先保持 `depth=1` 校验，浅历史无法证明归属时才按 `GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS` 逐步加深，最后才展开完整历史。发布流水线不得为了缩短 checkout 时间清空上游构建传入的 `COMMIT_HASH`。
+- 验证：扫描本地 Jenkins live job `config.xml`，确认 SCM `<url>` 都是 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；扫描所有生产 Jenkinsfile 的首次 `GitSCM checkout`，确认 `userRemoteConfigs` 带 `+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}`，`CloneOption` 带 `honorRefspec: true`；扫描发布流水线确认传给 `scripts/jenkins-checkout-source.sh` 的 `COMMIT_HASH` 未被硬编码为空；运行 `bash -n scripts/jenkins-checkout-source.sh`。
 - 关联：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`jenkins/Jenkinsfile.production-web-build`、`jenkins/Jenkinsfile.production-api-build`、`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-web-deploy`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-stdb-module-publish`、`jenkins/Jenkinsfile.production-server-provision`、`jenkins/Jenkinsfile.production-database-export`、`jenkins/Jenkinsfile.production-database-import`、`scripts/jenkins-checkout-source.sh`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
 
 ## Jenkins 可选参数在 set -u 下不能裸读
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 16e7939c..c0ab1715 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -250,6 +250,8 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 
 生产 Jenkins 的 `Pipeline script from SCM` 由 Jenkins controller 读取 Jenkinsfile。`Genarrative-Server-Provision` 是服务器初始化流水线，Job 配置里的 SCM URL 必须使用 controller 本机可访问的仓库路径或内网 Gitea 地址，不能使用 `https://git.genarrative.world/...`；否则日志一开始的 `Checking out git ... to read jenkins/Jenkinsfile.production-server-provision` 就会先从公网拉 Jenkinsfile。其它构建 / 发布流水线仍按各自 Jenkinsfile 的 checkout 口径执行；所有 `GitSCM checkout` 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`。
 
+`scripts/jenkins-checkout-source.sh` 是生产 Jenkinsfile 内部二次确认源码的统一入口。构建和发布流水线传入 `COMMIT_HASH` 时，脚本必须先保持 `depth=1` 浅拉，若上游 commit 已在浅历史内则直接校验并 checkout；只有浅历史无法证明 commit 属于目标分支时，才按 `GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS`（默认 `50 200 1000 5000`）逐步加深，最后才尝试展开完整历史。`Genarrative-Api-Deploy`、`Genarrative-Web-Deploy` 和 `Genarrative-Stdb-Module-Publish` 都必须保留上游构建传入的 `COMMIT_HASH`，不得为了缩短 checkout 时间改为空值或改用目标分支最新提交。
+
 
 `Genarrative-Stdb-Module-Publish` 在 `Pipeline script from SCM` 阶段如果一开始就报 `No such DSL method 'pipeline'`，优先检查 `jenkins/Jenkinsfile.production-stdb-module-publish` 是否带 UTF-8 BOM。Jenkins Declarative Pipeline 的首个 token 必须是纯 `pipeline`；仓库中的 Jenkinsfile 应保存为 UTF-8 without BOM，只有临时写给 Windows PowerShell 5.1 `-File` 执行的 `.ps1` 才需要按对应 helper 转成带 BOM。验证时可检查文件前三字节不再是 `EF BB BF`，并运行 `validateDeclarativePipeline` 或重放该流水线。
 
diff --git a/jenkins/Jenkinsfile.production-api-deploy b/jenkins/Jenkinsfile.production-api-deploy
index 8d17e08e..dcb824b6 100644
--- a/jenkins/Jenkinsfile.production-api-deploy
+++ b/jenkins/Jenkinsfile.production-api-deploy
@@ -89,17 +89,12 @@ pipeline {
             env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
           }
         }
-        script {
-          if (params.COMMIT_HASH?.trim()) {
-            echo "API 发布脚本 checkout 将忽略上游构建 commit=${params.COMMIT_HASH}，改用 ${params.SOURCE_BRANCH ?: 'master'} 最新提交，避免发布阶段回退到旧部署脚本。构建产物仍由 BUILD_NUMBER_TO_DEPLOY 决定。"
-          }
-        }
         sh '''
           bash -lc '
             set -euo pipefail
             chmod +x scripts/jenkins-checkout-source.sh
             SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
-            COMMIT_HASH="" \
+            COMMIT_HASH="${COMMIT_HASH:-}" \
             GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
             GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
             SOURCE_COMMIT_FILE=".jenkins-source-commit" \
diff --git a/scripts/jenkins-checkout-source.sh b/scripts/jenkins-checkout-source.sh
index 5ae89465..131bcd8e 100644
--- a/scripts/jenkins-checkout-source.sh
+++ b/scripts/jenkins-checkout-source.sh
@@ -51,11 +51,71 @@ fetch_source_branch() {
   fi
 
   echo "[jenkins-checkout-source] 尝试 Git 远端: ${remote_url:-origin}"
-  if [[ -z "${COMMIT_HASH}" ]]; then
-    git fetch --no-tags --prune --depth=1 origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
+  git fetch --no-tags --prune --depth=1 origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
+}
+
+is_shallow_repository() {
+  [[ "$(git rev-parse --is-shallow-repository 2>/dev/null || echo false)" == "true" ]]
+}
+
+resolve_requested_commit_if_on_branch() {
+  local requested_commit="$1"
+  local resolved_commit
+
+  if ! git cat-file -e "${requested_commit}^{commit}" 2>/dev/null; then
+    return 1
+  fi
+
+  resolved_commit="$(git rev-parse "${requested_commit}^{commit}")"
+  if ! git merge-base --is-ancestor "${resolved_commit}" "refs/remotes/origin/${SOURCE_BRANCH}" 2>/dev/null; then
+    return 1
+  fi
+
+  printf "%s\n" "${resolved_commit}"
+}
+
+resolve_requested_commit_with_deepen() {
+  local requested_commit="$1"
+  local deepen_steps_raw="${GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS:-50 200 1000 5000}"
+  local deepen_steps=()
+  local deepen_depth
+  local resolved_commit
+
+  # 中文注释：上游构建 commit 通常就是分支 HEAD，先吃浅克隆；确实不是浅历史内提交时再逐步加深。
+  if resolved_commit="$(resolve_requested_commit_if_on_branch "${requested_commit}")"; then
+    printf "%s\n" "${resolved_commit}"
+    return 0
+  fi
+
+  read -r -a deepen_steps <<<"${deepen_steps_raw}"
+  for deepen_depth in "${deepen_steps[@]}"; do
+    if [[ ! "${deepen_depth}" =~ ^[0-9]+$ || "${deepen_depth}" -le 1 ]]; then
+      echo "[jenkins-checkout-source] 忽略无效加深深度: ${deepen_depth}" >&2
+      continue
+    fi
+
+    echo "[jenkins-checkout-source] 浅历史未命中 commit=${requested_commit}，加深到 depth=${deepen_depth}" >&2
+    if is_shallow_repository; then
+      git fetch --no-tags --prune --depth="${deepen_depth}" origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
+    else
+      git fetch --no-tags --prune origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
+    fi
+
+    if resolved_commit="$(resolve_requested_commit_if_on_branch "${requested_commit}")"; then
+      printf "%s\n" "${resolved_commit}"
+      return 0
+    fi
+  done
+
+  if is_shallow_repository; then
+    echo "[jenkins-checkout-source] 逐步加深仍未命中 commit=${requested_commit}，最后尝试展开完整历史" >&2
+    git fetch --unshallow --no-tags origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}" || \
+      git fetch --no-tags --prune origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
   else
     git fetch --no-tags --prune origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
   fi
+
+  resolve_requested_commit_if_on_branch "${requested_commit}"
 }
 
 add_git_remote_candidate "${GIT_REMOTE_URL}"
@@ -80,17 +140,11 @@ else
   fi
 fi
 
-if [[ -n "${COMMIT_HASH}" && "$(git rev-parse --is-shallow-repository 2>/dev/null || echo false)" == "true" ]]; then
-  git fetch --unshallow --no-tags origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}" || true
-fi
-
 git cat-file -e "refs/remotes/origin/${SOURCE_BRANCH}^{commit}"
 
 if [[ -n "${COMMIT_HASH}" ]]; then
-  git cat-file -e "${COMMIT_HASH}^{commit}"
-  RESOLVED_COMMIT="$(git rev-parse "${COMMIT_HASH}^{commit}")"
-  if ! git merge-base --is-ancestor "${RESOLVED_COMMIT}" "refs/remotes/origin/${SOURCE_BRANCH}"; then
-    echo "[jenkins-checkout-source] 指定 commit 不属于 origin/${SOURCE_BRANCH}: ${RESOLVED_COMMIT}" >&2
+  if ! RESOLVED_COMMIT="$(resolve_requested_commit_with_deepen "${COMMIT_HASH}")"; then
+    echo "[jenkins-checkout-source] 指定 commit 不属于 origin/${SOURCE_BRANCH}: ${COMMIT_HASH}" >&2
     exit 1
   fi
 else