GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

chore: update spacetime dev scripts

Browse Source
This commit is contained in:
kdletters
2026-04-24 15:35:04 +08:00
parent 4f369617c7
commit 04288d4a40
4 changed files with 91 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md
View File

@@ -1,4 +1,4 @@
# Rust 本地联调与远端发布脚本方案
# Rust 本地联调与远端发布脚本方案
日期：`2026-04-22`
@@ -32,12 +32,13 @@ npm run dev:rust
默认流程：
1. 检查 `cargo`、`node` 与 `spacetime` CLI。
2. 启动 `spacetime --root-dir=server-rs/.spacetimedb/local start --edition standalone --listen-addr 127.0.0.1:3101`，确保本地数据库与 SpacetimeDB 内部日志不会落到开发者全局目录。
3. 等待 `spacetime server ping http://127.0.0.1:3101` 可用。
4. 执行 `spacetime publish <本地数据库名> --server http://127.0.0.1:3101 --module-path server-rs/crates/spacetime-module --yes`。
5. 注入 `GENARRATIVE_API_*` 与 `GENARRATIVE_SPACETIME_*` 后启动 `cargo run -p api-server`；直接运行 `api-server` 时，如未显式设置 `GENARRATIVE_SPACETIME_DATABASE`，服务端也会向上查找 `spacetime.local.json` 作为本地默认库名。
6. 注入 `GENARRATIVE_BACKEND_STACK=rust`、`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET` 后启动 Vite。
7. 任一子进程退出时，脚本回收其余子进程。
2. Windows Git Bash 下如 `server-rs/.spacetimedb/local/bin/current/spacetimedb-cli.exe` 不存在，先把本机 `spacetime` 所在安装目录的 `bin/` 与 `spacetime.exe` 同步到 `server-rs/.spacetimedb/local/`。
3. 启动 `spacetime --root-dir=server-rs/.spacetimedb/local start --edition standalone --listen-addr 127.0.0.1:3101`，确保本地数据库与 SpacetimeDB 内部日志不会落到开发者全局目录。
4. 等待 `spacetime --root-dir=server-rs/.spacetimedb/local server ping http://127.0.0.1:3101` 可用。
5. 执行 `spacetime --root-dir=server-rs/.spacetimedb/local publish <本地数据库名> --server http://127.0.0.1:3101 --module-path server-rs/crates/spacetime-module -c=on-conflict --yes`，确保 publish 的签名身份与 standalone 的本地控制库一致，并在当前开发阶段允许新版模块表结构变化且发生 schema 冲突时清除旧模块数据。
6. 注入 `GENARRATIVE_API_*` 与 `GENARRATIVE_SPACETIME_*` 后启动 `cargo run -p api-server`；直接运行 `api-server` 时，如未显式设置 `GENARRATIVE_SPACETIME_DATABASE`，服务端也会向上查找 `spacetime.local.json` 作为本地默认库名。
7. 注入 `GENARRATIVE_BACKEND_STACK=rust`、`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET` 后启动 Vite。
8. 任一子进程退出时，脚本回收其余子进程。
Vite 代理覆盖范围：
@@ -47,10 +48,11 @@ Vite 代理覆盖范围：
安全边界：
1. 默认不执行 `--clear-database`。
2. 只有显式传入 `--clear-database` 才允许清库重发。
1. 当前开发阶段默认执行 `-c=on-conflict`，允许本地开发库在表结构变化时清除旧模块数据后重发。
2. 只有显式传入 `--preserve-database` 时，才跳过 `-c=on-conflict` 并保留现有数据。
3. 如需要复用已经启动的 SpacetimeDB，可传 `--skip-spacetime`。
4. 如只想启动进程不发布模块，可传 `--skip-publish`。
5. 后续进入正式版本前，涉及表结构变化时必须在开发阶段补齐迁移表与迁移函数，不能依赖清库发布作为正式升级策略。
常用示例：
@@ -59,7 +61,7 @@ npm run dev:rust
./scripts/dev-rust-stack.sh
./scripts/dev-rust-stack.sh --api-port 8090 --spacetime-port 3110 --database genarrative-dev
./scripts/dev-rust-stack.sh --skip-spacetime --skip-publish
./scripts/dev-rust-stack.sh --clear-database
./scripts/dev-rust-stack.sh --preserve-database
```
日志提取：
@@ -72,7 +74,7 @@ npm run dev:rust:logs -- --follow
日志提取规则：
1. SpacetimeDB 模块日志以 `spacetime logs <database>` 为唯一提取入口，脚本不直接读取内部日志文件结构。
1. SpacetimeDB 模块日志以 `spacetime --root-dir=server-rs/.spacetimedb/local logs <database>` 为唯一提取入口，脚本不直接读取内部日志文件结构。
2. 默认读取 `spacetime.local.json` 的 `database` 字段，默认 server 为 `http://127.0.0.1:3101`。
3. 默认输出到 `logs/spacetime/<database>-<timestamp>.log`，并通过 `tee` 同步显示在终端。
4. `--follow` 仅用于本地追踪，会持续追加到同一个输出文件；停止时用 `Ctrl+C`。
@@ -80,7 +82,7 @@ npm run dev:rust:logs -- --follow
联调排错补充：
1. 如果首页公开广场出现 `上游服务请求失败`，优先检查 `api-server` 错误详情里的 `ws://.../v1/database/<database>/subscribe` 是否指向了未发布的库。
2. `spacetime list --server http://127.0.0.1:3101` 应能看到 `spacetime.local.json` 中的库名；若没有，执行 `spacetime publish <本地数据库名> --server http://127.0.0.1:3101 --module-path server-rs/crates/spacetime-module --yes`。
2. `spacetime --root-dir=server-rs/.spacetimedb/local list --server http://127.0.0.1:3101` 应能看到 `spacetime.local.json` 中的库名；若没有，执行 `spacetime --root-dir=server-rs/.spacetimedb/local publish <本地数据库名> --server http://127.0.0.1:3101 --module-path server-rs/crates/spacetime-module -c=on-conflict --yes`。
3. 发布库名与 `GENARRATIVE_SPACETIME_DATABASE` 不一致时，`/api/runtime/custom-world-gallery` 会从 Rust `api-server` 返回 `502`，前端首页只能展示空态或错误提示，无法自行修复。
## 3. Ubuntu 发布包脚本
@@ -108,7 +110,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`；`start.sh` 会先加载发布目录根部的 `.env`、`.env.local`，再回退到构建时通过 `--database`、`--api-port`、`--web-port`、`--spacetime-host`、`--spacetime-port` 写入的默认值，并默认导出 `NO_COLOR=1` 与 `CARGO_TERM_COLOR=never`，避免 ANSI 控制码写入日志文件；如果以 `--clear-database` 启动，则内部 `spacetime publish` 会追加 `-c always`。
8. 在目标目录写入 `start.sh` 与 `stop.sh`；`start.sh` 会先加载发布目录根部的 `.env`、`.env.local`，再回退到构建时通过 `--database`、`--api-port`、`--web-port`、`--spacetime-host`、`--spacetime-port` 写入的默认值，并默认导出 `NO_COLOR=1` 与 `CARGO_TERM_COLOR=never`，避免 ANSI 控制码写入日志文件；如果以 `--clear-database` 启动，则内部 `spacetime publish` 会追加 `-c=on-conflict`，仅在 schema 冲突时删除旧模块数据。
9. 默认执行 `scp -r -i ~\.ssh\dsk.pem build/<timestamp> ubuntu@82.157.175.59:/home/ubuntu/genarrative/` 上传发布包。
发布包结构：
@@ -150,8 +152,8 @@ cd build/<timestamp>
1. 构建脚本会把仓库根目录已有的 `.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；清库模式下会追加 `-c always`。
3. `start.sh` 默认不追加清理参数；只有显式执行 `./start.sh --clear-database` 才追加 `-c=on-conflict`，在 schema 冲突时清理旧模块数据后重发。
4. `start.sh` 使用 `spacetime publish --bin-path spacetime_module.wasm --yes` 发布当前包内 wasm；清库模式下会追加 `-c=on-conflict`，仅在 schema 冲突时删除旧模块数据。
5. 当前脚本是单目录进程启动方案，不替代生产 systemd、Nginx、TLS、日志轮转与守护进程配置。
6. 如只需要本地生成发布包，可传 `--skip-upload` 跳过默认 scp 上传。

6
scripts/deploy-rust-remote.sh
View File

@@ -448,7 +448,7 @@ usage() {
说明:
1. 启动当前发布包内的静态网站、SpacetimeDB 与 api-server。
2. 默认发布 spacetime_module.wasm 到 GENARRATIVE_SPACETIME_DATABASE，但不清库。
3. 只有显式传入 --clear-database 时才允许清空数据库重发。
3. 只有显式传入 --clear-database 时才会在 schema 冲突时清理旧模块数据后重发。
EOF
}
@@ -550,8 +550,8 @@ PUBLISH_ARGS=(
)
if [[ "${CLEAR_DATABASE}" -eq 1 ]]; then
# 按当前 SpacetimeDB CLI 约定使用 -c，等价于 --delete-data always。
PUBLISH_ARGS+=(-c)
# 发布包清库模式只在 schema 冲突时删除旧模块数据，避免无冲突升级误清数据。
PUBLISH_ARGS+=(-c=on-conflict)
fi
echo "[start] 发布 SpacetimeDB wasm: ${SPACETIME_DATABASE}"

75
scripts/dev-rust-stack.sh
View File

@@ -1,4 +1,4 @@
#!/usr/bin/env bash
#!/usr/bin/env bash
set -euo pipefail
@@ -8,13 +8,13 @@ usage() {
npm run dev:rust
./scripts/dev-rust-stack.sh --api-port 8090 --spacetime-port 3110
./scripts/dev-rust-stack.sh --skip-spacetime --skip-publish
./scripts/dev-rust-stack.sh --clear-database
./scripts/dev-rust-stack.sh --preserve-database
npm run dev:rust:logs -- --follow
说明:
1. 默认同时启动 SpacetimeDB standalone、Rust api-server 与 Vite 前端。
2. 默认会 publish server-rs/crates/spacetime-module，但不会清空数据库。
3. 只有显式传入 --clear-database 时，才会追加 spacetime publish --clear-database。
2. 当前开发阶段默认 publish server-rs/crates/spacetime-module 时追加 -c=on-conflict 在结构冲突时清理旧模块数据。
3. 只有显式传入 --preserve-database 时，才会跳过 -c=on-conflict。
4. SpacetimeDB 默认使用 server-rs/.spacetimedb/local 作为本地数据与日志目录。
EOF
}
@@ -67,7 +67,8 @@ cleanup() {
wait_for_spacetime() {
local server="$1"
local timeout_seconds="$2"
local process_pid="${3:-}"
local root_dir="$3"
local process_pid="${4:-}"
local deadline=$((SECONDS + timeout_seconds))
while ((SECONDS < deadline)); do
@@ -76,7 +77,7 @@ wait_for_spacetime() {
exit 1
fi
if spacetime server ping "${server}" >/dev/null 2>&1; then
if spacetime --root-dir="${root_dir}" server ping "${server}" >/dev/null 2>&1; then
return
fi
@@ -87,6 +88,51 @@ wait_for_spacetime() {
exit 1
}
sync_local_spacetime_install() {
local root_dir="$1"
# SpacetimeDB standalone 会在 --root-dir 下回调 bin/current/spacetimedb-cli.exe；
# Windows 本地开发使用工程内 root-dir 时，需要把用户级安装目录同步进来。
if [[ "${OSTYPE:-}" != msys* && "${OSTYPE:-}" != cygwin* ]]; then
return
fi
local target_cli="${root_dir}/bin/current/spacetimedb-cli.exe"
if [[ -f "${target_cli}" ]]; then
return
fi
local spacetime_command
spacetime_command="$(command -v spacetime || true)"
if [[ -z "${spacetime_command}" ]]; then
return
fi
local install_dir
install_dir="$(cd -- "$(dirname -- "${spacetime_command}")" && pwd)"
if [[ ! -d "${install_dir}/bin" ]]; then
return
fi
echo "[dev:rust] 同步本机 SpacetimeDB 安装到 ${root_dir}"
mkdir -p "${root_dir}"
cp -a "${install_dir}/bin" "${root_dir}/"
if [[ -f "${install_dir}/spacetime.exe" ]]; then
cp -f "${install_dir}/spacetime.exe" "${root_dir}/spacetime.exe"
fi
# Git Bash 复制 Windows junction 时可能不会生成可执行的 current 目录；
# 若 current 缺失，则用最新版本目录复制出一个真实目录，满足 standalone 回调路径。
if [[ ! -f "${target_cli}" ]]; then
local version_dir
version_dir="$(find "${root_dir}/bin" -mindepth 1 -maxdepth 1 -type d ! -name current | sort -V | tail -n 1)"
if [[ -n "${version_dir}" && -f "${version_dir}/spacetimedb-cli.exe" ]]; then
rm -rf "${root_dir}/bin/current"
cp -a "${version_dir}" "${root_dir}/bin/current"
fi
fi
}
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
SERVER_RS_DIR="${REPO_ROOT}/server-rs"
@@ -106,7 +152,7 @@ API_LOG="info,tower_http=info"
SPACETIME_TIMEOUT_SECONDS="60"
SKIP_SPACETIME=0
SKIP_PUBLISH=0
CLEAR_DATABASE=0
PRESERVE_DATABASE=0
PIDS=()
NAMES=()
@@ -186,7 +232,11 @@ while [[ $# -gt 0 ]]; do
shift
;;
--clear-database)
CLEAR_DATABASE=1
PRESERVE_DATABASE=0
shift
;;
--preserve-database)
PRESERVE_DATABASE=1
shift
;;
*)
@@ -242,6 +292,7 @@ echo "[dev:rust] spacetime root: ${SPACETIME_ROOT_DIR}"
if [[ "${SKIP_SPACETIME}" -ne 1 ]]; then
mkdir -p "${SPACETIME_ROOT_DIR}"
sync_local_spacetime_install "${SPACETIME_ROOT_DIR}"
echo "[dev:rust] 启动 spacetimedb"
(
cd "${SERVER_RS_DIR}"
@@ -257,7 +308,7 @@ fi
if [[ "${SKIP_PUBLISH}" -ne 1 ]]; then
echo "[dev:rust] 等待 SpacetimeDB 就绪"
wait_for_spacetime "${SPACETIME_SERVER}" "${SPACETIME_TIMEOUT_SECONDS}" "${PIDS[0]:-}"
wait_for_spacetime "${SPACETIME_SERVER}" "${SPACETIME_TIMEOUT_SECONDS}" "${SPACETIME_ROOT_DIR}" "${PIDS[0]:-}"
PUBLISH_ARGS=(
publish
@@ -266,14 +317,14 @@ if [[ "${SKIP_PUBLISH}" -ne 1 ]]; then
--module-path "${MODULE_PATH}"
)
if [[ "${CLEAR_DATABASE}" -eq 1 ]]; then
PUBLISH_ARGS+=(--clear-database)
if [[ "${PRESERVE_DATABASE}" -ne 1 ]]; then
PUBLISH_ARGS+=(-c=on-conflict)
fi
PUBLISH_ARGS+=(--yes)
echo "[dev:rust] 发布 SpacetimeDB 模块: ${DATABASE}"
spacetime "${PUBLISH_ARGS[@]}"
spacetime --root-dir="${SPACETIME_ROOT_DIR}" "${PUBLISH_ARGS[@]}"
fi
echo "[dev:rust] 启动 api-server"

9
scripts/spacetime-logs-local.sh
View File

@@ -13,6 +13,7 @@ usage() {
1. 从本地 SpacetimeDB 通过 spacetime logs 提取模块日志到本地文件。
2. 默认读取 spacetime.local.json 的 database 字段，默认 server 为 http://127.0.0.1:3101。
3. 默认输出到 logs/spacetime/<database>-<timestamp>.log；--follow 会持续追加并同步写到终端。
4. 默认使用 server-rs/.spacetimedb/local 作为 spacetime CLI root，保持本地身份与 standalone 一致。
EOF
}
@@ -51,6 +52,7 @@ REPO_ROOT="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
DATABASE=""
SPACETIME_SERVER="http://127.0.0.1:3101"
SPACETIME_ROOT_DIR="${REPO_ROOT}/server-rs/.spacetimedb/local"
LINES="200"
OUTPUT=""
FOLLOW=0
@@ -69,6 +71,10 @@ while [[ $# -gt 0 ]]; do
SPACETIME_SERVER="${2:?缺少 --server 的值}"
shift 2
;;
--spacetime-root-dir)
SPACETIME_ROOT_DIR="${2:?缺少 --spacetime-root-dir 的值}"
shift 2
;;
--lines|-n)
LINES="${2:?缺少 --lines 的值}"
shift 2
@@ -117,6 +123,7 @@ fi
echo "[stdb:logs] database: ${DATABASE}"
echo "[stdb:logs] server: ${SPACETIME_SERVER}"
echo "[stdb:logs] spacetime root: ${SPACETIME_ROOT_DIR}"
echo "[stdb:logs] output: ${OUTPUT}"
spacetime "${ARGS[@]}" | tee -a "${OUTPUT}"
spacetime --root-dir="${SPACETIME_ROOT_DIR}" "${ARGS[@]}" | tee -a "${OUTPUT}"