feat(jenkins): support sudo deploy hooks

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 命名