fix(release): bake deploy defaults into start script

docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md

@@ -104,7 +104,7 @@ npm run deploy:rust:remote
 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/` 下。
 7. 在目标目录写入 `web-server.mjs`，用于托管 `web/` 并把 `/api/*`、`/generated-*`、`/healthz` 反代到本包内的 `api-server`。
-8. 在目标目录写入 `start.sh` 与 `stop.sh`。
+8. 在目标目录写入 `start.sh` 与 `stop.sh`；`start.sh` 会先加载发布目录根部的 `.env`、`.env.local`，再回退到构建时通过 `--database`、`--api-port`、`--web-port`、`--spacetime-host`、`--spacetime-port` 写入的默认值。
 9. 默认执行 `scp -r -i ~\.ssh\dsk.pem build/<timestamp> ubuntu@82.157.175.59:/home/ubuntu/genarrative/` 上传发布包。
 
 发布包结构：
@@ -143,7 +143,7 @@ cd build/<timestamp>
 安全边界：
 
 1. 构建脚本会把仓库根目录已有的 `.env`、`.env.local` 一并复制进发布包，因此运行前必须确认这些文件内容适合被带入目标环境。
-2. 如果仓库根目录不存在 `.env` 或 `.env.local`，脚本会打印跳过日志，但不会因此失败。
+2. 如果仓库根目录不存在 `.env` 或 `.env.local`，脚本会打印跳过日志，但不会因此失败；此时 `start.sh` 仅使用构建时写入的默认值与运行时显式传入的环境变量。
 3. `start.sh` 默认不清空 SpacetimeDB；只有显式执行 `./start.sh --clear-database` 才允许清库重发。
 4. `start.sh` 使用 `spacetime publish --bin-path spacetime_module.wasm --yes` 发布当前包内 wasm。
 5. 当前脚本是单目录进程启动方案，不替代生产 systemd、Nginx、TLS、日志轮转与守护进程配置。

scripts/deploy-rust-remote.sh

@@ -3,7 +3,7 @@
 set -euo pipefail
 
 usage() {
-  cat <<'EOF'
+  cat <<EOF
 用法:
   npm run deploy:rust:remote
   ./scripts/deploy-rust-remote.sh --name 20260422-153000
@@ -17,13 +17,13 @@ usage() {
 
 常用参数:
   --name <folder-name>              指定 build 子目录名，默认使用当前时间 YYYYmmdd-HHMMSS
-  --database <database>             SpacetimeDB database，默认 genarrative-dev
-  --api-port <port>                 api-server 端口，默认 8082
-  --web-port <port>                 静态网站端口，默认 3000
-  --spacetime-port <port>           SpacetimeDB 端口，默认 3101
-  --ssh-key <path>                  上传使用的 SSH 私钥，默认 ~\.ssh\dsk.pem
-  --remote <user@host>              上传目标 SSH 主机，默认 ubuntu@82.157.175.59
-  --remote-dir <path>               上传目标目录，默认 /home/ubuntu/genarrative
+  --database <database>             SpacetimeDB database，默认 ${DATABASE}
+  --api-port <port>                 api-server 端口，默认 ${API_PORT}
+  --web-port <port>                 静态网站端口，默认 ${WEB_PORT}
+  --spacetime-port <port>           SpacetimeDB 端口，默认 ${SPACETIME_PORT}
+  --ssh-key <path>                  上传使用的 SSH 私钥，默认 ${SSH_KEY}
+  --remote <user@host>              上传目标 SSH 主机，默认 ${REMOTE_TARGET}
+  --remote-dir <path>               上传目标目录，默认 ${REMOTE_DIR}
   --skip-upload                     只生成本地发布包，不上传服务器
   --skip-web-build                  跳过 Vite 构建，仅用于调试
   --skip-api-build                  跳过 api-server 构建，仅用于调试
@@ -101,6 +101,17 @@ remote_shell_quote() {
   printf "'%s'" "$(printf "%s" "${value}" | sed "s/'/'\\\\''/g")"
 }
 
+replace_placeholder_in_file() {
+  local file_path="$1"
+  local placeholder="$2"
+  local value="$3"
+  local escaped_value="${value//\\/\\\\}"
+
+  escaped_value="${escaped_value//&/\\&}"
+  escaped_value="${escaped_value//|/\\|}"
+  sed -i "s|${placeholder}|${escaped_value}|g" "${file_path}"
+}
+
 SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
 SERVER_RS_DIR="${REPO_ROOT}/server-rs"
@@ -409,20 +420,25 @@ set -euo pipefail
 SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 PID_DIR="${SCRIPT_DIR}/run"
 LOG_DIR="${SCRIPT_DIR}/logs"
-SPACETIME_DATA_DIR="${GENARRATIVE_SPACETIME_DATA_DIR:-${SCRIPT_DIR}/spacetimedb-data}"
-SPACETIME_HOST="${GENARRATIVE_SPACETIME_HOST:-127.0.0.1}"
-SPACETIME_PORT="${GENARRATIVE_SPACETIME_PORT:-3101}"
-SPACETIME_SERVER_URL="${GENARRATIVE_SPACETIME_SERVER_URL:-http://${SPACETIME_HOST}:${SPACETIME_PORT}}"
-SPACETIME_DATABASE="${GENARRATIVE_SPACETIME_DATABASE:-genarrative-dev}"
-API_HOST="${GENARRATIVE_API_HOST:-127.0.0.1}"
-API_PORT="${GENARRATIVE_API_PORT:-8082}"
-API_LOG="${GENARRATIVE_API_LOG:-info,tower_http=info}"
-WEB_HOST="${GENARRATIVE_WEB_HOST:-0.0.0.0}"
-WEB_PORT="${GENARRATIVE_WEB_PORT:-3000}"
 CLEAR_DATABASE=0
 
 cd "${SCRIPT_DIR}"
 
+load_env_file() {
+  local env_file="$1"
+
+  if [[ ! -f "${env_file}" ]]; then
+    return
+  fi
+
+  echo "[start] 加载环境文件: ${env_file}"
+  set -a
+  # 发布包内环境文件由当前构建脚本生成，允许在启动时作为默认环境源加载。
+  # shellcheck disable=SC1090
+  source "${env_file}"
+  set +a
+}
+
 usage() {
   cat <<'EOF'
 用法:
@@ -454,6 +470,20 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+load_env_file "${SCRIPT_DIR}/.env"
+load_env_file "${SCRIPT_DIR}/.env.local"
+
+SPACETIME_DATA_DIR="${GENARRATIVE_SPACETIME_DATA_DIR:-${SCRIPT_DIR}/spacetimedb-data}"
+SPACETIME_HOST="${GENARRATIVE_SPACETIME_HOST:-__GENARRATIVE_DEFAULT_SPACETIME_HOST__}"
+SPACETIME_PORT="${GENARRATIVE_SPACETIME_PORT:-__GENARRATIVE_DEFAULT_SPACETIME_PORT__}"
+SPACETIME_SERVER_URL="${GENARRATIVE_SPACETIME_SERVER_URL:-http://${SPACETIME_HOST}:${SPACETIME_PORT}}"
+SPACETIME_DATABASE="${GENARRATIVE_SPACETIME_DATABASE:-__GENARRATIVE_DEFAULT_SPACETIME_DATABASE__}"
+API_HOST="${GENARRATIVE_API_HOST:-__GENARRATIVE_DEFAULT_API_HOST__}"
+API_PORT="${GENARRATIVE_API_PORT:-__GENARRATIVE_DEFAULT_API_PORT__}"
+API_LOG="${GENARRATIVE_API_LOG:-info,tower_http=info}"
+WEB_HOST="${GENARRATIVE_WEB_HOST:-__GENARRATIVE_DEFAULT_WEB_HOST__}"
+WEB_PORT="${GENARRATIVE_WEB_PORT:-__GENARRATIVE_DEFAULT_WEB_PORT__}"
+
 require_command() {
   local command_name="$1"
 
@@ -540,6 +570,14 @@ echo "[start] API: http://${API_HOST}:${API_PORT}"
 echo "[start] SpacetimeDB: ${SPACETIME_SERVER_URL}"
 START_SCRIPT
 
+replace_placeholder_in_file "${TARGET_DIR}/start.sh" "__GENARRATIVE_DEFAULT_SPACETIME_HOST__" "${SPACETIME_HOST}"
+replace_placeholder_in_file "${TARGET_DIR}/start.sh" "__GENARRATIVE_DEFAULT_SPACETIME_PORT__" "${SPACETIME_PORT}"
+replace_placeholder_in_file "${TARGET_DIR}/start.sh" "__GENARRATIVE_DEFAULT_SPACETIME_DATABASE__" "${DATABASE}"
+replace_placeholder_in_file "${TARGET_DIR}/start.sh" "__GENARRATIVE_DEFAULT_API_HOST__" "${API_HOST}"
+replace_placeholder_in_file "${TARGET_DIR}/start.sh" "__GENARRATIVE_DEFAULT_API_PORT__" "${API_PORT}"
+replace_placeholder_in_file "${TARGET_DIR}/start.sh" "__GENARRATIVE_DEFAULT_WEB_HOST__" "${WEB_HOST}"
+replace_placeholder_in_file "${TARGET_DIR}/start.sh" "__GENARRATIVE_DEFAULT_WEB_PORT__" "${WEB_PORT}"
+
 cat >"${TARGET_DIR}/stop.sh" <<'STOP_SCRIPT'
 #!/usr/bin/env bash
 
@@ -611,6 +649,8 @@ cat >"${TARGET_DIR}/README.md" <<EOF
 
 ## 环境变量
 
+- 启动时会先加载发布目录根部的 \`.env\` 与 \`.env.local\`，再回退到脚本内默认值。
+- 脚本内默认值来自构建时的 `--database`、`--api-port`、`--web-port`、`--spacetime-host`、`--spacetime-port` 参数。
 - \`GENARRATIVE_WEB_HOST\` / \`GENARRATIVE_WEB_PORT\`
 - \`GENARRATIVE_API_HOST\` / \`GENARRATIVE_API_PORT\` / \`GENARRATIVE_API_LOG\`
 - \`GENARRATIVE_SPACETIME_HOST\` / \`GENARRATIVE_SPACETIME_PORT\`