SpacetimeDB 2.13.0 配置参数详解

SpacetimeDB 2.13.0 配置详解:spacetime start 全部 9 个启动参数逐一实测(listen-addr/data-dir/in-memory/pg-port/page_pool_max_size/JWT 密钥等)、数据目录 config.toml 全文逐节解读、metadata.toml 与目录结构、CLI 侧 cli.toml 字段,附多实例隔离与安全收紧场景。

SpacetimeDBSpacetimeDB2026/10/24

SpacetimeDB 2.13.0 配置参数详解

目标:讲清 SpacetimeDB 2.13.0 服务端(standalone)的全部配置入口——spacetime start 启动参数、数据目录内 config.toml 服务器配置文件、metadata.toml、以及 CLI 侧 cli.toml——逐参数给出语义、默认值与实测验证结论。所有标注「实测」的内容均在 2026-10-23 于 Ubuntu 22.04 服务器上验证,回显照抄自真实执行结果。安装与启动前置见《SpacetimeDB 2.13.0 安装指南》。

一、环境信息

项目内容
组件版本SpacetimeDB 2.13.0(spacetimedb tool version 2.13.0; spacetimedb-lib version 2.13.0; rev: 08e1aba133671f9c631c6e70133a82faa0e7b283)
操作系统Ubuntu 22.04 LTS(x86_64)
运行用户root(家目录 /root,配置与数据路径中的 ~ 即 /root)
验证日期2026-10-23
验证方式spacetime start --help 参数清单照抄 + 每个参数逐一启动/运行验证;config.toml 等文件内容取自服务端首次启动后自动生成的真实文件

二、配置总览:三个配置位置

SpacetimeDB standalone 没有单一的「主配置文件」,配置分布在三个位置,优先级与职责如下:

位置载体职责何时生效
启动参数spacetime start [OPTIONS]监听地址、数据目录、持久化模式、PG wire 端口、页池上限、JWT 密钥路径每次启动
服务器配置文件<数据目录>/config.toml出站 HTTP 开关、日志级别、WASM/V8 过程实例池、V8 堆策略、WebSocket keepalive、commitlog 行为服务端启动时读取
CLI 配置~/.config/spacetime/cli.tomlCLI 侧默认服务器、已保存服务器列表、身份 token每次执行 CLI 命令

另有 metadata.toml(数据目录内,服务端生成,禁止手改)与 id_ecdsa(.pub)(CLI 配置目录内的 Identity 签发密钥)。

⚠️ 实测边界:spacetime start --help 共暴露 9 个选项,本篇逐一列出;其中 8 个做了真实启动/行为验证,仅 --enable-tracy(性能剖析,需 Tracy 客户端配套)未做运行验证,仅照抄帮助原文。

三、spacetime start 启动参数详解

参数清单照抄自 spacetime start --help(2.13.0 实测输出):

Usage: spacetime start [OPTIONS]

Options:
  -l, --listen-addr <LISTEN_ADDR>
          The address and port to listen for HTTP requests on
          
          [default: 0.0.0.0:3000]

      --data-dir <DATA_DIR>
          Directory for spacetimedb files

      --enable-tracy
          Enable the Tracy profiler

      --jwt-pub-key-path <JWT_PUB_KEY_PATH>
          Path to a public key (ECDSA/PKCS-8/PEM) for JWT validation

      --jwt-priv-key-path <JWT_PRIV_KEY_PATH>
          Path to a private key (ECDSA/PKCS-8/PEM) for signing JWTs

      --in-memory
          Don't use file-based persistence for the database

      --page_pool_max_size <PAGE_POOL_MAX_SIZE>
          Maximum size of page pool. This is a soft limit: only relevant
          while page pool is not full. If page pool is full, it will
          allocate additional memory. Must be a multiple of 64KiB.
          
          [default: 8GiB]

      --pg-port <PG_PORT>
          Port to bind for Postgres compatibility endpoint

      --non-interactive
          Don't run in interactive mode

  -h, --help
          Print help

3.1 --listen-addr(HTTP 监听地址,默认 0.0.0.0:3000)

  • 类型:IP:端口 字符串;帮助原文 "The address and port to listen for HTTP requests on"。
  • 实测①(缺省):启动日志 Starting SpacetimeDB listening on 0.0.0.0:3000。
  • 实测②(改绑定):spacetime start --non-interactive --listen-addr 127.0.0.1:3001 --data-dir /data/sdb-mem --in-memory 启动后日志:
2026-10-23T17:21:20.219033Z  INFO crates/standalone/src/subcommands/start.rs:266: Starting SpacetimeDB listening on 127.0.0.1:3001

随后 spacetime server ping http://127.0.0.1:3001 回显 Server is online: http://127.0.0.1:3001,参数生效。

💡 技术拓展:「监听地址」0.0.0.0(IPv4 全地址)与 127.0.0.1(仅本机回环)的选择即传统 socket 语义:生产对内网提供服务用 0.0.0.0 + 防火墙/反代收敛暴露面;仅本机调试用 127.0.0.1 最安全。

3.2 --data-dir(数据目录,缺省 ~/.local/share/spacetime/data)

  • 帮助原文 "Directory for spacetimedb files"。不传时服务端用平台数据目录(Linux root 下即 /root/.local/share/spacetime/data,见 spacetime start 横幅回显 database running in data directory ...)。
  • 实测:--data-dir /data/sdb-alt 启动成功,日志回显:
database running in data directory /data/sdb-alt
2026-10-23T17:19:30.387451Z  INFO crates/standalone/src/subcommands/start.rs:266: Starting SpacetimeDB listening on 127.0.0.1:3005

新目录随即被自动初始化(生成 config.toml、control-db/、logs/、program-bytes/、replicas/、spacetime.pid 等,结构见第五章)。

  • 单实例锁(实测):同一数据目录不允许两个实例。第二个实例启动(数据目录被 pid 3228 占用时)报错原文:
Error: cannot take lock on database; spacetime.pid already exists (owned by pid Some(3228))

⚠️ 实测坑点:--in-memory 模式同样受数据目录锁约束——不显式给 --data-dir 就起第二实例,即便开了 --in-memory 也会撞锁(实测命中)。多实例共存的正确姿势:每个实例独立的 --data-dir + 独立的 --listen-addr。

3.3 --in-memory(关闭持久化)

  • 帮助原文 "Don't use file-based persistence for the database"。进程退出数据全丢,属测试/临时实例选项。
  • 实测:与 --data-dir /data/sdb-mem --listen-addr 127.0.0.1:3001 组合启动成功、ping 在线(回显见 3.1)。注意它只是「不持久化应用数据」,锁文件与配置仍在 --data-dir 下生成。

3.4 --pg-port(PostgreSQL wire 协议端口,默认关闭)

  • 帮助原文 "Port to bind for Postgres compatibility endpoint"。不传即关闭——默认启动日志固定有 PostgreSQL wire protocol server disabled。
  • 实测开启:spacetime start --non-interactive --data-dir /data/sdb-pg --listen-addr 127.0.0.1:3004 --pg-port 5432,服务端日志出现:
2026-10-23T17:21:38.242255Z DEBUG crates/pg/src/pg_server.rs:387: PG: Starting SpacetimeDB Protocol listening on 127.0.0.1:5432
  • 用 psql 连接探测(psql -h 127.0.0.1 -p 5432 -U postgres -c "SELECT version();")实测回显:
Password for user postgres:
psql: error: connection to server at "127.0.0.1", port 5432 failed: fe_sendauth: no password supplied
        Is the server running on that host and accepting TCP/IP connections?

即 PG wire 端点开启后走标准 PostgreSQL 认证握手,需要密码(SpacetimeDB 侧对应身份 token);本篇实测到「握手可达、认证必须」为止,语义级 SQL 兼容范围未展开(它不是完整 PostgreSQL 语法面,定位见《SpacetimeDB 2.13.0 介绍与选型指南》)。

3.5 --page_pool_max_size(页池上限,默认 8GiB)

  • 帮助原文(照抄):"Maximum size of page pool. This is a soft limit: only relevant while page pool is not full. If page pool is full, it will allocate additional memory. Must be a multiple of 64KiB."——软限制:页池未满时作为上限参考;满了以后仍会继续额外分配内存。必须为 64 KiB 的倍数。
  • 实测①:--page_pool_max_size 128MiB 启动正常。
  • 实测②:--page_pool_max_size 100MiB(非 64KiB 整倍数)启动同样成功、无校验报错——即帮助中的倍数约束在本版本实测未在启动期强制(软限制语义),合规值仍建议按 64KiB 的倍数给。
  • 生产建议:按「数据集全内存常驻」的产品定位(见选型篇 3.3),把页池上限规划到物理内存预留水位内,并配合系统侧监控。

3.6 --jwt-pub-key-path / --jwt-priv-key-path(自定义 JWT 密钥)

  • 帮助原文 "Path to a public key (ECDSA/PKCS-8/PEM) for JWT validation" / "Path to a private key (ECDSA/PKCS-8/PEM) for signing JWTs"。默认缺省时服务端用 ~/.config/spacetime/id_ecdsa(.pub)(systemd 下进程参数回显 --jwt-key-dir /root/.config/spacetime/)。
  • 实测:显式传入现成 ECDSA 密钥对启动成功(与 --data-dir 组合):
spacetime start --non-interactive --data-dir /data/sdb-alt \
  --jwt-pub-key-path /root/.config/spacetime/id_ecdsa.pub \
  --jwt-priv-key-path /root/.config/spacetime/id_ecdsa

适用场景:需要把 Identity 签发密钥纳入统一密钥管理/轮换流程时,用本参数替换默认的本地密钥文件。

3.7 --non-interactive(非交互模式)

  • 帮助原文 "Don't run in interactive mode"。脚本化/后台运行(systemd、nohup、CI)建议始终加上;前台交互模式会渲染交互式控制台输出(2.13.0 启动横幅与日志面板)。

3.8 --enable-tracy(Tracy 性能剖析)

  • 帮助原文 "Enable the Tracy profiler"。性能剖析开关,需要本机运行 Tracy 客户端连接后才能看到数据;本篇未做实测(正常生产部署无需开启)。

四、服务器配置文件 config.toml 逐节详解

首次启动时服务端在 <数据目录>/config.toml 生成带完整注释的模板文件(本篇照抄 2.13.0 生成的真实全文并逐节解读)。文件头两行:

# [certificate-authority]
# jwt-priv-key-path = "~/.config/spacetime/id_ecdsa"
# jwt-pub-key-path = "~/.config/spacetime/id_ecdsa.pub"

[module-http]
# Whether database modules may make outbound HTTP requests. This applies to
# procedures and module HTTP handlers. Omit to allow requests.
# enabled = true

[logs]
# The default level filter for logging
# level = "ERROR"

# directives for logging, see link for syntax:
# https://docs.rs/tracing-subscriber/latest/tracing_subscriber/struct.EnvFilter.html#directives
directives = [
    "spacetimedb=debug",
    "spacetimedb_client_api=debug",
    "spacetimedb_lib=debug",
    "spacetimedb_standalone=debug",
    "spacetimedb_commitlog=info",
    "spacetimedb_durability=info",
    "axum::rejection=trace",
]

[wasm]
# Maximum number of WASM procedure instances per database. Omit to use the
# number of cores reported by the OS.
# procedure-instance-pool-size = 8

[v8]
# Maximum number of JS procedure isolates per database. Omit to use the number
# of cores reported by the OS.
# procedure-instance-pool-size = 8

[v8-heap-policy]
# Check the V8 heap after this many requests. Set to 0 to disable.
# heap-check-request-interval = 65536

# Also check the V8 heap after this much wall-clock time. Set to "0s" to disable.
# heap-check-time-interval = "30s"

# Trigger a GC when the heap reaches this fraction of the limit.
# heap-gc-trigger-fraction = 0.67

# Retire the worker if the heap is still this full after GC.
# heap-retire-fraction = 0.75

# Apply a V8 heap limit in MiB. Set to 0 to use V8's default limit.
# heap-limit-mb = 0

# [websocket]
# Interval at which keep-alive Ping frames are sent to clients.
# ping-interval = "15s"
# Close connections from which nothing was received, and to which no send
# progress was made, for this long. Slow clients that keep accepting data are
# not considered idle. Must be greater than ping-interval.
# idle-timeout = "30s"

[commitlog]
# The maximum supported commitlog format version, also used for writing.
# log-format-version = 1

# Maximum size in bytes for each commitlog segment.
# max-segment-size = 1073741824

# Number of bytes written to the commitlog after which an entry is added to the offset index.
# offset-index-interval-bytes = 4096

# Require that the commitlog segment is synced before adding an offset index entry.
# offset-index-require-segment-fsync = true

# Preallocate disk space for commitlog segments up to max-segment-size.
# Has no effect unless commitlog fallocate support is enabled.
# preallocate-segments = false

# Size in bytes of the memory buffer holding commit data before flushing to storage.
# write-buffer-size = 131072

# vim: set nowritebackup: << otherwise triggers cargo-watch

逐节解读(默认值均来自生成文件中的注释):

节参数语义与生产建议
[certificate-authority]jwt-priv-key-path / jwt-pub-key-path服务器作为 Identity 证书机构的 ECDSA 密钥路径;与启动参数 --jwt-*-key-path 等价的文件级配置。默认 ~/.config/spacetime/id_ecdsa(.pub)。密钥轮换/纳管时改这里或用启动参数覆盖
[module-http]enabled(缺省 true)模块出站 HTTP 总开关:约束 procedures 与模块 HTTP 处理器能否发外部请求。安全收紧场景设 enabled = false
[logs]level(缺省 "ERROR")全局日志级别兜底
[logs]directives(数组)tracing-subscriber EnvFilter 语法的定向级别,生成默认已把 spacetimedb 各 crate 开到 debug、commitlog/durability 为 info、axum::rejection 为 trace——排障时这是现成的细粒度开关清单;生产降噪可整体下调
[wasm]procedure-instance-pool-size(缺省=CPU 核数)每数据库 WASM 过程实例池上限(过程是可发外部 HTTP 的服务端函数形态)
[v8]procedure-instance-pool-size(缺省=CPU 核数)每数据库 JS(V8)过程 isolate 池上限;TS 过程负载高时与 [wasm] 一并按核数调优
[v8-heap-policy]heap-check-request-interval =65536每多少次请求检查一次 V8 堆;0 关闭
heap-check-time-interval ="30s"堆检查的最大时间间隔;"0s" 关闭
heap-gc-trigger-fraction =0.67堆占用达上限比例触发 GC
heap-retire-fraction =0.75GC 后仍高于该比例则退休该 worker(防长尾内存驻留)
heap-limit-mb =0(V8 默认)显式 V8 堆上限(MiB);多租户混布时建议给上界
[websocket]ping-interval ="15s"客户端 keep-alive Ping 间隔
idle-timeout ="30s"空闲连接超时(必须大于 ping-interval;慢速但仍在收数据的客户端不算空闲)
[commitlog]log-format-version =1commitlog 格式版本上限(写与读一致)
max-segment-size =1073741824(1 GiB)单个 commitlog 段最大字节数
offset-index-interval-bytes =4096每写入多少字节在 offset 索引追加一条(影响重启重放扫描粒度)
offset-index-require-segment-fsync =true加索引条目前强制段 fsync(持久性优先,默认正确)
preallocate-segments =false预分配段空间(需文件系统支持 fallocate;高写入吞吐场景可开)
write-buffer-size =131072(128 KiB)落盘前内存缓冲大小

⚠️ 修改守则:该文件由服务端生成并自带注释,注释掉的键即缺省值——只取消注释改需要的键,其余保持原样;改完重启服务端生效。

五、数据目录结构

服务端初始化后的真实目录树(实测 find <数据目录> -maxdepth 2):

/root/.local/share/spacetime/data
├── cache/wasmtime          # 编译后的 WASM 模块缓存(提升模块加载速度)
├── config.toml             # 服务器配置文件(见第四章)
├── control-db/             # 控制库:数据库目录、身份与元数据
│   ├── blobs/
│   ├── conf/
│   └── db/
├── logs/spacetime-standalone.log   # 服务端日志文件(与控制台输出并存)
├── metadata.toml           # 版本元数据(服务端生成,禁止手改)
├── program-bytes/cb        # 已发布模块的 WASM 字节码
├── replicas/1              # 数据副本工作区(commitlog + 数据库状态)
└── spacetime.pid           # 单实例锁(见 3.2)

metadata.toml 实测全文:

# THIS FILE IS GENERATED BY SPACETIMEDB, DO NOT MODIFY!

version = "2.13.0"
edition = "standalone"

服务端日志文件头部实测回显(重启后重放事务历史的真实痕迹,印证 commit log 机制):

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
2026-10-23T17:15:47.191467Z  INFO crates/engine/src/relational_db.rs:302: [c200342892f5aa39760975a3c67e8fa02d3a03c1991f3ddbd7ca771168129e19] DATABASE: durable_tx_offset is None
2026-10-23T17:15:47.191559Z  INFO crates/engine/src/relational_db.rs:726: [c200342892f5aa39760975a3c67e8fa02d3a03c1991f3ddbd7ca771168129e19] DATABASE: no usable snapshot in snapshot repo
2026-10-23T17:15:47.192478Z  INFO crates/datastore/src/locking_tx_datastore/replay.rs:42: [c200342892f5aa39760975a3c67e8fa02d3a03c1991f3ddbd7ca771168129e19] DATABASE: applying transaction history...

备份要点:需备份的核心是 replicas/(数据)、control-db/(元数据)、program-bytes/(模块)、config.toml 与 metadata.toml;cache/ 可再生,spacetime.pid 无需备份。备份前应停止服务端保证一致性。

六、CLI 配置 ~/.config/spacetime/cli.toml

CLI 侧配置文件由 spacetime 命令自动维护(改默认服务器等操作会打印 Saving config to /root/.config/spacetime/cli.toml.)。实测首次本地发布 + 切换默认服务器后的文件全文(token 已脱敏):

default_server = "local"
spacetimedb_token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.<...>.<...>"

[[server_configs]]
nickname = "maincloud"
host = "maincloud.spacetimedb.com"
protocol = "https"

[[server_configs]]
nickname = "local"
host = "127.0.0.1:3000"
protocol = "http"

字段说明:

字段语义管理命令
default_server不带 -s/--server 时命令的默认目标spacetime server set-default <nickname>
spacetimedb_token当前身份的 JWT(ES256);本机 standalone 场景下由服务端签发(payload 的 iss 为 localhost)spacetime login / spacetime logout
[[server_configs]]已保存服务器列表(nickname/host/protocol)spacetime server add/list/remove

同目录的 id_ecdsa(私钥,权限 600)与 id_ecdsa.pub 是本地 standalone 的 Identity 签发密钥对;.update_check_cache 是 CLI 升级检查缓存。这台机器的 Identity 信任根就是这对密钥——泄露即等于数据库管理身份泄露,建议纳入与私钥同级的保护基线。

七、常见配置场景

7.1 修改监听端口并常驻

# /etc/systemd/system/spacetimedb.service
ExecStart=/root/.local/bin/spacetime start --listen-addr 0.0.0.0:8300

7.2 多实例隔离

每个实例独立数据目录 + 独立端口,缺一不可(实测 --in-memory 也会撞数据目录锁):

spacetime start --non-interactive --data-dir /data/sdb-a --listen-addr 127.0.0.1:3001
spacetime start --non-interactive --data-dir /data/sdb-b --listen-addr 127.0.0.1:3002

7.3 关闭模块出站 HTTP(安全收紧)

config.toml 中取消注释并置 false:

[module-http]
enabled = false

7.4 生产降噪日志

config.toml 的 [logs]:level 保底 INFO,directives 数组按需保留少数目标,例如只留 "spacetimedb=info";排障期再临时放回生成模板的 debug 组合。

7.5 开启 PG wire 兼容端点

spacetime start --non-interactive --pg-port 5432

开启后默认日志由 PostgreSQL wire protocol server disabled 变为 PG: Starting SpacetimeDB Protocol listening on 127.0.0.1:5432(实测回显见 3.4)。

八、常见问题(FAQ)

问题结论
启动报 cannot take lock on database; spacetime.pid already exists同数据目录已有实例在跑;确认旧实例或换 --data-dir(实测回显见 3.2)
--in-memory 为什么还生成目录/锁它只关持久化,锁与配置仍在数据目录;多实例务必各给 --data-dir
页池上限是不是硬限制不是。帮助与实测均表明是软限制,页池满后仍会额外分配内存(见 3.5)
--page_pool_max_size 非 64KiB 倍数会拒绝吗2.13.0 实测启动期不校验(100MiB 成功启动),但仍应按帮助要求给整倍数值
PG wire 端口开了但 psql 连不上服务端在监听(日志有 PG: Starting 行),走标准 PG 认证需提供密码(身份 token);fe_sendauth: no password supplied 即未带密码(实测见 3.4)
standalone 支持 TLS 吗不支持(官方文档明确);用 Nginx/HAProxy 等反代终结 SSL
配置改了没生效启动参数每次启动读取;config.toml 亦在启动时读取——改完需重启服务端进程

九、参考链接

资料链接
本组件认知篇(定位与架构)《SpacetimeDB 2.13.0 介绍与选型指南》
本组件安装篇《SpacetimeDB 2.13.0 安装指南》
本组件 CLI 命令篇《SpacetimeDB 2.13.0 常用 CLI 命令详解》
Getting Started(standalone 说明)https://spacetimedb.com/docs/getting-started
tracing EnvFilter 语法([logs] directives)https://docs.rs/tracing-subscriber/latest/tracing_subscriber/struct.EnvFilter.html#directives