chore: update spacetime deploy pipeline controls

docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md

@@ -7,8 +7,8 @@
 本方案为当前仓库补齐 3 条 Jenkins 流水线：
 
 1. `构建`：只负责在仓库根目录执行 `npm run deploy:rust:remote -- --skip-upload`，生成发布包。
-2. `部署`：只负责把指定发布版本部署到 `/var/lib/jenkins/deploy/Genarrative/`，禁止人工直接点击执行。
-3. `构建并部署`：先构建，再把构建出的版本号传给 `部署` 流水线并等待部署完成。
+2. `部署`：只负责把指定发布版本部署到 `/var/lib/jenkins/deploy/Genarrative/`，禁止人工直接点击执行，并支持按参数决定是否清空 SpacetimeDB 数据。
+3. `构建并部署`：先构建，再把构建出的版本号传给 `部署` 流水线并等待部署完成；同时暴露 `WEB_PORT` 参数，默认把发布包 Web 端口写成 `80`，并透传是否清库。
 
 本次只补 Jenkins 编排与本地部署脚本，不改现有 Rust 发布包构建逻辑，不恢复旧 `server-node` 部署链。
 
@@ -83,6 +83,7 @@ jenkins/Jenkinsfile.deploy
 scripts/jenkins-deploy-release.sh \
   --source-dir <SOURCE_WORKSPACE_ROOT>/build/<BUILD_VERSION> \
   --deploy-dir /var/lib/jenkins/deploy/Genarrative \
+  [--clear-database] \
   --hook-with-sudo
 ```
 
@@ -91,7 +92,8 @@ 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. 执行新版本 `start.sh`。
+4. 如果 `CLEAR_DATABASE=true`，部署脚本会以 `./start.sh --clear-database` 启动新版本；这样发布阶段的 `spacetime publish` 会追加 `-c always`。
+5. 执行新版本 `start.sh`。
 
 如果 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，第 1 步和第 4 步会改为 `sudo -n` 调用；这要求 Jenkins 运行用户提前配置免密 sudo，否则部署会直接失败，不会进入交互式密码提示。
 
@@ -110,11 +112,13 @@ jenkins/Jenkinsfile.build-and-deploy
 1. 复用与 `构建` 相同的构建命令生成 `build/<BUILD_VERSION>/`。
 2. 归档 `build/<BUILD_VERSION>/**`。
 3. 记录当前 `NODE_NAME`、源码根目录、版本号。
-4. 触发 `部署` 流水线，并传递：
+4. 构建时额外透传 `--web-port <WEB_PORT>`，默认生成监听 `80` 的发布包。
+5. 触发 `部署` 流水线，并传递：
    - `BUILD_VERSION`
    - `SOURCE_WORKSPACE_ROOT`
    - `SOURCE_NODE_NAME`
    - `DEPLOY_DIRECTORY`
+   - `CLEAR_DATABASE`
    - `EXPECTED_UPSTREAM_JOB`
 
 ## 5. Jenkins 参数建议
@@ -125,6 +129,8 @@ 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`。
+6. `CLEAR_DATABASE`：部署阶段是否清空 SpacetimeDB 数据后再发布 wasm；默认 `false`。
 
 如果当前 Jenkins 没有额外配置独立 Agent，而是直接在控制器自身执行任务，`AGENT_LABEL` 应填写 `built-in`。
 如果 Jenkins 进程以默认 `jenkins` 用户运行，部署目录建议直接放在 `/var/lib/jenkins/deploy/Genarrative` 这类 Jenkins 自有目录下，避免再依赖 `/home/ubuntu/*` 的额外写权限。
@@ -135,13 +141,16 @@ jenkins/Jenkinsfile.build-and-deploy
 1. `SOURCE_WORKSPACE_ROOT`
 2. `SOURCE_NODE_NAME`
 3. `DEPLOY_DIRECTORY`
-4. `RUN_DEPLOY_HOOKS_WITH_SUDO`
-5. `EXPECTED_UPSTREAM_JOB`
+4. `CLEAR_DATABASE`
+5. `RUN_DEPLOY_HOOKS_WITH_SUDO`
+6. `EXPECTED_UPSTREAM_JOB`
 
 其中仅 `构建并部署` 流水线还需要：
 
 1. `DEPLOY_JOB_NAME`
 2. `RUN_DEPLOY_HOOKS_WITH_SUDO`
+3. `WEB_PORT`
+4. `CLEAR_DATABASE`
 
 如果你选择启用 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，推荐提前在服务器上增加一份最小 sudoers 配置，例如：