docs: clarify standalone deployment contracts

content/cn/docs/clients/restful-api/gremlin.md

@@ -67,7 +67,9 @@ curl --compressed -sS -X POST http://127.0.0.1:8080/gremlin \
 
 绑定名区分大小写：`<space>-<graph>` 是图，`__g_<space>-<graph>` 是遍历源。多图 Server 没有隐含的全局 `g`。
 `bindings` 用于查询变量，不能注册图；alias 目标也不能写成 `graph.traversal()` 表达式。
-没有 GraphSpace 的旧版独立图使用 `<graph>` 与 `__g_<graph>`。Server 启用鉴权时，补充配置要求的 HTTP 凭据，例如 `-u "$HG_USER:$HG_PASSWORD"`。
+Server 1.8 的单机 RocksDB 模式同样使用 `DEFAULT-hugegraph` 与 `__g_DEFAULT-hugegraph`；禁用 PD 不会改用旧别名。
+只有没有 GraphSpace 绑定的旧版 Server 才使用 `<graph>` 与 `__g_<graph>`。
+Server 启用鉴权时，补充配置要求的 HTTP 凭据，例如 `-u "$HG_USER:$HG_PASSWORD"`。
 
 同步 Gremlin 默认执行上限为 30000 毫秒，由 `gremlin-server.yaml` 的 `evaluationTimeout` 配置。
 全图计数与按标签过滤计数可能走不同执行路径，不能用 `g.V().count()` 的耗时推断标签扫描耗时。

content/cn/docs/clients/restful-api/traverser.md

@@ -2651,6 +2651,39 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/traversers/vertic
 - page：分页位置，选填项，默认为 null，不分页；当 page 为“”时表示分页的第一页，从 start 指示的位置开始
 - page_limit：分页获取顶点时，一页中顶点数目的上限，选填项，默认为 100000
 
+包含扫描参数校验修复的构建在所有后端都要求 `start` 与 `end`，缺少任意一项返回 HTTP 400。
+这也改变了旧版 HStore 与内存后端将缺参按零处理、可能返回不完整数据的行为。
+只有 RocksDB 与 HBase 将空字符串视为开放边界；HStore 与内存后端没有相同语义。
+
+下面的 **RocksDB** 示例通过显式 `page=` 请求有界分页的第一页：
+
+```bash
+curl -fsS -G \
+  'http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/traversers/vertices/scan' \
+  --data-urlencode 'start=' \
+  --data-urlencode 'end=' \
+  --data-urlencode 'page=' \
+  --data-urlencode 'page_limit=1000'
+```
+
+HStore 与内存后端应遍历 `vertices/shards` 返回的每个区间，使用原始 `start`、`end`，并为每个分片重新传入 `page=`。
+空 HStore 区间可能只扫描哈希零所属的分区；空的内存后端结束边界可能不返回任何数据。
+一个分页序列结束只代表该分片完成，还须继续导出其余返回的分片。
+边界编码依赖后端，不能将 RocksDB 返回的编码位置转换成下文的数值示例。
+后续请求保持同一组边界，并使用 `--data-urlencode` 传入响应的 `page` 游标。
+响应的 `page` 为 null 或空时结束；末页的元素数量可能少于 `page_limit`。
+
+| RocksDB 请求 | 行为 |
+| --- | --- |
+| `start=&end=&page=&page_limit=1000` | 第一页，最多 1000 个顶点 |
+| 相同边界并传入响应的 `page` | 同一分片的下一页 |
+| `start=&end=&page_limit=1000`，省略 `page` | 不分页，`page_limit` 不限制该响应 |
+| 缺少 `start` 或 `end` | 无效请求，不能省略参数来表示无界 |
+
+为兼容已有调用方，不分页形式仍然保留。
+导出程序应显式启用分页，避免一次读取整个大分片。
+`edges/scan` 使用相同规则；启用鉴权时需补充配置要求的 HTTP 凭据。
+
 ###### Method & Url
 
 ```text
@@ -2947,6 +2980,12 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/traversers/edges/
 - page：分页位置，选填项，默认为 null，不分页；当 page 为“”时表示分页的第一页，从 start 指示的位置开始
 - page_limit：分页获取边时，一页中边数目的上限，选填项，默认为 100000
 
+边扫描在所有后端都要求两个边界，只有 RocksDB 与 HBase 将空值视为开放边界。
+有界分页的第一页传入 `page=`，后续游标需要 URL 编码，并保持边界不变。
+省略 `page` 时不分页，`page_limit` 不限制结果数量。
+边界应取自 `edges/shards`，不能复用顶点分片的位置。
+HStore 与内存后端应逐个导出全部边分片，不能以空边界代替全图扫描。
+
 ###### Method & Url
 
 ```text

content/cn/docs/guides/dev-test/toplingdb.md

@@ -44,7 +44,17 @@ bash bin/prepare-topling.sh
 
 脚本校验复制后的 JAR 哈希、Topling Java 标识、唯一的 Linux x86_64 JNI 条目、ELF 架构及 native 依赖。
 安装前还会用所选 JNI 打开临时数据库，确认 EasyMigrate 配置实际改变了持久化的写缓冲区大小；类标识和哈希匹配但不支持该配置入口的构建会被拒绝。
-此探针不代表已有数据兼容性或所有生产配置均已验证。校验记录绑定已测试的 JAR 和 native 库，启动时拒绝缺失或失效的记录；从旧准备脚本升级时请重新准备一份新发行包。
+包含配置验证修复的构建还会在发布运行时前，以 native 导入检查实际配置。
+设置 `TOPLINGDB_EASY_MIGRATE_CONF` 时探测指定文件，否则使用组件的 `conf/toplingdb.yaml`。
+缺少插件会在准备阶段失败，避免准备成功后才在 Server 初始化阶段崩溃。
+此导入不会按生产 WAL 或日志路径打开数据库。
+若显式指定配置，启动组件时也要保留相同的环境变量。
+准备与运行时选择都会在启动器切换目录前，按调用方工作目录将相对路径转为绝对路径。
+两个步骤应使用同一文件，服务配置优先采用绝对路径以免歧义。
+导入检查针对准备时的实际文件；之后更换文件仍可能引入不支持的插件。
+重启组件前，应使用所选 JNI 验证替换后的配置。
+这些探针不代表已有数据兼容性或所有生产列族均已验证。
+校验记录绑定已测试的 JAR 和 native 库，启动时拒绝缺失或失效的记录；从旧准备脚本升级时请重新准备一份新发行包。
 默认/标准模式启动时会拒绝继承的 RocksDB JNI 预载库，Topling 模式则拒绝与所选 JNI 竞争的预载库；其他预载库继续保留。
 它将 `topling/rocksdbjni.jar`、对应 native 库和可选网页资源放在 `lib` 之外。已有 `topling` 目录时会拒绝准备；更换运行时请使用另一份已停止的新发行包。
 按实际部署需要，为 Server、PD 和 Store 分别执行准备步骤。
@@ -98,6 +108,40 @@ export TOPLINGDB_ROCKSDB_PROVIDER=topling
 发行包中的 native 配置关闭 HTTP 服务，并保留 Java 写入路径要求的 `memtable_as_log_index=false`。
 请按机器条件调整该文件；它与业务 provider、数据目录配置分别生效。
 
+自 Server 1.8.0+（master）起，发行包中的 `conf/toplingdb.yaml` 默认预设基于社区通用 JNI 的 SkipList 内存表与 BlockBasedTable 文件配置，不再依赖 CSPP、CSPPMemTabTable 或 DispatcherTable 插件。
+而现有及历史正式发行版本（如 1.7.0）附带的 `conf/toplingdb.yaml` 仍默认配置 `cspp` 内存表与 `DispatcherTable`。
+在旧版本上使用缺少 CSPP 插件的社区版 JNI 创建**全新空数据库**时，可将 `conf/toplingdb.yaml` 调整为 SkipList 和 BlockBasedTable，以防止初始化失败。
+
+缓存与写缓冲区参数是单项 native 预算；实际内存还随数据库和列族数量增长。
+请检查部署包中的实际配置。自定义 native 配置需要所选 JNI 提供对应插件。
+更改默认配置不会转换已有 SST 文件；其他表格式写入的数据仍需要兼容的 reader。
+
+升级已有 CSPP 部署前，先停止组件并保留匹配的 JNI、之前调优的配置与可恢复的数据备份。
+包含兼容配置修复的 Server、PD、Store 发行包会提供 `conf/toplingdb-legacy-cspp.yaml`，完整保留旧配置。
+准备和启动时，通过绝对路径 `TOPLINGDB_EASY_MIGRATE_CONF` 选择该文件或部署原有的配置。
+用于验证的社区 JNI 缺少 CSPP reader；旧 CSPP SST 的兼容性仍需要匹配 JNI 与真实旧格式数据验证。
+不能用社区配置替换已有 CSPP 部署的 native 设置。
+
+新默认值还调整了资源参数：缓存 8 GiB → 64 MiB、写缓冲 128 MiB → 16 MiB、最多缓冲数 6 → 3、后台任务 8 → 2。
+部分原有压缩整理调优也已移除。这些变化可能影响性能，不是透明的格式迁移。
+实测社区 JNI 中，Java 先设置 128 MiB 与六个缓冲，EasyMigrate 在打开数据库时实际应用 16 MiB、三个缓冲及 64 MiB 缓存。
+其他 JNI 构建应检查持久化 OPTIONS 与 `rocksdb.block-cache-capacity`，不能仅凭打开前的 Java getter 判断最终 native 值。
+
+标准 Server 容器包含 Java 17 JDK；包含准备工具修复的构建还提供 `unzip`。
+该镜像不捆绑或下载可选 JNI，制品的 glibc、libaio 与 CPU 要求仍须匹配基础镜像或宿主机。
+单机与 HStore 镜像的区别见 [Server 部署指南](/cn/docs/quickstart/hugegraph/hugegraph-server/)。
+
+Linux 上可在启动后检查单机 Server 实际映射的 JNI：
+
+```bash
+# 在 Server 发行包目录中，以服务账号执行。
+server_pid=$(cat bin/pid)
+grep -F 'topling/librocksdbjni-linux64.so' "/proc/$server_pid/maps"
+```
+
+API 请求成功本身不能证明选择了 Topling。
+应同时检查实际映射库与真实图写入、读取结果；这些运行态检查与 Helm 变体渲染测试分别验收。
+
 独立 Server 使用全新图时，首次启动前先初始化一次存储：
 
 ```bash

content/cn/docs/quickstart/hugegraph/hugegraph-server.md

@@ -113,12 +113,33 @@ serializer:
 
 完整容器部署指引请参考 [Docker 部署方式](https://github.com/apache/hugegraph/blob/master/docker/README.md)。
 
+使用 Server 构建时，应先区分制品与存储拓扑：
+
+| 制品 | 存储与依赖 |
+| --- | --- |
+| `hugegraph/hugegraph:<tag>` | 单机 RocksDB，不需要 PD 或 Store |
+| 标准二进制发行包 | 默认 `backend=rocksdb`、`serializer=binary`，`pd.peers` 已注释 |
+| `hugegraph/server:<tag>` | 默认 HStore，需要 PD 与 Store |
+| 当前 Helm `values-single.yaml` | 1 PD + 1 Store + 1 Server，仍为 HStore |
+
+Helm 的单节点预设不是单机 RocksDB 预设。
+Vermeer 与 SeaTunnel 的 `standalone` 设置也独立于 Server 后端，不会切换 Server 存储。
+
 快速启动使用 `RocksDB` 单机后端的 Server 容器：
 
 ```bash {tab="快速启动 (默认)"}
 docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph:1.7.0
 ```
 
+```bash {tab="使用命名持久化卷"}
+# 使用命名数据卷持久化 RocksDB 数据 (挂载至 /hugegraph-server/rocksdb-data)
+docker volume create hugegraph-rocksdb
+docker run -d --name=server -p 8080:8080 \
+  -e PASSWORD="replace-with-your-password" \
+  -v hugegraph-rocksdb:/hugegraph-server/rocksdb-data \
+  hugegraph/hugegraph:1.7.0
+```
+
 ```bash {tab="附带内置样例图"}
 # 启动时自动预加载内置样例图（marko / lop 等数据）
 docker run -itd --name=server -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0
@@ -135,6 +156,66 @@ docker run -itd --name=server -p 8080:8080 -e PASSWORD="replace-with-your-passwo
 - **验证服务可用性**：`curl -fsS http://127.0.0.1:8080/versions`
 {.td-cards-list}
 
+为保证可复现，应固定经过验证的 release tag；`latest` 会变动，发布镜像也可能尚未包含源码修复。
+命名卷持久化默认 RocksDB 路径，挂到 `/hugegraph-server/data` 不会保存该数据库。
+`PASSWORD` 在首次启动时初始化鉴权；更改环境变量不会轮换已有用户的密码。
+若要在全新空数据安装中复用 HStore 镜像，需显式设置 `HG_SERVER_BACKEND=rocksdb` 与 `HG_SERVER_USE_PD=false`。
+应使用包含本地后端等待逻辑与数据目录归属修复的镜像：它忽略残留 `pd.peers`，并以 10001:10001 预建 `rocksdb-data`，供新命名卷继承。
+旧 HStore 镜像仍需修正可写图配置，并设置正确的数据目录归属。
+不要以此切换已有 HStore 部署的后端，也不要复用其初始化标记。
+
+自定义配置 bind mount 必须允许 UID/GID 10001 写入。
+应挂载整个可写配置目录；entrypoint 使用原子替换，不能更新单文件 bind mount。
+优先使用命名数据卷，不要递归放宽宿主机目录权限。
+
+解压标准二进制发行包后，使用 Java 17 并确认图的 RocksDB 配置，再初始化和启动：
+
+```bash
+java -version
+# 在全新 Server 发行包目录内执行
+bin/init-store.sh
+bin/start-hugegraph.sh
+```
+
+若全新二进制部署需要鉴权，先在 `conf/rest-server.properties` 配置 `auth.admin_pa`，
+运行 `bin/enable-auth.sh`，再通过 stdin 向 `bin/init-store.sh` 提供同一密码。
+二进制初始化器不读取容器 entrypoint 的 `PASSWORD` 环境变量；含凭据的配置文件应限制访问权限。
+Java 11 无法运行 Server 1.8 字节码。
+
+启动后检查 `/versions`、读取 `/graphspaces/DEFAULT/graphs`，并发送真实 Gremlin 请求。
+Server 1.8 单机遍历源为 `__g_DEFAULT-hugegraph`，禁用 PD 不会恢复旧别名。
+GraphSpace 管理本身需要 PD，本地图列表仍可查询。
+可执行请求与鉴权选项见 [Gremlin API](/cn/docs/clients/restful-api/gremlin/)。
+
+对上述启用鉴权的容器，同时检查 REST 图与遍历源：
+
+```bash
+curl -fsS http://localhost:8080/versions
+curl -fsS -u 'admin:replace-with-your-password' \
+  http://localhost:8080/graphspaces/DEFAULT/graphs
+curl -fsS -u 'admin:replace-with-your-password' \
+  -H 'Content-Type: application/json' \
+  -d '{"gremlin":"g.V().count()","aliases":{"g":"__g_DEFAULT-hugegraph"}}' \
+  http://localhost:8080/gremlin
+```
+
+只有部署未启用鉴权时才省略凭据。
+版本端点正常不代表已验证图已加载或当前凭据具有图访问权限。
+
+| 现象 | 检查项 |
+| --- | --- |
+| 启动等待 PD/Store | 确认镜像与实际图后端，HStore 镜像会等待分布式存储 |
+| 更新属性时报 `Permission denied` | 配置目录须允许镜像的数字服务 UID/GID 写入 |
+| 更新属性时报 `Device or resource busy` | 将单文件配置 bind mount 改为可写目录挂载 |
+| 更换容器后数据消失 | 持久化 `rocksdb-data`，挂载 `data` 不覆盖默认数据库 |
+| `UnsupportedClassVersionError` | 确认二进制发行包使用 Java 17 启动 |
+| 单机 Gremlin 报 `Could not rebind` | 使用 Server 1.8 实际注册的 GraphSpace 别名 |
+
+停止或移除容器不会删除命名数据卷，重启时应保留并复用该卷。
+显式移除数据卷会删除本地图数据。
+更改 `PASSWORD` 或重建镜像不能替代数据迁移或凭据恢复。
+
+
 如果使用 Docker Desktop，则可以按如下方式设置相关选项：
 <div style="text-align: center;">
     <img src="/docs/images/images-server/31docker-option.jpg" alt="Docker Desktop 中 HugeGraph 容器的运行设置" style="width:33%;">

content/en/docs/clients/restful-api/gremlin.md

@@ -68,7 +68,8 @@ curl --compressed -sS -X POST http://127.0.0.1:8080/gremlin \
 Bindings are case-sensitive: `<space>-<graph>` selects the graph and `__g_<space>-<graph>` selects its traversal source.
 There is no implicit global `g` on a multi-graph Server. `bindings` supplies query variables;
 it does not register graphs, and an alias target cannot be the expression `graph.traversal()`.
-For a legacy standalone graph without a GraphSpace, the bindings are `<graph>` and `__g_<graph>`.
+Server 1.8 uses GraphSpace-scoped bindings in standalone RocksDB mode too: `DEFAULT-hugegraph` and `__g_DEFAULT-hugegraph`.
+Disabling PD does not select legacy aliases. Only older Servers without GraphSpace bindings use `<graph>` and `__g_<graph>`.
 For an authenticated Server, add its configured HTTP credentials, for example `-u "$HG_USER:$HG_PASSWORD"`.
 
 The default synchronous Gremlin evaluation timeout is 30000 milliseconds, configured by `evaluationTimeout` in `gremlin-server.yaml`.

content/en/docs/clients/restful-api/traverser.md

@@ -2658,6 +2658,38 @@ Retrieve vertices in batches based on the specified shard information (refer to
 - page: Page position for pagination, optional. Default is null, no pagination. When page is "", it represents the first page of pagination starting from the position indicated by start.
 - page_limit: The upper limit of the number of vertices per page when retrieving vertices with pagination, optional. Default is 100000.
 
+`start` and `end` must be present on every backend in builds containing the scan validation fix; missing either returns HTTP 400.
+This also changes older HStore and in-memory requests that treated missing bounds as zero and could return incomplete data.
+Empty strings represent open bounds only in RocksDB and HBase, not in HStore or in-memory scans.
+
+The following **RocksDB** example requests the first bounded page with explicit `page=`:
+
+```bash
+curl -fsS -G \
+  'http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/traversers/vertices/scan' \
+  --data-urlencode 'start=' \
+  --data-urlencode 'end=' \
+  --data-urlencode 'page=' \
+  --data-urlencode 'page_limit=1000'
+```
+
+For HStore and in-memory exports, iterate every range returned by `vertices/shards`, using its exact `start` and `end` and a fresh `page=`.
+An empty HStore range can stop after the partition containing hash zero; an empty in-memory end can produce no results.
+Finishing a page sequence completes that shard only; continue until every returned shard has been exported.
+Their encoding depends on the backend; do not convert RocksDB's encoded positions to the numeric examples below.
+Keep the same bounds on every continuation request and pass the returned `page` value through `--data-urlencode`.
+Stop when the response's `page` is null or empty, even if the final page contains fewer elements than `page_limit`.
+
+| RocksDB request | Behavior |
+| --- | --- |
+| `start=&end=&page=&page_limit=1000` | First page, at most 1000 vertices |
+| Same bounds and returned `page` token | Next page of the same shard |
+| `start=&end=&page_limit=1000` without `page` | Unpaged scan; `page_limit` does not bound the response |
+| Missing `start` or `end` | Invalid request; neither is an implicit open bound |
+
+The unpaged form remains supported for existing callers. Exporters should explicitly request paging to avoid materializing an entire large shard.
+The same rules apply to `edges/scan`. For authenticated Servers, supply the configured HTTP credentials.
+
 ###### Method & Url
 
 ```text
@@ -2954,6 +2986,12 @@ Batch retrieve edges by specifying shard information (refer to section 3.2.22.2
 - page: Page position for pagination, optional field. Default is null, which means no pagination. When `page` is empty, it indicates the first page of pagination starting from the position indicated by `start`.
 - page_limit: Upper limit of the number of edges per page for paginated retrieval, optional field. Default is 100000.
 
+As with vertex scans, both bounds are required on every backend; only RocksDB and HBase treat empty values as open bounds.
+Send `page=` for the first bounded page and URL-encode each returned continuation token, keeping the bounds unchanged.
+Omitting `page` selects an unpaged scan and ignores `page_limit`.
+Use boundaries from `edges/shards`; do not reuse vertex shard positions for edges.
+For HStore and in-memory exports, iterate every returned edge shard independently rather than using empty bounds for a whole-graph scan.
+
 ###### Method & Url
 
 ```text