Genarrative/.hermes/skills/genarrative-admin-backoffice/references/dev-rust-stack-startup-2026-05-08.md

npm run dev / scripts/dev-rust-stack.sh 启动修复记录

症状

• 多个 worktree 同时本地开发时，SpacetimeDB 数据库名可能相同，早期曾用项目级 CLI root 隔离 CLI 状态来规避冲突。
• 实测后确认：真正需要隔离的是 standalone 的 data-dir，不需要把 publish 也绑到项目级 CLI root。
• 早期脚本曾通过把用户级 SpacetimeDB 可执行文件目录同步到 server-rs/.spacetimedb/local/bin/current 来满足 standalone 回调需求，但这会把整套可执行文件复制进项目本地目录，维护成本高，也容易和用户级 CLI 版本漂移。
• 多个 worktree 同时启动时，SpacetimeDB 端口可能冲突；CLI 会询问是否使用最近的可用端口。
• 若 npm run dev 从仓库根目录直接执行 spacetime publish --module-path server-rs/crates/spacetime-module，内部 Cargo 不一定读取 server-rs/.cargo/config.toml，可能绕过 sccache/linker/target 缓存策略，表现为 spacetime-module 每次像全量重编译。
• api-server 首次冷编译时，默认 300 秒超时不够，容易在就绪前被回收。

当前方案

1. SpacetimeDB 可执行文件继续使用用户环境里的 spacetime 命令
   • 启动 standalone 时不再复制 spacetimedb-cli、版本目录或 bin/current。
   • spacetime start 不再通过工程内 CLI root 寻找可执行文件。
2. 数据目录显式指定到项目本地
   • 默认 SPACETIME_DATA_DIR=${SERVER_RS_DIR}/.spacetimedb/local/data。
   • 启动命令使用 spacetime start --data-dir "${SPACETIME_DATA_DIR}" --listen-addr ...。
   • 如需临时切换数据目录，可传 --spacetime-data-dir <path>。
3. 端口冲突时自动接受 SpacetimeDB 建议端口
   • 启动时不传 --non-interactive。
   • 脚本向 spacetime start 发送回车，接受“最近可用端口”的默认建议。
   • 随后从启动日志中的 Starting SpacetimeDB listening on ... 解析实际端口。
   • 解析出的实际端口会覆盖 SPACETIME_SERVER，后续 publish、api-server、前端代理统一使用这个端口。
4. publish 不再使用项目级 CLI root，但要从 server-rs 目录执行
   • 发布模块改为在 server-rs 下执行 spacetime publish ... --server "${SPACETIME_SERVER}" ...。
   • 这样 publish 使用用户级 CLI 默认身份/配置，不再依赖 worktree 内 CLI root。
   • 同时确保内部 Cargo 能读取 server-rs/.cargo/config.toml，复用项目级 sccache/linker/target 缓存策略，避免 npm run dev 比手动 publish 更容易触发慢速重编译。
5. 提高 api-server 就绪等待时间
   • API_SERVER_TIMEOUT_SECONDS 保持 600，降低首次冷编译误判失败概率。

复现 / 验证

• 运行脚本语法检查：bash -n scripts/dev-rust-stack.sh。
• 运行帮助检查：bash scripts/dev-rust-stack.sh --help，确认有 --spacetime-data-dir。
• 运行 npm run dev 后观察日志：
  • 输出 spacetime data: .../server-rs/.spacetimedb/local/data。
  • 不再出现同步/复制本机 SpacetimeDB 安装到项目 CLI root 的日志。
  • SpacetimeDB 能正常监听，并输出 spacetime actual: http://127.0.0.1:<实际端口>。
  • 若默认端口被占用，脚本应自动接受 SpacetimeDB 建议端口，并用实际端口发布模块、启动 api-server 和前端代理。
  • 模块发布成功。
  • 第二次无改动 publish 应接近手动 cd server-rs && spacetime publish ... 的增量速度。
  • api-server 进入健康检查等待并最终可访问 /healthz。

相关文件

• scripts/dev-rust-stack.sh
• server-rs/.spacetimedb/local/data/
• server-rs/.cargo/config.toml