SpacetimeDB 2.13.0 安装指南

SpacetimeDB 2.13.0 Linux 安装指南：官方脚本一键安装 CLI 与 standalone 服务端、-y 非交互与 PATH 配置、systemd 生产托管 unit 全文、多版本管理与升级降级，附 GitHub 直连失败自动切镜像、noexec /tmp 等真实排障实录。

SpacetimeDBSpacetimeDB2026/10/24

SpacetimeDB 2.13.0 安装指南

目标：在 Linux 服务器上完成 SpacetimeDB CLI（含 standalone 服务端）的真实安装、启动验证与生产级 systemd 托管，沉淀安装过程中的真实报错与解法。本文所有命令输出均为 2026-10-23 在测试服务器上的实测回显。组件定位与选型背景见《SpacetimeDB 2.13.0 介绍与选型指南》。

一、环境信息

项目内容
组件名称SpacetimeDB（CLI 工具名 spacetime，服务端二进制 spacetimedb-standalone）
版本2.13.0（当前最新稳定版，2026-10-21 发布）
操作系统Ubuntu 22.04 LTS（x86_64）
Shellbash（root 用户，家目录 /root）
安装日期2026-10-23
网络服务器可直连安装脚本站点 install.spacetimedb.com；到 GitHub 的直连受网络策略限制，二进制下载走代理（见 6.1 排障）

⚠️ 环境说明：本篇实测在一台由虚拟化平台拉起的 Ubuntu 22.04 独立服务器上进行（主机名 spacetimedb-lab），安装路径、服务编排均为单机真机视角，无 Kubernetes/编排层依赖。

二、安装对象与形态

SpacetimeDB 的 Linux 发行物是一个统一 CLI（spacetime），安装脚本会同时放置：

  • spacetime：CLI 主入口（版本管理、发布、查询、运维全走它）；
  • spacetimedb-standalone：单机服务端二进制（由 spacetime start 调起，一般不手动执行）；
  • 各版本的二进制存放在版本目录中，~/.local/bin/spacetime 是一个可切换版本的入口包装。

与先装数据库、再装应用运行时的传统组件化部署不同（例如 PostgreSQL 之外还要配套分库分表代理《Gaea 2.4.2 介绍与选型指南》或独立消息队列《BlazingMQ 介绍与选型指南》），SpacetimeDB 一个 CLI 即装齐「数据库 + 模块运行时」，不需要单独的应用服务器进程。

支持的 Linux 前提：官方安装脚本支持 Linux（另有 macOS/Windows），无发行版限制，仅依赖 curl（或 wget）与 sh。支持 x86_64 与 aarch64 架构（脚本自动探测平台选择二进制）。

三、安装前检查

root@spacetimedb-lab:~# uname -m
x86_64
root@spacetimedb-lab:~# cat /etc/os-release | head -2
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
root@spacetimedb-lab:~# curl --version | head -1
curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.1.1 brotli/1.0.9 zstd/1.4.8 libidn2/2.3.2 libpsl/0.21.0 (+libidn2/2.3.2) libssh/0.9.6 OpenSSH/8.9p1

四、方案一：官方一键脚本安装（推荐）

4.1 标准安装命令

官方安装命令（来源：spacetimedb.com/install，查询日期 2026-10-23）：

curl -sSf https://install.spacetimedb.com | sh

4.2 非交互安装（CI/自动化必加 -y）

在无终端交互能力的环境（CI 流水线、脚本化运维、curl | sh 管道场景）直接执行会得到报错。实测回显（不加 -y，安装器无法弹出确认提示）：

$ curl -sSf https://install.spacetimedb.com | sh
CLI configuration directory: /root/.config/spacetime/
`spacetime` binary directory: /root/.local/bin
Version install directory: /root/.local/share/spacetime/bin
Database directory: /root/.local/share/spacetime/data
Error: IO error: not a terminal

解法：给安装脚本传 -y（跳过确认对话框，脚本帮助原文：-y, --yes Skip the confirmation dialog）。管道传参的写法是把参数挂在 sh -s -- 之后：

curl -sSf https://install.spacetimedb.com | sh -s -- -y

实测成功回显（版本 2.13.0）：

$ curl -sSf https://install.spacetimedb.com | sh -s -- -y
Downloading installer...
CLI configuration directory: /root/.config/spacetime/
`spacetime` binary directory: /root/.local/bin
Version install directory: /root/.local/share/spacetime/bin
Database directory: /root/.local/share/spacetime/data
Downloading version 2.13.0
Installing version 2.13.0
warning: /root/.local/bin is not on your PATH. To use spacetime, run:
    export PATH="/root/.local/bin:$PATH"
Installation completed.
EXIT=0

安装器落地内容：

路径用途
/root/.local/bin/spacetimeCLI 入口（版本包装器）
/root/.local/share/spacetime/bin/<版本>/各版本二进制（含 spacetime、spacetimedb-standalone）
/root/.local/share/spacetime/bin/current指向当前使用版本的符号链接
/root/.local/share/spacetime/data/服务端数据目录（commit log、control-db 等，服务端首次启动时生成）
/root/.config/spacetime/CLI 配置（cli.toml、服务器身份密钥 id_ecdsa(.pub)）

4.3 PATH 持久化

安装器提示 /root/.local/bin 不在 PATH。当前会话立即生效并写入 profile 持久化：

export PATH="/root/.local/bin:$PATH"
echo 'export PATH="/root/.local/bin:$PATH"' >> ~/.bashrc

五、验证安装

$ spacetime --version
spacetimedb tool version 2.13.0; spacetimedb-lib version 2.13.0; rev: 08e1aba133671f9c631c6e70133a82faa0e7b283
$ spacetime version list
2.13.0 (current)

六、安装排障实录（真实报错与解法）

6.1 GitHub 直连失败：自动镜像回退与代理加速

安装器默认从 GitHub Releases 下载（SPACETIMEDB_DOWNLOAD_ROOT 缺省为 https://github.com/clockworklabs/SpacetimeDB/releases/latest/download），下载失败会自动切换到官方 S3 镜像（https://spacetimedb-client-binaries.s3.amazonaws.com，经 latest-version 接口解析最新 tag）。实测网络受限服务器上的完整过程回显：

$ curl -sSf https://install.spacetimedb.com | sh
Downloading installer...
curl: (56) OpenSSL SSL_read: Connection reset by peer, errno 104
Download failed, trying mirror...

两个排障结论：

  1. 镜像自动回退是真实行为：GitHub 拉取失败后安装器自己打印 Download failed, trying mirror... 并切到 S3。但镜像线路在国内网络下实测偏慢甚至长时间无进展，不可作为可靠的兜底预期。
  2. 可靠做法是给安装过程显式配代理（环境变量对脚本内的 curl 生效）：
export http_proxy=http://192.168.1.62:7897
export https_proxy=http://192.168.1.62:7897
curl -sSf https://install.spacetimedb.com | sh -s -- -y

实测走代理后 GitHub 下载立即成功（https://github.com 探测 200，0.27s），完整安装数秒完成。

6.2 挂载 /tmp 为 noexec 的机器：安装器无法执行

在 /tmp 以 noexec 挂载的服务器（部分安全加固基线如此）上，安装器把下载的中间二进制解到临时目录执行会失败，报错原文：

Cannot execute /tmp/tmp.7OBK2NQRWg/spacetime-install (likely because of mounting /tmp as
noexec).
Please copy the file to a location where you can execute binaries and run
./spacetime-install

解法（按官方提示绕开管道临时目录，手动下载安装器到可执行路径）：

curl -sSfL https://github.com/clockworklabs/SpacetimeDB/releases/latest/download/spacetimedb-update-x86_64-unknown-linux-gnu \
  -o /usr/local/bin/spacetime-install
chmod +x /usr/local/bin/spacetime-install
spacetime-install -y

实测该路径安装成功（版本探测与装目录逻辑与脚本一致）。aarch64 服务器把文件名中的 x86_64-unknown-linux-gnu 换成 aarch64-unknown-linux-gnu。

七、启动 standalone 服务端（前台）

$ spacetime start
 _____                    _     _         _   ____  _____
|_   _|__ _ __ _ ____   _(_)___| |_ _   _| | / ___|_   _|
  | |/ _ \ '__| '_ \ \ / / / __| __| | | | | \___ \ | |
  | |  __/ |  | |_) \ V /| \__ \ |_| |_| | |  ___) || |
  |_|\___|_|  | .__/ \_/ |_|___/\__|\__,_| |_|____/ |_|
              |_|
Development at the speed of light.

spacetimedb-standalone version: 2.13.0
spacetimedb-standalone path: /root/.local/share/spacetime/bin/2.13.0/spacetimedb-standalone
database running in data directory /root/.local/share/spacetime/data
2026-10-23T17:01:24.055555Z  INFO crates/standalone/src/subcommands/start.rs:266: Starting SpacetimeDB listening on 0.0.0.0:3000
2026-10-23T17:01:24.055574Z  INFO crates/standalone/src/subcommands/start.rs:287: PostgreSQL wire protocol server disabled

要点（均为实测确认）：

  • 默认监听 0.0.0.0:3000，改地址端口用 --listen-addr；
  • 前台运行，Ctrl+C 停止；数据目录缺省 /root/.local/share/spacetime/data，可用 --data-dir 指定；
  • standalone 不支持 SSL（官方 getting-started 明确说明），对外 HTTPS 需前置反向代理终结 TLS；
  • 同一数据目录同时只允许一个实例，重复启动报 Error: cannot take lock on database; spacetime.pid already exists (owned by pid Some(3228))（实测回显）；
  • 服务端日志同时落在 <数据目录>/logs/spacetime-standalone.log。

八、systemd 托管（生产推荐）

生产服务器用 systemd 托管为常驻服务。创建 /etc/systemd/system/spacetimedb.service：

[Unit]
Description=SpacetimeDB Standalone Server
After=network.target

[Service]
Type=simple
User=root
Environment=PATH=/root/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=/root/.local/bin/spacetime start
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并验证（实测回显）：

# systemctl daemon-reload
# systemctl enable spacetimedb
Created symlink /etc/systemd/system/multi-user.target.wants/spacetimedb.service → /etc/systemd/system/spacetimedb.service.
# systemctl start spacetimedb
# systemctl is-active spacetimedb
active
# systemctl status spacetimedb --no-pager -l
● spacetimedb.service - SpacetimeDB Standalone Server
     Loaded: loaded (/etc/systemd/system/spacetimedb.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-10-23 17:17:12 UTC; 12s ago
   Main PID: 12345 (spacetime)
     Tasks: 5 (limit: 4672)
     Memory: 34.1M (peak: 34.9M)
        CPU: 128ms
     CGroup: /system.slice/spacetimedb.service
             └─12345 /root/.local/share/spacetime/bin/2.13.0/spacetimedb-standalone start --data-dir /root/.local/share/spacetime/data --jwt-key-dir /root/.config/spacetime/
# spacetime server ping local
WARNING: This command is UNSTABLE and subject to breaking changes.

Server is online: http://127.0.0.1:3000

说明：systemd 下看到的真实进程是 spacetimedb-standalone start --data-dir ... --jwt-key-dir /root/.config/spacetime/，即 CLI 包装器已转发到版本目录中的服务端二进制；--jwt-key-dir 指向 CLI 配置目录，服务端复用其中的 id_ecdsa(.pub) 作为签发 Identity 的密钥对。

九、多版本管理（升级 / 降级 / 切换）

spacetime 内建版本管理，无需手动替换二进制：

$ spacetime version list --all
GitHub unavailable, fetching latest version from mirror...
2.13.0 (current)

$ spacetime version install 2.12.0 -y
$ spacetime version list
2.13.0 (current)
2.12.0

$ spacetime version use 2.12.0
Using spacetimedb version 2.12.0
$ spacetime --version
spacetimedb tool version 2.12.0; spacetimedb-lib version 2.12.0; rev: 2f8905d6aaf3e9ffcbce3a8a1a1e30e715ad5db7

$ spacetime version use 2.13.0
Using spacetimedb version 2.13.0
$ spacetime --version
spacetimedb tool version 2.13.0; spacetimedb-lib version 2.13.0; rev: 08e1aba133671f9c631c6e70133a82faa0e7b283

$ ls -la /root/.local/share/spacetime/bin/
total 16
drwxr-xr-x 4 root root 4096 Oct 23 17:09 .
drwxr-xr-x 4 root root 4096 Oct 23 17:00 ..
drwxr-xr-x 2 root root 4096 Oct 23 17:09 2.12.0
drwxr-xr-x 2 root root 4096 Oct 23 17:00 2.13.0
lrwxrwxrwx 1 root root    6 Oct 23 17:09 current -> 2.13.0

注意：version list --all 依赖 GitHub API 列出全部版本，GitHub 不可用时自动降级为从镜像取最新版本号（实测如此，此时列表只含已装版本）；version install 同样支持走代理（导出 http_proxy/https_proxy 即可）。

十、卸载

# 卸载指定版本
spacetime version uninstall 2.12.0 -y
# 完整清理（按 4.2 节安装路径）
rm -rf /root/.local/share/spacetime /root/.config/spacetime
rm -f /root/.local/bin/spacetime

十一、常见问题（FAQ）

问题现象与解法
下载缓慢/失败安装器会自动切 S3 镜像，但实测可能长时间无进展；用 export http_proxy=... https_proxy=... 走代理最可靠（见 6.1）
CI 中报 Error: IO error: not a terminal安装器要交互确认；加 -y（curl ... | sh -s -- -y，见 4.2）
/tmp noexec 报 Cannot execute ...spacetime-install手动下载 spacetimedb-update-<架构> 到可执行目录再运行（见 6.2）
命令找不到 spacetimePATH 未含 /root/.local/bin，写入 ~/.bashrc 或重开 shell（见 4.3）
3000 端口被占spacetime start --listen-addr 0.0.0.0:<其他端口>；同数据目录重复启动会报 spacetime.pid already exists（见第七章）
想完全禁用持久化spacetime start --in-memory（进程退出数据全丢，仅测试用）
对外 HTTPSstandalone 不支持 SSL，前置 Nginx/HAProxy 终结 TLS
发布模块时报 wasm32 target 缺失这是模块编译链问题，与服务端安装无关：rustup target add wasm32-unknown-unknown

十二、参考链接

资料链接
官方安装页https://spacetimedb.com/install
Getting Startedhttps://spacetimedb.com/docs/getting-started
GitHub Releases（手动下载二进制）https://github.com/clockworklabs/SpacetimeDB/releases
本组件认知篇《SpacetimeDB 2.13.0 介绍与选型指南》
配置参数详解《SpacetimeDB 2.13.0 配置参数详解》
CLI 命令详解《SpacetimeDB 2.13.0 常用 CLI 命令详解》