SpacetimeDB 入门指南从安装 CLI 到本地启动你的第一个实时数据库【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本篇指南基于 SpacetimeDB v1.12.0 官方入门文档带你完整走通安装spacetimeCLI → 登录认证 → 本地启动 Standalone 服务器的全流程并说明如何接入各语言 Quickstart 快速开始开发第一个模块server module。读完本文你将掌握如何安装并验证 CLI、如何通过 GitHub 完成身份认证与免密登录、如何用spacetime start在本地拉起数据库服务并理解其默认监听地址与配置文件以及下一步应该学习哪些核心概念数据库、表、函数、订阅、Client SDK。一、SpacetimeDB 快速上手总览SpacetimeDB 将数据库与应用服务器合二为一你编写一个模块module模块中的表结构直接成为数据库表模块中的 reducer / procedure / view 就是你的服务端逻辑客户端通过订阅机制实时同步数据。整个开发流程围绕一个统一的命令行工具spacetime展开安装 CLI—— 获得spacetime、spacetimedb-standalone等可执行文件登录认证—— 用 GitHub 身份登录获得发布与管理数据库的授权选择语言跑通 Quickstart—— 用 Rust / TypeScript / C# / C 编写并发布第一个模块本地运行服务器—— 用spacetime start启动 Standalone 版本在localhost:3000上联调。下面按照官方入门文档docs/versioned_docs/version-1.12.0/00100-intro/00100-getting-started/00100-getting-started.md的脉络逐一展开。二、安装spacetimeCLI 工具spacetimeCLI 是你管理数据库和部署的核心工具。官方为不同平台提供了安装脚本其中 Unix/Linux/macOS 使用 crates/update/spacetime-install.shWindows 使用同目录下的spacetime-install.ps1。以 Unix 为例curl --proto https --tlsv1.2 -sSf https://install.spacetimedb.com | sh安装脚本支持以下参数参数说明--root-dir ROOT_DIR指定本地安装目录不指定时使用平台默认路径-y, --yes跳过确认对话框适合脚本化安装-h, --help打印帮助信息从脚本源码crates/update/spacetime-install.sh可以看到安装器会先检查系统是否具备curl或wget随后自动检测操作系统与 CPU 架构从官方 Release 下载对应的spacetimedb-update-host二进制再引导安装spacetimeCLI 与配套的服务器程序。提示安装完成后建议在一个新的终端中执行spacetime --help或spacetime version见 crates/cli/src/subcommands/version.rs验证命令是否已加入PATH。三、登录 SpacetimeDBGitHub 身份认证SpacetimeDB 使用 GitHub 登录对用户进行身份认证目的是防止未授权访问——例如别人冒充你覆盖发布你的模块。登录命令非常简单spacetime login执行后 CLI 会自动打开浏览器引导你在 GitHub 上完成授权。如果你跳过了这一步任何需要登录的命令如spacetime publish在执行时都会再次提示你先登录。登录的底层流程从源码 crates/cli/src/subcommands/login.rs 可以看出spacetime login并非直接把 GitHub 授权结果写入本地而是经过一次换取令牌的流程CLI 向认证服务器默认https://spacetimedb.com的/api/auth/cli/login/request-token请求一个一次性 request token打开https://spacetimedb.com/login/cli?token...等待用户在浏览器中完成 GitHub 授权CLI 轮询/api/auth/cli/status待用户批准后拿到 web session token再用该 session token 访问/api/spacetimedb-token换取正式的spacetimedb_token写入 CLI 配置文件。登录相关的高级用法命令说明spacetime login --token token跳过完整登录流程直接用令牌登录源码中对应spacetimedb-token参数见 login.rsspacetime login --no-browser不自动打开浏览器改为在终端打印授权 URL 供手动打开适合无 GUI 的服务器环境spacetime login show查看当前登录身份加--token可同时显示 auth token注意token 属于敏感信息请勿分享spacetime logout退出登录并清除本地令牌crates/cli/src/subcommands/logout.rs登录成功后spacetime login show会打印你的 identityCLI 会将令牌保存到本地配置文件即cli.toml参见 crates/cli/src/config.rs后续spacetime publish、spacetime sql等命令会自动携带身份无需重复登录。四、选择语言并完成你的第一个 Quickstart登录完成后就可以开始开发 SpacetimeDB 模块了。SpacetimeDB 官方提供了多种服务端语言与对应的 Quickstart 指南你可以直接通过spacetime init初始化项目# 以 Rust 为例 spacetime init my-project --lang rust当前仓库中可用的语言支持与对应入门指南如下TypeScriptTypeScript QuickstartRustRust QuickstartC#C# QuickstartReact前端接入示例React Quickstart更完整的语言支持矩阵含 C、Unreal 等可参考语言支持文档。每个 Quickstart 都会带你走完定义表 → 编写 reducer → 构建 → 发布 → 客户端订阅的最小闭环。Quickstart 之外常用的模块开发命令围绕模块开发spacetimeCLI 还提供了这些高频命令详见 skills/cli/SKILL.md# 构建模块默认 release--debug 加快迭代 spacetime build spacetime build --debug # 开发模式自动重建、自动发布、自动生成客户端绑定 spacetime dev # 生成客户端绑定代码 spacetime generate --lang typescript --out-dir ./client/src/module_bindings # 发布到本地服务器--server local spacetime publish my-database --server local --yes五、本地运行 SpacetimeDBspacetime start与 Standalone 服务器要在本地开发 SpacetimeDB 数据库需要运行 Standalone 版本的服务器。安装好 CLI 后直接执行spacetime start服务器默认监听3000端口可通过--listen-addr参数自定义spacetime start --listen-addr 0.0.0.0:4000本地模式的两个注意事项Standalone 模式会以前台方式运行spacetime start不会退到后台需要保持终端开启想终止服务时按Ctrl-C即可。⚠️Standalone 模式不支持 SSL本地开发走明文 HTTP默认http://127.0.0.1:3000仅适合开发环境。spacetime start背后发生了什么从源码 crates/cli/src/subcommands/start.rs 可以看到spacetime start实际上是一个转发命令根据--edition默认standalone解析要启动的服务器程序名spacetimedb-standalone或spacetimedb-cloud通过resolve_sibling_binary找到与 CLI 同目录下的服务器二进制以子进程方式调用spacetimedb-standalone start并显式传入两个关键参数--data-dir paths.data_dir数据库数据存放目录--jwt-key-dir paths.cli_config_dirJWT 密钥目录本地身份认证用。因此安装spacetimeCLI 时配套安装的spacetimedb-standalone是真正干活的服务进程CLI 只负责定位并转发参数。持久化默认监听地址如果不想每次手动传--listen-addr可以在 CLI 配置文件cli.toml中写入持久化默认值源码支持见 crates/cli/src/config.rs 与 start.rslisten_addr 0.0.0.0:4000优先级规则配置文件中存在listen_addr时会被自动使用但当命令行显式传入--listen-addr时命令行参数优先生效因为 Standalone 取最后一个--listen-addr的值CLI 会把配置值放在转发参数之前见 start.rs。Standalone 服务器的可选配置本地服务器还支持通过配置文件调整运行参数。仓库中的示例配置见 crates/standalone/config.toml其中值得关注的部分包括配置节关键项说明[logs]level/directives日志级别过滤与按模块设置的日志指令示例中默认将spacetimedb等核心 crate 设为debug[module-http]enabled是否允许模块发出出站 HTTP 请求默认允许[wasm]/[v8]procedure-instance-pool-size每个数据库的 WASM / JS 过程实例池大小缺省按操作系统核数[websocket]ping-interval/idle-timeoutWebSocket 心跳与空闲超时[commitlog]max-segment-size/write-buffer-size等提交日志commitlog的分段大小、内存写缓冲等持久化参数服务器管理命令spacetime start启动后可以通过spacetime server系列命令管理已配置的服务器源码位于 crates/cli/src/subcommands/server.rs# 查看已配置的服务器 spacetime server list # 添加本地服务器并设为默认 spacetime server add local --url http://localhost:3000 --default # 切换默认服务器 spacetime server set-default local # 测试连通性 spacetime server ping local # 清空本地数据 spacetime server clearCLI 出厂自带两组服务器配置见 crates/cli/src/config.rsmaincloudhttps://maincloud.spacetimedb.com生产云环境默认与localhttp://127.0.0.1:3000本地开发。发布时若不指定服务器默认发往maincloud本地开发请显式使用--server local。六、下一步深入学习 SpacetimeDB 核心概念完成 Quickstart 之后建议按下面的顺序深入官方核心概念文档对应 v1.12.0 文档树 docs/versioned_docs/version-1.12.0/00200-core-concepts/数据库Databases理解数据库的生命周期、发布publish与管理机制以及模块即数据库的核心模型表Tables用表、列、索引定义数据结构函数Functions编写 reducer、procedure 与 view 来实现服务端逻辑订阅Subscriptions实现客户端与服务端之间的实时数据同步Client SDK 语言Client SDKs将客户端应用连接到 SpacetimeDB 数据库。另外如果你希望先建立整体认知可以参考同一目录下的 What is SpacetimeDB 与 关键架构 两篇文档它们对模块运行时、客户端 API、订阅与事务模型有更系统的说明。七、常见问题排查Not logged in执行spacetime login完成认证对只读的公开操作也可以使用--anonymous以匿名身份执行。Server not responding先执行spacetime server ping local确认本地服务状态若针对本地服务器请确认spacetime start正在前台运行。本地端口被占用通过--listen-addr或cli.toml中的listen_addr改用其他端口如4000。Schema conflict重发布失败本地调试时可清空数据后重新发布例如spacetime publish my-db --delete-dataalways --yes该参数也适用于远程请谨慎使用。Rust 模块构建失败确认已安装wasm32-unknown-unknown编译目标执行rustup target add wasm32-unknown-unknown后重试。至此你已经完成了 SpacetimeDB 从安装到本地运行的全链路准备。接下来选择一个你熟悉的语言跑通 Quickstart就能真正体验以光速开发的实时多玩家应用开发流程。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考