SpacetimeDB 模块发布完整指南从spacetime build到spacetime publish的构建、发布与迁移实战【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本篇指南系统讲解 SpacetimeDB 中模块从源码到线上数据库的全流程如何针对不同运行时Rust/C# 编译为 WASM、TypeScript 打包为 V8 JavaScript构建模块如何通过spacetime publish创建新数据库或原子化更新已有数据库以及--break-clients、--delete-data、--yes等关键选项的适用场景。读完本文你将掌握模块发布命令的完整参数体系、底层执行链路crates/cli/src/subcommands/publish.rs、自动迁移的兼容性边界以及一套可落地的发布与回滚策略。发布前必读理解模块的运行目标在发布之前需要先明确模块的编译产物形态因为不同的服务端语言对应不同的运行时Rust 与 C# 模块编译为 WebAssemblyWASM由 SpacetimeDB 内置的 WASM 运行时执行TypeScript 模块通过打包器产出可在 V8 JavaScript 引擎中运行的 bundle不经过 WASM。这一区分在源码层面有直接体现spacetime publish在决定发布产物时会检查wasm_file与js_file两条路径并携带host_typeWasm或Js查询参数上传给服务端见 crates/cli/src/subcommands/publish.rs 与 L635 的builder.query([(host_type, host_type)])。因此发布命令本身并不关心语言的差异它只关心最终交付的是哪种运行时产物。模块目录约定发布时 CLI 会在当前目录下查找模块工程默认查找顺序为当前目录下的spacetimedb/子目录当前目录本身。该逻辑实现在default_publish_module_pathcrates/cli/src/subcommands/publish.rs若spacetimedb/目录存在则优先使用否则回退到当前目录。这解释了为什么官方模板如 templates/basic-rs/spacetimedb、templates/basic-ts/spacetimedb统一把模块工程放在spacetimedb/下——发布、构建命令无需额外指定路径即可命中模块。第一步构建模块spacetime build进入模块目录通常是项目内的spacetimedb/执行spacetime build该命令会编译你的模块并校验其结构。从源码看spacetime build实际完成的工作包括解析模块路径--module-path缺省时同样遵循spacetimedb/子目录优先的规则见 crates/cli/src/subcommands/build.rs根据模块语言分发到对应的构建任务Rust / C# / TypeScript / C见 crates/cli/src/tasks 目录下的rust.rs、csharp.rs、javascript.rs、cpp.rs对src/目录进行 lint检查非功能性print语句默认 lint 目录为src可通过--lint-dir覆盖或置空关闭产出可发布的 WASM 二进制或 JS bundle。spacetime build常用选项选项说明-p, --module-path MODULE_PATH模块工程路径默认spacetimedb/子目录其次当前目录--lint-dir DIR检查非功能性print语句的目录默认src设为空字符串则跳过 lint-d, --debug以 debug 而非 release 模式构建适合本地快速迭代官方注释明确“不建议用于 CI”--features FEATURES透传给构建进程的附加特性如 Rust 模块的--features feature1,feature2--dotnet-version VERSION指定 C# 项目目标 .NET SDK 主版本如 8 或 10缺省时自动检测:::tip 如果最终目的是发布则无需单独执行spacetime build——spacetime publish会在需要时自动触发构建。对于全部构建选项可参考 spacetime build CLI 参考。 :::第二步发布前认证spacetime login在发布到托管服务之前需要先通过认证建立身份spacetime login命令会打开浏览器窗口完成认证认证完成后凭据保存在本地。从 crates/cli/src/subcommands/login.rs 的实现看登录流程包含如下细节默认向https://spacetimedb.com请求一次性 token然后轮询认证服务器等待用户在浏览器中批准web_loginL206-L250认证成功后换取 SpacetimeDB 登录令牌spacetimedb_loginL264-L283并将令牌保存到本地配置支持--no-browser不自动打开浏览器打印 URL 由用户手动打开、--token TOKEN直接使用已有令牌跳过整个流程、spacetime login show查看当前登录身份加--token可同时显示令牌自托管场景可用--server-issued-login直接向目标服务器登录但这种登录方式对其他服务器无效。若未登录就执行发布CLI 会尝试交互式登录get_auth_header内部处理见 crates/cli/src/subcommands/publish.rs在非交互脚本中可通过--yesskip-login显式跳过登录提示。第三步发布新数据库发布模块并创建新数据库spacetime publish DATABASE_NAME数据库命名规则DATABASE_NAME必须满足正则/^[a-z0-9](-[a-z0-9])*$/即只能由小写 ASCII 字母和数字组成多个单词之间用连字符-分隔如my-chat-app。位置参数也接受数据库 identity。该规则定义在 CLI 参考 的 Arguments 小节并由源码中的validate_name_or_identity执行校验crates/cli/src/subcommands/publish.rs。发布命令的完整执行链路spacetime publish DATABASE_NAME依次完成构建模块如果尚未构建通过build::exec_with_argstring触发可透传--build-options、NativeAOT 与 .NET 版本设置crates/cli/src/subcommands/publish.rs创建新数据库若提供了数据库名则向/v1/database/name发送 PUT 请求若未提供名称则 POST 到/v1/databaseL589-L617上传并安装模块将程序字节码作为请求体发送builder.body(program_bytes).send()L637运行init生命周期 reducer若模块中定义了开始接受客户端连接。保存数据库 identity发布成功后CLI 会输出数据库的域名与 identity。务必保存这个 identity——后续的数据库管理如spacetime logs、spacetime call、spacetime describe、spacetime delete都要靠它或域名来定位数据库。若目标是官方托管服务maincloud.spacetimedb.com还会额外打印 Dashboard 地址L655-L659。第四步更新已有数据库与自动迁移对已发布数据库重新执行同一条命令即可完成更新spacetime publish DATABASE_NAME服务端会依次进行构建你的模块尝试自动迁移 schema使旧数据适配新模块定义原子化替换新模块——发布要么整体成功、要么整体失败不会出现半新半旧状态维持既有客户端连接不中断。自动迁移的兼容性边界“schema”指模块代码中声明的表、reducer、procedure、视图及其依赖类型的集合。SpacetimeDB 的自动迁移详见 自动迁移文档把变更分为三类安全变更总是允许不破坏客户端新增表、新增索引、增删Auto Inc注解、表从私有转公开、新增 reducer、移除Unique约束。潜在破坏性变更允许迁移但未更新客户端可能报错在表末尾新增带默认值的列、变更或移除 reducer旧客户端调用会得到运行时错误、表从公开转私有已订阅的客户端报错、仅改访问器名而保留规范名、移除空表会断开活动客户端、移除Primary Key注解、移除索引可能使基于半连接的订阅查询失效。禁止变更自动迁移会直接失败移除非空表、移除或修改既有列含类型/规范名/顺序变更、新增无默认值的列、在表中间插入列、变更表是否用于scheduling、新增Unique或Primary Key约束、更改索引访问器名。如果你的更新无法自动迁移应参考 增量迁移文档 中的生产级模式开发测试阶段可接受数据丢失时才考虑使用--delete-data整体重置。破坏性变更--break-clients如果更新包含无法自动迁移的破坏性变更需要显式声明接受客户端被破坏spacetime publish --break-clients DATABASE_NAME⚠️警告这会使尚未升级到新 schema 的既有客户端无法继续工作。从源码看--break-clients等价于--yesbreak-clients它跳过“此次变更会 BREAK 既有客户端”的确认提示但不会在变更会导致数据库数据删除时强制发布crates/cli/src/subcommands/publish.rs。真正决定是否清空数据的是--delete-data见下文。其底层通过pre_publish接口向服务端上传模块字节码服务端返回迁移计划若计划标记break_clients为真CLI 会提示确认确认后携带policyBreakClients令牌执行发布apply_pre_publish_if_neededL756-L824。如果本次发布是从 1.x 升级到 2.0 的大版本升级请先阅读 1.x 到 2.0 升级说明。CLI 检测到大版本升级时会要求输入upgrade确认并提示升级后无法回退到 1.0见confirm_major_version_upgradeL345-L368。清空数据--delete-data彻底重置数据库并删除全部数据spacetime publish DATABASE_NAME --delete-data⚠️警告这会永久删除数据库中的所有数据--delete-data短选项-c支持三种取值控制清空发生的时机取值行为always发布到既有数据库前无条件销毁该模块关联的全部数据on-conflict仅当发布会遇到无法自动迁移的破坏性 schema 变更时才清空数据never从不主动清空默认值若必须手动迁移发布将中止执行always清空前CLI 会打印This will DESTROY the current ... module, and ALL corresponding data.并二次确认confirm_and_clearL325-L343。在自动化流水线中可用--yesdelete-data跳过该确认——但请务必确认清空是可接受的。第五步发布选项全景spacetime publish的完整签名是spacetime publish [OPTIONS] [name|identity]除上文已讲的参数外常用选项如下均来自 CLI 参考选项说明-p, --module-path MODULE_PATH模块工程路径绝对或相对默认spacetimedb/子目录其次当前目录-b, --bin-path WASM_FILE直接发布已编译的 WASM 二进制跳过构建与--module-path、--build-options、--js-path互斥-j, --js-path JS_FILEUNSTABLE直接发布已打包的 JavaScript 文件跳过构建--build-options BUILD_OPTIONS透传给构建命令的选项例如--build-options--lint-dir-s, --server SERVER托管数据库的服务器昵称、域名或 URL--parent PARENT父数据库的域名或 identity新数据库继承父库的团队权限只能在创建时设置更新时无效--organization ORGANIZATION新数据库归属的组织名称或 identity组织成员权限适用于该库同样只能在创建时设置--anonymous以匿名身份执行操作-y, --yes [YES]跳过确认提示见下文详述--no-config忽略spacetime.json配置--env ENV配置文件的层级环境名如dev、staging--native-aot对 C# 模块使用 NativeAOT-LLVM 编译实验性支持 Windows以及安装了 .NET 10 的 Linux--dotnet-version VERSION指定 C# 项目目标 .NET SDK 主版本缺省自动检测--yes跳过各类确认提示--yes-y用于自动化场景跳过交互确认。不带值时等价于--yesall。可精细指定要跳过的提示类别多个值可用逗号分隔或重复传参spacetime publish my-db --yesmigrate,break-clients spacetime publish my-db --yesmigrate --yesbreak-clients--yes取值跳过的提示all等价于传入下面所有选项remote“发布到非本地服务器”确认migrate迁移确认例如大版本升级break-clients“会 BREAK 既有客户端”确认skip-login不提示登录认证采用非交互方式delete-data“将 DESTROY ... 全部数据”的破坏性确认注意值必须用附着即--yes my-db会把my-db当作数据库名而非--yes的值见 crates/cli/src/subcommands/publish.rs 的 clap 定义。使用spacetime.json管理发布目标从 crates/cli/src/spacetime_config.rs 的配置模型看spacetime publish会优先读取项目根目录的spacetime.json可通过--no-config忽略、--env切换环境分层。配置文件以数据库为核心组织目标database、server、module_path、build_options、wasm_file、js_file、parent、organization等键见build_publish_schemacrates/cli/src/subcommands/publish.rs支持父子目标继承CLI 传入的数据库名会以 glob 模式匹配配置文件中的多个目标一次发布多个数据库spacetime init生成随机数据库后缀时CLI 传入的名称与配置不一致也会正确合并模块级配置若配置中存在多个目标而 CLI 未指定数据库名会提示指定名称或 identity 以选中单一目标。这使得把发布目标固化到仓库配置中、团队共享一致的发布参数成为可能。发布流程的底层调用链综合以上内容一次发布在 CLI 侧的完整调用链为对应 crates/cli/src/subcommands/publish.rs 的exec_with_options→execute_publish_configs加载spacetime.json配置或仅用 CLI 参数解析出发布目标集合确定module_path与构建选项若指定--bin-path/--js-path则跳过构建获取认证头未登录且未加--yesskip-login时触发登录校验数据库名与 parent本地构建或读取预编译产物读取程序字节码对非本地服务器非localhost/127.0.0.1执行发布前二次确认若有数据库名先调用pre_publish接口获取迁移计划新库返回 404 视为无需迁移按计划提示迁移/破坏性变更确认或触发清空流程PUT/v1/database/name或 POST/v1/database上传模块附加host_type、parent、org、num_replicas等参数解析PublishResult打印“Created new / Updated database with name/identity”权限不足时给出建议的新域名。其中num_replicas为隐藏的 UNSTABLE 选项--num-replicas用于指定数据库副本数L233-L238。发布最佳实践开发阶段早期开发中数据丢失可接受时放心使用--delete-data-calways快速重置使用-d/--debug或单独执行spacetime build加速本地迭代为开发、预发、生产分别建立独立数据库用spacetime.json固化各自目标。生产阶段谨慎规划 schema 变更发布前对照自动迁移的三类兼容性规则逐条检查与客户端升级协同涉及潜在破坏性变更时先升级客户端再发布--break-clients把断连窗口降到最低优先向后兼容尽量新增表/reducer 而非修改既有结构用增量迁移模式处理复杂变更保留数据库 identity作为后续运维操作的定位依据。发布之后下一步学习模块上线后可以继续深入学习连接客户端 与数据库交互深入了解表、reducer 与procedure 的定义与生命周期查阅自动迁移 与增量迁移 的完整规则若使用spacetime dev进行本地热重载开发参考开发命令文档。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考