# 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` 的 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. 本地 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. 如目标其实是其它已运行的 SpacetimeDB 服务，改用 `GENARRATIVE_SPACETIME_SERVER_URL` 指向该服务，避免误启动本地 standalone。

## 6. 脚本诊断

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

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