1

docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md

@@ -34,7 +34,7 @@ npm run dev:rust
 1. 检查 `cargo`、`node` 与 `spacetime` CLI。
 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` 可用。
+4. 等待 `spacetime --root-dir=server-rs/.spacetimedb/local server ping http://127.0.0.1:3101` 可用；判定标准必须包含输出中的 `Server is online:`，不能只依赖 CLI 退出码，因为 SpacetimeDB CLI `2.1.0` 在 `502 Bad Gateway` 时也可能返回退出码 `0`。
 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. 等待 `http://127.0.0.1:<api-port>/healthz` 返回 HTTP 响应后再启动 Vite，避免前端初始化请求早于 Rust `api-server` 监听完成并在终端刷出 `ECONNREFUSED 127.0.0.1:<api-port>`。
@@ -65,6 +65,23 @@ npm run dev:rust
 ./scripts/dev-rust-stack.sh --preserve-database
 ```
 
+bindings 生成：
+
+```bash
+npm run spacetime:generate
+npm run spacetime:generate -- --rust-only
+```
+
+生成规则：
+
+1. `npm run spacetime:generate` 是本仓库刷新 SpacetimeDB Rust client bindings 的唯一推荐入口。
+2. 前端不直连 SpacetimeDB，不生成 TypeScript bindings；前端只通过 Rust `api-server` 暴露的 HTTP / SSE contract 访问后端。
+3. Rust bindings 不生成私有表绑定，不追加 `--include-private`，生成到短临时目录后同步到 `server-rs/crates/spacetime-client/src/module_bindings`。
+4. Windows 下 SpacetimeDB CLI `2.1.0` 会在生成结束后把所有生成文件路径一次性传给 formatter；Rust bindings 文件较多，若直接输出到仓库深目录，可能触发 `Could not format generated files: 文件名或扩展名太长。`。该错误不是单个最长文件路径超过限制，而是 formatter 子进程参数总长超过 Windows `CreateProcess` 限制。
+5. CLI 在上述 formatter 失败时仍可能返回退出码 `0`；脚本会捕获输出，只要出现 `Could not format generated files` 就视为失败。
+6. 根目录 `spacetime.json` 不配置 `generate` 目标，避免裸 `spacetime generate` 在 Windows 上直接碰到 Rust formatter 路径总长限制，也避免误生成前端 bindings。
+7. 不直接手写或局部补 `server-rs/crates/spacetime-client/src/module_bindings` 下的生成文件；schema 变化后重新执行本脚本，并补跑编码检查与对应类型检查。
+
 日志提取：
 
 ```bash
@@ -86,6 +103,7 @@ npm run dev:rust:logs -- --follow
 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`，前端首页只能展示空态或错误提示，无法自行修复。
 4. 如果 Vite 输出 `/api/auth/refresh`、`/api/auth/login-options` 或 `/api/runtime/custom-world-gallery` 的 `ECONNREFUSED`，先确认当前脚本是否已经打印 `等待 api-server 就绪` 并通过；正常情况下 Vite 只会在 `/healthz` 可访问后启动，不应再因为 Rust 监听未完成而代理失败。
+5. 如果 `spacetime server ping` 打印 `Server could not be reached (502 Bad Gateway)`，即使命令退出码为 `0` 也必须视为未就绪；脚本会继续等待新启动实例，或在 root-dir 已被其他实例占用时输出占用进程。
 
 编译警告治理：
 
@@ -93,6 +111,12 @@ npm run dev:rust:logs -- --follow
 2. 仅供测试断言使用的辅助函数使用 `#[cfg(test)]` 限定，避免进入 `cargo run -p api-server` 的普通二进制编译。
 3. 已无调用入口且无迁移价值的映射函数直接删除；如果后续新增同类 SpacetimeDB 记录映射，再按实际调用路径补回，避免提前保留死代码。
 
+Maincloud API 重启补充：
+
+1. `npm run api-server:maincloud` 会先读取 `.env`、`.env.local`，把 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 映射为 `api-server` 使用的 `GENARRATIVE_SPACETIME_*`，再运行 `cargo run -p api-server --manifest-path server-rs/Cargo.toml`。
+2. Windows 下脚本会尽力停止本仓库 `server-rs/target/debug/api-server.exe` 对应的旧进程，避免 cargo 重新编译时 exe 被占用。
+3. 旧进程已经退出或清理过程中出现瞬时等待失败时，不应阻断新的 `api-server` 启动；脚本只记录清理失败并继续启动。
+
 ## 3. Ubuntu 发布包脚本
 
 入口：