Fix Jenkins deploy database logging and validation

docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md

@@ -101,13 +101,13 @@ scripts/jenkins-deploy-release.sh \
 2. 覆盖前如果旧部署目录存在 `migration-bootstrap-secret.txt`，先复制到 `deploy-state/migration-bootstrap-secret.previous.txt`，供新版本 `start.sh` 在 schema 冲突自动迁移时授权导出旧库。该文件属于 Jenkins 部署状态，不放入 `run/`，避免 `sudo` 启停脚本生成的 root 私有运行目录阻断后续部署写入。
 3. 只删除发布产物白名单中的旧文件，例如 `web/`、`api-server`、`spacetime_module.wasm`、`migration-bootstrap-secret.txt`、`scripts/`、`.env*`、`start.sh`、`stop.sh`、`web-server.mjs`、`README.md`。
 4. 将指定版本目录中的同名发布产物复制到部署目录；文件产物使用普通复制，`web/`、`scripts/` 等目录产物必须递归复制。
-5. 把 `WEB_PORT`、`MIGRATE_ON_CONFLICT`、`MIGRATION_DIRECTORY` 写入部署目录 `.env.local`，确保通过 sudo 执行 `start.sh` 时仍能读取 Jenkins 参数。
+5. 把 `WEB_PORT`、`MIGRATE_ON_CONFLICT`、`MIGRATION_DIRECTORY` 写入部署目录 `.env.local`，确保通过 sudo 执行 `start.sh` 时仍能读取 Jenkins 参数；启动前读取 `.env` 与 `.env.local` 中最终的 `GENARRATIVE_SPACETIME_DATABASE`，打印并校验其符合 SpacetimeDB 数据库名规则。
 6. 如果 `CLEAR_DATABASE=true`，部署脚本会以 `./start.sh --clear-database` 启动新版本；这样发布阶段的 `spacetime publish` 会追加 `-c=on-conflict`，代表人工确认清库，不进入自动导出和回灌。
 7. 执行新版本 `start.sh`；普通发布遇到 schema 冲突时，默认由发布包内迁移脚本自动导出旧库、清库发布新 wasm、导入回灌。
 
 如果 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，旧版本 `stop.sh` 和新版本 `start.sh` 会改为 `sudo -n` 调用；这要求 Jenkins 运行用户提前配置免密 sudo，否则部署会直接失败，不会进入交互式密码提示。
 
-这样可以满足“发布文件直接覆盖”的要求，同时保留部署目录里像 `.spacetimedb/`、`logs/`、`run/`、`deploy-state/`、`database-migrations/` 这类运行态目录，不会因为部署被整体删除。`run/` 只承载 pid 等启停运行状态；`deploy-state/` 承载 Jenkins 覆盖部署前保存的旧迁移引导密钥，必须由 Jenkins 用户保持可写。发布白名单内的 `.env`、`.env.local` 会先以构建产物中的文件为准；部署脚本会在启动 hook 前移除这些环境文件中的 UTF-8 BOM 与 CRLF，并把 Jenkins 部署参数 `WEB_PORT` 写入 `.env.local` 的 `GENARRATIVE_WEB_PORT`，把 `MIGRATE_ON_CONFLICT` 写入 `GENARRATIVE_SPACETIME_MIGRATE_ON_CONFLICT`，把 `MIGRATION_DIRECTORY` 写入 `GENARRATIVE_SPACETIME_MIGRATION_DIR`，避免 `start.sh` 在 Bash 下把首行变量名误解析成命令，也避免端口和迁移配置只停留在上游构建阶段。`start.sh` 会先执行 Ubuntu 专用 `sync_ubuntu_spacetime_install`，优先从 `/usr/.local/share/spacetime/bin/<version>/spacetimedb-cli` 或 `$HOME/.local/share/spacetime/bin/<version>/spacetimedb-cli` 同步到部署目录 `.spacetimedb/bin/current/spacetimedb-cli`，后续启动、探活和 root-dir 占用判定都使用部署目录内 `.spacetimedb/`，且不再额外设置 `--data-dir`，避免 Jenkins 机器全局 `spacetime login` 变化影响本地库更新；如遇 `403 Forbidden`，按 `SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md` 排查数据库所有者与 CLI 身份。
+这样可以满足“发布文件直接覆盖”的要求，同时保留部署目录里像 `.spacetimedb/`、`logs/`、`run/`、`deploy-state/`、`database-migrations/` 这类运行态目录，不会因为部署被整体删除。`run/` 只承载 pid 等启停运行状态；`deploy-state/` 承载 Jenkins 覆盖部署前保存的旧迁移引导密钥，必须由 Jenkins 用户保持可写。发布白名单内的 `.env`、`.env.local` 会先以构建产物中的文件为准；部署脚本会在启动 hook 前移除这些环境文件中的 UTF-8 BOM 与 CRLF，并把 Jenkins 部署参数 `WEB_PORT` 写入 `.env.local` 的 `GENARRATIVE_WEB_PORT`，把 `MIGRATE_ON_CONFLICT` 写入 `GENARRATIVE_SPACETIME_MIGRATE_ON_CONFLICT`，把 `MIGRATION_DIRECTORY` 写入 `GENARRATIVE_SPACETIME_MIGRATION_DIR`，并在启动前输出最终 `GENARRATIVE_SPACETIME_DATABASE`，避免 `start.sh` 在 Bash 下把首行变量名误解析成命令，也避免端口、数据库名和迁移配置只停留在上游构建阶段。`start.sh` 会先执行 Ubuntu 专用 `sync_ubuntu_spacetime_install`，优先从 `/usr/.local/share/spacetime/bin/<version>/spacetimedb-cli` 或 `$HOME/.local/share/spacetime/bin/<version>/spacetimedb-cli` 同步到部署目录 `.spacetimedb/bin/current/spacetimedb-cli`，后续启动、探活和 root-dir 占用判定都使用部署目录内 `.spacetimedb/`，且不再额外设置 `--data-dir`，避免 Jenkins 机器全局 `spacetime login` 变化影响本地库更新；如遇 `403 Forbidden`，按 `SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md` 排查数据库所有者与 CLI 身份。
 
 ### 4.3 构建并部署
 

docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md

@@ -140,7 +140,7 @@ npm run deploy:rust:remote
 3. 使用 Vite 构建前端 release 到目标目录的 `web/`。
 4. 执行 `cargo build -p api-server --release --target x86_64-unknown-linux-gnu --manifest-path server-rs/Cargo.toml`，并把 `api-server` 复制到目标目录。
 5. 执行 `cargo build -p spacetime-module --release --target wasm32-unknown-unknown --manifest-path server-rs/Cargo.toml`，并把 `spacetime_module.wasm` 复制到目标目录。
-6. 把仓库根目录的 `.env` 与 `.env.local` 分别复制到目标目录根部和目标目录的 `web/` 下；复制后统一移除 UTF-8 BOM 与 CRLF，避免目标服务器 Bash 加载环境文件失败。
+6. 把仓库根目录的 `.env` 与 `.env.local` 分别复制到目标目录根部和目标目录的 `web/` 下；复制后统一移除 UTF-8 BOM 与 CRLF，并把 `GENARRATIVE_SPACETIME_DATABASE` 覆盖为本次 `--database` 参数，避免 Jenkins 工作区里残留的旧 `.env.local` 覆盖发布包目标库。
 7. 在目标目录写入 `web-server.mjs`，用于托管 `web/` 并把 `/api/*`、`/generated-*`、`/healthz` 反代到本包内的 `api-server`。
 8. 在目标目录写入 `start.sh` 与 `stop.sh`；`start.sh` 会先按 `KEY=value` 子集加载发布目录根部的 `.env`、`.env.local`，兼容 UTF-8 BOM 与 CRLF，再回退到构建时通过 `--database`、`--api-port`、`--web-port`、`--spacetime-host`、`--spacetime-port` 写入的默认值，并默认导出 `NO_COLOR=1` 与 `CARGO_TERM_COLOR=never`，避免 ANSI 控制码写入日志文件；同时按 Ubuntu 发布环境使用发布目录内 `.spacetimedb/` 作为 root-dir，不再额外设置 `--data-dir`，启动前先执行 `sync_ubuntu_spacetime_install`，优先从 `/usr/.local/share/spacetime/bin/<version>/spacetimedb-cli` 或 `$HOME/.local/share/spacetime/bin/<version>/spacetimedb-cli` 同步到 `.spacetimedb/bin/current/spacetimedb-cli`，当前线上 `spacetime` 入口为 `/usr/local/bin/spacetime`；启动参数为 `spacetime --root-dir ./.spacetimedb start --edition standalone --listen-addr <host>:<port>`，探活必须确认 `server ping` 输出包含 `Server is online:`；普通启动先无清库发布，若 publish 输出可判定为 schema 冲突，则自动导出旧库、清库发布新 wasm、导入回灌；如果以 `--clear-database` 启动，则内部 `spacetime publish` 会追加 `-c=on-conflict`，代表人工确认清库，不触发自动回灌。
 9. 默认执行 `scp -r -i ~\.ssh\dsk.pem build/<timestamp> ubuntu@82.157.175.59:/home/ubuntu/genarrative/` 上传发布包。

jenkins/Jenkinsfile.deploy

@@ -99,12 +99,18 @@ pipeline {
       }
 
       steps {
+        script {
+          // 部署脚本使用当前 Deploy 作业 checkout 出来的版本，避免重放旧 build 目录时继续执行旧脚本。
+          env.DEPLOY_SCRIPT_PATH = "${pwd()}/scripts/jenkins-deploy-release.sh"
+        }
+
         dir("${params.SOURCE_WORKSPACE_ROOT}") {
           sh """
             bash -lc '
               set -euo pipefail
               test -d "build/${params.BUILD_VERSION}"
-              chmod +x scripts/jenkins-deploy-release.sh
+              deploy_script="${env.DEPLOY_SCRIPT_PATH}"
+              chmod +x "\${deploy_script}"
               deploy_args=(
                 --source-dir "build/${params.BUILD_VERSION}"
                 --deploy-dir "${params.DEPLOY_DIRECTORY}"
@@ -125,7 +131,7 @@ pipeline {
                 deploy_args+=(--hook-with-sudo)
               fi
               # 只部署上游已构建好的版本目录，避免部署阶段再次构建产生漂移。
-              ./scripts/jenkins-deploy-release.sh "\${deploy_args[@]}"
+              "\${deploy_script}" "\${deploy_args[@]}"
             '
           """
         }

scripts/deploy-rust-remote.sh

@@ -71,6 +71,31 @@ normalize_env_file() {
   cp "${temp_file}" "${env_file}"
 }
 
+write_env_override() {
+  local env_file="$1"
+  local key="$2"
+  local value="$3"
+  local temp_file="${env_file}.tmp.$$"
+
+  mkdir -p "$(dirname "${env_file}")"
+  if [[ -f "${env_file}" ]]; then
+    # 发布包参数是本次构建的权威值，必须覆盖从 Jenkins 工作区复制进来的旧 .env.local。
+    awk -v target_key="${key}" '
+      BEGIN {
+        pattern = "^[[:space:]]*(export[[:space:]]+)?" target_key "="
+      }
+      $0 !~ pattern {
+        print
+      }
+    ' "${env_file}" >"${temp_file}"
+  else
+    : >"${temp_file}"
+  fi
+
+  printf "%s=%s\n" "${key}" "${value}" >>"${temp_file}"
+  cp "${temp_file}" "${env_file}"
+}
+
 copy_optional_file() {
   local source_path="$1"
   local target_path_a="$2"
@@ -330,6 +355,8 @@ echo "[deploy:rust] 发布包目录: ${TARGET_DIR}"
 
 copy_optional_file "${REPO_ROOT}/.env" "${TARGET_DIR}/.env" "${WEB_DIR}/.env" ".env"
 copy_optional_file "${REPO_ROOT}/.env.local" "${TARGET_DIR}/.env.local" "${WEB_DIR}/.env.local" ".env.local"
+write_env_override "${TARGET_DIR}/.env.local" "GENARRATIVE_SPACETIME_DATABASE" "${DATABASE}"
+write_env_override "${WEB_DIR}/.env.local" "GENARRATIVE_SPACETIME_DATABASE" "${DATABASE}"
 
 if [[ "${SKIP_WEB_BUILD}" -ne 1 ]]; then
   echo "[deploy:rust] 构建 Vite release -> ${WEB_DIR}"

scripts/jenkins-deploy-release.sh

@@ -59,6 +59,15 @@ validate_port() {
   fi
 }
 
+validate_spacetime_database_name() {
+  local database="$1"
+
+  if [[ ! "${database}" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+    echo "[jenkins-deploy] GENARRATIVE_SPACETIME_DATABASE 必须匹配 SpacetimeDB 数据库名规则 ^[a-z0-9]+(-[a-z0-9]+)*$，只能使用小写字母、数字，并用单个短横线分隔: ${database}" >&2
+    exit 1
+  fi
+}
+
 normalize_env_file() {
   local env_file="$1"
   local temp_file="${env_file}.tmp.$$"
@@ -72,6 +81,57 @@ normalize_env_file() {
   cp "${temp_file}" "${env_file}"
 }
 
+read_env_value() {
+  local key="$1"
+  shift
+  local env_file=""
+  local line=""
+  local line_number=0
+  local parsed_key=""
+  local parsed_value=""
+  local value=""
+  local utf8_bom=$'\xef\xbb\xbf'
+
+  for env_file in "$@"; do
+    if [[ ! -f "${env_file}" ]]; then
+      continue
+    fi
+
+    line_number=0
+    while IFS= read -r line || [[ -n "${line}" ]]; do
+      line_number=$((line_number + 1))
+      if [[ "${line_number}" -eq 1 ]]; then
+        line="${line#"${utf8_bom}"}"
+      fi
+      line="${line%$'\r'}"
+
+      if [[ "${line}" =~ ^[[:space:]]*$ || "${line}" =~ ^[[:space:]]*# ]]; then
+        continue
+      fi
+
+      if [[ ! "${line}" =~ ^[[:space:]]*(export[[:space:]]+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$ ]]; then
+        continue
+      fi
+
+      parsed_key="${BASH_REMATCH[2]}"
+      parsed_value="${BASH_REMATCH[3]}"
+      if [[ "${parsed_key}" != "${key}" ]]; then
+        continue
+      fi
+
+      value="${parsed_value}"
+      if [[ "${#value}" -ge 2 && "${value:0:1}" == '"' && "${value: -1}" == '"' ]]; then
+        value="${value:1:${#value}-2}"
+        value="${value//\\\"/\"}"
+      elif [[ "${#value}" -ge 2 && "${value:0:1}" == "'" && "${value: -1}" == "'" ]]; then
+        value="${value:1:${#value}-2}"
+      fi
+    done <"${env_file}"
+  done
+
+  printf "%s" "${value}"
+}
+
 normalize_release_env_files() {
   local release_dir="$1"
 
@@ -337,6 +397,14 @@ write_env_override "${DEPLOY_DIR}/.env.local" "GENARRATIVE_WEB_PORT" "${WEB_PORT
 write_env_override "${DEPLOY_DIR}/.env.local" "GENARRATIVE_SPACETIME_MIGRATE_ON_CONFLICT" "${MIGRATE_ON_CONFLICT}"
 write_env_override "${DEPLOY_DIR}/.env.local" "GENARRATIVE_SPACETIME_MIGRATION_DIR" "${MIGRATION_DIR}"
 
+DEPLOY_DATABASE="$(read_env_value "GENARRATIVE_SPACETIME_DATABASE" "${DEPLOY_DIR}/.env" "${DEPLOY_DIR}/.env.local")"
+if [[ -z "${DEPLOY_DATABASE}" ]]; then
+  echo "[jenkins-deploy] 部署包未显式写入 GENARRATIVE_SPACETIME_DATABASE；将由 start.sh 使用构建时默认值。" >&2
+else
+  validate_spacetime_database_name "${DEPLOY_DATABASE}"
+  echo "[jenkins-deploy] SpacetimeDB 发布数据库: ${DEPLOY_DATABASE}"
+fi
+
 echo "[jenkins-deploy] 启动新版本: ${DEPLOY_DIR}"
 if [[ "${CLEAR_DATABASE}" == "1" ]]; then
   echo "[jenkins-deploy] 以清库模式启动新版本"