SpacetimeDB 本地 replica identity 不一致处理方案

日期：2026-04-30

1. 问题

本地启动 SpacetimeDB standalone 时出现：

error starting database: failed to init replica 1 for <new-database-identity>: mismatched database identity: <old-database-identity> != <new-database-identity>

本次现场日志中，server-rs/.spacetimedb/local/data/logs/spacetime-standalone.log 显示：

2026-04-30T12:17:26Z 开始按 c2006f3d846a8259512006a556b1bc3f751a9aef6608fc0ee75788deea6d9331 启动数据库。
replica 1 的持久化数据仍带有旧库 c20037fcfaac4e5c4b1f492f026a4f6119a98f56319b77f21ef021ededf8b7ae。
SpacetimeDB 因同一个副本目录中 identity 不一致而拒绝继续启动。

这不是 Rust 编译错误，也不是 api-server:maincloud 的 token 错误。只要错误来自 server-rs/.spacetimedb/local/.../spacetime-standalone.log，优先按本地 root-dir 数据目录污染处理。

2. 根因

spacetime start --edition standalone 会在同一个 --root-dir 下保存控制库、程序字节、WAL 与 replica 数据。当前仓库默认本地 root-dir 是：

server-rs/.spacetimedb/local

当这个目录曾经启动并发布过旧 database identity，之后又用同一个 root-dir 初始化或发布到另一个 database identity 时，可能出现：

control-db 记录的是新库。
data/replicas/1 里仍残留旧库 WAL 或快照。
启动时 SpacetimeDB 尝试把旧 replica 当作新库加载，触发 mismatched database identity。

3. 处理原则

不在脚本里默认删除 .spacetimedb 数据，避免误删本地开发数据。
如果只是本地开发库且数据可丢弃，优先备份后重建 data 目录。
如果数据必须保留，不要清理目录；应改回创建旧库时使用的 database/root-dir，或先导出迁移数据。
Maincloud 发布与本地 standalone root-dir 是两条链路；不要通过切回 server-node 或 PostgreSQL 绕过。

4. 本地可丢弃数据时的修复

PowerShell：

$root = "C:\Genarrative\server-rs\.spacetimedb\local"
Get-CimInstance Win32_Process |
  Where-Object { $_.Name -match "spacetime" -and $_.CommandLine -and $_.CommandLine.Replace("/", "\") -like "*$($root.Replace("/", "\"))*" } |
  Select-Object ProcessId, Name, CommandLine

确认占用进程后停止：

Stop-Process -Id <pid> -Force

备份运行态数据目录：

$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
Move-Item -LiteralPath "C:\Genarrative\server-rs\.spacetimedb\local\data" -Destination "C:\Genarrative\server-rs\.spacetimedb\local\data.identity-mismatch-backup.$stamp"

重新启动本地链路：

npm run dev:rust

npm run dev:rust 会重新启动 standalone、发布 spacetime-module，并生成新的本地数据库运行态。

5. 需要保留数据时的处理

不要移动或删除 server-rs/.spacetimedb/local/data。先确认旧库 identity 对应的数据库名、root-dir 与发布命令，然后选择：

用旧库对应的 database/root-dir 重新启动。
使用迁移导出脚本导出旧数据，再清理本地 root-dir 并导入到新库。
如目标其实是 Maincloud，改用 npm run api-server:maincloud 连接云端，避免误启动本地 standalone。

6. 脚本诊断

scripts/dev-rust-stack.sh 已补充本地启动失败诊断：

SpacetimeDB 进程在就绪前退出时，会打印 spacetime-standalone.log 尾部。
若日志包含 mismatched database identity，会提示本地 data/replicas/1 与当前 control-db identity 不一致。
诊断只输出建议，不自动清理数据。

3.6 KiB Raw Blame History Unescape Escape