GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify SpacetimeDB root-dir usage
Some checks failed
CI / verify (push) Has been cancelled
Details

Browse Source
This commit is contained in:
kdletters
2026-05-11 14:27:33 +08:00
parent ac2cf78ffa
commit 10ed4fa051
13 changed files with 86 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/technical/SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md
View File

@@ -16,17 +16,17 @@ error starting database: failed to init replica 1 for <new-database-identity>: m
2. `replica 1` 的持久化数据仍带有旧库 `c20037fcfaac4e5c4b1f492f026a4f6119a98f56319b77f21ef021ededf8b7ae`。
3. SpacetimeDB 因同一个副本目录中 identity 不一致而拒绝继续启动。
这不是 Rust 编译错误，也不是 `api-server` 的 token 错误。只要错误来自 `server-rs/.spacetimedb/local/.../spacetime-standalone.log`，优先按本地 root-dir 数据目录污染处理。
这不是 Rust 编译错误，也不是 `api-server` 的 token 错误。只要错误来自 `server-rs/.spacetimedb/local/.../spacetime-standalone.log`，优先按本地 SpacetimeDB 数据目录污染处理。
## 2. 根因
`spacetime start --edition standalone` 会在同一个 `--root-dir` 下保存控制库、程序字节、WAL 与 replica 数据。当前仓库默认本地 root-dir 是：
`spacetime start --edition standalone` 会在本地数据目录中保存控制库、程序字节、WAL 与 replica 数据。当前仓库默认本地数据目录是：
```text
server-rs/.spacetimedb/local
server-rs/.spacetimedb/local/data
```
当这个目录曾经启动并发布过旧 database identity，之后又用同一个 root-dir 初始化或发布到另一个 database identity 时，可能出现：
当这个目录曾经启动并发布过旧 database identity，之后又用同一个数据目录初始化或发布到另一个 database identity 时，可能出现：
1. `control-db` 记录的是新库。
2. `data/replicas/1` 里仍残留旧库 WAL 或快照。
@@ -36,8 +36,8 @@ server-rs/.spacetimedb/local
1. 不在脚本里默认删除 `.spacetimedb` 数据，避免误删本地开发数据。
2. 如果只是本地开发库且数据可丢弃，优先备份后重建 `data` 目录。
3. 如果数据必须保留，不要清理目录；应改回创建旧库时使用的 database/root-dir，或先导出迁移数据。
4. 本地 standalone root-dir 与其它部署目标是两条链路；不要通过切回 `server-node` 或 PostgreSQL 绕过。
3. 如果数据必须保留，不要清理目录；应改回创建旧库时使用的 database/server，或先导出迁移数据。
4. 本地 standalone 数据目录与其它部署目标是两条链路；不要通过切回 `server-node` 或 PostgreSQL 绕过。
## 4. 本地可丢弃数据时的修复
@@ -73,10 +73,10 @@ npm run dev:rust
## 5. 需要保留数据时的处理
不要移动或删除 `server-rs/.spacetimedb/local/data`。先确认旧库 identity 对应的数据库名、root-dir 与发布命令，然后选择：
不要移动或删除 `server-rs/.spacetimedb/local/data`。先确认旧库 identity 对应的数据库名、server 与发布命令，然后选择：
1. 用旧库对应的 database/root-dir 重新启动。
2. 使用迁移导出脚本导出旧数据，再清理本地 root-dir 并导入到新库。
1. 用旧库对应的 database/server 重新启动或连接。
2. 使用迁移导出脚本导出旧数据，再清理本地数据目录并导入到新库。
3. 如目标其实是其它已运行的 SpacetimeDB 服务，改用 `GENARRATIVE_SPACETIME_SERVER_URL` 指向该服务，避免误启动本地 standalone。
## 6. 脚本诊断