Skip to content

[Test] record helm isse #103

Open
Open

Description

@imbajin

单机 + Helm 多引擎实测问题核对

最近核对:2026-11-02(Asia/Singapore)。已拉取 org 远端最新 master,逐项核对记录与代码。
历史测试矩阵没有整批复跑;通过/失败数字仍是原 2026-10-31 实测结果。

  • 🔗 Server 修复 PR #363:scan 缺参校验、Topling 默认配置与准备验证、镜像 unzip、单机配方与别名文档,530 行。
  • 🔗 双语官网文档 PR #60:单机/HStore 制品区别、分页契约、Gremlin 别名、Topling 准备与验证,302 行。
  • ✅ 已完成项与订正项已在详情评论中默认折叠,区分「已进入 master」与「修复分支验证通过、待合入」。
  • ⚠️ 分布式 DEGRADED 原现场、Hubble → HStore 完整克隆链路、Topling 容器/集群变体往返、大图任务现场仍需人工确认。
  • 已确认的能力限制:克隆仅支持无边标签 Schema、不复制数据;当前 Helm 不支持纯 Server + 本地 RocksDB 拓扑。没有将这些限制标为完整能力已修复。

逐项状态、验证证据与待确认项 → 详情评论

历史测试总览:2026-10-31(旧矩阵与 Topling 分支记录,点击展开)

Helm 实测总览

最近更新 2026-10-31 · 测试基线 apache/hugegraph 29333a6ec + chart 0.4.0
(master 已前进到 bd3ab564,2 个提交未复测,见详情评论)


一、RocksDB 模式

项目 单机(无 PD/Store) 1+1+1 单点集群 3+3+3 分布式
部署方式 docker 直启 / 二进制发行版(chart 不支持,见详情) Helm values-single Helm values-cluster
存储引擎 本地 rocksdb;分支上另测 topling hstore(PD + Store) hstore(PD + Store)
组件 Server + 本地 RocksDB 1 PD + 1 Store + 1 Server
+ Hubble + Vermeer + SeaTunnel
3 PD + 3 Store + 3 Server
+ Hubble + Vermeer 1M/3W + SeaTunnel ×2
测试矩阵 50 项适用 165 项 165 项
通过 49 135 135
失败 0 1 2
跳过 / 不适用 1 / 115 22 21
  • 单机的 115 项不适用:无 PD/Store、无 Hubble/Vermeer/SeaTunnel
  • 单机两种载体(容器 / 二进制发行版 + JDK17)结果一致:49 通过 / 1 跳过 / 0 失败
  • 单机在 PR fix: schema not cached in spark/flink loader apache/hugegraph-toolchain#334 最新代码(4ea84b83e) 上复测同样 49/1/0,二进制载体已跑通 topling 引擎(证据见详情第 7 项)
  • 1+1+1 与 3+3+3 的失败项相同根因:Hubble 图克隆不可用;分布式另有集群概览 DEGRADED
  • 分布式专项:三个 Server 读同一 id 一致、Vermeer 4 Pod、16 Pod Running、11 PVC Bound

二、ToplingDB 模式(变体)

项目 值
来源 PR #334 codex/topling-images(核心集成 apache#179)
机制 global.runtimeVariant=topling → pd/store/server 镜像 tag 追加 -topling,所以仍是集群模式,不是单机
拓扑 与 1+1+1 相同,server.backend 仍为 hstore,可复用同一批 PVC 原地切换
该分支 chart 0.2.0(无 Vermeer / SeaTunnel 模板)
测试矩阵 170 项 = 122 适用 + 48 不适用
静态校验 TP-01 镜像 tag 与 nodeSelector 注入:通过;TP-02 digest 冲突明确报错:通过
集群实测 未执行(TP-03 运行态引擎 / TP-04↔TP-05 变体往返 待跑)
单机引擎实测 已跑通:二进制载体 + topling JNI,50 项适用跑出 49/1/0(容器载体受限,见详情第 7 项)

未解决问题(5)→ 查看详情

逐项复现步骤、证据、已修复项、单机部署配方、调用契约订正与 CI 记录,全部在详情评论中。

Activity

  1. imbajin commented on Oct 28, 2026

    @imbajin
    Author

    实测问题核对与修复清单

    最后核对:2026-11-02(Asia/Singapore)。已真实拉取各 org 远端 master:
    Server 8e327b8f3、Toolchain 7e1683f5、Vermeer/Computer 3a8d988c、官网文档 cd196415。
    历史 49/50、135/165 等数字仍对应 2026-10-31 的旧实测,本轮没有重跑整个部署矩阵。

    本轮新修复仅提交 org:

    • 🔗 Server #363,提交 640686323,406 增 / 124 删(530 行)。
    • 🔗 Doc #60,提交 ca75f7e3,298 增 / 4 删(302 行)。
    • 两个 PR 已互相链接;分支修复已验证不等于已合入,也不等于镜像已发布。

    一、存疑 ⚠️(需人工确认)与已确认的能力限制

    1. 原第 2 项:分布式集群概览 DEGRADED / service_not_ready 的现场根因尚未验收。
      最新 Toolchain 已包含 PD 地址映射诊断、未归属 Service 指标样本和独立 Store 生命周期展示,Server 已包含 Store /-/lifecycle。
      pd-client Service/VIP 不能可靠标识具体 PD 成员;不能把它的指标分配给任意节点,也不能把 Store STARTED 当作就绪。
      本轮 121 项运维采集/解析/数据服务测试通过,但没有原 3+3+3 现场的逐节点 /-/state、PD /v1/ready 和实际部署版本证据,未宣称现场已修复。

    2. 原第 1 项:完整图克隆的验收范围需确认。
      最新两端已修复不存在的克隆端点;本轮 4 项真实 RocksDB 克隆 API 测试通过。
      当前能力明确限定为同空间、无任何边标签的 Schema 克隆,不复制数据;含边标签在建图前拒绝,避免丢失父子边关系。
      这不是“完整 Schema/数据克隆已实现”。Hubble 浏览器 → Server → HStore 的现场链路尚未复验。

    3. 原第 4 项:Helm 纯 Server + 本地 RocksDB 仍是未支持的拓扑。
      已确认当前 chart 只支持 HStore;values-single.yaml 是 1 PD + 1 Store + 1 Server。
      单机开箱路径使用标准 RocksDB 镜像/发行包,见折叠项;本轮没有新增 Helm RocksDB 拓扑。
      Vermeer/SeaTunnel 自己的 standalone 设置不会改变 Server 后端。

    4. 原第 7 项:Topling 容器和集群变体仍待镜像/现场验收。
      默认 YAML 与准备检查已修复并用真实 JNI/Server 验证,见折叠项。
      Topling 镜像 PR #334 仍未合入;本轮未构建/发布新镜像,JNI 的 glibc、libaio 与 CPU 要求仍须匹配载体。
      TP-03 运行态集群引擎、TP-04/05 同 PVC 变体往返尚未执行,不能由 Helm 渲染通过代替。

    5. 大图异步任务现场仍存疑。
      原 4165 万顶点的队头阻塞没有本轮同规模复现。历史中等规模未复现不等于原现场已修复;没有增加任意超时。

    二、✅ 已修复 / 已订正(默认折叠)

    ✅ 原第 1 项:Hubble/SDK 克隆端点已修复并进入最新 master(能力边界见上)

    Server master 0e9f25751(org #361 / ASF #3439)与 Toolchain master 7e1683f5(org #121 / ASF apache#870)已配套落地。
    Hubble/SDK 调用显式 POST .../graphs/{target}/schema-clone?source={source},不再调用不存在的 /clone,也不回退成创建空图。
    同空间、无边标签 Schema 的属性键、顶点标签、索引可复制;图数据不复制。失败后可能残留目标图,需检查,不自动删除。
    官网 org #58 对应内容已进入文档 master。

    本轮:SDK GraphsAPITest 15 项通过;Hubble 克隆控制器/配置能力 22 项通过;Server 克隆/本地绑定单元 13 项通过、真实 RocksDB 克隆 API 4 项通过。
    上述结果不扩展“含边标签拒绝”的能力边界。

    ✅ 原第 2 项的诊断缺口已修复并进入最新 master;现场 DEGRADED 仍存疑

    Toolchain 已包含 org #120(ASF apache#876)与 org #127 对应实现:
    保留 PD 映射诊断,把无法归属节点的 Service 指标单独展示,独立采集 Store 进程生命周期。
    Server master 8e327b8f3 已包含 org #362(ASF #3441),官网 master 也包含对应说明。

    本轮 LiveOperationsCollectorTest 69、DefaultOperationsDataServiceTest 24、OperationsPayloadParserTest 28,合计 121 项通过。
    这些测试使用受控响应,不是原分布式现场验收;未放宽健康判定。

    ✅ 原第 3 项:Vermeer 日志文档已修复并进入最新 master

    Server master e15a05809 已包含 org #360(ASF #3440)。
    helm/hugegraph/docs/vermeer.md 已明确 chart 关闭文件日志,使用 kubectl logs ... -c master/worker;单 Pod 模式也分别查看两个容器。
    不再要求读取不存在的 /go/bin/vermeer_data/vermeer.log。本轮核对了最新文档与 chart 配置。

    ✅ 原第 4 项:标准单机路径已确认;部署配方已补齐(新 PR 待合入)

    最新标准二进制配置已经是 backend=rocksdb、serializer=binary,pd.peers 已注释;标准镜像为 hugegraph/hugegraph。
    hugegraph/server 是 HStore 镜像,不能把它的默认等待 PD/Store 视为标准单机路径。
    新空数据安装若复用 HStore 镜像,可显式设置 HG_SERVER_BACKEND=rocksdb 与 HG_SERVER_USE_PD=false,无需配置文件 bind mount;不要切换已有 HStore 部署的数据后端。

    本轮使用最新源码发行包,不启动 PD/Store,完成 RocksDB 初始化、/versions、真实图 API、分页与克隆请求。
    Server #363 新增 docs/deployment-standalone.md:
    说明 Java 17、auth.admin_pa + stdin 初始化、UID/GID 10001、目录而非单文件挂载,以及默认数据卷 /hugegraph-server/rocksdb-data。
    Doc #60 同步中英配方。Helm 的能力限制仍列在上方。

    ✅ 原第 5 项:单机 Gremlin 别名文档已修复(新 PR 待合入)

    最新源码单机实测:__g_hugegraph 返回 400,__g_DEFAULT-hugegraph 返回 200。
    Server 1.8 的别名由版本/绑定契约决定,不由是否启用 PD 决定;无 PD 的 RocksDB 同样使用 DEFAULT-<graph> / __g_DEFAULT-<graph>。
    只有没有 GraphSpace 绑定的旧 Server 才使用旧别名。
    Server #363 修正仓库 REST 指南;Doc #60 修正官网中英 Gremlin 页。

    ✅ 原第 6 项:scan 缺参 500 已修复(新 PR 待合入)

    在最新 master 真实复现:顶点和边 scan?page_limit=5 都返回 500,根因为空边界传到 Base64 解码。
    Server #363 对两个接口校验 start / end 是否缺失,返回 400 + 缺失参数名;显式空值仍允许。
    本轮 10 项真实 RocksDB HTTP 回归全部通过:缺两项/任一项、显式空边界、有界分页与游标续读、旧的不分页契约。

    分页仍需显式传 page=;省略它时 page_limit 不限制整分片响应。这是保留的既有契约,已在仓库和 Doc #60 中英说明,不静默改变旧调用方行为。

    ✅ 原第 7 项:Topling 默认 YAML、准备校验与 unzip 缺口已修复(新 PR 待合入)

    使用 PR #334 已固定的社区 JNI 制品,校验 SHA-256:
    c9066873d5eb38585517c0c4065565897aab96629585731b6fb36d64b81efef2。
    旧 Server YAML 真实复现 ImportAutoFile ... NotFound / class = cspp。

    Server #363:

    • 默认改用社区 JNI 可用的 SkipList + BlockBasedTable,不再要求 CSPP/DispatcherTable。
    • 准备脚本先用临时 DB 验证 EasyMigrate,再 native 导入实际配置;缺少插件时拒绝发布运行时并清理临时目录。导入验证不按生产 WAL/日志路径打开数据库。
    • 两个 Server Dockerfile 增加 unzip。最新 master 基础镜像已是 Java 17 JDK,历史“纯 JRE 无编译模块”不再适用于当前 Dockerfile。

    本轮:真实 JNI 准备通过;旧 YAML 被新脚本干净拒绝;真实 Server 初始化成功,属性键/标签创建、顶点写入与回读通过,/proc/<pid>/maps 确认 5 段 Topling JNI 映射。
    新增准备脚本契约回归并接入 CI。此验证为 Linux 二进制载体;未宣称新容器/集群已验收。

    ✅ 历史已合入修复 / 非缺陷订正仍保留

    历史 Hubble Schema 默认值、Gremlin/Cypher 原始/包装超时、Server /apis 路径与不存在标签重建、Vermeer task 集合 POST、Helm 外部入口等记录保留于下方历史原文。
    最新 Vermeer 源码已含拒绝无效集合 POST 的修复;本轮 go test -tags=dev ./apps/master/services -count=1 通过。
    双语 HTTP 契约 org #56(ASF apache#552)已进入当前官网 master,不再是“待合入”。

    没有复跑旧数据集的性能结论,也没有把错误端点/缺少请求体/权限预设策略当作新引擎缺陷。

    ## 三、本轮验证范围
    • Server:全 38 模块 clean compile、发行包/测试依赖构建、EditorConfig 与 diff 检查通过。
    • Server:10 项 scan HTTP + 4 项克隆 HTTP、13 项克隆/绑定单元测试通过。
    • SDK:15 项 GraphsAPITest 通过;Hubble:克隆/配置/运维相关 143 项通过。
    • Vermeer:services 包测试通过(dev 构建标签用于本地 UI 资源)。
    • Topling:真实可信 JNI、配置导入正反例、真实 Server 初始化与图写读、映射库确认通过;准备/选择脚本检查通过。
    • 官网:290 项源码测试完成,1 项既有跳过;严格生产构建、35 项 Chromium 搜索检查、链接/diff 检查通过。
    • 更宽的既有 GraphsApiStandaloneTest 另有 4 项默认图管理断言预期 200,当前独立模式实际返回 400(GraphSpace 管理不支持);未计为通过,也未改动这些接口来迎合测试。
    • 新 PR 的远端 CI 以各 PR 当前 head 为准;本轮没有手动重跑历史失败 CI,没有新建 ASF PR,没有部署或发布镜像。

    历史原文:2026-10-31 实测、证据与修复进展(保留追溯,状态以本轮核对为准)

    实测问题与修复清单(统一维护)

    最后更新:2026-10-31(修复进展),实测基线 apache/hugegraph master 29333a6ec + chart 0.4.0。
    结构:当前未解决在最前;已完成 / 已撤回 / 已订正的一律折叠到「已完成 / 可忽略」。


    一、当前未解决(7 项:3 个功能 + 4 个文档/打包)

    1. Hubble 图克隆端到端不可用(P2,单机与分布式均复现)

    调用链:GraphsController.clone → client.graphs().clone() → POST {graphs}/{graph}/clone。

    • Server 的 /apis 路由表里没有 /clone 子资源;克隆是建图接口的参数 clone_graph_name
    • 实测 POST /graphspaces/DEFAULT/graphs/hugegraph/clone → 400(后端 404)
    • 实测 POST /graphspaces/DEFAULT/graphs/{新名} + {"clone_graph_name":"hugegraph"} → 201,
      但目标图 schema 未复制(轮询 30 秒 vertexlabels 仍为 0)

    即 Hubble 走了不存在的端点;现场把参数放入 JSON,而 Server 将其作为查询参数读取。Server 的配置克隆实现也不会复制 Schema 或数据。

    修复进展: Toolchain PR #121 / ASF #870 和 Server PR #361 / ASF #3439 配套提供同空间 Schema 克隆,官网文档 PR #58 / ASF #554 说明能力和失败后的残留,明确不复制数据;旧 Server 不会回退为创建空图。先前 RocksDB 和 SDK 验证覆盖了顶点 Schema,但后续审查发现存储可能丢失父子边标签关系。为避免静默复制错误,配套修复将对含任何边标签的源图在建图前拒绝,目前仅支持无边标签的 Schema;完整 Hubble UI 到 Server、HStore 和现场仍待复验,上述 PR 均未合入。上游审查意见对应修复已推送:Server 新提交通过单元、RocksDB 及全模块编译检查,最新真实 HTTP 尚未复验;Toolchain 浏览器回归通过。更新后的三项 PR 的 CI 正在运行。

    2. 分布式模式集群概览报 DEGRADED(P2,仅分布式)

    GET /api/v1.3/operations/overview
      overall: DEGRADED, reason: service_not_ready
      server:  AVAILABLE / UP
      stores:  AVAILABLE / UP
      pd:      PARTIAL / UP, reason: pd_metrics_unmapped
               configured_origin: http://<release>-pd-client.<ns>.svc:8620
               status: no_match, matched_nodes: 0, discovered_nodes: 3
               members[*]: origin=...-pd-N.<release>-pd.<ns>.svc:8620,
                           origin_matches=false, base_path_matches=true
    

    PD 成员实际端点是 <release>-pd-N.<release>-pd.<ns>.svc,与配置的 pd-client 服务名不匹配,
    指标组 system 无法映射。数据面正常(读写、三 Server 一致性、Pod 与 PVC 状态均通过)。

    修复进展: Toolchain PR #120 / ASF #876 防止数据故障遮蔽地址映射诊断;不推断 VIP 对应节点,也不改变健康判定。现场 service_not_ready 与逐节点指标采集问题仍待排查;PR #127 增加未归属的 PD Service 样本和独立 Store 进程状态展示,不将 Service 样本分配给节点,也不把进程 STARTED 视为就绪。该修复及配套 Store #362 尚未合入和现场验收。

    3. 文档与实现不符(P3)

    chart docs/vermeer.md 写日志位于 /go/bin/vermeer_data/vermeer.log;实测该文件不存在,
    日志实际输出到容器 stdout(kubectl logs 可读 758 行)。

    修复进展: Server PR #360 / ASF #3440 修正文档和容器日志命令;ASF 当前提交 CI 已通过,独立审查无阻塞意见,尚未合入。


    4. 单机模式(无 PD/Store + 本地 RocksDB)没有开箱路径(P3,容器与二进制均复现)

    实测中依次踩到五道坎:

    1. chart values.schema.json 把 server.backend 限定为 const: "hstore" → 无法用 Helm 部署单机;
    2. 官方 hugegraph/server:latest 镜像内置 backend=hstore + pd.peers=127.0.0.1:8686
      → 直接 docker run 会卡在 wait-storage.sh 等 Store,300 秒后
      ERROR: Timeout waiting for storage backend 退出 1;
    3. 镜像以 uid 10001 运行,bind mount 的配置若不可写,entrypoint 的 set_prop(sed -i)报 Permission denied;
    4. 单文件 bind mount 上 sed -i 的 rename 报 Device or resource busy,必须挂整个 conf/graphs 目录;
    5. rocksdb 数据目录是 /hugegraph-server/rocksdb-data(不是 ./data)。

    二进制发行版(bin/start-hugegraph.sh)同样如此,另加三条:

    1. 发行版 conf/graphs/hugegraph.properties 出厂值也是 backend=hstore + pd.peers=127.0.0.1:8686;
    2. HugeGraph 1.8 要求 Java 17(maven.compiler.release=17),宿主默认 Java 11 会 UnsupportedClassVersionError;
    3. 鉴权初始化走 stdin 而非环境变量,且密码属性名是 auth.admin_pa(不是直觉上的 auth.admin_password):
    # 二进制部署的正确顺序
    sed -i -E 's/^backend=.*/backend=rocksdb/'  conf/graphs/hugegraph.properties
    sed -i -E 's/^pd\.peers=.*/# disabled/'     conf/graphs/hugegraph.properties
    echo "auth.admin_pa=$PW" >>                 conf/rest-server.properties
    ./bin/enable-auth.sh
    printf '%s\n' "$PW" | ./bin/init-store.sh
    ./bin/start-hugegraph.sh

    已验证可行的配方(本次 SA1 实测 49/50 通过):

    # 导出镜像默认 conf/graphs 并改成 rocksdb
    docker run --rm -v /tmp/g:/out --entrypoint sh hugegraph/server:latest \
      -c 'cp -r /hugegraph-server/conf/graphs/. /out/'
    sed -i -E 's/^[[:space:]]*backend[[:space:]]*=.*/backend=rocksdb/' /tmp/g/hugegraph.properties
    sed -i -E 's/^[[:space:]]*pd\.peers[[:space:]]*=.*/# disabled/' /tmp/g/hugegraph.properties
    chmod -R 777 /tmp/g
    # 挂目录(不是单文件),数据挂到 rocksdb-data
    docker run -d --name hg-standalone -p 18080:8080 -e PASSWORD="<admin>" \
      -v /tmp/g:/hugegraph-server/conf/graphs \
      -v /tmp/hgdata:/hugegraph-server/rocksdb-data hugegraph/server:latest

    5. 文档对单机模式的 Gremlin 别名描述与实现不符(P3)

    docs/rest-api-usage.md 称「standalone legacy graph 用 <graph> 和 __g_<graph>」。单机实测:

    aliases 结果
    {"graph":"hugegraph","g":"__g_hugegraph"} 400 Could not rebind [g] to [__g_hugegraph] ... not in the Graph or TraversalSource global bindings
    {"graph":"DEFAULT-hugegraph","g":"__g_DEFAULT-hugegraph"} 200
    不带 aliases 400 No such property: g

    即单机(无 GraphSpace 概念)也必须用 graphspace 形式的 DEFAULT-<graph> 绑定。

    6. traversers/*/scan 缺少 start/end 参数时返回 500 而非 400(P3)

    该端点用于按 shard 区间分页导出,start/end 都是必填,但缺失时没有参数校验,直接空指针:

    GET /graphspaces/DEFAULT/graphs/hugegraph/traversers/vertices/scan?page_limit=5
    → 500 {"message":"Cannot invoke \"String.isEmpty()\" because \"value\" is null",
           "trace":["org.apache.hugegraph.util.StringEncoding.decodeBase64(...)",
                    "RocksDBTable$RocksDBShardSplitter.position(RocksDBTable.java:393)", ...]}
    

    应为 400 + 明确提示。同组端点的其他契约实测如下(可作为测试参考):

    调用 结果
    GET .../vertices/shards?split_size=1048576 200 {"shards":[{"start":"gXYx","end":"gnYyMAA=","length":0}]}
    GET .../edges/shards?split_size=1048576 200 {"shards":[{"start":"","end":"4294967295","length":0}]}
    GET .../vertices/shards?split_size=100 400 The split-size must be >= 1048576 bytes
    GET .../vertices/scan?start=&end=&page=&page_limit=5 200,游标翻页正常,末页 page 为空
    GET .../vertices/scan?start=&end=&page_limit=5(不带 page) 200 但忽略 page_limit,一次返回整个 shard 且无游标

    后两条对 loader 类消费方有实际影响:必须显式带 page=(空值)才进入分页模式,否则大 shard 会一次性返回全部数据。

    7. server 侧 topling 运行时无法自备,且自带 toplingdb.yaml 与本镜像 JNI 不兼容(P3)

    单机(无 PD/Store,本地 RocksDB)启用 topling 引擎时,在 server:latest-topling 上四面受阻:

    # 阻碍 证据
    1 entrypoint 启用 topling 前强制要求先跑 prepare-topling.sh,镜像自身未预置 Error: run /hugegraph-server/bin/prepare-topling.sh before enabling Topling
    2 容器内跑 prepare 失败:server 镜像无 unzip(store 镜像有 /usr/bin/unzip) prepare-topling.sh: line 39: unzip: command not found
    3 prepare 用 java --source 17 做能力探测,需完整 JDK;纯 JRE 报 Module jdk.compiler not in boot Layer 换 JDK 17 后通过
    4 用 JDK 完成 prepare 后,init-store 仍崩于镜像自带的 conf/toplingdb.yaml ImportAutoFile(...toplingdb.yaml) = NotFound ... class = cspp

    第 4 条是核心:server 镜像的 yaml 用 MemTableRepFactory: cspp + TableFactory 指向 CSPP 系列的 memtable-sst 表工厂,
    而同镜像内的 JNI 解析不到该插件类;store 镜像的 yaml 用 skiplist + block_based,换这份后
    init-store 立即成功,随后 50 项跑出 49 通过 / 1 跳过 / 0 失败。

    可见引擎确实生效(非日志推断):/proc/<pid>/maps 有 5 段 topling/librocksdbjni-linux64.so,
    classpath 首位为 topling/rocksdbjni.jar,环境含 TOPLINGDB_ROCKSDB_PROVIDER=topling 与
    LD_PRELOAD=.../topling/librocksdbjni-linux64.so。

    影响面:chart 只给 pd/store 注入 hugegraph.apache.org/rocksdb-runtime: topling,server 模板未注入,
    当前 Helm 部署不受影响。但镜像 ship 了 prepare-topling.sh、preload-topling.sh、
    conf/toplingdb.yaml 且 entrypoint 做强制校验,容易被理解为「server 也支持 topling」,实际只有
    二进制载体(宿主有 unzip + JDK17 + 换 yaml)才能跑通。

    二、已完成 / 可忽略(已修复、已撤回、已订正、非缺陷;点开查看)

    原「待确认」三项的结论

    Gremlin 直连别名 —— 已解决,非缺陷。
    正确别名在 HStore 模式同样有效(原报告只验证了 RocksDB,现已补齐):

    {"gremlin":"g.V().count()","aliases":{"graph":"DEFAULT-hugegraph","g":"__g_DEFAULT-hugegraph"}}

    POST /gremlin 返回 200。规则:图绑定 <graphspace>-<graph>、遍历源绑定
    __g_<graphspace>-<graph>;别名目标必须是已存在的绑定名,不能写 graph.traversal() 这类表达式。
    不带 aliases 时返回 No such property: g 属预期行为(Server 可托管多个图,没有隐含全局 g)。

    HStore 异步任务阻塞 —— 中等规模未复现。

    • 中等规模(1,000,000 边 / 563,912 顶点)复测:两个 4 跳遍历任务仍 running 时,
      后提交的小任务 15 秒内 success,未复现队头阻塞。
    • 原始 4165 万顶点那次:任务 40004 持续 running、progress=0、task_update 等于 task_create;
      后续任务 40015 停在 new;删除 40004(204)后 40015 在 8 秒内成功。
    • progress=0 本身不足以证明任务挂死,慢扫描与大标签场景仍需在大数据量下单独定位。
      没有据此增加任意超时,也没有宣称原现场已修复。

    Vermeer 计算 HTTP 400 —— 契约已确认,调用方参数层级错误。
    POST /api/v1.3/vermeer/task 是加载图的入口(JsonLoad{graphspace,graph,force,params,task_type}),
    不是计算入口。计算应使用 POST .../algorithms/vermeer,body 为
    {"params":{"compute.algorithm":"degree"}} —— 算法键嵌套在 params 下且为扁平点号形式;
    按此调用返回 200 并产生任务。原报告缺失层级导致的 400 不再记为引擎缺陷。

    已撤回 / 设计行为

    • Vermeer unload 空操作已撤回。 该接口需要 body;不带 body 返回 400
      Required request body is missing。带 graphspace / graph 后 200,10 秒内 state=gone,
      再 load 可到 loaded;chart 示例原本带 body。
    • SeaTunnel graph_a 不是缺陷。 按指南先建 graph_a,demo 作业正常 FINISHED 并写入 10 个顶点。
    • POST /graphs 返回 405 不算建图缺陷。 建图使用 /graphspaces/{space}/graphs/{name}
      和后端要求的配置。GET /graphspaces 仅支持 PD 模式,独立模式可用 GET /graphs 查看已配置图。
    • Server 删除索引没有必需的 delete_all 参数。 返回 task_id 后轮询任务结果;
      此前“必须 delete_all=true”的结论订正。
    • 审计记录端点不存在。 已核对 Hubble 全部 Controller,无 audit 路由。
    • Server 无图样本端点。 /apis 路由表中无 sample;样本能力在 Hubble(/sample)。
    • 不把错误端点的 404、缺少请求体的 400、权限预设策略和同步查询执行时限单独记为已确认引擎 bug。

    已合入的修复 PR

    修复 PR 已提交 已完成问题 修复 PR 已合入(ASF)
    正确 Hubble 创建标签省略/null style 或 open_label_index 导致 NPE;补齐默认值,保留显式 false 与样式。缺省顶点样式使用与外部创建标签一致的名字配色。 org #104 / ASF #859 ✅ 2026-10-30
    正确 Gremlin / Cypher 的原始或包装传输超时漏判;统一返回 504,提示检查连接,长查询可走异步任务。同步执行时限本身不算此 bug。 同上 Toolchain PR,提交 181e9e0 ✅ 2026-10-30
    正确 /apis 返回相对路径产生解析歧义、根资源子路径出现重复斜杠;修正为规范根相对路径。原报告中的“硬编码 /apis 前缀”已订正。 org #354 / ASF #3431 ✅ 2026-10-29
    正确 重建不存在的顶点、边或索引标签将 null 放入 task_id,导致 500 NPE。现返回 404,正常重建保留 202 和有效 task_id。 同上 Server PR ✅ 2026-10-29
    正确 原生 Vermeer POST /api/v1/tasks 返回 {"code":200} 却不建任务。现返回 405、Allow: GET,明确使用 /api/v1/tasks/create;修正原生 PageRank/任务状态示例。 org #21 / ASF #368 ✅ 2026-10-29
    正确 Helm 外部 HTTP 入口说明:easy 默认 NodePort,strict 默认 ClusterIP;ClusterIP 可经 port-forward / 网关访问,RPC / Worker 保持内部。apache#552 保留已合入的四份 Helm 文档。 ASF doc #551 ✅ 已合入

    Server、Toolchain、Vermeer 对应 org PR 已关闭。合入不等于原 HStore 现场或规模性能已经复测。

    验证与审查记录(按对应提交;不是所有当前 CI 的通过声明)

    • Server:旧二进制复现缺失标签重建 500;8 项路径/重建单元测试、2 项真实 RocksDB API 测试及
      全 38 模块 clean compile 通过。
    • Vermeer:旧代码六组任务集合 POST 均错误返回 200;修复后 Go 1.23.7 services 包测试通过,
      认证仍先返回 401。
    • Toolchain 181e9e0:真实慢 HTTP Gremlin 和 Cypher 原始/包装超时测试在旧代码得到 400,
      修复后 66 项查询/schema/样式/响应测试通过。此前导入/Cypher/权限契约测试另通过 52 项。
    • 文档:此前最终站点构建通过 290 项源码测试(1 项既有跳过)、版本/输出校验和 35 项浏览器搜索检查;
      545ff7d 的小段双语前提说明完成链接和 diff 检查。
    • 旧 SDK 安装失败是生产端与消费端 JDK patch 不一致,已由 083d430 传递精确版本;
      严格来源和校验和检查保留。该旧 head 的 ASF run 40738187045 共 29 个 job 成功,
      org 前端失败的根因没有据此推断为已解决。
    • 新提交的 CI 结果以各 PR 的对应 head / run 为准。没有手动重跑旧失败 CI,也没有绕过已拒绝的日志读取。
    • Org 三条新行内线程已解决;两条 ASF 线程的修复已同步,但 resolveReviewThread 被集成权限拒绝,
      未换渠道重试。
    • 自动 issue 监控已按“连续三轮无外部内容更新且超过三小时”暂停;本次整理不自动恢复监控。

    三、仍待合入

    修复 PR 已提交 问题 / 修复内容 修复 PR 已合入(ASF)
    正确 双语 HTTP 契约缺口:登录、Gremlin/Cypher、schema、导入、权限预设、异步任务、近似统计和 Vermeer 加载/计算;页面明确 schema 默认值需包含 apache#859 的构建。 org #56 / ASF #552,提交 545ff7d 待合入;Helm 说明已由 apache#551 合入

    四、复测覆盖与数字

    部署形态 代码版本 载体 存储引擎 适用项 通过 失败
    单机 master 29333a6ec 容器 rocksdb 50 49 0
    单机 master 29333a6ec 二进制 rocksdb 50 49 0
    单机 PR apache#334 4ea84b83e 容器 rocksdb 50 49 0
    单机 PR apache#334 4ea84b83e 二进制 topling 50 49 0
    1+1+1 单点集群 master 29333a6ec Helm hstore 165 135 1
    3+3+3 分布式 master 29333a6ec Helm hstore 165 135 2

    全部形态的失败数为 0,除集群侧那两个已知项(图克隆、分布式概览 DEGRADED);
    单机统一 1 项跳过(S-17 与 S-16 语义重叠)。

    单机 115 项不适用(无 PD/Store / Hubble / Vermeer / SeaTunnel);分布式专项全部通过。

    本轮按源码契约补齐(原记 BLOCKED 的项目实际不阻塞):

    项 源码契约 结果
    Vermeer 计算 {"params":{"compute.algorithm":"..."}} 200,产生任务
    Vermeer 算法能力 GET .../algorithms/olap/capability 200
    图元素导入 multipart file + 图元素 JSON 200,顶点可回读
    权限预设 PUT .../auth/users/{id}/preset 200
    反向读取 chart 挂载的 hugegraph-source.conf 作业 FINISHED
    空间统计 POST .../statistics + GET .../statistics/vermeer 200
    traversers GET + 查询参数(source 需 JSON 引号) 6 项全部 200
    运维视图 operations/overview、operations/nodes 200,server/pd/store 均 UP

    分布式专项:3 Server 读同一 id 结果一致;Vermeer 4 Pod;16 Pod Running;11 PVC Bound。

    ToplingDB 变体(TP1,已准备、待执行) —— 契约与静态校验细节:

    • 变体选择:global.runtimeVariant: standard | topling(默认 standard)。取 topling 时
      _helpers.tpl 给 pd/store/server 的 tag 追加 -topling,并强制注入
      nodeSelector: {kubernetes.io/arch: amd64, kubernetes.io/os: linux};
      若用户已设置冲突值则渲染直接 fail。
    • digest 冲突保护:chart 内有独立的 runtime-variant-validation.yaml,同时存在
      *-topling 变体与非空 digest 时渲染失败并提示
      digest overrides the selected -topling tag. Clear the digest and use a matching version tag。
      因此不存在“静默用错镜像”的路径(TP-02 通过)。
    • 变体切换语义:同一批 PVC 原地切换,文档要求切换前正常停机;
      TP-04(topling→standard)与 TP-05(standard→topling)将校验切换后数据仍可读。
    • 该分支 chart 为 0.2.0,比 master 落后 7 个 helm 提交,不含 Vermeer / SeaTunnel 模板,
      因此矩阵 170 项中有 48 项(V / VM / N / ST / X-03 / OP-04)标记为不适用。

    仍未覆盖:浏览器 UI 实测(需人工环境)、Vermeer 任务取消 / Worker 删除等破坏性场景、
    SeaTunnel 反向导出到文件、「大图算法」等性能项。


    五、调用契约订正(新测试可直接照用)

    • Hubble 登录字段为 user_name / user_password,后续保留会话 cookie;Gremlin 集成请求另需
      username / password。使用 HTTPS 传输凭据。
    • schema 样式字段为 display_fields / join_symbols;不包含 fix(hubble): handle schema defaults and timeouts apache/hugegraph-toolchain#859 的构建须显式提供
      "open_label_index":true,"style":{"display_fields":["~id"]}。
    • Cypher 请求使用 {"content":"MATCH (n) RETURN count(n)","preview":false},不是 query 或嵌套 gremlin-query。
    • 导入为 multipart 字段 file,内容是图元素 JSON,不是 Loader 作业规格或 CSV。
      顶点使用 id/label/properties,边使用 label/source/target/properties,先建对应 schema。
      空 vertices/edges 接受成功不代表真实导入模型已验证。
    • GraphSpace 的用户 POST 是旧角色分配接口,不是注册账号;账号注册在顶层
      POST /api/v1.3/auth/users。自定义角色被策略禁用时,使用 .../auth/users/{id}/preset
      及 GS_READ_ONLY / GS_READ_WRITE / GS_ADMIN。没有放宽权限策略。
    • 图克隆只能通过建图接口的 clone_graph_name 参数(见「当前未解决」第 1 条)。
    • traversers 是 GET + 查询参数:kout/kneighbor/shortestpath/rings 的 source
      需 JSON 引号编码(%221%3Amarko%22);count/paths 用 POST body
      (count 为 source+steps,paths 为 sources/targets 的 {ids:[...]} 形式)。
    • UI 的 /asyncTasks 不等于 API 的 /async-tasks;旧版无 GraphSpace Server 的异步 Gremlin
      路径为 /graphs/{graph}/jobs/gremlin,轮询 /graphs/{graph}/tasks/{task_id}。
    • scan_limit=100000 且 approximate=true 的计数是有界扫描结果,不能当作全图精确计数;
      需要精确值时用 GET .../statistics/vermeer(approximate:false,需先 load 图)。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions