docs: clarify SpacetimeDB root-dir usage

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