diff --git a/docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md b/docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md
index 10404b3c..8c584969 100644
--- a/docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md
+++ b/docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md
@@ -22,6 +22,7 @@
 6. `部署` 不重新构建，不重新上传，不从 Jenkins 插件仓库复制产物，直接使用上游构建节点的本地 `build/<版本号>/` 目录。
 7. `部署` 流水线读取触发原因时必须使用 `currentBuild.getBuildCauses(...)` 这类白名单方法，不能直接访问 `currentBuild.rawBuild`，否则会被 Jenkins Script Security 拦截。
 8. 由于 Jenkins Pipeline 的 `build` 步骤触发下游时，原因类型通常是 `org.jenkinsci.plugins.workflow.support.steps.build.BuildUpstreamCause`，实现上需要同时兼容它和经典的 `hudson.model.Cause$UpstreamCause`，否则会把真实的上游触发误判成人工执行。
+9. 如果线上进程的启停必须经过 `sudo`，只允许 `start.sh` / `stop.sh` 这两个 hook 使用 `sudo -n` 执行，部署目录清空与文件覆盖仍保持普通权限。
 
 ## 3. 节点与工作区要求
 
@@ -81,7 +82,8 @@ jenkins/Jenkinsfile.deploy
 ```bash
 scripts/jenkins-deploy-release.sh \
   --source-dir <SOURCE_WORKSPACE_ROOT>/build/<BUILD_VERSION> \
-  --deploy-dir /var/lib/jenkins/deploy/Genarrative
+  --deploy-dir /var/lib/jenkins/deploy/Genarrative \
+  --hook-with-sudo
 ```
 
 脚本语义：
@@ -91,6 +93,8 @@ scripts/jenkins-deploy-release.sh \
 3. 将指定版本目录中的内容移动到部署目录。
 4. 执行新版本 `start.sh`。
 
+如果 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，第 1 步和第 4 步会改为 `sudo -n` 调用；这要求 Jenkins 运行用户提前配置免密 sudo，否则部署会直接失败，不会进入交互式密码提示。
+
 这样可以满足你要求的“直接覆盖部署目录中的所有文件”。同时这也意味着部署目录内原有的 `.env`、`.env.local`、日志和本地 SpacetimeDB 数据都会被清掉，最终以构建产物中的文件为准。
 
 ### 4.3 构建并部署
@@ -131,11 +135,22 @@ jenkins/Jenkinsfile.build-and-deploy
 1. `SOURCE_WORKSPACE_ROOT`
 2. `SOURCE_NODE_NAME`
 3. `DEPLOY_DIRECTORY`
-4. `EXPECTED_UPSTREAM_JOB`
+4. `RUN_DEPLOY_HOOKS_WITH_SUDO`
+5. `EXPECTED_UPSTREAM_JOB`
 
 其中仅 `构建并部署` 流水线还需要：
 
 1. `DEPLOY_JOB_NAME`
+2. `RUN_DEPLOY_HOOKS_WITH_SUDO`
+
+如果你选择启用 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，推荐提前在服务器上增加一份最小 sudoers 配置，例如：
+
+```text
+jenkins ALL=(root) NOPASSWD: /var/lib/jenkins/deploy/Genarrative/start.sh
+jenkins ALL=(root) NOPASSWD: /var/lib/jenkins/deploy/Genarrative/stop.sh
+```
+
+这样可以把提权范围收敛到固定部署目录下的启停脚本，而不是把整个部署流程都交给 `sudo`。
 
 ## 6. 推荐 Job 命名
 
diff --git a/jenkins/Jenkinsfile.build-and-deploy b/jenkins/Jenkinsfile.build-and-deploy
index b63cde20..88b66acd 100644
--- a/jenkins/Jenkinsfile.build-and-deploy
+++ b/jenkins/Jenkinsfile.build-and-deploy
@@ -13,6 +13,7 @@ pipeline {
     booleanParam(name: 'RUN_NPM_CI', defaultValue: false, description: '构建前是否执行 npm ci')
     string(name: 'DEPLOY_JOB_NAME', defaultValue: 'Genarrative-Deploy', description: '部署流水线作业名')
     string(name: 'DEPLOY_DIRECTORY', defaultValue: '/var/lib/jenkins/deploy/Genarrative', description: '固定部署目录')
+    booleanParam(name: 'RUN_DEPLOY_HOOKS_WITH_SUDO', defaultValue: true, description: 'start.sh / stop.sh 是否通过 sudo -n 执行')
   }
 
   stages {
@@ -65,6 +66,7 @@ pipeline {
             string(name: 'SOURCE_WORKSPACE_ROOT', value: env.WORKSPACE_ROOT),
             string(name: 'BUILD_VERSION', value: env.EFFECTIVE_BUILD_VERSION),
             string(name: 'DEPLOY_DIRECTORY', value: params.DEPLOY_DIRECTORY),
+            booleanParam(name: 'RUN_DEPLOY_HOOKS_WITH_SUDO', value: params.RUN_DEPLOY_HOOKS_WITH_SUDO),
             string(name: 'EXPECTED_UPSTREAM_JOB', value: env.JOB_NAME),
           ]
       }
diff --git a/jenkins/Jenkinsfile.deploy b/jenkins/Jenkinsfile.deploy
index e963c5cd..ce92e1b1 100644
--- a/jenkins/Jenkinsfile.deploy
+++ b/jenkins/Jenkinsfile.deploy
@@ -11,6 +11,7 @@ pipeline {
     string(name: 'SOURCE_WORKSPACE_ROOT', defaultValue: '', description: '上游源码根目录')
     string(name: 'BUILD_VERSION', defaultValue: '', description: '待部署版本号')
     string(name: 'DEPLOY_DIRECTORY', defaultValue: '/var/lib/jenkins/deploy/Genarrative', description: '固定部署目录')
+    booleanParam(name: 'RUN_DEPLOY_HOOKS_WITH_SUDO', defaultValue: true, description: 'start.sh / stop.sh 是否通过 sudo -n 执行')
     string(name: 'EXPECTED_UPSTREAM_JOB', defaultValue: '', description: '允许触发本作业的上游作业名')
   }
 
@@ -83,10 +84,15 @@ pipeline {
               set -euo pipefail
               test -d "build/${params.BUILD_VERSION}"
               chmod +x scripts/jenkins-deploy-release.sh
-              # 只部署上游已构建好的版本目录，避免部署阶段再次构建产生漂移。
-              ./scripts/jenkins-deploy-release.sh \
-                --source-dir "build/${params.BUILD_VERSION}" \
+              deploy_args=(
+                --source-dir "build/${params.BUILD_VERSION}"
                 --deploy-dir "${params.DEPLOY_DIRECTORY}"
+              )
+              if [[ "${params.RUN_DEPLOY_HOOKS_WITH_SUDO}" == "true" ]]; then
+                deploy_args+=(--hook-with-sudo)
+              fi
+              # 只部署上游已构建好的版本目录，避免部署阶段再次构建产生漂移。
+              ./scripts/jenkins-deploy-release.sh "\${deploy_args[@]}"
             '
           """
         }
diff --git a/scripts/jenkins-deploy-release.sh b/scripts/jenkins-deploy-release.sh
index 142e1d69..a5914d1a 100644
--- a/scripts/jenkins-deploy-release.sh
+++ b/scripts/jenkins-deploy-release.sh
@@ -5,7 +5,7 @@ set -euo pipefail
 usage() {
   cat <<'EOF'
 用法:
-  ./scripts/jenkins-deploy-release.sh --source-dir /path/to/build/123 --deploy-dir /var/lib/jenkins/deploy/Genarrative
+  ./scripts/jenkins-deploy-release.sh --source-dir /path/to/build/123 --deploy-dir /var/lib/jenkins/deploy/Genarrative [--hook-with-sudo]
 
 说明:
   1. 如果部署目录已有旧版本且存在 stop.sh，则先执行旧版本 stop.sh。
@@ -16,6 +16,7 @@ usage() {
 参数:
   --source-dir <path>     必填，待部署的发布目录，例如 build/123
   --deploy-dir <path>     必填，固定部署目录，例如 /var/lib/jenkins/deploy/Genarrative
+  --hook-with-sudo        可选，仅对 start.sh/stop.sh 使用 sudo -n 执行
 EOF
 }
 
@@ -31,6 +32,7 @@ require_argument() {
 
 SOURCE_DIR=""
 DEPLOY_DIR=""
+HOOK_WITH_SUDO="0"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -46,6 +48,10 @@ while [[ $# -gt 0 ]]; do
       DEPLOY_DIR="${2:?缺少 --deploy-dir 的值}"
       shift 2
       ;;
+    --hook-with-sudo)
+      HOOK_WITH_SUDO="1"
+      shift
+      ;;
     *)
       echo "[jenkins-deploy] 未知参数: $1" >&2
       usage >&2
@@ -57,6 +63,35 @@ done
 require_argument "${SOURCE_DIR}" "--source-dir"
 require_argument "${DEPLOY_DIR}" "--deploy-dir"
 
+run_hook() {
+  local hook_dir="$1"
+  local hook_name="$2"
+  local hook_path="${hook_dir}/${hook_name}"
+
+  if [[ ! -x "${hook_path}" ]]; then
+    echo "[jenkins-deploy] hook 不存在或不可执行: ${hook_path}" >&2
+    exit 1
+  fi
+
+  # 仅在启停脚本阶段使用 sudo，文件清理与移动仍保持普通权限，避免放大授权范围。
+  if [[ "${HOOK_WITH_SUDO}" == "1" ]]; then
+    echo "[jenkins-deploy] 使用 sudo 执行 ${hook_name}: ${hook_path}"
+    (
+      cd "${hook_dir}"
+      sudo -n "${hook_path}"
+    ) || {
+      echo "[jenkins-deploy] sudo 执行 ${hook_name} 失败，请确认 jenkins 用户已配置免密 sudo 权限。" >&2
+      exit 1
+    }
+    return
+  fi
+
+  (
+    cd "${hook_dir}"
+    "./${hook_name}"
+  )
+}
+
 if [[ ! -d "${SOURCE_DIR}" ]]; then
   echo "[jenkins-deploy] 发布目录不存在: ${SOURCE_DIR}" >&2
   exit 1
@@ -73,10 +108,7 @@ fi
 
 if [[ -x "${DEPLOY_DIR}/stop.sh" ]]; then
   echo "[jenkins-deploy] 先停止旧版本: ${DEPLOY_DIR}"
-  (
-    cd "${DEPLOY_DIR}"
-    ./stop.sh
-  )
+  run_hook "${DEPLOY_DIR}" "stop.sh"
 else
   echo "[jenkins-deploy] 部署目录无可执行 stop.sh，跳过停服"
 fi
@@ -87,12 +119,13 @@ find "${DEPLOY_DIR}" -mindepth 1 -maxdepth 1 -exec rm -rf {} +
 echo "[jenkins-deploy] 移动发布内容: ${SOURCE_DIR} -> ${DEPLOY_DIR}"
 find "${SOURCE_DIR}" -mindepth 1 -maxdepth 1 -exec mv {} "${DEPLOY_DIR}/" \;
 
-chmod +x "${DEPLOY_DIR}/start.sh" "${DEPLOY_DIR}/stop.sh"
+chmod +x "${DEPLOY_DIR}/start.sh"
+
+if [[ -f "${DEPLOY_DIR}/stop.sh" ]]; then
+  chmod +x "${DEPLOY_DIR}/stop.sh"
+fi
 
 echo "[jenkins-deploy] 启动新版本: ${DEPLOY_DIR}"
-(
-  cd "${DEPLOY_DIR}"
-  ./start.sh
-)
+run_hook "${DEPLOY_DIR}" "start.sh"
 
 echo "[jenkins-deploy] 完成"