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 字段,附多实例隔离与安全收紧场景。
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.toml | CLI 侧默认服务器、已保存服务器列表、身份 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.75 | GC 后仍高于该比例则退休该 worker(防长尾内存驻留) | |
heap-limit-mb =0(V8 默认) | 显式 V8 堆上限(MiB);多租户混布时建议给上界 | |
[websocket] | ping-interval ="15s" | 客户端 keep-alive Ping 间隔 |
idle-timeout ="30s" | 空闲连接超时(必须大于 ping-interval;慢速但仍在收数据的客户端不算空闲) | |
[commitlog] | log-format-version =1 | commitlog 格式版本上限(写与读一致) |
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 |