Files
Genarrative/docs/technical/SPACETIMEDB_MAINCLOUD_PUBLISH_2026-04-24.md
2026-04-26 20:50:58 +08:00

2.9 KiB
Raw Blame History

SpacetimeDB Maincloud 发布与 api-server 适配方案

目标

新增一条明确的 npm 命令链,用于把 server-rs/crates/spacetime-module 发布到 SpacetimeDB Maincloud并让 api-server 可以使用同一套 Maincloud 数据库配置启动。

环境变量约定

Maincloud 发布不复用本地 spacetime.local.json,避免误把本地开发库名发布到云端。需要显式提供:

变量 用途
GENARRATIVE_SPACETIME_MAINCLOUD_DATABASE Maincloud 数据库名,发布脚本优先读取
GENARRATIVE_SPACETIME_MAINCLOUD_SERVER_URL Maincloud 服务地址,默认 https://maincloud.spacetimedb.com
GENARRATIVE_SPACETIME_MAINCLOUD_TOKEN api-server 连接 Maincloud 时使用的 token

兼容 api-server 现有变量:

变量 用途
GENARRATIVE_SPACETIME_SERVER_URL api-server 实际连接地址
GENARRATIVE_SPACETIME_DATABASE api-server 实际连接数据库
GENARRATIVE_SPACETIME_TOKEN api-server 实际连接 token

npm 命令

npm run spacetime:publish:maincloud

执行内容:

  1. 使用 cargo build -p spacetime-module --target wasm32-unknown-unknown --release 构建 wasm。
  2. 使用 spacetime publish <database> --server maincloud --bin-path <wasm> --yes 发布到 Maincloud。
  3. 输出 api-server 需要的 Maincloud 环境变量,便于部署进程复用。

如需 schema 冲突时清库发布:

npm run spacetime:publish:maincloud -- --clear-database

api-server 启动

npm run api-server:maincloud

执行内容:

  1. .env.env.local 读取默认环境。
  2. GENARRATIVE_SPACETIME_MAINCLOUD_* 映射为 api-server 已支持的 GENARRATIVE_SPACETIME_*
  3. 在 Windows 启动前检查 server-rs/target/debug/api-server.exe 对应的旧进程;如果旧进程仍在运行,先停止它,避免 Rust 编译阶段覆盖 exe 时出现 failed to remove file ... 拒绝访问。 (os error 5)
  4. 启动 cargo run -p api-server --manifest-path server-rs/Cargo.toml

设计约束

  • Maincloud 数据库名必须显式配置,不能默认读取本地 spacetime.local.json
  • 发布脚本只处理 SpacetimeDB 模块发布,不启动本地 SpacetimeDB。
  • api-server 继续通过 SpacetimeClientConfigserver_url / database / token 连接数据库,不在前端增加逻辑。
  • Windows 进程清理只能匹配本仓库 server-rs/target/debug/api-server.exe 的完整路径,不能按进程名泛化清理,避免影响其他 Rust 服务。