From a1a02eee7d78cd007e772613b4a854f37d122a0a Mon Sep 17 00:00:00 2001 From: kdletters Date: Tue, 21 Apr 2026 01:58:46 +0800 Subject: [PATCH] build: add spacetime local dev scripts --- .gitignore | 1 + .../01_M0_M2_FOUNDATION_AND_AUTH.md | 3 +- ...M_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md | 2 +- server-rs/README.md | 7 +- server-rs/apps/spacetime-module/README.md | 12 +++- server-rs/scripts/spacetime-dev.ps1 | 67 +++++++++++++++++++ server-rs/scripts/spacetime-dev.sh | 52 ++++++++++++++ 7 files changed, 138 insertions(+), 6 deletions(-) create mode 100644 server-rs/scripts/spacetime-dev.ps1 create mode 100644 server-rs/scripts/spacetime-dev.sh diff --git a/.gitignore b/.gitignore index 7719d554..1896b30d 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,7 @@ temp*build*/ /server-node/data/* !/server-node/data/.gitkeep /server-rs/target/ +/server-rs/.spacetimedb/ /public/generated-animations /public/generated-character-drafts /public/generated-characters diff --git a/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md b/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md index cfa2a3c2..bda3bbb0 100644 --- a/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md +++ b/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md @@ -123,7 +123,8 @@ 交付物：[../server-rs/scripts/check.ps1](../server-rs/scripts/check.ps1)、[../server-rs/scripts/check.sh](../server-rs/scripts/check.sh) - [x] 新增 smoke 脚本 交付物：[../server-rs/scripts/smoke.ps1](../server-rs/scripts/smoke.ps1)、[../server-rs/scripts/smoke.sh](../server-rs/scripts/smoke.sh) -- [ ] 新增 SpacetimeDB 本地开发脚本 +- [x] 新增 SpacetimeDB 本地开发脚本 + 交付物：[../server-rs/scripts/spacetime-dev.ps1](../server-rs/scripts/spacetime-dev.ps1)、[../server-rs/scripts/spacetime-dev.sh](../server-rs/scripts/spacetime-dev.sh) ### 阶段验收 diff --git a/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md b/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md index 1768e95d..bd599d8f 100644 --- a/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md +++ b/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md @@ -244,7 +244,7 @@ server-rs/ └─ scripts/ ├─ dev.sh / dev.ps1 ├─ check.sh / check.ps1 - ├─ spacetime-publish.sh + ├─ spacetime-dev.sh / spacetime-dev.ps1 └─ smoke.sh / smoke.ps1 ``` diff --git a/server-rs/README.md b/server-rs/README.md index 7da3a059..30146b32 100644 --- a/server-rs/README.md +++ b/server-rs/README.md @@ -14,7 +14,7 @@ ## 2. 当前阶段说明 -当前目录已经完成以下三十二项初始化： +当前目录已经完成以下三十四项初始化： 1. 为新后端预留正式目录并把路径固定到仓库结构中。 2. 创建虚拟 workspace `Cargo.toml`，后续 package 会逐项挂入。 @@ -48,10 +48,13 @@ 30. 创建 `scripts/check.sh`，固定 Unix-like 本地统一检查入口。 31. 创建 `scripts/smoke.ps1`，固定 Windows 本地冒烟验证入口。 32. 创建 `scripts/smoke.sh`，固定 Unix-like 本地冒烟验证入口。 +33. 创建 `scripts/spacetime-dev.ps1`，固定 Windows 本地 SpacetimeDB 启动入口。 +34. 创建 `scripts/spacetime-dev.sh`，固定 Unix-like 本地 SpacetimeDB 启动入口。 后续任务会继续在本目录内按顺序补齐： -1. SpacetimeDB 本地开发脚本 +1. `apps/spacetime-module` 的表、reducer、view 聚合入口 +2. `module-auth` 的身份表、JWT 与 refresh cookie 主链 ## 3. 已冻结边界 diff --git a/server-rs/apps/spacetime-module/README.md b/server-rs/apps/spacetime-module/README.md index 52d836cc..fb76e8dd 100644 --- a/server-rs/apps/spacetime-module/README.md +++ b/server-rs/apps/spacetime-module/README.md @@ -10,17 +10,25 @@ 2. 聚合各独立模块 package 的 reducer 3. 聚合各独立模块 package 的 view / 读模型 4. 生成可发布的 SpacetimeDB wasm 模块 +5. 由 `../../scripts/spacetime-dev.ps1` 与 `../../scripts/spacetime-dev.sh` 驱动的本地 standalone 启动链路 ## 2. 当前阶段说明 -当前提交仅完成目录占位，不提前进入具体 schema 与 reducer 实现。 +当前阶段仍未进入具体 schema 与 reducer 实现，但已经补齐本地 standalone 启动脚本，先把 SpacetimeDB 进程入口固定下来。 后续与本 package 直接相关的任务包括： 1. 建立模块聚合入口 2. 设计表、reducer、view 的聚合方式 3. 接入身份 claims 透传 -4. 接入本地开发与发布脚本 +4. 在实体 module scaffold 落地后接入 publish / dev 循环 + +当前本地开发脚本约定： + +1. `../../scripts/spacetime-dev.ps1` 与 `../../scripts/spacetime-dev.sh` 当前固定执行 `spacetime start` 的 standalone 模式。 +2. 默认监听 `127.0.0.1:3001`，避免与 `api-server` 默认 `3000` 端口冲突。 +3. 本地数据目录固定到 `server-rs/.spacetimedb/local`，避免污染全局 SpacetimeDB 根目录。 +4. 当前阶段暂不自动 publish `apps/spacetime-module`，待 module 实体 scaffold 与聚合入口落地后再扩展。 ## 3. 边界约束 diff --git a/server-rs/scripts/spacetime-dev.ps1 b/server-rs/scripts/spacetime-dev.ps1 new file mode 100644 index 00000000..b6aff1d0 --- /dev/null +++ b/server-rs/scripts/spacetime-dev.ps1 @@ -0,0 +1,67 @@ +[CmdletBinding()] +param( + [Alias("h")] + [switch]$Help, + [string]$ListenHost = "127.0.0.1", + [int]$Port = 3001, + [string]$RootDir = "" +) + +$ErrorActionPreference = "Stop" + +function Write-Usage { + @( + 'Usage:' + ' ./server-rs/scripts/spacetime-dev.ps1' + ' ./server-rs/scripts/spacetime-dev.ps1 -ListenHost 127.0.0.1 -Port 3101' + '' + 'Notes:' + ' 1. Start local standalone SpacetimeDB for the Genarrative Rust backend' + ' 2. Store local SpacetimeDB state in server-rs/.spacetimedb/local by default' + ' 3. Current stage only boots the standalone server and does not publish a module yet' + ) -join [Environment]::NewLine +} + +if ($Help) { + Write-Usage + exit 0 +} + +$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$serverRsDir = Split-Path -Parent $scriptDir + +if ([string]::IsNullOrWhiteSpace($RootDir)) { + $RootDir = Join-Path $serverRsDir ".spacetimedb\local" +} + +if (-not (Test-Path (Join-Path $serverRsDir "apps\spacetime-module\README.md"))) { + throw "Missing server-rs/apps/spacetime-module/README.md, cannot start SpacetimeDB local dev script." +} + +$spacetimeCommand = Get-Command spacetime -ErrorAction SilentlyContinue + +if ($null -eq $spacetimeCommand) { + throw @( + "Missing 'spacetime' CLI.", + "Install guide: https://spacetimedb.com/install", + "Windows PowerShell: iwr https://windows.spacetimedb.com -useb | iex" + ) -join " " +} + +New-Item -ItemType Directory -Force -Path $RootDir | Out-Null + +$listenAddress = "$ListenHost`:$Port" + +Write-Host "[server-rs:spacetime-dev] working dir: $serverRsDir" +Write-Host "[server-rs:spacetime-dev] root dir: $RootDir" +Write-Host "[server-rs:spacetime-dev] listen addr: $listenAddress" +Write-Host "[server-rs:spacetime-dev] mode: standalone" +Write-Host "[server-rs:spacetime-dev] note: module publish is deferred until apps/spacetime-module scaffold lands" + +Push-Location $serverRsDir +try { + & $spacetimeCommand.Source --root-dir $RootDir start --edition standalone --listen-addr $listenAddress +} +finally { + Pop-Location +} diff --git a/server-rs/scripts/spacetime-dev.sh b/server-rs/scripts/spacetime-dev.sh new file mode 100644 index 00000000..f38ea8af --- /dev/null +++ b/server-rs/scripts/spacetime-dev.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash + +set -euo pipefail + +# 当前阶段只负责启动本地 standalone SpacetimeDB，先把服务器进程和数据目录口径固定下来，不提前耦合 publish 流程。 + +usage() { + cat <<'EOF' +用法: + ./server-rs/scripts/spacetime-dev.sh + GENARRATIVE_SPACETIME_PORT=3101 ./server-rs/scripts/spacetime-dev.sh + +说明: + 1. 启动 Genarrative Rust 后端使用的本地 standalone SpacetimeDB + 2. 默认把本地数据目录放到 `server-rs/.spacetimedb/local` + 3. 当前阶段只负责启动 standalone server，暂不自动 publish `apps/spacetime-module` +EOF +} + +if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then + usage + exit 0 +fi + +SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" +SERVER_RS_DIR="$(cd -- "${SCRIPT_DIR}/.." && pwd)" +LISTEN_HOST="${GENARRATIVE_SPACETIME_HOST:-127.0.0.1}" +PORT="${GENARRATIVE_SPACETIME_PORT:-3001}" +ROOT_DIR="${GENARRATIVE_SPACETIME_ROOT_DIR:-${SERVER_RS_DIR}/.spacetimedb/local}" + +if [[ ! -f "${SERVER_RS_DIR}/apps/spacetime-module/README.md" ]]; then + echo "[server-rs:spacetime-dev] 未找到 apps/spacetime-module/README.md，无法启动本地 SpacetimeDB 脚本。" >&2 + exit 1 +fi + +if ! command -v spacetime >/dev/null 2>&1; then + echo "[server-rs:spacetime-dev] 缺少 spacetime CLI。" >&2 + echo "[server-rs:spacetime-dev] 安装文档: https://spacetimedb.com/install" >&2 + echo "[server-rs:spacetime-dev] Linux/macOS 安装命令: curl -sSf https://install.spacetimedb.com | sh" >&2 + exit 1 +fi + +mkdir -p "${ROOT_DIR}" + +echo "[server-rs:spacetime-dev] 工作目录: ${SERVER_RS_DIR}" +echo "[server-rs:spacetime-dev] 数据目录: ${ROOT_DIR}" +echo "[server-rs:spacetime-dev] 监听地址: ${LISTEN_HOST}:${PORT}" +echo "[server-rs:spacetime-dev] 模式: standalone" +echo "[server-rs:spacetime-dev] 说明: 当前阶段暂不自动 publish apps/spacetime-module" + +cd "${SERVER_RS_DIR}" +spacetime --root-dir "${ROOT_DIR}" start --edition standalone --listen-addr "${LISTEN_HOST}:${PORT}"