docs: clarify SpacetimeDB root-dir usage

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 上传。