chore: pass web port through jenkins deploy

docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md

@@ -8,7 +8,7 @@
 
 1. `构建`：只负责在仓库根目录执行 `npm run deploy:rust:remote -- --skip-upload`，生成发布包。
 2. `部署`：只负责把指定发布版本部署到 `/var/lib/jenkins/deploy/Genarrative/`，允许人工按参数启动，并支持按参数决定是否清空 SpacetimeDB 数据。
-3. `构建并部署`：先构建，再把构建出的版本号传给 `部署` 流水线并等待部署完成；同时暴露 `WEB_PORT` 参数，默认把发布包 Web 端口写成 `80`，并透传是否清库。
+3. `构建并部署`：先构建，再把构建出的版本号传给 `部署` 流水线并等待部署完成；同时暴露 `WEB_PORT` 参数，默认把发布包 Web 端口写成 `25001`，并把同名端口参数继续透传给下游部署，部署阶段以该参数作为最终监听端口。
 
 本次只补 Jenkins 编排与本地部署脚本，不改现有 Rust 发布包构建逻辑，不恢复旧 `server-node` 部署链。
 
@@ -24,6 +24,7 @@
 8. `部署` 流水线读取触发原因时必须使用 `currentBuild.getBuildCauses(...)` 这类白名单方法，不能直接访问 `currentBuild.rawBuild`，否则会被 Jenkins Script Security 拦截。
 9. 由于 Jenkins Pipeline 的 `build` 步骤触发下游时，原因类型通常是 `org.jenkinsci.plugins.workflow.support.steps.build.BuildUpstreamCause`，实现上需要同时兼容它和经典的 `hudson.model.Cause$UpstreamCause`，否则会把真实的上游触发误判成人工执行。
 10. 如果线上进程的启停必须经过 `sudo`，只允许 `start.sh` / `stop.sh` 这两个 hook 使用 `sudo -n` 执行，部署目录清空与文件覆盖仍保持普通权限。
+11. `WEB_PORT` 必须在 `构建并部署` 与 `部署` 两条流水线之间使用同名参数传递；部署脚本会把最终端口写入固定部署目录 `.env.local` 的 `GENARRATIVE_WEB_PORT`，避免 `sudo` 启动 hook 时环境变量被清理导致端口回退。
 
 ## 3. 节点与工作区要求
 
@@ -85,6 +86,7 @@ jenkins/Jenkinsfile.deploy
 scripts/jenkins-deploy-release.sh \
   --source-dir <SOURCE_WORKSPACE_ROOT>/build/<BUILD_VERSION> \
   --deploy-dir /var/lib/jenkins/deploy/Genarrative \
+  --web-port <WEB_PORT> \
   [--clear-database] \
   --hook-with-sudo
 ```
@@ -94,12 +96,12 @@ scripts/jenkins-deploy-release.sh \
 1. 若部署目录已有旧版本且存在 `stop.sh`，先执行旧版本 `stop.sh`。
 2. 只删除发布产物白名单中的旧文件，例如 `web/`、`api-server`、`spacetime_module.wasm`、`.env*`、`start.sh`、`stop.sh`、`web-server.mjs`、`README.md`。
 3. 将指定版本目录中的同名发布产物移动到部署目录。
-4. 如果 `CLEAR_DATABASE=true`，部署脚本会以 `./start.sh --clear-database` 启动新版本；这样发布阶段的 `spacetime publish` 会追加 `-c always`。
+4. 如果 `CLEAR_DATABASE=true`，部署脚本会以 `./start.sh --clear-database` 启动新版本；这样发布阶段的 `spacetime publish` 会追加 `-c=on-conflict`。
 5. 执行新版本 `start.sh`。
 
 如果 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，第 1 步和第 4 步会改为 `sudo -n` 调用；这要求 Jenkins 运行用户提前配置免密 sudo，否则部署会直接失败，不会进入交互式密码提示。
 
-这样可以满足“发布文件直接覆盖”的要求，同时保留部署目录里像 `spacetimedb-data/`、`logs/`、`run/` 这类运行态目录，不会因为部署被整体删除。发布白名单内的 `.env`、`.env.local` 仍会以构建产物中的文件为准；部署脚本会在启动 hook 前移除这些环境文件中的 UTF-8 BOM 与 CRLF，避免 `start.sh` 在 Bash 下把首行变量名误解析成命令。
+这样可以满足“发布文件直接覆盖”的要求，同时保留部署目录里像 `spacetimedb-data/`、`logs/`、`run/` 这类运行态目录，不会因为部署被整体删除。发布白名单内的 `.env`、`.env.local` 会先以构建产物中的文件为准；部署脚本会在启动 hook 前移除这些环境文件中的 UTF-8 BOM 与 CRLF，并把 Jenkins 部署参数 `WEB_PORT` 写入 `.env.local` 的 `GENARRATIVE_WEB_PORT`，避免 `start.sh` 在 Bash 下把首行变量名误解析成命令，也避免端口配置只停留在上游构建阶段。
 
 ### 4.3 构建并部署
 
@@ -115,12 +117,13 @@ jenkins/Jenkinsfile.build-and-deploy
 2. 复用与 `构建` 相同的构建命令生成 `build/<BUILD_VERSION>/`。
 3. 归档 `build/<BUILD_VERSION>/**`。
 4. 记录当前 `NODE_NAME`、源码根目录、版本号。
-5. 构建时额外透传 `--web-port <WEB_PORT>`，默认生成监听 `80` 的发布包。
+5. 构建时额外透传 `--web-port <WEB_PORT>`，默认生成监听 `25001` 的发布包。
 6. 触发 `部署` 流水线，并传递：
    - `BUILD_VERSION`
    - `SOURCE_WORKSPACE_ROOT`
    - `SOURCE_NODE_NAME`
    - `DEPLOY_DIRECTORY`
+   - `WEB_PORT`
    - `CLEAR_DATABASE`
    - `EXPECTED_UPSTREAM_JOB`
 
@@ -132,7 +135,7 @@ jenkins/Jenkinsfile.build-and-deploy
 2. `GENARRATIVE_WORKSPACE_ROOT`：源码根目录；为空时回退到 Jenkins 当前工作区。
 3. `BUILD_VERSION`：发布版本号；为空时回退到 `BUILD_NUMBER`。
 4. `RUN_NPM_CI`：是否在构建前执行 `npm ci`。
-5. `WEB_PORT`：发布包内静态网站监听端口；`构建并部署` 默认值为 `80`。
+5. `WEB_PORT`：静态网站监听端口；`构建并部署` 默认值为 `25001`，并通过下游 `部署` 同名参数作为最终启动端口。
 6. `CLEAR_DATABASE`：部署阶段是否清空 SpacetimeDB 数据后再发布 wasm；默认 `false`。
 
 如果当前 Jenkins 没有额外配置独立 Agent，而是直接在控制器自身执行任务，`AGENT_LABEL` 应填写 `built-in`。
@@ -147,6 +150,7 @@ jenkins/Jenkinsfile.build-and-deploy
 4. `CLEAR_DATABASE`
 5. `RUN_DEPLOY_HOOKS_WITH_SUDO`
 6. `EXPECTED_UPSTREAM_JOB`
+7. `WEB_PORT`
 
 其中仅 `构建并部署` 流水线还需要：