Ubuntu 24.04 自托管 SpacetimeDB 完整指南systemd 服务、Nginx 反向代理与 HTTPS 实战【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本指南以 SpacetimeDB 1.12.0 官方自托管文档为主体完整讲解如何在 Ubuntu 24.04 服务器上从零搭建一个生产可用的 SpacetimeDB 实例创建专属系统用户、以 systemd 守护进程常驻运行、用 Nginx 反向代理按路由粒度控制访问范围、通过 Lets Encrypt 免费证书启用 HTTPS并覆盖版本升级与常见故障排查。读完本文你将具备独立部署并安全暴露一个可被官方 CLI 与各语言 SDK 正常访问的自托管 SpacetimeDB 服务端能力。前置条件开始前请确保满足以下条件一台全新的 Ubuntu 24.04 服务器VM 或任意云实例均可一个已解析到该服务器公网 IP 的域名例如example.comHTTPS 证书签发依赖域名服务器上的sudo权限。整篇部署的核心思路是SpacetimeDB 服务进程只监听本机回环地址127.0.0.1:3000对外流量统一由 Nginx 承担并在 Nginx 层按 URL 路由决定哪些 API 暴露给公网、哪些仅限本机使用。Step 1创建专属用户并安装 SpacetimeDB出于安全考虑SpacetimeDB 不应以 root 身份运行而是使用一个独立的系统用户并将数据目录固定在一个专用路径下sudo mkdir /stdb sudo useradd --system spacetimedb sudo chown -R spacetimedb:spacetimedb /stdb随后以spacetimedb用户身份运行官方安装脚本。安装脚本接受--root-dir与--yes参数前者指定所有 SpacetimeDB 文件的存放根目录本例为/stdb后者跳过交互确认sudo -u spacetimedb bash -c curl -sSf https://install.spacetimedb.com | sh -s -- --root-dir /stdb --yes从源码看--root-dir是 CLI 的全局选项定义于 crates/cli/src/main.rs其作用是「存储所有 spacetime 文件的根目录」。CLI 在启动时会根据该目录构造完整路径集数据目录、配置目录、二进制目录等见 crates/cli/src/main.rs。安装完成后可执行文件即位于/stdb/spacetime。Step 2创建 Systemd 服务并开机自启编写服务单元文件为了让 SpacetimeDB 在服务器重启后自动运行、崩溃后自动拉起使用 systemd 托管是标准做法。先创建服务文件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配置要点说明Userspacetimedb以非 root 的专属用户运行与 Step 1 的目录归属保持一致WorkingDirectory/stdb服务的工作目录Afternetwork.target保证网络就绪后再启动服务Restartalways进程异常退出后自动重启。这里的spacetime start命令值得深入理解。从 crates/cli/src/subcommands/start.rs 的源码可以看到CLI 的start子命令实际上会解析出目标版本二进制spacetimedb-standalone并为其拼装start --data-dir 数据目录 --jwt-key-dir 配置目录参数后执行替换式启动Unix 下通过execvp直接接管当前进程。而真正监听端口的参数最终由 standalone 服务解析--listen-addr别名-l的默认值为0.0.0.0:3000含义是监听所有网卡的 3000 端口见 crates/standalone/src/subcommands/start.rs。本教程刻意将其设为127.0.0.1:3000即只监听回环地址——这是后续 Nginx 反向代理安全模型的前提公网流量无法直连 3000 端口所有入口请求都必须经过 Nginx 的路由过滤。start子命令还支持在cli.toml中持久化默认监听地址listen_addr 0.0.0.0:4000显式传入的--listen-addr优先级更高可覆盖配置文件默认值。启用并启动服务sudo systemctl enable spacetimedb sudo systemctl start spacetimedb检查运行状态sudo systemctl status spacetimedbStep 3安装并配置 Nginx 反向代理安装 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; } # Log streaming benefits from longer read timeout and disabled buffering location ~ ^/v1/database/[^/]/logs$ { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_buffering off; proxy_read_timeout 3600s; } # 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; } }这份配置是自托管部署中最重要的安全边界逐段拆解其含义1. 全量放行的注释块location /默认关闭注释中明确指出SpacetimeDB 默认是完全开放的任何人只要知道地址就能向实例发布publish数据库。若你希望保留「人人可发布」的能力例如纯开发环境可以取消这段注释同时注释掉底部的拦截段。但对生产环境务必保持关闭。2. WebSocket 订阅路由/v1/database/db/subscribe必需这段是 WebSocket 功能正常运转的唯一必需配置。官方注释强调客户端正是通过这个 WebSocket 通道创建身份identity、调用 reducer、订阅表数据的。因此无论采取何种安全策略这段都必须保留。它使用 Nginx 的Upgrade/Connection头完成 WebSocket 协议升级的透传对应 SpacetimeDB 客户端 API 中的订阅路由。3. 日志流路由/v1/database/db/logsspacetime logs命令通过该路由流式拉取数据库日志。日志流是长时间连接的 SSE 场景因此需要禁用缓冲proxy_buffering off并拉长读取超时proxy_read_timeout 3600s防止 Nginx 缓冲或超时切断日志推送。4. HTTP reducer 调用路由/v1/db/call/reducer默认关闭Rust/C# 客户端通常通过 WebSocket 调用 reducer但 HTTP 形式同样存在。若你希望允许通过纯 HTTP 调用 reducer取消这段注释即可。5. HTTP SQL 查询路由/v1/db/sql默认关闭对应spacetime sql命令与 HTTP SQL 接口。默认关闭以缩小攻击面。6. 身份路由/v1/identity必需官方注释特别指出TypeScript SDK 的正常运行依赖该路由Rust 与 C# SDK 则为可选。TypeScript 客户端创建/登录身份走 HTTP 接口因此生产环境若需支持 TS 客户端这段必须保留。7. 兜底拦截location /其余所有路由仅允许本机127.0.0.1访问、其余来源一律拒绝。这样从公网角度看实例只暴露了订阅、日志、身份三条最小必要路由而publish、sql、call等管理/写路径全部被挡在 Nginx 层之外——从源码结构看这与 CLI 各子命令的调用路径发布、SQL 等均需访问管理类 API是一致的从而有效阻止远程用户向你的实例发布数据库。启用站点并重启 Nginxsudo ln -s /etc/nginx/sites-available/spacetimedb /etc/nginx/sites-enabled/ sudo systemctl restart nginx配置防火墙确保防火墙放行 Nginx 的完整流量80/443sudo ufw allow Nginx Full sudo ufw reloadStep 4使用 Lets Encrypt 加密 HTTPS安装 Certbotsudo apt install certbot python3-certbot-nginx -y申请 SSL 证书运行以下命令将example.com替换为你自己的域名sudo certbot --nginx -d example.comCertbot 会自动完成以下工作校验域名所有权、向 Lets Encrypt 申请证书、修改 Nginx 配置以启用 TLS 并配置 HTTP→HTTPS 跳转。完成后重启 Nginx 应用变更sudo systemctl restart nginx证书自动续期Certbot 安装时会自动注册一个续期定时器。验证其处于激活状态sudo systemctl status certbot.timerLets Encrypt 证书有效期约为 90 天该定时器会在到期前自动续期并重载 Nginx。Step 5验证安装并接入 CLI在本地开发机上执行以下命令把新服务器注册到 CLI 的服务器配置中example.com替换为你的域名spacetime server add self-hosted --url https://example.com关于server add背后的行为从 crates/cli/src/subcommands/server.rs 的源码可以确认它会向服务器请求并打印指纹fingerprint并保存用于后续连接时的身份校验若服务器未运行或网络不通会给出明确提示并支持--no-fingerprint跳过指纹获取支持-d/--default将该服务器设为默认以及spacetime server list、spacetime server set-default、spacetime server ping内部请求/v1/ping见 crates/cli/src/subcommands/server.rs等配套管理命令。如何向受保护实例发布模块正如 Nginx 配置注释所强调的由于生产配置默认拦截了公网publish路径远程直接spacetime publish会失败。官方推荐的发布流程是本地构建出 WASM 模块 →scp拷贝到服务器 → 在服务器本机绕过 Nginx 的127.0.0.1白名单以本地服务器身份发布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上述命令中的spacetime build会调用本仓库模板中常见的 Rust 模块构建流程产物为wasm32-unknown-unknown目标下的spacetime_module.wasm。可以将这三条命令封装成 shell 脚本以简化流程也可以将其集成进 GitHub Actions 等 CI在特定事件如 PR 合入主分支触发自动发布。若在 Step 3 中取消了/v1/publish限制即开放远程发布则无需此流程可直接远程spacetime publish。Step 6升级 SpacetimeDB 版本升级到最新版本先停止服务再执行升级sudo systemctl stop spacetimedbsudo -u spacetimedb -i -- spacetime --root-dir/stdb version upgrade从源码实现看spacetime version子命令会调用独立的多调用二进制spacetimedb-update并将--root-dir原样透传见 crates/cli/src/subcommands/version.rs。升级过程会先向发布源解析最新版本下载对应架构的预编译归档优先 GitHub Release失败时自动回退到镜像源解压到版本目录后切换当前版本见 crates/update/src/cli/upgrade.rs。安装指定版本如需固定到某个特定版本号sudo -u spacetimedb -i -- spacetime --root-dir/stdb install version-numberinstall子命令支持--edition默认standalone、--use安装后立即切换等参数并将二进制安装到以版本号命名的目录下见 crates/update/src/cli/install.rs。最后重启服务使新版本生效sudo systemctl start spacetimedb建议升级后回到 Step 5 的验证流程确认实例与各 SDK 客户端兼容。Step 7常见故障排查SpacetimeDB 服务启动失败先查看服务日志定位错误sudo journalctl -u spacetimedb --no-pager | tail -20确认二进制文件权限正确sudo ls -lah /stdb/spacetime若缺少可执行权限例如安装后权限被意外修改补充执行位sudo chmod x /stdb/spacetime另外结合 crates/standalone/src/subcommands/start.rs 的实现服务启动时还会检查端口占用若 3000 端口已被其他进程占用会明确报错并提示「请释放端口或通过--listen-addr指定其他端口」。这与 systemd 服务文件中--listen-addr的配置直接相关排查时可留意是否有进程抢占端口。Lets Encrypt 证书续期异常手动执行一次续期演练dry-run观察错误输出sudo certbot renew --dry-run常见原因包括域名 DNS 解析失效、防火墙未放行 80/443 端口回看 Step 3 的 ufw 配置等。Nginx 启动失败先用测试命令校验配置语法sudo nginx -t再查看 Nginx 日志sudo journalctl -u nginx --no-pager | tail -20附基于 config.toml 的生产调优方向SpacetimeDB 1.12.0 的 standalone 实例支持通过配置文件进一步调优。仓库中的示例配置 crates/standalone/config.toml 完整展示了可用配置段生产部署时可参考其中的核心项[logs]默认日志级别与 directives 过滤规则示例中spacetimedbdebug、spacetimedb_commitloginfo等可按需收紧为ERROR以减少日志量[wasm]/[v8]每个数据库的 WASM 过程实例池 / JS isolate 池大小省略时按系统核心数自动决定适用于模块并发量较高的场景[v8-heap-policy]V8 堆检查频率与 GC 触发阈值heap-gc-trigger-fraction、heap-limit-mb等主要影响 TypeScript 模块的堆管理[websocket]ping-interval心跳间隔与idle-timeout空闲超时可配合 Nginx 的proxy_read_timeout一并调整避免长连接被中间层切断[commitlog]预写日志段的max-segment-size、write-buffer-size等持久化参数影响写放大与刷盘频率。该配置文件的解析与加载路径位于 standalone 服务启动逻辑中见 crates/standalone/src/subcommands/start.rs 的ConfigFile结构。小结至此一套生产可用的自托管 SpacetimeDB 部署已完成spacetimedb系统用户 systemd 守护 仅监听回环地址的服务进程 Nginx 按路由白名单反向代理 Lets Encrypt HTTPS 全覆盖。这套模型的核心安全思想是「最小暴露」通过 Nginx 兜底拦截公网只能访问订阅、日志与身份这三条必要路由而发布、SQL 等管理操作保留在本机或受控流程内兼顾了安全性与各语言 SDK 的正常工作尤其 TypeScript 客户端依赖的/v1/identity路由。如需进一步了解 CLI 服务器管理的更多细节可阅读 crates/cli/src/subcommands/server.rs 的源码部署相关文档的现行版本可参考 docs/docs/00300-resources 目录。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ubuntu 24.04 自托管 SpacetimeDB 完整指南：systemd 服务、Nginx 反向代理与 HTTPS 实战
Ubuntu 24.04 自托管 SpacetimeDB 完整指南systemd 服务、Nginx 反向代理与 HTTPS 实战【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本指南以 SpacetimeDB 1.12.0 官方自托管文档为主体完整讲解如何在 Ubuntu 24.04 服务器上从零搭建一个生产可用的 SpacetimeDB 实例创建专属系统用户、以 systemd 守护进程常驻运行、用 Nginx 反向代理按路由粒度控制访问范围、通过 Lets Encrypt 免费证书启用 HTTPS并覆盖版本升级与常见故障排查。读完本文你将具备独立部署并安全暴露一个可被官方 CLI 与各语言 SDK 正常访问的自托管 SpacetimeDB 服务端能力。前置条件开始前请确保满足以下条件一台全新的 Ubuntu 24.04 服务器VM 或任意云实例均可一个已解析到该服务器公网 IP 的域名例如example.comHTTPS 证书签发依赖域名服务器上的sudo权限。整篇部署的核心思路是SpacetimeDB 服务进程只监听本机回环地址127.0.0.1:3000对外流量统一由 Nginx 承担并在 Nginx 层按 URL 路由决定哪些 API 暴露给公网、哪些仅限本机使用。Step 1创建专属用户并安装 SpacetimeDB出于安全考虑SpacetimeDB 不应以 root 身份运行而是使用一个独立的系统用户并将数据目录固定在一个专用路径下sudo mkdir /stdb sudo useradd --system spacetimedb sudo chown -R spacetimedb:spacetimedb /stdb随后以spacetimedb用户身份运行官方安装脚本。安装脚本接受--root-dir与--yes参数前者指定所有 SpacetimeDB 文件的存放根目录本例为/stdb后者跳过交互确认sudo -u spacetimedb bash -c curl -sSf https://install.spacetimedb.com | sh -s -- --root-dir /stdb --yes从源码看--root-dir是 CLI 的全局选项定义于 crates/cli/src/main.rs其作用是「存储所有 spacetime 文件的根目录」。CLI 在启动时会根据该目录构造完整路径集数据目录、配置目录、二进制目录等见 crates/cli/src/main.rs。安装完成后可执行文件即位于/stdb/spacetime。Step 2创建 Systemd 服务并开机自启编写服务单元文件为了让 SpacetimeDB 在服务器重启后自动运行、崩溃后自动拉起使用 systemd 托管是标准做法。先创建服务文件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配置要点说明Userspacetimedb以非 root 的专属用户运行与 Step 1 的目录归属保持一致WorkingDirectory/stdb服务的工作目录Afternetwork.target保证网络就绪后再启动服务Restartalways进程异常退出后自动重启。这里的spacetime start命令值得深入理解。从 crates/cli/src/subcommands/start.rs 的源码可以看到CLI 的start子命令实际上会解析出目标版本二进制spacetimedb-standalone并为其拼装start --data-dir 数据目录 --jwt-key-dir 配置目录参数后执行替换式启动Unix 下通过execvp直接接管当前进程。而真正监听端口的参数最终由 standalone 服务解析--listen-addr别名-l的默认值为0.0.0.0:3000含义是监听所有网卡的 3000 端口见 crates/standalone/src/subcommands/start.rs。本教程刻意将其设为127.0.0.1:3000即只监听回环地址——这是后续 Nginx 反向代理安全模型的前提公网流量无法直连 3000 端口所有入口请求都必须经过 Nginx 的路由过滤。start子命令还支持在cli.toml中持久化默认监听地址listen_addr 0.0.0.0:4000显式传入的--listen-addr优先级更高可覆盖配置文件默认值。启用并启动服务sudo systemctl enable spacetimedb sudo systemctl start spacetimedb检查运行状态sudo systemctl status spacetimedbStep 3安装并配置 Nginx 反向代理安装 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; } # Log streaming benefits from longer read timeout and disabled buffering location ~ ^/v1/database/[^/]/logs$ { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_buffering off; proxy_read_timeout 3600s; } # 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; } }这份配置是自托管部署中最重要的安全边界逐段拆解其含义1. 全量放行的注释块location /默认关闭注释中明确指出SpacetimeDB 默认是完全开放的任何人只要知道地址就能向实例发布publish数据库。若你希望保留「人人可发布」的能力例如纯开发环境可以取消这段注释同时注释掉底部的拦截段。但对生产环境务必保持关闭。2. WebSocket 订阅路由/v1/database/db/subscribe必需这段是 WebSocket 功能正常运转的唯一必需配置。官方注释强调客户端正是通过这个 WebSocket 通道创建身份identity、调用 reducer、订阅表数据的。因此无论采取何种安全策略这段都必须保留。它使用 Nginx 的Upgrade/Connection头完成 WebSocket 协议升级的透传对应 SpacetimeDB 客户端 API 中的订阅路由。3. 日志流路由/v1/database/db/logsspacetime logs命令通过该路由流式拉取数据库日志。日志流是长时间连接的 SSE 场景因此需要禁用缓冲proxy_buffering off并拉长读取超时proxy_read_timeout 3600s防止 Nginx 缓冲或超时切断日志推送。4. HTTP reducer 调用路由/v1/db/call/reducer默认关闭Rust/C# 客户端通常通过 WebSocket 调用 reducer但 HTTP 形式同样存在。若你希望允许通过纯 HTTP 调用 reducer取消这段注释即可。5. HTTP SQL 查询路由/v1/db/sql默认关闭对应spacetime sql命令与 HTTP SQL 接口。默认关闭以缩小攻击面。6. 身份路由/v1/identity必需官方注释特别指出TypeScript SDK 的正常运行依赖该路由Rust 与 C# SDK 则为可选。TypeScript 客户端创建/登录身份走 HTTP 接口因此生产环境若需支持 TS 客户端这段必须保留。7. 兜底拦截location /其余所有路由仅允许本机127.0.0.1访问、其余来源一律拒绝。这样从公网角度看实例只暴露了订阅、日志、身份三条最小必要路由而publish、sql、call等管理/写路径全部被挡在 Nginx 层之外——从源码结构看这与 CLI 各子命令的调用路径发布、SQL 等均需访问管理类 API是一致的从而有效阻止远程用户向你的实例发布数据库。启用站点并重启 Nginxsudo ln -s /etc/nginx/sites-available/spacetimedb /etc/nginx/sites-enabled/ sudo systemctl restart nginx配置防火墙确保防火墙放行 Nginx 的完整流量80/443sudo ufw allow Nginx Full sudo ufw reloadStep 4使用 Lets Encrypt 加密 HTTPS安装 Certbotsudo apt install certbot python3-certbot-nginx -y申请 SSL 证书运行以下命令将example.com替换为你自己的域名sudo certbot --nginx -d example.comCertbot 会自动完成以下工作校验域名所有权、向 Lets Encrypt 申请证书、修改 Nginx 配置以启用 TLS 并配置 HTTP→HTTPS 跳转。完成后重启 Nginx 应用变更sudo systemctl restart nginx证书自动续期Certbot 安装时会自动注册一个续期定时器。验证其处于激活状态sudo systemctl status certbot.timerLets Encrypt 证书有效期约为 90 天该定时器会在到期前自动续期并重载 Nginx。Step 5验证安装并接入 CLI在本地开发机上执行以下命令把新服务器注册到 CLI 的服务器配置中example.com替换为你的域名spacetime server add self-hosted --url https://example.com关于server add背后的行为从 crates/cli/src/subcommands/server.rs 的源码可以确认它会向服务器请求并打印指纹fingerprint并保存用于后续连接时的身份校验若服务器未运行或网络不通会给出明确提示并支持--no-fingerprint跳过指纹获取支持-d/--default将该服务器设为默认以及spacetime server list、spacetime server set-default、spacetime server ping内部请求/v1/ping见 crates/cli/src/subcommands/server.rs等配套管理命令。如何向受保护实例发布模块正如 Nginx 配置注释所强调的由于生产配置默认拦截了公网publish路径远程直接spacetime publish会失败。官方推荐的发布流程是本地构建出 WASM 模块 →scp拷贝到服务器 → 在服务器本机绕过 Nginx 的127.0.0.1白名单以本地服务器身份发布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上述命令中的spacetime build会调用本仓库模板中常见的 Rust 模块构建流程产物为wasm32-unknown-unknown目标下的spacetime_module.wasm。可以将这三条命令封装成 shell 脚本以简化流程也可以将其集成进 GitHub Actions 等 CI在特定事件如 PR 合入主分支触发自动发布。若在 Step 3 中取消了/v1/publish限制即开放远程发布则无需此流程可直接远程spacetime publish。Step 6升级 SpacetimeDB 版本升级到最新版本先停止服务再执行升级sudo systemctl stop spacetimedbsudo -u spacetimedb -i -- spacetime --root-dir/stdb version upgrade从源码实现看spacetime version子命令会调用独立的多调用二进制spacetimedb-update并将--root-dir原样透传见 crates/cli/src/subcommands/version.rs。升级过程会先向发布源解析最新版本下载对应架构的预编译归档优先 GitHub Release失败时自动回退到镜像源解压到版本目录后切换当前版本见 crates/update/src/cli/upgrade.rs。安装指定版本如需固定到某个特定版本号sudo -u spacetimedb -i -- spacetime --root-dir/stdb install version-numberinstall子命令支持--edition默认standalone、--use安装后立即切换等参数并将二进制安装到以版本号命名的目录下见 crates/update/src/cli/install.rs。最后重启服务使新版本生效sudo systemctl start spacetimedb建议升级后回到 Step 5 的验证流程确认实例与各 SDK 客户端兼容。Step 7常见故障排查SpacetimeDB 服务启动失败先查看服务日志定位错误sudo journalctl -u spacetimedb --no-pager | tail -20确认二进制文件权限正确sudo ls -lah /stdb/spacetime若缺少可执行权限例如安装后权限被意外修改补充执行位sudo chmod x /stdb/spacetime另外结合 crates/standalone/src/subcommands/start.rs 的实现服务启动时还会检查端口占用若 3000 端口已被其他进程占用会明确报错并提示「请释放端口或通过--listen-addr指定其他端口」。这与 systemd 服务文件中--listen-addr的配置直接相关排查时可留意是否有进程抢占端口。Lets Encrypt 证书续期异常手动执行一次续期演练dry-run观察错误输出sudo certbot renew --dry-run常见原因包括域名 DNS 解析失效、防火墙未放行 80/443 端口回看 Step 3 的 ufw 配置等。Nginx 启动失败先用测试命令校验配置语法sudo nginx -t再查看 Nginx 日志sudo journalctl -u nginx --no-pager | tail -20附基于 config.toml 的生产调优方向SpacetimeDB 1.12.0 的 standalone 实例支持通过配置文件进一步调优。仓库中的示例配置 crates/standalone/config.toml 完整展示了可用配置段生产部署时可参考其中的核心项[logs]默认日志级别与 directives 过滤规则示例中spacetimedbdebug、spacetimedb_commitloginfo等可按需收紧为ERROR以减少日志量[wasm]/[v8]每个数据库的 WASM 过程实例池 / JS isolate 池大小省略时按系统核心数自动决定适用于模块并发量较高的场景[v8-heap-policy]V8 堆检查频率与 GC 触发阈值heap-gc-trigger-fraction、heap-limit-mb等主要影响 TypeScript 模块的堆管理[websocket]ping-interval心跳间隔与idle-timeout空闲超时可配合 Nginx 的proxy_read_timeout一并调整避免长连接被中间层切断[commitlog]预写日志段的max-segment-size、write-buffer-size等持久化参数影响写放大与刷盘频率。该配置文件的解析与加载路径位于 standalone 服务启动逻辑中见 crates/standalone/src/subcommands/start.rs 的ConfigFile结构。小结至此一套生产可用的自托管 SpacetimeDB 部署已完成spacetimedb系统用户 systemd 守护 仅监听回环地址的服务进程 Nginx 按路由白名单反向代理 Lets Encrypt HTTPS 全覆盖。这套模型的核心安全思想是「最小暴露」通过 Nginx 兜底拦截公网只能访问订阅、日志与身份这三条必要路由而发布、SQL 等管理操作保留在本机或受控流程内兼顾了安全性与各语言 SDK 的正常工作尤其 TypeScript 客户端依赖的/v1/identity路由。如需进一步了解 CLI 服务器管理的更多细节可阅读 crates/cli/src/subcommands/server.rs 的源码部署相关文档的现行版本可参考 docs/docs/00300-resources 目录。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考