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 上传。