Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,88 +0,0 @@
|
||||
# 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`，优先按本地 SpacetimeDB 数据目录污染处理。
|
||||
|
||||
## 2. 根因
|
||||
|
||||
`spacetime start --edition standalone` 会在本地数据目录中保存控制库、程序字节、WAL 与 replica 数据。当前仓库默认本地数据目录是：
|
||||
|
||||
```text
|
||||
server-rs/.spacetimedb/local/data
|
||||
```
|
||||
|
||||
当这个目录曾经启动并发布过旧 database identity，之后又用同一个数据目录初始化或发布到另一个 database identity 时，可能出现：
|
||||
|
||||
1. `control-db` 记录的是新库。
|
||||
2. `data/replicas/1` 里仍残留旧库 WAL 或快照。
|
||||
3. 启动时 SpacetimeDB 尝试把旧 replica 当作新库加载，触发 `mismatched database identity`。
|
||||
|
||||
## 3. 处理原则
|
||||
|
||||
1. 不在脚本里默认删除 `.spacetimedb` 数据，避免误删本地开发数据。
|
||||
2. 如果只是本地开发库且数据可丢弃，优先备份后重建 `data` 目录。
|
||||
3. 如果数据必须保留，不要清理目录；应改回创建旧库时使用的 database/server，或先导出迁移数据。
|
||||
4. 本地 standalone 数据目录与其它部署目标是两条链路；不要通过切回 `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 对应的数据库名、server 与发布命令，然后选择：
|
||||
|
||||
1. 用旧库对应的 database/server 重新启动或连接。
|
||||
2. 使用迁移导出脚本导出旧数据，再清理本地数据目录并导入到新库。
|
||||
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. 诊断只输出建议，不自动清理数据。
|
||||
Reference in New Issue
Block a user