From 9348fc4c070c92f5e8c69bd6ca10f064f9542ddc Mon Sep 17 00:00:00 2001 From: orion Date: Sun, 1 Nov 2026 17:01:58 +0000 Subject: [PATCH 1/3] docs: clarify standalone deployment contracts and ToplingDB boundary - Distinguish standalone RocksDB artifacts from HStore and Helm single-node presets. - Document required scan bounds and explicit pagination without changing the unpaged contract. - Correct standalone Gremlin aliases and GraphSpace-scoped traversal sources. - Clarify ToplingDB community SkipList/BlockBasedTable profile version boundary (Server 1.8.0+ / #3447 vs legacy cspp memtable). --- .../cn/docs/clients/restful-api/gremlin.md | 4 +- .../cn/docs/clients/restful-api/traverser.md | 36 +++++++++ content/cn/docs/guides/dev-test/toplingdb.md | 33 +++++++- .../quickstart/hugegraph/hugegraph-server.md | 79 +++++++++++++++++++ .../en/docs/clients/restful-api/gremlin.md | 3 +- .../en/docs/clients/restful-api/traverser.md | 35 ++++++++ content/en/docs/guides/dev-test/toplingdb.md | 34 +++++++- .../quickstart/hugegraph/hugegraph-server.md | 79 +++++++++++++++++++ 8 files changed, 299 insertions(+), 4 deletions(-) diff --git a/content/cn/docs/clients/restful-api/gremlin.md b/content/cn/docs/clients/restful-api/gremlin.md index 961cbd339..88ce34a76 100644 --- a/content/cn/docs/clients/restful-api/gremlin.md +++ b/content/cn/docs/clients/restful-api/gremlin.md @@ -67,7 +67,9 @@ curl --compressed -sS -X POST http://127.0.0.1:8080/gremlin \ 绑定名区分大小写：`-` 是图，`__g_-` 是遍历源。多图 Server 没有隐含的全局 `g`。 `bindings` 用于查询变量，不能注册图；alias 目标也不能写成 `graph.traversal()` 表达式。 -没有 GraphSpace 的旧版独立图使用 `` 与 `__g_`。Server 启用鉴权时，补充配置要求的 HTTP 凭据，例如 `-u "$HG_USER:$HG_PASSWORD"`。 +Server 1.8 的单机 RocksDB 模式同样使用 `DEFAULT-hugegraph` 与 `__g_DEFAULT-hugegraph`；禁用 PD 不会改用旧别名。 +只有没有 GraphSpace 绑定的旧版 Server 才使用 `` 与 `__g_`。 +Server 启用鉴权时，补充配置要求的 HTTP 凭据，例如 `-u "$HG_USER:$HG_PASSWORD"`。 同步 Gremlin 默认执行上限为 30000 毫秒，由 `gremlin-server.yaml` 的 `evaluationTimeout` 配置。 全图计数与按标签过滤计数可能走不同执行路径，不能用 `g.V().count()` 的耗时推断标签扫描耗时。 diff --git a/content/cn/docs/clients/restful-api/traverser.md b/content/cn/docs/clients/restful-api/traverser.md index 7e8a380ef..45eec6644 100644 --- a/content/cn/docs/clients/restful-api/traverser.md +++ b/content/cn/docs/clients/restful-api/traverser.md @@ -2651,6 +2651,37 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/traversers/vertic - page：分页位置，选填项，默认为 null，不分页；当 page 为“”时表示分页的第一页，从 start 指示的位置开始 - page_limit：分页获取顶点时，一页中顶点数目的上限，选填项，默认为 100000 +`start` 与 `end` 都必须出现，即使需要无界扫描，也应传入显式空值。 +包含扫描参数校验修复的构建在缺参时返回 HTTP 400；旧构建可能返回 HTTP 500。 +调用方升级后仍应保留两个参数，缺参不表示无界。 + +有界分页导出需要显式传入初始空 `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' +``` + +逐分片导出时，应以 `vertices/shards` 返回的原始 `start` 与 `end` 替换空边界。 +边界编码依赖后端，不能将 RocksDB 返回的编码位置转换成下文的数值示例。 +后续请求保持同一组边界，并使用 `--data-urlencode` 传入响应的 `page` 游标。 +响应的 `page` 为 null 或空时结束；末页的元素数量可能少于 `page_limit`。 + +| 请求 | 行为 | +| --- | --- | +| `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 +2978,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/traversers/edges/ - page：分页位置，选填项，默认为 null，不分页；当 page 为“”时表示分页的第一页，从 start 指示的位置开始 - page_limit：分页获取边时，一页中边数目的上限，选填项，默认为 100000 +边扫描同样要求两个边界，无界时传入显式空值。 +有界分页的第一页传入 `page=`，后续游标需要 URL 编码，并保持边界不变。 +省略 `page` 时不分页，`page_limit` 不限制结果数量。 +边界应取自 `edges/shards`，不能复用顶点分片的位置。 + ###### Method & Url ```text diff --git a/content/cn/docs/guides/dev-test/toplingdb.md b/content/cn/docs/guides/dev-test/toplingdb.md index 44f8abfdf..14ae70312 100644 --- a/content/cn/docs/guides/dev-test/toplingdb.md +++ b/content/cn/docs/guides/dev-test/toplingdb.md @@ -44,7 +44,15 @@ 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 +106,29 @@ export TOPLINGDB_ROCKSDB_PROVIDER=topling 发行包中的 native 配置关闭 HTTP 服务，并保留 Java 写入路径要求的 `memtable_as_log_index=false`。 请按机器条件调整该文件；它与业务 provider、数据目录配置分别生效。 +自 Server 1.8.0+（`apache/hugegraph#3447` / 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。 + +标准 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 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 0b54c746b..11f9c04c3 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/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:` | 单机 RocksDB，不需要 PD 或 Store | +| 标准二进制发行包 | 默认 `backend=rocksdb`、`serializer=binary`，`pd.peers` 已注释 | +| `hugegraph/server:` | 默认 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,64 @@ 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`。 +不要以此切换已有 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，则可以按如下方式设置相关选项：
Docker Desktop 中 HugeGraph 容器的运行设置 diff --git a/content/en/docs/clients/restful-api/gremlin.md b/content/en/docs/clients/restful-api/gremlin.md index 0bd868be6..79a6cfad1 100644 --- a/content/en/docs/clients/restful-api/gremlin.md +++ b/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: `-` selects the graph and `__g_-` 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 `` and `__g_`. +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 `` and `__g_`. 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`. diff --git a/content/en/docs/clients/restful-api/traverser.md b/content/en/docs/clients/restful-api/traverser.md index dce444cad..5050f2870 100644 --- a/content/en/docs/clients/restful-api/traverser.md +++ b/content/en/docs/clients/restful-api/traverser.md @@ -2658,6 +2658,36 @@ 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, including for an open-ended scan. +An empty value is valid; a missing parameter returns HTTP 400 in builds containing the scan validation fix. +Older builds can return HTTP 500 instead. Keep both parameters when upgrading a caller. + +For a bounded export, send an explicit empty initial `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 separate shards, use the exact `start` and `end` returned by `vertices/shards` instead of empty bounds. +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`. + +| 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 +2984,11 @@ 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; use explicit empty values for 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. + ###### Method & Url ```text diff --git a/content/en/docs/guides/dev-test/toplingdb.md b/content/en/docs/guides/dev-test/toplingdb.md index 993b0a2ab..e0474e68e 100644 --- a/content/en/docs/guides/dev-test/toplingdb.md +++ b/content/en/docs/guides/dev-test/toplingdb.md @@ -44,7 +44,15 @@ bash bin/prepare-topling.sh The script verifies the copied JAR's hash, Topling Java marker, one Linux x86_64 JNI entry, ELF architecture and native dependencies. Before installation, a disposable database verifies that the selected JNI actually applies EasyMigrate configuration to its persisted write-buffer size. -Unsupported builds are rejected even when their marker and hash match. The probe does not certify existing-data compatibility or every production setting. +Unsupported builds are rejected even when their marker and hash match. +In builds containing the profile validation fix, a second native import validates the actual configuration before publishing the runtime. +It uses `TOPLINGDB_EASY_MIGRATE_CONF` when set, otherwise the component's `conf/toplingdb.yaml`. +Missing plugins fail preparation instead of leaving a runtime that fails during Server initialization. +This import does not open databases using production WAL or log paths. +Keep an explicit configuration override in the service environment when starting the component too. +The import validates the file present during preparation. Replacing that file later can introduce unsupported plugins; +validate the replacement with the selected JNI before restarting the component. +These probes do not certify existing-data compatibility or every production column family. A checksum receipt binds this verification to the installed JAR and native library; launchers reject missing or changed receipts. Use a fresh distribution when upgrading from an older preparation script. Launch rejects inherited RocksDB JNI preloads in default/standard mode and competing JNI in Topling mode, while preserving unrelated preloads. @@ -104,6 +112,30 @@ The launcher uses that component's `conf/toplingdb.yaml`. Set `TOPLINGDB_EASY_MI The shipped native profile disables its HTTP server and keeps `memtable_as_log_index=false`, which the Java write path requires. Tune that profile for the host; it is separate from the business provider and data-path configuration. +Starting with Server 1.8.0+ (`apache/hugegraph#3447` / master), distributions ship a community-native profile in `conf/toplingdb.yaml` +using standard SkipList memtables and BlockBasedTable files by default, which does not require CSPP, CSPPMemTabTable, or DispatcherTable plugins. +In contrast, existing and earlier release builds (such as 1.7.0) ship `conf/toplingdb.yaml` configured with the `cspp` memtable and `DispatcherTable`. +When using community JNI without CSPP plugins on earlier builds, adjust `conf/toplingdb.yaml` to use SkipList and BlockBasedTable to avoid initialization failures. + +The cache and write-buffer values are individual native budgets; memory also grows with the number of databases and column families. +Inspect the actual profile in the distribution you deploy. Custom native profiles must name plugins supplied by the selected JNI. +Changing the default profile does not convert existing SST files; data written with another table format still needs its compatible reader. + +The standard Server container includes a Java 17 JDK; builds containing the preparation-tool fix also include `unzip`. +It does not bundle or download optional JNI. The artifact's glibc, libaio and CPU requirements must match the base image or deployment host. +Use the [Server deployment guide](/docs/quickstart/hugegraph/hugegraph-server/) to distinguish the standalone and HStore images. + +On Linux, verify the running standalone Server's mapped JNI after startup: + +```bash +# Run in the Server distribution, as the service account. +server_pid=$(cat bin/pid) +grep -F 'topling/librocksdbjni-linux64.so' "/proc/$server_pid/maps" +``` + +A successful API response alone does not establish that Topling was selected. +Check the mapped library and a real graph write/read together; keep these checks separate from a Helm runtime-variant render test. + For a fresh standalone Server graph, initialize its store once before the first startup: ```bash diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index c52ec8b3a..d5af568a9 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -120,12 +120,33 @@ There are four ways to deploy the Server service: For complete container setup instructions, refer to the [Docker deployment guide](https://github.com/apache/hugegraph/blob/master/docker/README.md). +For Server builds, select the appropriate artifact and storage topology: + +| Artifact | Storage and dependencies | +| --- | --- | +| `hugegraph/hugegraph:` | Standalone RocksDB; no PD or Store required | +| Standard binary distribution | Ships `backend=rocksdb`, `serializer=binary`; `pd.peers` is commented out | +| `hugegraph/server:` | HStore defaults; requires PD and Store | +| Helm `values-single.yaml` | 1 PD + 1 Store + 1 Server; still HStore | + +Helm's single-node preset is not a standalone RocksDB preset. +Vermeer and SeaTunnel have independent `standalone` settings that do not change the Server backend. + Run a standalone Server container with the RocksDB backend: ```bash {tab="Quick Start (Default)"} docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph:1.7.0 ``` +```bash {tab="With Persistent Volume"} +# Persist RocksDB data using a named volume (mounted to /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="With Sample Graph"} # Preload the built-in sample graph at startup docker run -itd --name=server -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0 @@ -142,6 +163,64 @@ Common container inspection operations: - **Verify service health**: `curl -fsS http://127.0.0.1:8080/versions` {.td-cards-list} +Pin a tested release tag for reproducibility; mutable tags such as `latest` may lag source fixes. +The named volume persists the default RocksDB path. Mounting `/hugegraph-server/data` does not persist that database. +Authentication is initialized from `PASSWORD` on first startup; changing this variable does not rotate an existing user's password. +To reuse the HStore image for a new empty standalone installation, explicitly set both `HG_SERVER_BACKEND=rocksdb` and `HG_SERVER_USE_PD=false`. +Do not switch an existing HStore installation's backend or reuse its initialization marker this way. + +Custom configuration bind mounts must be writable by UID/GID 10001. +Mount the whole writable configuration directory: the entrypoint's atomic file replacement cannot update a single-file bind mount. +Prefer named data volumes rather than recursively changing host-directory permissions. + +For an unpacked standard binary distribution, use Java 17, confirm the graph's RocksDB settings, then initialize and start it: + +```bash +java -version +# Run inside the fresh Server distribution directory +bin/init-store.sh +bin/start-hugegraph.sh +``` + +For authentication on a fresh binary distribution, first configure `auth.admin_pa` in `conf/rest-server.properties`, +run `bin/enable-auth.sh`, and provide the same password on stdin to `bin/init-store.sh`. +The binary initializer does not read the container entrypoint's `PASSWORD` variable. Restrict access to credential-bearing configuration files. +Java 11 cannot execute Server 1.8 bytecode. + +Check `/versions`, list `/graphspaces/DEFAULT/graphs`, and send a real Gremlin request after startup. +Standalone Server 1.8 uses the traversal source `__g_DEFAULT-hugegraph`; disabling PD does not restore legacy graph aliases. +GraphSpace management itself requires PD; local graph listing remains available. +See the [Gremlin API](/docs/clients/restful-api/gremlin/) for a runnable request and authentication options. + +For the authenticated container above, verify both the REST graph and its traversal source: + +```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 +``` + +Omit credentials only when the deployment has authentication disabled. +The version endpoint alone does not verify access to a loaded graph. + +| Symptom | Check | +| --- | --- | +| Startup waits for PD/Store | Confirm the image and active graph backend; the HStore image deliberately waits for distributed storage | +| `Permission denied` updating properties | Configuration directories must be writable by the image's numeric service UID/GID | +| `Device or resource busy` updating properties | Replace the single-file configuration bind mount with a writable directory mount | +| Data disappears after container replacement | Persist `rocksdb-data`; a mount at `data` does not cover the default database | +| `UnsupportedClassVersionError` | Check that the binary distribution is launched with Java 17 | +| `Could not rebind` in standalone Gremlin | Use the GraphSpace-scoped alias registered by Server 1.8 | + +Stopping or removing the container does not delete its named data volume. +Retain that volume for a restart; removing it explicitly deletes the local graph data. +Changing `PASSWORD` or rebuilding an image is not a data migration or credential recovery procedure. + + If you use Docker Desktop, you can set the options as follows:
Docker Desktop settings for a HugeGraph container From 3caedd998d85e0ae7af1bd41ba09992ad5953c53 Mon Sep 17 00:00:00 2001 From: dark Date: Mon, 2 Nov 2026 23:33:36 +0800 Subject: [PATCH 2/3] docs: remove intermediate PR references from ToplingDB guide (EN/CN) --- content/cn/docs/guides/dev-test/toplingdb.md | 2 +- content/en/docs/guides/dev-test/toplingdb.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/content/cn/docs/guides/dev-test/toplingdb.md b/content/cn/docs/guides/dev-test/toplingdb.md index 14ae70312..0b9104e2a 100644 --- a/content/cn/docs/guides/dev-test/toplingdb.md +++ b/content/cn/docs/guides/dev-test/toplingdb.md @@ -106,7 +106,7 @@ export TOPLINGDB_ROCKSDB_PROVIDER=topling 发行包中的 native 配置关闭 HTTP 服务，并保留 Java 写入路径要求的 `memtable_as_log_index=false`。 请按机器条件调整该文件；它与业务 provider、数据目录配置分别生效。 -自 Server 1.8.0+（`apache/hugegraph#3447` / master）起，发行包中的 `conf/toplingdb.yaml` 默认预设基于社区通用 JNI 的 SkipList 内存表与 BlockBasedTable 文件配置，不再依赖 CSPP、CSPPMemTabTable 或 DispatcherTable 插件。 +自 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 配置，以防止服务初始化失败。 diff --git a/content/en/docs/guides/dev-test/toplingdb.md b/content/en/docs/guides/dev-test/toplingdb.md index e0474e68e..62ed673ac 100644 --- a/content/en/docs/guides/dev-test/toplingdb.md +++ b/content/en/docs/guides/dev-test/toplingdb.md @@ -112,10 +112,11 @@ The launcher uses that component's `conf/toplingdb.yaml`. Set `TOPLINGDB_EASY_MI The shipped native profile disables its HTTP server and keeps `memtable_as_log_index=false`, which the Java write path requires. Tune that profile for the host; it is separate from the business provider and data-path configuration. -Starting with Server 1.8.0+ (`apache/hugegraph#3447` / master), distributions ship a community-native profile in `conf/toplingdb.yaml` +Starting with Server 1.8.0+ (master), distributions ship a community-native profile in `conf/toplingdb.yaml` using standard SkipList memtables and BlockBasedTable files by default, which does not require CSPP, CSPPMemTabTable, or DispatcherTable plugins. In contrast, existing and earlier release builds (such as 1.7.0) ship `conf/toplingdb.yaml` configured with the `cspp` memtable and `DispatcherTable`. -When using community JNI without CSPP plugins on earlier builds, adjust `conf/toplingdb.yaml` to use SkipList and BlockBasedTable to avoid initialization failures. +When using community JNI without CSPP plugins on earlier builds, adjust `conf/toplingdb.yaml` +to use SkipList and BlockBasedTable to avoid initialization failures. The cache and write-buffer values are individual native budgets; memory also grows with the number of databases and column families. Inspect the actual profile in the distribution you deploy. Custom native profiles must name plugins supplied by the selected JNI. From ada46e0980877f081d516919a4dc2fac9c1700a7 Mon Sep 17 00:00:00 2001 From: orion Date: Mon, 2 Nov 2026 18:12:46 +0000 Subject: [PATCH 3/3] docs: address storage contract review findings Limit empty shard bounds to supported backends and describe the all-backend required-bound change. Qualify local-backend image reuse by the wait and data-directory fixes. Document Topling configuration precedence, absolute path handling and legacy CSPP upgrade requirements. --- .../cn/docs/clients/restful-api/traverser.md | 17 ++++++++++------- content/cn/docs/guides/dev-test/toplingdb.md | 15 ++++++++++++++- .../quickstart/hugegraph/hugegraph-server.md | 2 ++ .../en/docs/clients/restful-api/traverser.md | 17 ++++++++++------- content/en/docs/guides/dev-test/toplingdb.md | 15 ++++++++++++++- .../quickstart/hugegraph/hugegraph-server.md | 3 +++ 6 files changed, 53 insertions(+), 16 deletions(-) diff --git a/content/cn/docs/clients/restful-api/traverser.md b/content/cn/docs/clients/restful-api/traverser.md index 45eec6644..a5bfae66c 100644 --- a/content/cn/docs/clients/restful-api/traverser.md +++ b/content/cn/docs/clients/restful-api/traverser.md @@ -2651,11 +2651,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/traversers/vertic - page：分页位置，选填项，默认为 null，不分页；当 page 为“”时表示分页的第一页，从 start 指示的位置开始 - page_limit：分页获取顶点时，一页中顶点数目的上限，选填项，默认为 100000 -`start` 与 `end` 都必须出现，即使需要无界扫描，也应传入显式空值。 -包含扫描参数校验修复的构建在缺参时返回 HTTP 400；旧构建可能返回 HTTP 500。 -调用方升级后仍应保留两个参数，缺参不表示无界。 +包含扫描参数校验修复的构建在所有后端都要求 `start` 与 `end`，缺少任意一项返回 HTTP 400。 +这也改变了旧版 HStore 与内存后端将缺参按零处理、可能返回不完整数据的行为。 +只有 RocksDB 与 HBase 将空字符串视为开放边界；HStore 与内存后端没有相同语义。 -有界分页导出需要显式传入初始空 `page`： +下面的 **RocksDB** 示例通过显式 `page=` 请求有界分页的第一页： ```bash curl -fsS -G \ @@ -2666,12 +2666,14 @@ curl -fsS -G \ --data-urlencode 'page_limit=1000' ``` -逐分片导出时，应以 `vertices/shards` 返回的原始 `start` 与 `end` 替换空边界。 +HStore 与内存后端应遍历 `vertices/shards` 返回的每个区间，使用原始 `start`、`end`，并为每个分片重新传入 `page=`。 +空 HStore 区间可能只扫描哈希零所属的分区；空的内存后端结束边界可能不返回任何数据。 +一个分页序列结束只代表该分片完成，还须继续导出其余返回的分片。 边界编码依赖后端，不能将 RocksDB 返回的编码位置转换成下文的数值示例。 后续请求保持同一组边界，并使用 `--data-urlencode` 传入响应的 `page` 游标。 响应的 `page` 为 null 或空时结束；末页的元素数量可能少于 `page_limit`。 -| 请求 | 行为 | +| RocksDB 请求 | 行为 | | --- | --- | | `start=&end=&page=&page_limit=1000` | 第一页，最多 1000 个顶点 | | 相同边界并传入响应的 `page` | 同一分片的下一页 | @@ -2978,10 +2980,11 @@ 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 diff --git a/content/cn/docs/guides/dev-test/toplingdb.md b/content/cn/docs/guides/dev-test/toplingdb.md index 0b9104e2a..fff3e0f73 100644 --- a/content/cn/docs/guides/dev-test/toplingdb.md +++ b/content/cn/docs/guides/dev-test/toplingdb.md @@ -49,6 +49,8 @@ bash bin/prepare-topling.sh 缺少插件会在准备阶段失败，避免准备成功后才在 Server 初始化阶段崩溃。 此导入不会按生产 WAL 或日志路径打开数据库。 若显式指定配置，启动组件时也要保留相同的环境变量。 +准备与运行时选择都会在启动器切换目录前，按调用方工作目录将相对路径转为绝对路径。 +两个步骤应使用同一文件，服务配置优先采用绝对路径以免歧义。 导入检查针对准备时的实际文件；之后更换文件仍可能引入不支持的插件。 重启组件前，应使用所选 JNI 验证替换后的配置。 这些探针不代表已有数据兼容性或所有生产列族均已验证。 @@ -108,12 +110,23 @@ export TOPLINGDB_ROCKSDB_PROVIDER=topling 自 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 配置，以防止服务初始化失败。 +在旧版本上使用缺少 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/)。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 11f9c04c3..b0699101d 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -160,6 +160,8 @@ docker run -itd --name=server -p 8080:8080 -e PASSWORD="replace-with-your-passwo 命名卷持久化默认 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 写入。 diff --git a/content/en/docs/clients/restful-api/traverser.md b/content/en/docs/clients/restful-api/traverser.md index 5050f2870..0358a7fbe 100644 --- a/content/en/docs/clients/restful-api/traverser.md +++ b/content/en/docs/clients/restful-api/traverser.md @@ -2658,11 +2658,11 @@ 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, including for an open-ended scan. -An empty value is valid; a missing parameter returns HTTP 400 in builds containing the scan validation fix. -Older builds can return HTTP 500 instead. Keep both parameters when upgrading a caller. +`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. -For a bounded export, send an explicit empty initial `page`: +The following **RocksDB** example requests the first bounded page with explicit `page=`: ```bash curl -fsS -G \ @@ -2673,12 +2673,14 @@ curl -fsS -G \ --data-urlencode 'page_limit=1000' ``` -For separate shards, use the exact `start` and `end` returned by `vertices/shards` instead of empty bounds. +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`. -| Request | Behavior | +| 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 | @@ -2984,10 +2986,11 @@ 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; use explicit empty values for open bounds. +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 diff --git a/content/en/docs/guides/dev-test/toplingdb.md b/content/en/docs/guides/dev-test/toplingdb.md index 62ed673ac..1c5c56e71 100644 --- a/content/en/docs/guides/dev-test/toplingdb.md +++ b/content/en/docs/guides/dev-test/toplingdb.md @@ -50,6 +50,8 @@ It uses `TOPLINGDB_EASY_MIGRATE_CONF` when set, otherwise the component's `conf/ Missing plugins fail preparation instead of leaving a runtime that fails during Server initialization. This import does not open databases using production WAL or log paths. Keep an explicit configuration override in the service environment when starting the component too. +Preparation and runtime selection normalize relative overrides against the caller's working directory before the launcher changes directories. +Use the same file in both steps; an absolute service configuration path avoids ambiguity. The import validates the file present during preparation. Replacing that file later can introduce unsupported plugins; validate the replacement with the selected JNI before restarting the component. These probes do not certify existing-data compatibility or every production column family. @@ -116,12 +118,23 @@ Starting with Server 1.8.0+ (master), distributions ship a community-native prof using standard SkipList memtables and BlockBasedTable files by default, which does not require CSPP, CSPPMemTabTable, or DispatcherTable plugins. In contrast, existing and earlier release builds (such as 1.7.0) ship `conf/toplingdb.yaml` configured with the `cspp` memtable and `DispatcherTable`. When using community JNI without CSPP plugins on earlier builds, adjust `conf/toplingdb.yaml` -to use SkipList and BlockBasedTable to avoid initialization failures. +to use SkipList and BlockBasedTable for a **new, empty database** to avoid initialization failures. The cache and write-buffer values are individual native budgets; memory also grows with the number of databases and column families. Inspect the actual profile in the distribution you deploy. Custom native profiles must name plugins supplied by the selected JNI. Changing the default profile does not convert existing SST files; data written with another table format still needs its compatible reader. +For an existing CSPP installation, stop the component and preserve its matching JNI, previous tuned configuration and recoverable data backup. +Distributions containing the compatibility-profile fix ship `conf/toplingdb-legacy-cspp.yaml` in Server, PD and Store, preserving the old profile. +Select that file or the deployment's previous profile with an absolute `TOPLINGDB_EASY_MIGRATE_CONF` during preparation and startup. +The community JNI used for validation lacks CSPP readers; old CSPP SST compatibility still needs matching JNI and real old-format data. +Do not replace an existing CSPP installation's native settings with the community profile. + +The new defaults also change tuning: cache 8 GiB → 64 MiB, write buffer 128 MiB → 16 MiB, maximum buffers 6 → 3, background jobs 8 → 2. +Other previous compaction tuning is absent. These changes can affect performance and are not a transparent format migration. +With the tested community JNI, Java initially sets 128 MiB and six buffers, but EasyMigrate applies 16 MiB, three buffers and a 64 MiB cache at open. +Verify other JNI builds against persisted OPTIONS and `rocksdb.block-cache-capacity`; Java getters before open do not show the final native values. + The standard Server container includes a Java 17 JDK; builds containing the preparation-tool fix also include `unzip`. It does not bundle or download optional JNI. The artifact's glibc, libaio and CPU requirements must match the base image or deployment host. Use the [Server deployment guide](/docs/quickstart/hugegraph/hugegraph-server/) to distinguish the standalone and HStore images. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index d5af568a9..14798bd6c 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -167,6 +167,9 @@ Pin a tested release tag for reproducibility; mutable tags such as `latest` may The named volume persists the default RocksDB path. Mounting `/hugegraph-server/data` does not persist that database. Authentication is initialized from `PASSWORD` on first startup; changing this variable does not rotate an existing user's password. To reuse the HStore image for a new empty standalone installation, explicitly set both `HG_SERVER_BACKEND=rocksdb` and `HG_SERVER_USE_PD=false`. +Use an image containing the local-backend storage-wait and data-directory ownership fixes: +it ignores retained `pd.peers` and pre-creates `rocksdb-data` owned by 10001:10001 for a fresh named volume. +Older HStore images need a corrected writable graph configuration and data-directory ownership instead. Do not switch an existing HStore installation's backend or reuse its initialization marker this way. Custom configuration bind mounts must be writable by UID/GID 10001.