fix(deploy): preserve runtime data directories

docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md

@@ -89,13 +89,13 @@ scripts/jenkins-deploy-release.sh \
 脚本语义：
 
 1. 若部署目录已有旧版本且存在 `stop.sh`，先执行旧版本 `stop.sh`。
-2. 直接清空部署目录中的全部旧文件。
-3. 将指定版本目录中的内容移动到部署目录。
+2. 只删除发布产物白名单中的旧文件，例如 `web/`、`api-server`、`spacetime_module.wasm`、`.env*`、`start.sh`、`stop.sh`、`web-server.mjs`、`README.md`。
+3. 将指定版本目录中的同名发布产物移动到部署目录。
 4. 执行新版本 `start.sh`。
 
 如果 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，第 1 步和第 4 步会改为 `sudo -n` 调用；这要求 Jenkins 运行用户提前配置免密 sudo，否则部署会直接失败，不会进入交互式密码提示。
 
-这样可以满足你要求的“直接覆盖部署目录中的所有文件”。同时这也意味着部署目录内原有的 `.env`、`.env.local`、日志和本地 SpacetimeDB 数据都会被清掉，最终以构建产物中的文件为准。
+这样可以满足“发布文件直接覆盖”的要求，同时保留部署目录里像 `spacetimedb-data/`、`logs/`、`run/` 这类运行态目录，不会因为部署被整体删除。发布白名单内的 `.env`、`.env.local` 仍会以构建产物中的文件为准。
 
 ### 4.3 构建并部署
 

docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md

@@ -140,6 +140,8 @@ cd build/<timestamp>
 ./stop.sh
 ```
 
+如果后续通过 Jenkins 的部署脚本把发布包覆盖到固定部署目录，部署阶段默认只替换 `web/`、`api-server`、`spacetime_module.wasm`、`.env*`、`start.sh`、`stop.sh`、`web-server.mjs`、`README.md` 等发布产物，不会删除部署目录中的 `spacetimedb-data/`、`logs/`、`run/` 这类运行态目录。
+
 安全边界：
 
 1. 构建脚本会把仓库根目录已有的 `.env`、`.env.local` 一并复制进发布包，因此运行前必须确认这些文件内容适合被带入目标环境。

scripts/jenkins-deploy-release.sh

@@ -9,8 +9,8 @@ usage() {
 
 说明:
   1. 如果部署目录已有旧版本且存在 stop.sh，则先执行旧版本 stop.sh。
-  2. 直接清空部署目录中的全部旧文件。
-  3. 把指定发布目录中的内容移动到部署目录。
+  2. 仅删除并替换发布产物文件，保留部署目录中的运行数据目录。
+  3. 把指定发布目录中的内容覆盖到部署目录。
   4. 最后执行新版本 start.sh。
 
 参数:
@@ -33,6 +33,17 @@ require_argument() {
 SOURCE_DIR=""
 DEPLOY_DIR=""
 HOOK_WITH_SUDO="0"
+DEPLOY_ITEMS=(
+  ".env"
+  ".env.local"
+  "README.md"
+  "api-server"
+  "spacetime_module.wasm"
+  "start.sh"
+  "stop.sh"
+  "web"
+  "web-server.mjs"
+)
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -114,10 +125,20 @@ else
 fi
 
 echo "[jenkins-deploy] 清空部署目录: ${DEPLOY_DIR}"
-find "${DEPLOY_DIR}" -mindepth 1 -maxdepth 1 -exec rm -rf {} +
+for item in "${DEPLOY_ITEMS[@]}"; do
+  if [[ -e "${DEPLOY_DIR}/${item}" ]]; then
+    echo "[jenkins-deploy] 删除旧产物: ${DEPLOY_DIR}/${item}"
+    rm -rf "${DEPLOY_DIR:?}/${item}"
+  fi
+done
 
 echo "[jenkins-deploy] 移动发布内容: ${SOURCE_DIR} -> ${DEPLOY_DIR}"
-find "${SOURCE_DIR}" -mindepth 1 -maxdepth 1 -exec mv {} "${DEPLOY_DIR}/" \;
+for item in "${DEPLOY_ITEMS[@]}"; do
+  if [[ -e "${SOURCE_DIR}/${item}" ]]; then
+    echo "[jenkins-deploy] 覆盖产物: ${item}"
+    mv "${SOURCE_DIR}/${item}" "${DEPLOY_DIR}/"
+  fi
+done
 
 chmod +x "${DEPLOY_DIR}/start.sh"