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..a5bfae66c 100644 --- a/content/cn/docs/clients/restful-api/traverser.md +++ b/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 diff --git a/content/cn/docs/guides/dev-test/toplingdb.md b/content/cn/docs/guides/dev-test/toplingdb.md index 44f8abfdf..fff3e0f73 100644 --- a/content/cn/docs/guides/dev-test/toplingdb.md +++ b/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 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 0b54c746b..b0699101d 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,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，则可以按如下方式设置相关选项：
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..0358a7fbe 100644 --- a/content/en/docs/clients/restful-api/traverser.md +++ b/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 diff --git a/content/en/docs/guides/dev-test/toplingdb.md b/content/en/docs/guides/dev-test/toplingdb.md index 993b0a2ab..1c5c56e71 100644 --- a/content/en/docs/guides/dev-test/toplingdb.md +++ b/content/en/docs/guides/dev-test/toplingdb.md @@ -44,7 +44,17 @@ 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. +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. 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 +114,42 @@ 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+ (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 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. + +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..14798bd6c 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,67 @@ 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`. +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. +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