在 Railway 上部署 SpacetimeDB从官方模板到客户端接入的完整指南【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDBSpacetimeDB 是一款将数据库逻辑与业务逻辑合二为一的实时数据库官方为其维护了一键部署模板可以让开发者跳过自建虚拟机和运维环节直接获得一个托管的数据库实例。本文以仓库中的 Railway 部署指南 为核心完整讲解从创建 Railway 服务、接入 CLI、发布数据库到客户端连接的整条链路并结合本仓库 CLI 源码server 子命令、publish 子命令、standalone 启动参数深入说明每个命令背后的实际行为与参数含义。读完本文你将能够独立在 Railway 上托管一个 SpacetimeDB 实例并通过任意受支持的 SDK 连接和使用它。Railway 模板部署了什么Railway 是一个托管平台用于部署基础设施和应用服务。如果不想自己维护 VM官方 Railway 模板是在最短时间内跑起 SpacetimeDB 的途径。该模板主要做了三件事拉取官方镜像部署的是第一方镜像clockworklabs/spacetime即 SpacetimeDB 的独立服务器standalone发行版暴露端口3000SpacetimeDB 的 HTTP 与 WebSocket 服务默认监听 3000 端口。从本仓库的启动参数源码可以看到spacetime start的--listen-addr默认值正是0.0.0.0:3000见 crates/standalone/src/subcommands/start.rs模板直接沿用了这一默认行为挂载持久化存储/stdb数据库的数据目录被挂载到容器的/stdb路径保证实例重启后数据不丢失。部署完成后服务即处于运行状态你可以通过 CLI 向其发布一个或多个数据库。需要特别注意的是模板只负责把 SpacetimeDB 服务器本身跑起来并不会替你发布模块。你的数据库 schema 与业务逻辑仍然需要通过spacetime publish来部署这一点在本文第 3 步会详细展开。前置条件开始之前请确认以下三项均已就绪一个 Railway 账户本地已安装 SpacetimeDB CLI官方安装脚本见 SpacetimeDB 安装文档 或仓库内的 spacetime-install.sh一个已准备好待发布的 SpacetimeDB 模块项目Rust、C#、TypeScript、C 均可对应模块工程模板可参考 templates 目录。第 1 步部署官方 Railway 模板打开官方部署模板入口点击Deploy Now按钮然后新建一个 Railway 项目或选择已有项目等待部署完成在 Railway 控制台打开该 service复制其公共域名public domain或为它绑定自定义域名。这个域名就是你后续 CLI 和客户端连接该 SpacetimeDB 实例的 base URL。域名形如https://my-railway-app.up.railway.app务必复制完整含https://协议头。第 2 步将 Railway 部署注册到 CLISpacetimeDB CLI 通过“命名服务器named server”来管理多个远端连接。执行以下命令将你的 Railway 域名注册为一个昵称为railway的服务器spacetime server add --url https://your-railway-domain railway实际示例spacetime server add --url https://my-railway-app.up.railway.app railway这里railway是昵称nickname后续所有命令都可以用railway代替完整的 URL。从源码看server add的行为在 crates/cli/src/subcommands/server.rs 中server add的参数定义如下--url必填服务器的 URL位置参数name必填该服务器的昵称-d, --default可选将新服务器设为默认服务器后续命令省略--server时即指向它--no-fingerprint可选跳过对服务器的指纹fingerprint校验。执行server add时CLI 会默认向服务器请求一次指纹并保存在本地配置中见 exec_add。这一机制用于后续连接时校验服务器身份防止连接被中间人替换。若服务器暂时不可达导致无法获取指纹命令会失败并给出提示此时可以使用--no-fingerprint跳过该步骤。另外需要注意--url中的协议头只能是http或https见 crates/cli/src/util.rs 中的VALID_PROTOCOLS且 URL 末尾多余的/会被自动去除避免后续拼接路径时出现双斜杠。验证连接注册完成后可以可选地验证实例是否在线spacetime server ping railway从 exec_ping 的实现可以看到该命令实际是向{url}/v1/ping发送 HTTP GET 请求返回200 OK时打印Server is online返回404时说明该地址不是 SpacetimeDB 端点其余状态码则提示服务器不可达。其他常用服务器管理命令spacetime server list列出所有已保存的服务器配置并标注当前默认服务器spacetime server set-default name|host|url切换默认服务器spacetime server edit --new-name nick --url url railway修改已保存服务器的昵称或地址会重新校验指纹spacetime server remove railway移除服务器配置。第 3 步发布你的数据库在模块项目目录下将数据库发布到刚才注册的 Railway 部署spacetime publish my-database --server railway其中my-database是数据库名称--server railway指定目标服务器昵称-s为短选项见 common_args.rs。之后若要更新已有数据库只需再次运行同一条命令SpacetimeDB 会进行 schema 迁移并更新模块。publish 命令的关键参数从 crates/cli/src/subcommands/publish.rs 可以看到publish还支持以下常用参数参数说明-p, --module-path PATH模块项目路径默认依次查找spacetimedb/子目录、当前目录-b, --bin-path WASM直接发布已编译好的 wasm 二进制跳过本地构建与--module-path互斥-j, --js-path JS发布 JavaScript 模块UNSTABLE与上述参数互斥--build-options OPTS透传给构建命令的额外选项例如--build-options--lint-dir-c, --clear-database在发布前清空目标数据库的数据当发布目标不是本地服务器localhost/127.0.0.1时CLI 会显示确认提示见 publish.rs并引导你登录以获得发布凭据。在无人值守的 CI 场景中可用-y/--yes跳过确认见 common_args.rs。关于发布权限的提醒与 自托管指南 中 Nginx 反向代理默认“只允许订阅与身份注册、禁止远端发布”的保守配置不同Railway 官方模板默认开放了 SpacetimeDB 的标准 HTTP/WebSocket 端口因此你可以直接从本地发布数据库。这也意味着任何知道该域名的人理论上都可以尝试连接或发布如果实例对外长期开放建议关注身份认证如 SpacetimeAuth与网络策略。第 4 步连接客户端发布完成后客户端就可以使用 Railway 域名作为服务器 URI、数据库名称作为目标数据库来建立连接。所有受支持 SDK 都采用DbConnection构造器builder模式以下为各语言的核心连接代码。TypeScriptimport { DbConnection } from ./module_bindings; const conn DbConnection.builder() .withUri(https://my-railway-app.up.railway.app) .withDatabaseName(my_database) .build();C#含 Unityusing SpacetimeDB; var conn DbConnection.Builder() .WithUri(https://my-railway-app.up.railway.app) .WithDatabaseName(my_database) .Build();Rustuse module_bindings::DbConnection; let conn DbConnection::builder() .with_uri(https://my-railway-app.up.railway.app) .with_database_name(my_database) .build();Unreal#include ModuleBindings/DbConnection.h UDbConnection* Conn UDbConnection::Builder() -WithUri(TEXT(https://my-railway-app.up.railway.app)) -WithDatabaseName(TEXT(my_database)) -Build();带身份令牌的连接若实例启用了身份认证可通过.withToken(your_auth_token_here)Rust 为.with_token(...)在构造连接时传入令牌。该令牌会在连接建立时发送给服务器用于校验你的身份。令牌的获取与管理方式参见 SpacetimeAuth 文档连接状态可通过onConnect/on_connect等回调观察。完整的连接模式、生命周期回调、重连策略与多语言示例参见 Connecting to SpacetimeDB。多数据库与更新多数据库共存一个 Railway 托管的 SpacetimeDB 实例可以同时托管多个数据库。只需针对每个数据库各执行一次spacetime publish db-name --server railway即可更新已有数据库重新运行spacetime publish同一命令即可完成模块与 schema 的升级删除与清理可在本地通过spacetime server remove railway移除服务器配置如需清空某个本地数据库数据可参考spacetime server clear该命令作用于本地数据目录参见 server.rs请谨慎使用。与自托管方案对比如何选择Railway 模板适合以下场景希望跳过操作系统、反向代理、systemd 与证书管理等运维环节快速获得一个可达的实例开发、演示、原型验证或对底层可控性要求不高的生产项目希望复用 Railway 提供的域名、自动重启与存储挂载能力。如果你需要完全控制主机、反向代理规则与操作系统层面的配置例如按 自托管指南 用 Nginx Lets Encrypt systemd 搭建生产环境或通过 Nginx 的location规则精细控制谁能发布、谁能订阅则应选择自托管方案。两种方案的核心差异在于Railway 模板把端口与存储直接开放给你使用而自托管指南默认只开放/v1/identity与/v1/database/db/subscribe两条路径其余管理性路由仅限本机访问。小结通过本文的四步流程——部署官方模板、spacetime server add注册服务器、spacetime publish发布数据库、客户端DbConnection接入——你可以在一小时内获得一个可远程访问的 SpacetimeDB 实时数据库服务。结合仓库源码server add的指纹校验、ping的/v1/ping探活、publish的非本地发布确认等细节能帮助你在排障与自动化集成如 CI 流水线时做出更准确的判断。若后续对实例的可控性提出更高要求自托管指南 提供了完整的进阶方案。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Railway 上部署 SpacetimeDB：从官方模板到客户端接入的完整指南
在 Railway 上部署 SpacetimeDB从官方模板到客户端接入的完整指南【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDBSpacetimeDB 是一款将数据库逻辑与业务逻辑合二为一的实时数据库官方为其维护了一键部署模板可以让开发者跳过自建虚拟机和运维环节直接获得一个托管的数据库实例。本文以仓库中的 Railway 部署指南 为核心完整讲解从创建 Railway 服务、接入 CLI、发布数据库到客户端连接的整条链路并结合本仓库 CLI 源码server 子命令、publish 子命令、standalone 启动参数深入说明每个命令背后的实际行为与参数含义。读完本文你将能够独立在 Railway 上托管一个 SpacetimeDB 实例并通过任意受支持的 SDK 连接和使用它。Railway 模板部署了什么Railway 是一个托管平台用于部署基础设施和应用服务。如果不想自己维护 VM官方 Railway 模板是在最短时间内跑起 SpacetimeDB 的途径。该模板主要做了三件事拉取官方镜像部署的是第一方镜像clockworklabs/spacetime即 SpacetimeDB 的独立服务器standalone发行版暴露端口3000SpacetimeDB 的 HTTP 与 WebSocket 服务默认监听 3000 端口。从本仓库的启动参数源码可以看到spacetime start的--listen-addr默认值正是0.0.0.0:3000见 crates/standalone/src/subcommands/start.rs模板直接沿用了这一默认行为挂载持久化存储/stdb数据库的数据目录被挂载到容器的/stdb路径保证实例重启后数据不丢失。部署完成后服务即处于运行状态你可以通过 CLI 向其发布一个或多个数据库。需要特别注意的是模板只负责把 SpacetimeDB 服务器本身跑起来并不会替你发布模块。你的数据库 schema 与业务逻辑仍然需要通过spacetime publish来部署这一点在本文第 3 步会详细展开。前置条件开始之前请确认以下三项均已就绪一个 Railway 账户本地已安装 SpacetimeDB CLI官方安装脚本见 SpacetimeDB 安装文档 或仓库内的 spacetime-install.sh一个已准备好待发布的 SpacetimeDB 模块项目Rust、C#、TypeScript、C 均可对应模块工程模板可参考 templates 目录。第 1 步部署官方 Railway 模板打开官方部署模板入口点击Deploy Now按钮然后新建一个 Railway 项目或选择已有项目等待部署完成在 Railway 控制台打开该 service复制其公共域名public domain或为它绑定自定义域名。这个域名就是你后续 CLI 和客户端连接该 SpacetimeDB 实例的 base URL。域名形如https://my-railway-app.up.railway.app务必复制完整含https://协议头。第 2 步将 Railway 部署注册到 CLISpacetimeDB CLI 通过“命名服务器named server”来管理多个远端连接。执行以下命令将你的 Railway 域名注册为一个昵称为railway的服务器spacetime server add --url https://your-railway-domain railway实际示例spacetime server add --url https://my-railway-app.up.railway.app railway这里railway是昵称nickname后续所有命令都可以用railway代替完整的 URL。从源码看server add的行为在 crates/cli/src/subcommands/server.rs 中server add的参数定义如下--url必填服务器的 URL位置参数name必填该服务器的昵称-d, --default可选将新服务器设为默认服务器后续命令省略--server时即指向它--no-fingerprint可选跳过对服务器的指纹fingerprint校验。执行server add时CLI 会默认向服务器请求一次指纹并保存在本地配置中见 exec_add。这一机制用于后续连接时校验服务器身份防止连接被中间人替换。若服务器暂时不可达导致无法获取指纹命令会失败并给出提示此时可以使用--no-fingerprint跳过该步骤。另外需要注意--url中的协议头只能是http或https见 crates/cli/src/util.rs 中的VALID_PROTOCOLS且 URL 末尾多余的/会被自动去除避免后续拼接路径时出现双斜杠。验证连接注册完成后可以可选地验证实例是否在线spacetime server ping railway从 exec_ping 的实现可以看到该命令实际是向{url}/v1/ping发送 HTTP GET 请求返回200 OK时打印Server is online返回404时说明该地址不是 SpacetimeDB 端点其余状态码则提示服务器不可达。其他常用服务器管理命令spacetime server list列出所有已保存的服务器配置并标注当前默认服务器spacetime server set-default name|host|url切换默认服务器spacetime server edit --new-name nick --url url railway修改已保存服务器的昵称或地址会重新校验指纹spacetime server remove railway移除服务器配置。第 3 步发布你的数据库在模块项目目录下将数据库发布到刚才注册的 Railway 部署spacetime publish my-database --server railway其中my-database是数据库名称--server railway指定目标服务器昵称-s为短选项见 common_args.rs。之后若要更新已有数据库只需再次运行同一条命令SpacetimeDB 会进行 schema 迁移并更新模块。publish 命令的关键参数从 crates/cli/src/subcommands/publish.rs 可以看到publish还支持以下常用参数参数说明-p, --module-path PATH模块项目路径默认依次查找spacetimedb/子目录、当前目录-b, --bin-path WASM直接发布已编译好的 wasm 二进制跳过本地构建与--module-path互斥-j, --js-path JS发布 JavaScript 模块UNSTABLE与上述参数互斥--build-options OPTS透传给构建命令的额外选项例如--build-options--lint-dir-c, --clear-database在发布前清空目标数据库的数据当发布目标不是本地服务器localhost/127.0.0.1时CLI 会显示确认提示见 publish.rs并引导你登录以获得发布凭据。在无人值守的 CI 场景中可用-y/--yes跳过确认见 common_args.rs。关于发布权限的提醒与 自托管指南 中 Nginx 反向代理默认“只允许订阅与身份注册、禁止远端发布”的保守配置不同Railway 官方模板默认开放了 SpacetimeDB 的标准 HTTP/WebSocket 端口因此你可以直接从本地发布数据库。这也意味着任何知道该域名的人理论上都可以尝试连接或发布如果实例对外长期开放建议关注身份认证如 SpacetimeAuth与网络策略。第 4 步连接客户端发布完成后客户端就可以使用 Railway 域名作为服务器 URI、数据库名称作为目标数据库来建立连接。所有受支持 SDK 都采用DbConnection构造器builder模式以下为各语言的核心连接代码。TypeScriptimport { DbConnection } from ./module_bindings; const conn DbConnection.builder() .withUri(https://my-railway-app.up.railway.app) .withDatabaseName(my_database) .build();C#含 Unityusing SpacetimeDB; var conn DbConnection.Builder() .WithUri(https://my-railway-app.up.railway.app) .WithDatabaseName(my_database) .Build();Rustuse module_bindings::DbConnection; let conn DbConnection::builder() .with_uri(https://my-railway-app.up.railway.app) .with_database_name(my_database) .build();Unreal#include ModuleBindings/DbConnection.h UDbConnection* Conn UDbConnection::Builder() -WithUri(TEXT(https://my-railway-app.up.railway.app)) -WithDatabaseName(TEXT(my_database)) -Build();带身份令牌的连接若实例启用了身份认证可通过.withToken(your_auth_token_here)Rust 为.with_token(...)在构造连接时传入令牌。该令牌会在连接建立时发送给服务器用于校验你的身份。令牌的获取与管理方式参见 SpacetimeAuth 文档连接状态可通过onConnect/on_connect等回调观察。完整的连接模式、生命周期回调、重连策略与多语言示例参见 Connecting to SpacetimeDB。多数据库与更新多数据库共存一个 Railway 托管的 SpacetimeDB 实例可以同时托管多个数据库。只需针对每个数据库各执行一次spacetime publish db-name --server railway即可更新已有数据库重新运行spacetime publish同一命令即可完成模块与 schema 的升级删除与清理可在本地通过spacetime server remove railway移除服务器配置如需清空某个本地数据库数据可参考spacetime server clear该命令作用于本地数据目录参见 server.rs请谨慎使用。与自托管方案对比如何选择Railway 模板适合以下场景希望跳过操作系统、反向代理、systemd 与证书管理等运维环节快速获得一个可达的实例开发、演示、原型验证或对底层可控性要求不高的生产项目希望复用 Railway 提供的域名、自动重启与存储挂载能力。如果你需要完全控制主机、反向代理规则与操作系统层面的配置例如按 自托管指南 用 Nginx Lets Encrypt systemd 搭建生产环境或通过 Nginx 的location规则精细控制谁能发布、谁能订阅则应选择自托管方案。两种方案的核心差异在于Railway 模板把端口与存储直接开放给你使用而自托管指南默认只开放/v1/identity与/v1/database/db/subscribe两条路径其余管理性路由仅限本机访问。小结通过本文的四步流程——部署官方模板、spacetime server add注册服务器、spacetime publish发布数据库、客户端DbConnection接入——你可以在一小时内获得一个可远程访问的 SpacetimeDB 实时数据库服务。结合仓库源码server add的指纹校验、ping的/v1/ping探活、publish的非本地发布确认等细节能帮助你在排障与自动化集成如 CI 流水线时做出更准确的判断。若后续对实例的可控性提出更高要求自托管指南 提供了完整的进阶方案。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
