添加maincloud发布

docs/technical/SPACETIMEDB_MAINCLOUD_PUBLISH_2026-04-24.md

@@ -0,0 +1,59 @@
+# 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 命令
+
+```bash
+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 冲突时清库发布：
+
+```bash
+npm run spacetime:publish:maincloud -- --clear-database
+```
+
+## api-server 启动
+
+```bash
+npm run api-server:maincloud
+```
+
+执行内容：
+
+1. 从 `.env` 与 `.env.local` 读取默认环境。
+2. 将 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 映射为 `api-server` 已支持的 `GENARRATIVE_SPACETIME_*`。
+3. 启动 `cargo run -p api-server --manifest-path server-rs/Cargo.toml`。
+
+## 设计约束
+
+- Maincloud 数据库名必须显式配置，不能默认读取本地 `spacetime.local.json`。
+- 发布脚本只处理 SpacetimeDB 模块发布，不启动本地 SpacetimeDB。
+- `api-server` 继续通过 `SpacetimeClientConfig` 的 `server_url / database / token` 连接数据库，不在前端增加逻辑。