尧图网页设计 
SpacetimeDB 自托管实战指南Ubuntu 24.04 上的 Nginx Lets Encrypt systemd 生产部署【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本指南以 SpacetimeDB 官方自托管文档为主体完整演示如何在一台全新的 Ubuntu 24.04 服务器上部署 SpacetimeDB创建专用系统用户安装运行时、用 systemd 托管服务进程、通过 Nginx 反向代理暴露 WebSocket/HTTP 接口并配置 HTTPS 证书、在默认封闭策略下安全地向远程实例发布模块以及如何升级版本与排查故障。读完本文你将具备一套可直接复制的生产级自托管方案并理解每一步背后的源码级原理。前置条件开始之前你需要准备一台全新的 Ubuntu 24.04 服务器VM 或任意云厂商实例一个已解析到该服务器 IP 的域名例如example.com服务器上的sudo权限。整个部署流程涉及七个步骤创建专用用户 → 配置 systemd 服务 → 安装并配置 Nginx → 用 Lets Encrypt 加固 HTTPS → 验证并配置 CLI 连接 → 升级版本 → 故障排查。第一步为 SpacetimeDB 创建专用系统用户出于安全考虑建议为 SpacetimeDB 创建一个专用的系统用户spacetimedb让服务进程以最小权限运行避免直接使用 root 或普通高权限账号sudo mkdir /stdb sudo useradd --system spacetimedb sudo chown -R spacetimedb:spacetimedb /stdb/stdb将作为 SpacetimeDB 的专属数据与安装根目录useradd --system创建的是系统账户无登录 shell、UID 落在系统范围内适合守护进程场景将/stdb的所有权交给spacetimedb用户后续安装与运行都无需 root 写权限。然后以该用户身份执行官方安装脚本并指定根目录与自动确认sudo -u spacetimedb bash -c curl -sSf https://install.spacetimedb.com | sh -s -- --root-dir /stdb --yes--root-dir /stdb会把 CLI 二进制、版本目录与数据目录统一收敛到/stdb之下--yes跳过交互确认适合脚本化安装。从源码看--root-dir是 CLI 与自更新工具共用的路径锚点spacetimedb-update的所有子命令都接受该参数并通过SpacetimePaths::from_root_dir派生出 bin 目录与数据目录。第二步创建 systemd 服务为了让 SpacetimeDB 在开机时自动运行并在崩溃后自动拉起需要编写一个 systemd unit 文件sudo nano /etc/systemd/system/spacetimedb.service写入如下内容[Unit] DescriptionSpacetimeDB Server Afternetwork.target [Service] ExecStart/stdb/spacetime --root-dir/stdb start --listen-addr127.0.0.1:3000 Restartalways Userspacetimedb WorkingDirectory/stdb [Install] WantedBymulti-user.target逐项说明ExecStart以/stdb/spacetime启动服务。spacetime start只是 CLI 的转发入口实际会 exec 真正的spacetimedb-standalone start见 crates/cli/src/subcommands/start.rs并把--data-dir与 JWT 密钥目录一并传下去--listen-addr127.0.0.1:3000仅监听本机回环地址。standalone 的--listen-addr-l默认值是0.0.0.0:3000监听所有网卡见 crates/standalone/src/subcommands/start.rs自托管时通常让 Nginx 独占公网入口因此这里显式收窄到回环地址避免服务直接暴露在公网Restartalways进程异常退出时由 systemd 自动重启Userspacetimedb以第一步创建的专用用户运行WantedBymulti-user.target开机自启。如果你希望把监听地址做成持久默认值也可以在 CLI 配置文件cli.toml中写入listen_addr 0.0.0.0:4000。当配置存在时Config::start_listen_addr会将其作为默认值注入显式传入的--listen-addr优先见 crates/cli/src/subcommands/start.rs 的注释说明。启用并启动服务sudo systemctl enable spacetimedb sudo systemctl start spacetimedb检查服务状态sudo systemctl status spacetimedb第三步安装并配置 Nginx 反向代理Nginx 负责把公网 80/443 端口的流量转发给回环地址上的 SpacetimeDB默认 3000 端口并为后续的 Lets Encrypt 证书提供承载。安装 Nginxsudo apt update sudo apt install nginx -y配置反向代理与路由白名单创建站点配置文件sudo nano /etc/nginx/sites-available/spacetimedb写入以下内容请将example.com替换为你自己的域名server { listen 80; server_name example.com; ######################################### # By default SpacetimeDB is completely open so that anyone can publish to it. If you want to block # users from creating new databases you should keep this section commented out. Otherwise, if you # want to open it up (probably for dev environments) then you can uncomment this section and then # also comment out the location / section below. ######################################### # location / { # proxy_pass http://localhost:3000; # proxy_http_version 1.1; # proxy_set_header Upgrade $http_upgrade; # proxy_set_header Connection Upgrade; # proxy_set_header Host $host; # } # Anyone can subscribe to any database. # Note: This is the only section *required* for the websocket to function properly. Clients will # be able to create identities, call reducers, and subscribe to tables through this websocket. location ~ ^/v1/database/[^/]/subscribe$ { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection Upgrade; proxy_set_header Host $host; } # Uncomment this section to allow all HTTP reducer calls # location ~ ^/v1/[^/]/call/[^/]$ { # proxy_pass http://localhost:3000; # proxy_http_version 1.1; # proxy_set_header Upgrade $http_upgrade; # proxy_set_header Connection Upgrade; # proxy_set_header Host $host; # } # Uncomment this section to allow all HTTP sql requests # location ~ ^/v1/[^/]/sql$ { # proxy_pass http://localhost:3000; # proxy_http_version 1.1; # proxy_set_header Upgrade $http_upgrade; # proxy_set_header Connection Upgrade; # proxy_set_header Host $host; # } # NOTE: This is required for the typescript sdk to function, it is optional # for the rust and the C# SDKs. location /v1/identity { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection Upgrade; proxy_set_header Host $host; } # Block all other routes explicitly. Only localhost can use these routes. If you want to open your # server up so that anyone can publish to it you should comment this section out. location / { allow 127.0.0.1; deny all; } }这段配置默认只放行两类路由其余一律只允许本机访问location ~ ^/v1/database/[^/]/subscribe$数据库订阅 WebSocket 端点客户端通过它创建身份、调用 reducer 并订阅表变更——这是 WebSocket 正常工作的唯一必需放行项。该端点对应源码路由GET /database/:name_or_identity/subscribe见 crates/client-api/src/routes/database.rslocation /v1/identity身份管理端点POST /identity创建身份等见 crates/client-api/src/routes/identity.rsTypeScript SDK 依赖它Rust 与 C# SDK 则属于可选被注释掉的^/v1/[^/]/call/[^/]$HTTP reducer 调用见 crates/client-api/src/routes/database.rs与^/v1/[^/]/sql$HTTP SQL 请求见 crates/client-api/src/routes/database.rs默认不对外兜底的location /用allow 127.0.0.1; deny all;拒绝一切远端请求从而阻止所有远程用户向你的实例发布数据库。理解这段配置的关键在于路由结构所有客户端路由都挂在/v1前缀之下见 crates/client-api/src/routes/mod.rs而健康检查/探活端点则是/v1/ping见 crates/client-api/src/routes/mod.rs。WebSocket 与 HTTP 调用共用同一套路径因此需要Upgrade/Connection头转发来支持协议升级。启用站点并重启 Nginxsudo ln -s /etc/nginx/sites-available/spacetimedb /etc/nginx/sites-enabled/ sudo systemctl restart nginx配置防火墙确保防火墙放行 HTTPS与 HTTP流量sudo ufw allow Nginx Full sudo ufw reloadNginx Full是 UFW 内置的规则同时放行 80 与 443 端口。若 UFW 未启用可以sudo ufw enable后再执行上述命令。第四步使用 Lets Encrypt 加固 HTTPS安装 Certbotsudo apt install certbot python3-certbot-nginx -ypython3-certbot-nginx是 Nginx 插件允许 Certbot 自动改写 Nginx 配置并完成证书部署。申请 SSL 证书将example.com替换为你自己的域名后执行sudo certbot --nginx -d example.comCertbot 会通过 HTTP-01 挑战验证域名所有权自动为 Nginx 配置 SSL 并重载服务。完成后重启 Nginx 以确认配置生效sudo systemctl restart nginx自动续期Certbot 在安装时会自动注册一个 systemd 定时器certbot.timer。验证其处于活动状态sudo systemctl status certbot.timer证书有效期接近届满时定时器会自动执行续期并重载 Nginx无需人工干预。第五步验证安装并连接 CLI在你的本地开发机上把新服务器加入 CLI 的服务器配置替换example.comspacetime server add self-hosted --url https://example.com从源码看spacetime server add支持多个参数见 crates/cli/src/subcommands/server.rs--url必填服务器 URL支持https://example.com形式也接受host:port写法源码中会自动去除末尾/并解析出 host 与协议https/httpself-hosted为该服务器配置起一个昵称后续所有命令可用昵称引用-d/--default将新服务器设为默认服务器--no-fingerprint跳过服务器指纹校验。spacetime server add默认会向服务器请求并保存指纹fingerprint这是防止中间人攻击的信任锚点如果服务器尚未就绪可以先用--no-fingerprint跳过稍后通过spacetime server fingerprint name补录。CLI 还提供配套的服务器管理子命令同见 crates/cli/src/subcommands/server.rsspacetime server list列出所有已保存的服务器配置及默认标记spacetime server set-default name切换默认服务器spacetime server ping name探测服务器在线状态请求/v1/ping见 crates/cli/src/subcommands/server.rsspacetime server edit --new-name ... --url ...修改昵称或 URLspacetime server remove name删除配置。受限模式下的发布流程由于第三步的 Nginx 配置默认封死了/路由远端用户无法直接通过 HTTP 发布数据库。此时推荐的做法是在本机构建模块把编译产物拷贝到服务器主机上再通过本机通道发布。例如spacetime build scp target/wasm32-unknown-unknown/release/spacetime_module.wasm ubuntuhost:/home/ubuntu/ ssh ubuntuhost spacetime publish -s local --bin-path spacetime_module.wasm database-name命令解析对应 crates/cli/src/subcommands/publish.rsspacetime build在本地把模块编译为 WASMRust 模块产物默认位于target/wasm32-unknown-unknown/release/scp把.wasm产物上传到服务器spacetime publish -s local-s/--server指定服务器此处为默认的本地服务器即服务器本机的 CLI 配置能够直连 127.0.0.1 而不经过被封锁的 Nginx 路由--bin-path spacetime_module.wasm-b/--bin-path指示跳过构建、直接发布指定的预编译二进制与--module-path、--build-options互斥。可以把上述命令封装成 shell 脚本让发布流程更快更稳定也可以将类似脚本接入 CI例如 GitHub Actions在PR 合入 master等事件触发时自动发布到服务器。补充说明发布到非本机地址时CLI 会先打印You are about to publish to a non-local server: host并要求确认见 crates/cli/src/subcommands/publish.rs。在自动化场景下可以用--yes跳过交互确认它支持按类别细分--yesremote跳过远程发布确认、--yesmigrate、--yesbreak-clients、--yesskip-login、--yesdelete-data或直接--yes等价于--yesall。第六步升级 SpacetimeDB 版本升级前先停止服务避免运行中的实例被替换sudo systemctl stop spacetimedb升级到最新版本sudo -u spacetimedb -i -- spacetime --root-dir/stdb version upgradespacetime version子命令是版本管理的入口会把请求转发给自更新工具spacetimedb-update见 crates/cli/src/subcommands/version.rs后者负责从发布源下载并切换版本。upgrade会获取最新版本、安装并把当前版本指针切换到新版本见 crates/update/src/cli/upgrade.rs。要安装指定版本使用sudo -u spacetimedb -i -- spacetime --root-dir/stdb install version-numberinstall version安装指定版本若加--use参数则在安装后立即切换过去见 crates/update/src/cli/install.rs。spacetime version还支持list列出已安装版本、uninstall version等子命令见 crates/update/src/cli.rs。最后重新启动服务sudo systemctl start spacetimedb第七步故障排查SpacetimeDB 服务启动失败查看服务日志定位错误sudo journalctl -u spacetimedb --no-pager | tail -20确认spacetimedb用户对可执行文件与数据目录拥有正确权限sudo ls -lah /stdb/spacetime如果缺少可执行权限手动补上sudo chmod x /stdb/spacetimeLets Encrypt 证书续期异常手动触发一次续期演练检查报错sudo certbot renew --dry-runNginx 启动失败先做配置语法自检sudo nginx -t发现错误后查看 Nginx 日志sudo journalctl -u nginx --no-pager | tail -20生产加固进阶理解并调优 config.toml首次以某个数据目录启动时standalone 会在数据目录下写入一份默认的config.toml见 crates/standalone/src/subcommands/start.rs仓库内模板见 crates/standalone/config.toml。自托管场景下值得关注的关键配置段包括[module-http] enabled是否允许数据库模块发起出站 HTTP 请求覆盖 procedure 与模块 HTTP handler默认允许[logs] level/directives日志级别过滤与 tracing 指令模板默认开启spacetimedb*系列的 debug 日志便于运维观察[wasm] procedure-instance-pool-size每个数据库的 WASM procedure 实例池上限缺省按 OS 报告的 CPU 核数决定[v8]段对应 JS 实例池[websocket] ping-interval与idle-timeoutWebSocket 心跳 Ping 帧间隔默认15s与空闲超时默认30s必须大于 ping-interval慢客户端也会被正确纳入空闲判定[commitlog]提交日志段大小、写缓冲、offset 索引与预分配策略等持久化相关参数直接影响写吞吐与崩溃恢复。修改config.toml后重启spacetimedb服务即可生效。结合 crates/standalone/config.toml 中的完整注释你可以根据服务器规格与业务规模连接数、模块调用频率、数据量逐步调优。至此一台由 systemd 托管、Nginx 反向代理、Lets Encrypt 提供 HTTPS、默认拒绝远端发布的高安全性 SpacetimeDB 自托管实例即告完成并且具备版本升级与完整排障手段可作为生产或长期运行环境直接投入使用。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SpacetimeDB 自托管实战指南：Ubuntu 24.04 上的 Nginx + Let‘s Encrypt + systemd 生产部署
SpacetimeDB 自托管实战指南Ubuntu 24.04 上的 Nginx Lets Encrypt systemd 生产部署【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本指南以 SpacetimeDB 官方自托管文档为主体完整演示如何在一台全新的 Ubuntu 24.04 服务器上部署 SpacetimeDB创建专用系统用户安装运行时、用 systemd 托管服务进程、通过 Nginx 反向代理暴露 WebSocket/HTTP 接口并配置 HTTPS 证书、在默认封闭策略下安全地向远程实例发布模块以及如何升级版本与排查故障。读完本文你将具备一套可直接复制的生产级自托管方案并理解每一步背后的源码级原理。前置条件开始之前你需要准备一台全新的 Ubuntu 24.04 服务器VM 或任意云厂商实例一个已解析到该服务器 IP 的域名例如example.com服务器上的sudo权限。整个部署流程涉及七个步骤创建专用用户 → 配置 systemd 服务 → 安装并配置 Nginx → 用 Lets Encrypt 加固 HTTPS → 验证并配置 CLI 连接 → 升级版本 → 故障排查。第一步为 SpacetimeDB 创建专用系统用户出于安全考虑建议为 SpacetimeDB 创建一个专用的系统用户spacetimedb让服务进程以最小权限运行避免直接使用 root 或普通高权限账号sudo mkdir /stdb sudo useradd --system spacetimedb sudo chown -R spacetimedb:spacetimedb /stdb/stdb将作为 SpacetimeDB 的专属数据与安装根目录useradd --system创建的是系统账户无登录 shell、UID 落在系统范围内适合守护进程场景将/stdb的所有权交给spacetimedb用户后续安装与运行都无需 root 写权限。然后以该用户身份执行官方安装脚本并指定根目录与自动确认sudo -u spacetimedb bash -c curl -sSf https://install.spacetimedb.com | sh -s -- --root-dir /stdb --yes--root-dir /stdb会把 CLI 二进制、版本目录与数据目录统一收敛到/stdb之下--yes跳过交互确认适合脚本化安装。从源码看--root-dir是 CLI 与自更新工具共用的路径锚点spacetimedb-update的所有子命令都接受该参数并通过SpacetimePaths::from_root_dir派生出 bin 目录与数据目录。第二步创建 systemd 服务为了让 SpacetimeDB 在开机时自动运行并在崩溃后自动拉起需要编写一个 systemd unit 文件sudo nano /etc/systemd/system/spacetimedb.service写入如下内容[Unit] DescriptionSpacetimeDB Server Afternetwork.target [Service] ExecStart/stdb/spacetime --root-dir/stdb start --listen-addr127.0.0.1:3000 Restartalways Userspacetimedb WorkingDirectory/stdb [Install] WantedBymulti-user.target逐项说明ExecStart以/stdb/spacetime启动服务。spacetime start只是 CLI 的转发入口实际会 exec 真正的spacetimedb-standalone start见 crates/cli/src/subcommands/start.rs并把--data-dir与 JWT 密钥目录一并传下去--listen-addr127.0.0.1:3000仅监听本机回环地址。standalone 的--listen-addr-l默认值是0.0.0.0:3000监听所有网卡见 crates/standalone/src/subcommands/start.rs自托管时通常让 Nginx 独占公网入口因此这里显式收窄到回环地址避免服务直接暴露在公网Restartalways进程异常退出时由 systemd 自动重启Userspacetimedb以第一步创建的专用用户运行WantedBymulti-user.target开机自启。如果你希望把监听地址做成持久默认值也可以在 CLI 配置文件cli.toml中写入listen_addr 0.0.0.0:4000。当配置存在时Config::start_listen_addr会将其作为默认值注入显式传入的--listen-addr优先见 crates/cli/src/subcommands/start.rs 的注释说明。启用并启动服务sudo systemctl enable spacetimedb sudo systemctl start spacetimedb检查服务状态sudo systemctl status spacetimedb第三步安装并配置 Nginx 反向代理Nginx 负责把公网 80/443 端口的流量转发给回环地址上的 SpacetimeDB默认 3000 端口并为后续的 Lets Encrypt 证书提供承载。安装 Nginxsudo apt update sudo apt install nginx -y配置反向代理与路由白名单创建站点配置文件sudo nano /etc/nginx/sites-available/spacetimedb写入以下内容请将example.com替换为你自己的域名server { listen 80; server_name example.com; ######################################### # By default SpacetimeDB is completely open so that anyone can publish to it. If you want to block # users from creating new databases you should keep this section commented out. Otherwise, if you # want to open it up (probably for dev environments) then you can uncomment this section and then # also comment out the location / section below. ######################################### # location / { # proxy_pass http://localhost:3000; # proxy_http_version 1.1; # proxy_set_header Upgrade $http_upgrade; # proxy_set_header Connection Upgrade; # proxy_set_header Host $host; # } # Anyone can subscribe to any database. # Note: This is the only section *required* for the websocket to function properly. Clients will # be able to create identities, call reducers, and subscribe to tables through this websocket. location ~ ^/v1/database/[^/]/subscribe$ { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection Upgrade; proxy_set_header Host $host; } # Uncomment this section to allow all HTTP reducer calls # location ~ ^/v1/[^/]/call/[^/]$ { # proxy_pass http://localhost:3000; # proxy_http_version 1.1; # proxy_set_header Upgrade $http_upgrade; # proxy_set_header Connection Upgrade; # proxy_set_header Host $host; # } # Uncomment this section to allow all HTTP sql requests # location ~ ^/v1/[^/]/sql$ { # proxy_pass http://localhost:3000; # proxy_http_version 1.1; # proxy_set_header Upgrade $http_upgrade; # proxy_set_header Connection Upgrade; # proxy_set_header Host $host; # } # NOTE: This is required for the typescript sdk to function, it is optional # for the rust and the C# SDKs. location /v1/identity { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection Upgrade; proxy_set_header Host $host; } # Block all other routes explicitly. Only localhost can use these routes. If you want to open your # server up so that anyone can publish to it you should comment this section out. location / { allow 127.0.0.1; deny all; } }这段配置默认只放行两类路由其余一律只允许本机访问location ~ ^/v1/database/[^/]/subscribe$数据库订阅 WebSocket 端点客户端通过它创建身份、调用 reducer 并订阅表变更——这是 WebSocket 正常工作的唯一必需放行项。该端点对应源码路由GET /database/:name_or_identity/subscribe见 crates/client-api/src/routes/database.rslocation /v1/identity身份管理端点POST /identity创建身份等见 crates/client-api/src/routes/identity.rsTypeScript SDK 依赖它Rust 与 C# SDK 则属于可选被注释掉的^/v1/[^/]/call/[^/]$HTTP reducer 调用见 crates/client-api/src/routes/database.rs与^/v1/[^/]/sql$HTTP SQL 请求见 crates/client-api/src/routes/database.rs默认不对外兜底的location /用allow 127.0.0.1; deny all;拒绝一切远端请求从而阻止所有远程用户向你的实例发布数据库。理解这段配置的关键在于路由结构所有客户端路由都挂在/v1前缀之下见 crates/client-api/src/routes/mod.rs而健康检查/探活端点则是/v1/ping见 crates/client-api/src/routes/mod.rs。WebSocket 与 HTTP 调用共用同一套路径因此需要Upgrade/Connection头转发来支持协议升级。启用站点并重启 Nginxsudo ln -s /etc/nginx/sites-available/spacetimedb /etc/nginx/sites-enabled/ sudo systemctl restart nginx配置防火墙确保防火墙放行 HTTPS与 HTTP流量sudo ufw allow Nginx Full sudo ufw reloadNginx Full是 UFW 内置的规则同时放行 80 与 443 端口。若 UFW 未启用可以sudo ufw enable后再执行上述命令。第四步使用 Lets Encrypt 加固 HTTPS安装 Certbotsudo apt install certbot python3-certbot-nginx -ypython3-certbot-nginx是 Nginx 插件允许 Certbot 自动改写 Nginx 配置并完成证书部署。申请 SSL 证书将example.com替换为你自己的域名后执行sudo certbot --nginx -d example.comCertbot 会通过 HTTP-01 挑战验证域名所有权自动为 Nginx 配置 SSL 并重载服务。完成后重启 Nginx 以确认配置生效sudo systemctl restart nginx自动续期Certbot 在安装时会自动注册一个 systemd 定时器certbot.timer。验证其处于活动状态sudo systemctl status certbot.timer证书有效期接近届满时定时器会自动执行续期并重载 Nginx无需人工干预。第五步验证安装并连接 CLI在你的本地开发机上把新服务器加入 CLI 的服务器配置替换example.comspacetime server add self-hosted --url https://example.com从源码看spacetime server add支持多个参数见 crates/cli/src/subcommands/server.rs--url必填服务器 URL支持https://example.com形式也接受host:port写法源码中会自动去除末尾/并解析出 host 与协议https/httpself-hosted为该服务器配置起一个昵称后续所有命令可用昵称引用-d/--default将新服务器设为默认服务器--no-fingerprint跳过服务器指纹校验。spacetime server add默认会向服务器请求并保存指纹fingerprint这是防止中间人攻击的信任锚点如果服务器尚未就绪可以先用--no-fingerprint跳过稍后通过spacetime server fingerprint name补录。CLI 还提供配套的服务器管理子命令同见 crates/cli/src/subcommands/server.rsspacetime server list列出所有已保存的服务器配置及默认标记spacetime server set-default name切换默认服务器spacetime server ping name探测服务器在线状态请求/v1/ping见 crates/cli/src/subcommands/server.rsspacetime server edit --new-name ... --url ...修改昵称或 URLspacetime server remove name删除配置。受限模式下的发布流程由于第三步的 Nginx 配置默认封死了/路由远端用户无法直接通过 HTTP 发布数据库。此时推荐的做法是在本机构建模块把编译产物拷贝到服务器主机上再通过本机通道发布。例如spacetime build scp target/wasm32-unknown-unknown/release/spacetime_module.wasm ubuntuhost:/home/ubuntu/ ssh ubuntuhost spacetime publish -s local --bin-path spacetime_module.wasm database-name命令解析对应 crates/cli/src/subcommands/publish.rsspacetime build在本地把模块编译为 WASMRust 模块产物默认位于target/wasm32-unknown-unknown/release/scp把.wasm产物上传到服务器spacetime publish -s local-s/--server指定服务器此处为默认的本地服务器即服务器本机的 CLI 配置能够直连 127.0.0.1 而不经过被封锁的 Nginx 路由--bin-path spacetime_module.wasm-b/--bin-path指示跳过构建、直接发布指定的预编译二进制与--module-path、--build-options互斥。可以把上述命令封装成 shell 脚本让发布流程更快更稳定也可以将类似脚本接入 CI例如 GitHub Actions在PR 合入 master等事件触发时自动发布到服务器。补充说明发布到非本机地址时CLI 会先打印You are about to publish to a non-local server: host并要求确认见 crates/cli/src/subcommands/publish.rs。在自动化场景下可以用--yes跳过交互确认它支持按类别细分--yesremote跳过远程发布确认、--yesmigrate、--yesbreak-clients、--yesskip-login、--yesdelete-data或直接--yes等价于--yesall。第六步升级 SpacetimeDB 版本升级前先停止服务避免运行中的实例被替换sudo systemctl stop spacetimedb升级到最新版本sudo -u spacetimedb -i -- spacetime --root-dir/stdb version upgradespacetime version子命令是版本管理的入口会把请求转发给自更新工具spacetimedb-update见 crates/cli/src/subcommands/version.rs后者负责从发布源下载并切换版本。upgrade会获取最新版本、安装并把当前版本指针切换到新版本见 crates/update/src/cli/upgrade.rs。要安装指定版本使用sudo -u spacetimedb -i -- spacetime --root-dir/stdb install version-numberinstall version安装指定版本若加--use参数则在安装后立即切换过去见 crates/update/src/cli/install.rs。spacetime version还支持list列出已安装版本、uninstall version等子命令见 crates/update/src/cli.rs。最后重新启动服务sudo systemctl start spacetimedb第七步故障排查SpacetimeDB 服务启动失败查看服务日志定位错误sudo journalctl -u spacetimedb --no-pager | tail -20确认spacetimedb用户对可执行文件与数据目录拥有正确权限sudo ls -lah /stdb/spacetime如果缺少可执行权限手动补上sudo chmod x /stdb/spacetimeLets Encrypt 证书续期异常手动触发一次续期演练检查报错sudo certbot renew --dry-runNginx 启动失败先做配置语法自检sudo nginx -t发现错误后查看 Nginx 日志sudo journalctl -u nginx --no-pager | tail -20生产加固进阶理解并调优 config.toml首次以某个数据目录启动时standalone 会在数据目录下写入一份默认的config.toml见 crates/standalone/src/subcommands/start.rs仓库内模板见 crates/standalone/config.toml。自托管场景下值得关注的关键配置段包括[module-http] enabled是否允许数据库模块发起出站 HTTP 请求覆盖 procedure 与模块 HTTP handler默认允许[logs] level/directives日志级别过滤与 tracing 指令模板默认开启spacetimedb*系列的 debug 日志便于运维观察[wasm] procedure-instance-pool-size每个数据库的 WASM procedure 实例池上限缺省按 OS 报告的 CPU 核数决定[v8]段对应 JS 实例池[websocket] ping-interval与idle-timeoutWebSocket 心跳 Ping 帧间隔默认15s与空闲超时默认30s必须大于 ping-interval慢客户端也会被正确纳入空闲判定[commitlog]提交日志段大小、写缓冲、offset 索引与预分配策略等持久化相关参数直接影响写吞吐与崩溃恢复。修改config.toml后重启spacetimedb服务即可生效。结合 crates/standalone/config.toml 中的完整注释你可以根据服务器规格与业务规模连接数、模块调用频率、数据量逐步调优。至此一台由 systemd 托管、Nginx 反向代理、Lets Encrypt 提供 HTTPS、默认拒绝远端发布的高安全性 SpacetimeDB 自托管实例即告完成并且具备版本升级与完整排障手段可作为生产或长期运行环境直接投入使用。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考