docs: clarify SpacetimeDB root-dir usage

2026-05-11 14:27:33 +08:00
parent ac2cf78ffa
commit 10ed4fa051
13 changed files with 86 additions and 85 deletions
--- a/docs/technical/AUTH_SNAPSHOT_AND_MATCH3D_LOCAL_DEV_FIX_2026-05-01.md
+++ b/docs/technical/AUTH_SNAPSHOT_AND_MATCH3D_LOCAL_DEV_FIX_2026-05-01.md
@@ -67,9 +67,11 @@ HTTP status server error (503 Service Unavailable)
 远端 `xushi-p4wfr` 挂起期间，抓大鹅本地体验应使用本地 SpacetimeDB：

 ```powershell
-spacetime --root-dir=server-rs/.spacetimedb/local start --edition standalone --listen-addr 127.0.0.1:3101
+npm run dev:rust
 $env:GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET="codex-local-bootstrap-secret-20260501"
-spacetime --root-dir=server-rs/.spacetimedb/local publish xushi-p4wfr --server http://127.0.0.1:3101 --module-path server-rs/crates/spacetime-module -c=on-conflict --yes
+Push-Location server-rs
+spacetime publish xushi-p4wfr --server http://127.0.0.1:3101 --module-path crates/spacetime-module -c=on-conflict --yes
+Pop-Location
 ```

 再让 Rust API 指向本地库：
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -79,7 +79,7 @@
 - [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)：冻结 SpacetimeDB 表结构变更约束、自动迁移可接受范围、冲突后的系统行为，以及保留旧数据的增量迁移流程；凡涉及 `spacetime publish`、表字段调整或 `migration.rs` 对齐时优先参考。
 - [PRODUCT_NAMING_BAIMENG_RENAME_2026-05-01.md](./PRODUCT_NAMING_BAIMENG_RENAME_2026-05-01.md)：冻结当前对外中文命名，产品展示名统一为“百梦”，消费单位为“光点”，公开账号标识为“百梦号”，创作侧称谓为“百梦主”。
 - [SPACETIMEDB_CLOUD_CONFIG_REMOVAL_2026-05-02.md](./SPACETIMEDB_CLOUD_CONFIG_REMOVAL_2026-05-02.md)：记录旧云端 SpacetimeDB 配置、发布脚本和默认文档口径的移除结果，冻结后续仅使用本地或显式 `SERVER_URL` 的运维规则。
- [SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md](./SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md)：记录本地 standalone 启动时报 `mismatched database identity` 的 root-dir/replica 数据残留根因、备份重建步骤和脚本诊断口径。
+- [SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md](./SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md)：记录本地 standalone 启动时报 `mismatched database identity` 的数据目录/replica 数据残留根因、备份重建步骤和脚本诊断口径。
 - [AUTH_SNAPSHOT_AND_MATCH3D_LOCAL_DEV_FIX_2026-05-01.md](./AUTH_SNAPSHOT_AND_MATCH3D_LOCAL_DEV_FIX_2026-05-01.md)：记录远端库挂起导致认证快照同步和抓大鹅创作失败的根因、认证同步非阻断修复、`/api/creation` Vite 代理补齐和本地 SpacetimeDB 可跑链路。
 - [LLM_MODEL_ROUTING_RPG_AND_CREATION_2026-04-30.md](./LLM_MODEL_ROUTING_RPG_AND_CREATION_2026-04-30.md)：冻结 RPG 运行时剧情推理使用 `doubao-seed-character-251128` 的 `/chat/completions`，以及所有模板创作大模型推理使用 `deepseek-v3-2-251201` 的 `/responses`。
 - [PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md](./PROFILE_INVITE_CODE_REGISTRATION_AND_ADMIN_2026-04-30.md)：冻结邀请码从“我的 Tab 填写”迁到注册环节的前后端边界、`profile_invite_code.metadata_json` 表结构扩展、管理员邀请码虚拟主体和奖励规则。
@@ -113,11 +113,11 @@
 - [RPG_SCENE_ACT_PREVIEW_BOOTSTRAP_FIX_2026-04-30.md](./RPG_SCENE_ACT_PREVIEW_BOOTSTRAP_FIX_2026-04-30.md)：记录编辑器幕预览卡在“正在载入这一幕”时的启动态根因，收口预览本地运行态装配与禁持久化首段 story 注入。
 - [PUZZLE_RESULT_AUTOSAVE_AND_TAG_GATE_FIX_2026-04-28.md](./PUZZLE_RESULT_AUTOSAVE_AND_TAG_GATE_FIX_2026-04-28.md)：记录拼图结果页名称与标签编辑自动保存、发布门槛统一到 `3~6` 标签，以及前端发布校验不再被旧 session blocker 卡死的修复口径。
 - [WORK_AUTHOR_ID_RESOLUTION_2026-04-30.md](./WORK_AUTHOR_ID_RESOLUTION_2026-04-30.md)：记录作品作者以 `owner_user_id` 为真相源，API 按用户 ID 解析最新昵称与公开用户码，历史 `author_display_name` 仅作为兼容回退。
- [SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md](./SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md)：记录发布包 `start.sh` 只输出“SpacetimeDB 进程在就绪前退出”时的诊断补强，启动失败或超时时自动回显 `logs/spacetimedb.log`、`server ping`、端口监听和 root-dir 相关进程。
+- [SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md](./SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md)：历史事故记录，保留旧发布包 `start.sh` 只输出“SpacetimeDB 进程在就绪前退出”时的诊断补强；该文档不再作为当前发布或人工排障依据。
 - [RPG_AND_AGENT_CHAT_TRUE_SSE_STREAMING_2026-04-26.md](./RPG_AND_AGENT_CHAT_TRUE_SSE_STREAMING_2026-04-26.md)：记录 RPG 运行时 NPC 聊天、RPG/自定义世界 Agent 与大鱼 Agent 从“拼完整 SSE 字符串后一次性返回”改为 `mpsc + Sse<Event>` 真流式输出的后端落地口径。
- [SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md](./SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md)：记录发布包 `start.sh` root-dir 占用检测把 `grep -F .../.spacetimedb` 误判为 SpacetimeDB 实例的根因、脚本修复和现场处理方式。
+- [SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md](./SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md)：历史事故记录，保留旧发布包 `start.sh` 占用检测把 `grep -F .../.spacetimedb` 误判为 SpacetimeDB 实例的根因；该文档不再作为当前发布或人工排障依据。
 - [RPG_BATTLE_HEALTHBAR_AND_ACTION_PRESENTATION_FIX_2026-04-26.md](./RPG_BATTLE_HEALTHBAR_AND_ACTION_PRESENTATION_FIX_2026-04-26.md)：记录 RPG 战斗血条安全锚点、服务端战斗回包前端短表现，以及 `battle_use_skill` 指定技能兜底结算的修复口径。
- [SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md](./SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md)：记录发布包 `start.sh` 执行 `spacetime publish` 遇到 `403 Forbidden` 的身份根因、`.spacetimedb/` root-dir 隔离修复和排查步骤。
+- [SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md](./SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md)：历史事故记录，保留旧发布包执行 `spacetime publish` 遇到 `403 Forbidden` 的身份根因；当前人工命令禁止使用 `spacetime --root-dir`，CI/CD 脚本内部受控用法除外。
 - [SPACETIMEDB_TABLE_CATALOG.md](./SPACETIMEDB_TABLE_CATALOG.md)：持续维护当前 SpacetimeDB 表目录，按领域说明每张表的作用、字段结构、索引和常用 `spacetime sql` 查询模板。
 - [RPG_OPENING_SCENE_ACT_IMAGE_PRESENTATION_SYNC_2026-04-26.md](./RPG_OPENING_SCENE_ACT_IMAGE_PRESENTATION_SYNC_2026-04-26.md)：记录开局场景与普通场景复用同一场景展示解析服务，修复列表幕缩略图和详情幕背景预览图片不一致的问题。
 - [FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md](./FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md)：记录网站启动后首次加载约三分钟的前端根因，收口 `RouteImageReadyGate` 首屏图片门控和 Vite dev server 无关文件监听范围。
--- a/docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md
+++ b/docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md
@@ -114,7 +114,7 @@ npm run dev:rust:logs -- --follow

 日志提取规则：

-1. SpacetimeDB 模块日志以 `spacetime --root-dir=server-rs/.spacetimedb/local logs <database>` 为唯一提取入口，脚本不直接读取内部日志文件结构。
+1. SpacetimeDB 模块日志以 `spacetime logs <database> --server <实际本地 server>` 或 `npm run dev:rust:logs` 为提取入口，脚本不直接读取内部日志文件结构。
 2. 默认读取 `spacetime.local.json` 的 `database` 字段，默认 server 为 `http://127.0.0.1:3101`。
 3. 默认输出到 `logs/spacetime/<database>-<timestamp>.log`，并通过 `tee` 同步显示在终端。
 4. `--follow` 仅用于本地追踪，会持续追加到同一个输出文件；停止时用 `Ctrl+C`。
@@ -125,8 +125,8 @@ npm run dev:rust:logs -- --follow
 2. `spacetime list --server http://127.0.0.1:3101` 应能看到 `spacetime.local.json` 中的库名；若没有，执行 `spacetime publish <本地数据库名> --server http://127.0.0.1:3101 --module-path server-rs/crates/spacetime-module --build-options="--debug" -c=on-conflict --yes`。
 3. 发布库名与 `GENARRATIVE_SPACETIME_DATABASE` 不一致时，`/api/runtime/custom-world-gallery` 会从 Rust `api-server` 返回 `502`，前端首页只能展示空态或错误提示，无法自行修复。
 4. 如果 Vite 输出 `/api/auth/refresh`、`/api/auth/login-options` 或 `/api/runtime/custom-world-gallery` 的 `ECONNREFUSED`，先确认当前脚本是否已经打印 `等待 api-server 就绪` 并通过；正常情况下 Vite 只会在 `/healthz` 可访问后启动，不应再因为 Rust 监听未完成而代理失败。
-5. 如果 `spacetime server ping` 打印 `Server could not be reached (502 Bad Gateway)`，即使命令退出码为 `0` 也不能直接视为已就绪；本地脚本会继续探测 `/v1/ping`。若 `/v1/ping` 返回 `200`，说明 standalone 已经可用，可以继续发布模块；若 `/v1/ping` 也失败，脚本会继续等待新启动实例，或在 root-dir 已被其他实例占用时输出占用进程。
-6. 如果本地 `spacetime publish` 显示 `401` 无权限，且确认本地开发数据可以丢弃，可执行 `spacetime --root-dir=server-rs/.spacetimedb/local server clear` 清除本地 SpacetimeDB 数据库后重新发布。重新发布时日志应表现为创建新的数据库，而不是更新旧数据库；如果仍显示更新旧库或继续无权限，说明 root-dir、库名或 CLI 身份仍未对齐。
+5. 如果 `spacetime server ping` 打印 `Server could not be reached (502 Bad Gateway)`，即使命令退出码为 `0` 也不能直接视为已就绪；本地脚本会继续探测 `/v1/ping`。若 `/v1/ping` 返回 `200`，说明 standalone 已经可用，可以继续发布模块；若 `/v1/ping` 也失败，脚本会继续等待新启动实例，或在本地数据目录已被其他实例占用时输出占用进程。
+6. 如果本地 `spacetime publish` 显示 `401` 无权限，且确认本地开发数据可以丢弃，先停止本地 SpacetimeDB，再备份或删除 `server-rs/.spacetimedb/local/data` 后重新运行 `npm run dev`。重新发布时日志应表现为创建新的数据库，而不是更新旧数据库；如果仍显示更新旧库或继续无权限，说明数据目录、库名或 CLI 身份仍未对齐。除 CI/CD 脚本内部受控用法外，人工清理不要使用 `spacetime --root-dir`。
 7. Windows / Git Bash 下读取 `spacetime.pid` 或 `dev-rust-spacetime-url` 时，如果文件正被 SpacetimeDB 更新，不能用 `tr/head/xargs` 管道直接读；脚本使用 Node 读取并短重试，避免出现 `tr: read error: Device or resource busy` 后直接中断。

 编译警告治理：
@@ -166,12 +166,12 @@ npm run deploy:rust:remote
 5. 执行 `cargo build -p spacetime-module --release --target wasm32-unknown-unknown --manifest-path server-rs/Cargo.toml`，并把 `spacetime_module.wasm` 复制到目标目录。
 6. 把仓库根目录的 `.env` 与 `.env.local` 分别复制到目标目录根部和目标目录的 `web/` 下；复制后统一移除 UTF-8 BOM 与 CRLF，并把 `GENARRATIVE_SPACETIME_DATABASE` 覆盖为本次 `--database` 参数，避免 Jenkins 工作区里残留的旧 `.env.local` 覆盖发布包目标库。
 7. 在目标目录写入 `web-server.mjs`，用于托管 `web/` 与 `web/admin/`；其中 `/admin` 跳转到 `/admin/`，`/admin/` 提供后台 SPA，`/admin/api/*`、`/api/*`、`/generated-*`、`/healthz` 反代到本包内的 `api-server`。
-8. 在目标目录写入 `start.sh` 与 `stop.sh`；`start.sh` 会先按 `KEY=value` 子集加载发布目录根部的 `.env`、`.env.local`，兼容 UTF-8 BOM 与 CRLF，再回退到构建时通过 `--database`、`--api-port`、`--web-host`、`--web-port`、`--spacetime-host`、`--spacetime-port` 写入的默认值，其中 Web 默认只监听 `127.0.0.1`；并默认导出 `NO_COLOR=1` 与 `CARGO_TERM_COLOR=never`，避免 ANSI 控制码写入日志文件；同时按 Ubuntu 发布环境使用发布目录内 `.spacetimedb/` 作为 root-dir，不再额外设置 `--data-dir`，启动前先执行 `sync_ubuntu_spacetime_install`，优先从 `/usr/.local/share/spacetime/bin/<version>/spacetimedb-cli` 或 `$HOME/.local/share/spacetime/bin/<version>/spacetimedb-cli` 同步到 `.spacetimedb/bin/current/spacetimedb-cli`，当前线上 `spacetime` 入口为 `/usr/local/bin/spacetime`；启动参数为 `spacetime --root-dir ./.spacetimedb start --edition standalone --listen-addr <host>:<port>`，探活必须确认 `server ping` 输出包含 `Server is online:`；普通启动先无清库发布，若 publish 输出可判定为 schema 冲突，则自动导出旧库、清库发布新 wasm、导入回灌；如果以 `--clear-database` 启动，则内部 `spacetime publish` 会追加 `-c=on-conflict`，代表人工确认清库，不触发自动回灌。
+8. 在目标目录写入 `start.sh` 与 `stop.sh`；`start.sh` 会先按 `KEY=value` 子集加载发布目录根部的 `.env`、`.env.local`，兼容 UTF-8 BOM 与 CRLF，再回退到构建时通过 `--database`、`--api-port`、`--web-host`、`--web-port`、`--spacetime-host`、`--spacetime-port` 写入的默认值，其中 Web 默认只监听 `127.0.0.1`；并默认导出 `NO_COLOR=1` 与 `CARGO_TERM_COLOR=never`，避免 ANSI 控制码写入日志文件；SpacetimeDB 启动、探活和发布由发布脚本内部统一编排。脚本内部如保留 `--root-dir`，只属于 CI/CD 或发布包受控用法，不作为人工命令模板。普通启动先无清库发布，若 publish 输出可判定为 schema 冲突，则自动导出旧库、清库发布新 wasm、导入回灌；如果以 `--clear-database` 启动，则内部 `spacetime publish` 会追加 `-c=on-conflict`，代表人工确认清库，不触发自动回灌。
 9. 默认执行 `scp -r -i ~\.ssh\dsk.pem build/<timestamp> ubuntu@82.157.175.59:/home/ubuntu/genarrative/` 上传发布包。

 SpacetimeDB database 名称必须匹配 `^[a-z0-9]+(-[a-z0-9]+)*$`：只能使用小写字母、数字，并用单个短横线分隔；大写字母、点号、下划线、首尾短横线和连续短横线都会触发 `spacetime publish` 的 `invalid characters in database name`。发布包构建脚本和 `start.sh` 都会提前拦截这类非法名称。

-发布包构建日志会输出 `SpacetimeDB 发布数据库: <database>`；目标服务器执行 `start.sh` 时会在发布前输出最终加载后的 `database/server/root-dir`，用于确认 `.env.local` 或 Jenkins 参数覆盖后的实际发布目标。
+发布包构建日志会输出 `SpacetimeDB 发布数据库: <database>`；目标服务器执行 `start.sh` 时会在发布前输出最终加载后的 `database/server/数据目录或脚本运行目录`，用于确认 `.env.local` 或 Jenkins 参数覆盖后的实际发布目标。

 发布包结构：

@@ -225,8 +225,8 @@ cd build/<timestamp>
 5. 自动迁移导出旧库时优先读取 `deploy-state/migration-bootstrap-secret.previous.txt`，导入新库时读取当前发布包 `migration-bootstrap-secret.txt`；Jenkins 部署脚本会在覆盖发布包前保存旧密钥。该快照属于部署状态，不放入 `run/`，避免启停 hook 通过 `sudo` 运行后把部署阶段要写的文件变成 root 私有。手工覆盖发布包时，也应在覆盖前保留旧模块的引导密钥，否则旧库导出可能无法授权。
 6. 自动迁移 JSON 默认写入发布目录下 `database-migrations/<database>/`；可通过 `GENARRATIVE_SPACETIME_MIGRATION_DIR` 改写。该目录属于运行态，不应被 Jenkins 覆盖部署删除。
 7. 只有显式执行 `./start.sh --clear-database` 才追加 `-c=on-conflict`，该模式代表人工确认清库，不执行导出和回灌。
-8. `start.sh` 会先复用已经按目标地址就绪的 SpacetimeDB；如果同一个 `.spacetimedb/` root-dir 已被其他未就绪实例占用，则只输出命令名为 `spacetime` 或 `spacetimedb-cli` 且命令行包含当前 root-dir 的真实占用进程并失败，避免把排查用的 `grep` / `awk` 误判为 SpacetimeDB 实例。
-9. 如果 `spacetime publish` 报 `403 Forbidden`，优先确认 `spacetime --root-dir ./.spacetimedb login show` 输出的身份是否有权更新目标库；`--clear-database` 不能绕过身份授权。
+8. `start.sh` 会先复用已经按目标地址就绪的 SpacetimeDB；如果同一个 `.spacetimedb/` 运行目录已被其他未就绪实例占用，则只输出真实占用进程并失败，避免把排查用的 `grep` / `awk` 误判为 SpacetimeDB 实例。
+9. 如果 `spacetime publish` 报 `403 Forbidden`，优先确认 `spacetime login show` 输出的身份是否有权更新目标库，并确认 `GENARRATIVE_SPACETIME_DATABASE` / `GENARRATIVE_SPACETIME_SERVER_URL` 未指向错误环境；`--clear-database` 不能绕过身份授权。除 CI/CD 脚本内部受控用法外，人工排障不要使用 `spacetime --root-dir`。
 10. 当前脚本是单目录进程启动方案，不替代生产 systemd、Nginx、TLS、日志轮转与守护进程配置。
 11. 如只需要本地生成发布包，可传 `--skip-upload` 跳过默认 scp 上传。

--- a/docs/technical/SPACETIMEDB_CLOUD_CONFIG_REMOVAL_2026-05-02.md
+++ b/docs/technical/SPACETIMEDB_CLOUD_CONFIG_REMOVAL_2026-05-02.md
@@ -39,4 +39,4 @@ GENARRATIVE_SPACETIME_TOKEN

 1. 新增 SpacetimeDB 运维脚本时，不允许把云端服务写成默认值。
 2. 文档中的验证命令统一使用 `npm run api-server`。
-3. 如果某次任务需要连接非本地 SpacetimeDB，必须在文档和验证记录中写清楚实际 `SERVER_URL`、数据库名和 root-dir。
+3. 如果某次任务需要连接非本地 SpacetimeDB，必须在文档和验证记录中写清楚实际 `SERVER_URL`、数据库名和身份来源；除 CI/CD 脚本内部受控用法外，不再把 `--root-dir` 写入人工命令。
--- a/docs/technical/SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md
+++ b/docs/technical/SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md
@@ -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. 脚本诊断
--- a/docs/technical/SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md
+++ b/docs/technical/SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md
@@ -2,6 +2,8 @@

 日期：`2026-04-27`

+状态：历史事故记录。本文针对旧发布包 `start.sh` 的诊断补强，相关 `start.sh` 运行细节已过时，不再作为当前发布或人工排障依据。当前 SpacetimeDB 人工命令不得使用 `--root-dir`，CI/CD 脚本内部受控用法除外。
+
 ## 1. 问题

 执行发布包内 `start.sh` 时，可能只看到：
@@ -16,10 +18,10 @@
 ## 2. 常见根因

 1. `GENARRATIVE_SPACETIME_PORT` 对应端口已被其他进程占用。
-2. `.spacetimedb/` root-dir 权限不正确，当前用户无法写入数据、bin 或日志目录。
+2. `.spacetimedb/` 运行目录权限不正确，当前用户无法写入数据或日志目录。
 3. 目标机 `spacetime` 安装不完整，发布包同步不到可执行的 `bin/current/spacetimedb-cli`。
 4. 目标机上的 `spacetime` 版本与脚本启动参数不兼容。
-5. 旧 SpacetimeDB 进程仍持有同一 root-dir 或数据锁，但当前 `GENARRATIVE_SPACETIME_SERVER_URL` 指向的端口未就绪。
+5. 旧 SpacetimeDB 进程仍持有同一运行目录或数据锁，但当前 `GENARRATIVE_SPACETIME_SERVER_URL` 指向的端口未就绪。
 6. `.spacetimedb/bin/current/` 下只有 `spacetimedb-cli`，缺少 `spacetimedb-standalone`，日志会显示 `exec failed for .../spacetimedb-standalone`。

 ## 3. 落地修复
@@ -31,11 +33,11 @@
 3. 当 SpacetimeDB 进程提前退出或等待超时时，自动打印：
   - `GENARRATIVE_SPACETIME_SERVER_URL` 对应的目标地址。
   - `GENARRATIVE_SPACETIME_HOST:GENARRATIVE_SPACETIME_PORT` 对应的监听地址。
-   - 当前 `GENARRATIVE_SPACETIME_ROOT_DIR`。
+   - 当前 `.spacetimedb/` 运行目录。
   - `logs/spacetimedb.log` 最近 120 行。
   - `spacetime server ping` 的原始输出。
   - `ss` 或 `netstat` 中当前端口的监听情况。
-   - 同一 root-dir 下仍在运行的 SpacetimeDB 进程。
+   - 同一运行目录下仍在运行的 SpacetimeDB 进程。

 ## 4. 现场排查

@@ -43,7 +45,7 @@

 ```bash
 tail -n 120 logs/spacetimedb.log
-spacetime --root-dir ./.spacetimedb server ping "${GENARRATIVE_SPACETIME_SERVER_URL:-http://127.0.0.1:3101}"
+spacetime server ping "${GENARRATIVE_SPACETIME_SERVER_URL:-http://127.0.0.1:3101}"
 ss -ltnp | grep ':3101' || true
 ```

@@ -54,7 +56,7 @@ exec failed for /var/lib/jenkins/deploy/Genarrative/.spacetimedb/bin/current/spa
 No such file or directory (os error 2)
 ```

-说明发布目录的 SpacetimeDB root-dir 中同步了 CLI，但没有同步 standalone。现场可先执行：
+说明发布目录的 SpacetimeDB 运行目录中同步了 CLI，但没有同步 standalone。该段仅适用于仍保留 CI/CD 内部受控 `--root-dir` 的旧发布包；新人工排障不要引入 `--root-dir`。现场可先执行：

 ```bash
 cd /var/lib/jenkins/deploy/Genarrative
--- a/docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md
+++ b/docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md
@@ -1,7 +1,9 @@
-# start.sh 发布 SpacetimeDB 遇到 403 的处理方案
+# SpacetimeDB publish 遇到 403 的处理方案

 日期：`2026-04-26`

+状态：历史事故记录。本文涉及发布包 `start.sh` 的描述已过时，不再作为当前发布或排障入口。当前人工命令约束以 `AGENTS.md`、`.hermes/shared-memory/pitfalls.md` 和现行本地/生产技术文档为准；除 CI/CD 脚本内部受控用法外，不再使用 `spacetime --root-dir`。
+
 ## 1. 问题

 执行发布包内 `start.sh` 时，`spacetime publish` 可能在 `Checking for breaking changes...` 后失败：
@@ -23,42 +25,41 @@ SpacetimeDB 的数据库更新权限绑定到创建或被授权的身份。只
 3. `GENARRATIVE_SPACETIME_SERVER_URL` 指向其它 SpacetimeDB 服务，而当前 CLI 身份不是该数据库的所有者或授权成员。
 4. `.env.local` 中的 `GENARRATIVE_SPACETIME_DATABASE` 指向了另一个环境的数据库名或数据库 identity。

-## 3. 落地修复
+## 3. 当前处理口径

-发布包生成的 `start.sh` 使用发布目录下的 `.spacetimedb/` 作为 SpacetimeDB root：
+除 CI/CD 脚本内部受控用法外，人工命令、本地联调、临时排障和文档示例不再使用 `spacetime --root-dir`。后续处理遵循：

-```bash
-GENARRATIVE_SPACETIME_ROOT_DIR="${SCRIPT_DIR}/.spacetimedb"
-```
+1. 本地开发优先使用项目脚本 `npm run dev` / `npm run dev:rust`。
+2. 手工发布必须显式传 `--server` 或 `--server-url`，不依赖 CLI 默认 server。
+3. 身份问题通过同一 CLI 登录态、专用运行用户、显式 token 或 SpacetimeDB 侧授权处理。
+4. 本地数据隔离使用项目脚本维护的数据目录，必要时通过 `--data-dir` 启动 standalone；不要用 `--root-dir` 作为人工排障手段。

-启动、探活和发布统一使用：
-
-```bash
-spacetime --root-dir="${GENARRATIVE_SPACETIME_ROOT_DIR}" ...
-```
-
-`spacetime start` 不再额外设置 `--data-dir`，启动前会先执行 Ubuntu 专用 `sync_ubuntu_spacetime_install`，优先从 `/usr/.local/share/spacetime/bin/<version>/spacetimedb-cli` 或 `$HOME/.local/share/spacetime/bin/<version>/spacetimedb-cli` 同步到 `.spacetimedb/bin/current/spacetimedb-cli`；当前线上 `spacetime` 入口为 `/usr/local/bin/spacetime`。启动参数、探活和 root-dir 占用判定都使用同一个 `.spacetimedb/`。这样可以把发布包与部署机全局 `~/.spacetime` 隔离，避免后续人工 `spacetime login` 影响本地发布包。但如果旧 `.spacetimedb/` 已经由另一个身份创建，仍需要按第 4 节处理。
-
-本地 `npm run dev:rust` / `scripts/dev-rust-stack.sh` 也必须遵循同一条规则：`server ping`、`start` 和 `publish` 都显式使用 `server-rs/.spacetimedb/local` 作为 `--root-dir`。不要让发布命令回退到全局 CLI 登录态，否则会出现本地 root 已有目标库权限，但裸 `spacetime publish` 仍使用另一个身份发起预检查并返回 403。
+历史上曾用项目级 CLI root 隔离身份；该方案已废弃。CI/CD 脚本如因生产运行用户隔离仍保留内部受控用法，不得复制为人工命令模板。

 ## 4. 排查与处理

 先在执行 `start.sh` 的同一台机器、同一用户下确认身份：

-```bash
-spacetime --root-dir ./.spacetimedb login show
-spacetime --root-dir ./.spacetimedb list --server http://127.0.0.1:3101
-```
-
-本地开发栈排查时使用仓库本地 root：
-
 ```bash
 spacetime login show
-spacetime --root-dir server-rs/.spacetimedb/local login show
-spacetime --root-dir server-rs/.spacetimedb/local list --server http://127.0.0.1:3101
+spacetime server list
+spacetime list --server http://127.0.0.1:3101
 ```

-如果裸 `spacetime login show` 的身份与 `--root-dir server-rs/.spacetimedb/local login show` 不一致，而目标库只出现在本地 root 的 `list` 结果中，说明不能使用裸 `spacetime publish`。应通过 `npm run dev:rust` 或显式追加 `--root-dir=server-rs/.spacetimedb/local` 重新发布。
+本地开发栈排查时确认项目脚本记录的实际 server，再用同一个 server 验证：
+
+```powershell
+Get-Content -Encoding UTF8 server-rs/.spacetimedb/local/data/dev-rust-spacetime-url
+spacetime login show
+spacetime list --server http://127.0.0.1:3101
+```
+
+如果 `spacetime login show` 的身份无权更新目标库，不要尝试通过 `--root-dir` 绕过。应选择以下路径之一：
+
+1. 重新登录目标库 owner 或被授权的身份。
+2. 在 SpacetimeDB 侧给当前身份补授权。
+3. 如果只是本地开发库且数据可丢弃，按 4.1 重置本地库后重新发布。
+4. 如果是连错服务或库名，修正 `.env.local` 中的 `GENARRATIVE_SPACETIME_DATABASE` / `GENARRATIVE_SPACETIME_SERVER_URL`。

 ### 4.1 `npm run dev` 本地 401 / 403 快速恢复

@@ -91,7 +92,7 @@ spacetime login --server-issued-login local
 spacetime publish --server local A
 ```

-这条流程适合“本地 `npm run dev` 因旧 token、旧本地库或 CLI 默认 server 混乱导致无法继续”的场景。若当前目标库需要保留数据，不要执行 `spacetime server clear -y`，先按上一段对比 `login show`、`--root-dir` 和数据库所有者身份。
+这条流程适合“本地 `npm run dev` 因旧 token、旧本地库或 CLI 默认 server 混乱导致无法继续”的场景。若当前目标库需要保留数据，不要执行 `spacetime server clear -y`，先确认 `login show`、目标 server、数据库名和数据库所有者身份。

 如果目标是本地部署库，且允许清空本地数据：

@@ -105,7 +106,7 @@ mv .spacetimedb ".spacetimedb.backup.$(date +%Y%m%d-%H%M%S)"

 1. 不要删除 `.spacetimedb/`。
 2. 找到创建该数据库的 SpacetimeDB 身份。
-3. 用该身份对应的 CLI root 执行发布，或在 SpacetimeDB 侧补授权后再发布。
+3. 用该身份登录当前 CLI，或在 SpacetimeDB 侧补授权后再发布。

 如果目标是其它 SpacetimeDB 服务：

@@ -116,5 +117,6 @@ mv .spacetimedb ".spacetimedb.backup.$(date +%Y%m%d-%H%M%S)"
 ## 5. 约束

 1. `--clear-database` 只处理 schema 冲突时的数据清理，不会绕过 SpacetimeDB 身份授权。
-2. 不要通过切回旧 `server-node` 或 PostgreSQL 绕过发布错误。
-3. 前端与 `api-server` 的数据库名必须和 `start.sh` 发布的库名一致，否则后续接口会连到未发布或无权限的库。
+2. 除 CI/CD 脚本内部受控用法外，不要在人工排障或文档示例中使用 `spacetime --root-dir`。
+3. 不要通过切回旧 `server-node` 或 PostgreSQL 绕过发布错误。
+4. 前端与 `api-server` 的数据库名必须和 `start.sh` 发布的库名一致，否则后续接口会连到未发布或无权限的库。
--- a/docs/technical/SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md
+++ b/docs/technical/SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md
@@ -2,6 +2,8 @@

 日期：`2026-04-27`

+状态：历史事故记录。本文只解释旧发布包 `start.sh` 的一次误报修复，相关 `root-dir` 检测不再作为当前发布或人工排障口径。当前人工命令不得使用 `spacetime --root-dir`，CI/CD 脚本内部受控用法除外。
+
 ## 1. 问题

 执行发布包内 `start.sh` 时，可能出现：