1

docs/technical/SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md

@@ -0,0 +1,88 @@
+# SpacetimeDB 本地 replica identity 不一致处理方案
+
+日期：`2026-04-30`
+
+## 1. 问题
+
+本地启动 SpacetimeDB standalone 时出现：
+
+```text
+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` 显示：
+
+1. `2026-04-30T12:17:26Z` 开始按 `c2006f3d846a8259512006a556b1bc3f751a9aef6608fc0ee75788deea6d9331` 启动数据库。
+2. `replica 1` 的持久化数据仍带有旧库 `c20037fcfaac4e5c4b1f492f026a4f6119a98f56319b77f21ef021ededf8b7ae`。
+3. 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 是：
+
+```text
+server-rs/.spacetimedb/local
+```
+
+当这个目录曾经启动并发布过旧 database identity，之后又用同一个 root-dir 初始化或发布到另一个 database identity 时，可能出现：
+
+1. `control-db` 记录的是新库。
+2. `data/replicas/1` 里仍残留旧库 WAL 或快照。
+3. 启动时 SpacetimeDB 尝试把旧 replica 当作新库加载，触发 `mismatched database identity`。
+
+## 3. 处理原则
+
+1. 不在脚本里默认删除 `.spacetimedb` 数据，避免误删本地开发数据。
+2. 如果只是本地开发库且数据可丢弃，优先备份后重建 `data` 目录。
+3. 如果数据必须保留，不要清理目录；应改回创建旧库时使用的 database/root-dir，或先导出迁移数据。
+4. Maincloud 发布与本地 standalone root-dir 是两条链路；不要通过切回 `server-node` 或 PostgreSQL 绕过。
+
+## 4. 本地可丢弃数据时的修复
+
+PowerShell：
+
+```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
+```
+
+确认占用进程后停止：
+
+```powershell
+Stop-Process -Id <pid> -Force
+```
+
+备份运行态数据目录：
+
+```powershell
+$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"
+```
+
+重新启动本地链路：
+
+```powershell
+npm run dev:rust
+```
+
+`npm run dev:rust` 会重新启动 standalone、发布 `spacetime-module`，并生成新的本地数据库运行态。
+
+## 5. 需要保留数据时的处理
+
+不要移动或删除 `server-rs/.spacetimedb/local/data`。先确认旧库 identity 对应的数据库名、root-dir 与发布命令，然后选择：
+
+1. 用旧库对应的 database/root-dir 重新启动。
+2. 使用迁移导出脚本导出旧数据，再清理本地 root-dir 并导入到新库。
+3. 如目标其实是 Maincloud，改用 `npm run api-server:maincloud` 连接云端，避免误启动本地 standalone。
+
+## 6. 脚本诊断
+
+`scripts/dev-rust-stack.sh` 已补充本地启动失败诊断：
+
+1. SpacetimeDB 进程在就绪前退出时，会打印 `spacetime-standalone.log` 尾部。
+2. 若日志包含 `mismatched database identity`，会提示本地 `data/replicas/1` 与当前 control-db identity 不一致。
+3. 诊断只输出建议，不自动清理数据。