xerj SLA 兼容性对战测试解读:44/57 通过率背后的 ES 兼容策略与修复路线

原创2026-10-17 20:36:531,723 阅读
文章标签:人工智能搜索引擎本地部署后端MCP 服务

xerj SLA 兼容性对战测试解读:44/57 通过率背后的 ES 兼容策略与修复路线

本文以 xerj 在 2026-04-15 执行的 SLA Battle Test 结果报告(engine/reports/2026-04-15T21-38-59_sla_battle_summary.md)为主线,拆解这场真实 HTTP 层测试的设计方法、13 项失败的具体成因,并结合当前仓库源码与后续测试报告,说明 xerj 的 Elasticsearch 兼容层如何从"核心通过、边缘缺件"演进到可支撑现有 ES 客户端直接接入。读完本文,你将理解 xerj 兼容层的能力边界、每个失败项背后的实现层原因,以及如何亲自复现这场 SLA 对战。

报告背景与结论概览

该报告生成于 2026-04-15 21:38:59(MDT),运行环境为 32 核、119 GiB 内存的开发机,被测版本为 xerj v0.1.0,对应提交 c7fa334 revert: M5.24 dv_cache LRU — didn't help either。测试的总体结论如下:

Metric Count
PASSED 44
FAILED 13
Pass rate 77.2%

同一时段还配套产出了两份关联报告:同日 21:30 的 Cargo 测试结果(192 通过 / 2 失败,失败集中在 chaos_flush_during_writes 与 chaos_rapid_restart_loop 两个混沌测试),以及后续一系列 ES API 兼容对照测试。三者共同勾勒出 v0.1.0 时期 xerj 的真实成熟度:核心搜索能力已经可用,但边缘功能与运维路径尚未补齐。

测试方法论:14 个场景、57 项真实 HTTP 检查

这场 SLA 对战并非单元测试,而是通过 engine/tests/battle_sla.sh 驱动的真实 HTTP 层集成测试:脚本启动一个 xerj 实例,随后用 curl 逐一执行 14 个场景下的 57 项检查,每一条命令都带时间戳写入日志,以便事后对同一组请求做可复现回放。

场景与用户反馈分类的对应

14 个场景直接对应用户反馈分类目录(user-feedback/01 至 user-feedback/14),每个场景围绕一类运维痛点设计:

# 场景 核心断言
01 运维复杂度 建索引 + 批量写入 10 条 + 搜索,全程 < 60 秒
02 成本与定价 服务 1 000 条文档后 RSS < 512 MiB
03 JVM 与内存 启动 RSS < 512 MiB,10 K 文档后 < 1 GiB
04 扩展与分片 快速创建 100 个索引全部成功且 < 10 秒
05 许可与信任 LICENSE 存在且含 OSI 许可文本、无 license-gate 响应头
06 升级与迁移 写入 50 条 → kill → 重启 → 数据完整(WAL 重放)
07 查询与性能 bool+range、terms agg、search_after 深分页、平均搜索延迟 < 100 ms
08 数据模型限制 动态映射:新增字段无需 reindex 即可查询
09 安全 开启 auth 的实例拒绝无凭据请求(401)
10 文档与 UX 默认配置文件的键数量 ≤ 60(对比 ES 的 3000+ 配置项)
11 AI 与向量 dense_vector 映射 + KNN 搜索 + _analyze
12 日志分析 10 000 条日志落盘 ≤ 50 MiB,时间范围查询可用
13 厂商与支持 运维端点全部 200 且延迟 < 200 ms
14 生态与替代 dashboard summary、_sql、_analyze、explain-plan 可用

可复现设计

脚本为每次检查打印 CMD : 行,且报告头部声明:所有命令只需把端口 19200 替换为 9200,即可对着真实 Elasticsearch 8.x 集群原样回放,得到"苹果对苹果"的对比结果。这就是"SLA Battle"名称的由来——不是自我验收,而是与 ES 的逐命令对照。仓库中的 engine/tests/battle_real.sh 进一步演示了双机对照形态:同一批请求同时发往 ES 8.13(:9200)与 xerj(:3322),比较 _id、result、found、聚合均值、耗时与 RSS 内存。

测试实例通过脚本内的 write_config() 生成临时 TOML 配置,核心片段如下(与 engine/xerj.default.toml 的配置结构一致):

[server]
es_compat_port = 19200
rest_port      = 19080
grpc_port      = 19081
data_dir       = "/tmp/... "
bind_address   = "127.0.0.1"

[auth]
enabled = false

[tls]
enabled = false

默认端口选择 19200 而非 9200,正是为了避免与环境中可能正在运行的 ES 实例冲突——这份克制也服务于"可复现性"。

核心兼容面:CRUD / Bulk / Search / Scroll / Aggs 全线可用

报告在 Analysis 一节给出的关键结论是:核心 ES 兼容面(CRUD、Bulk、Search、Scroll、Aggs)达到 44/57 = 77% 通过率。这意味着 ES 客户端最常用的数据面已经成型。次日(2026-04-16)的 ES API 兼容对照测试报告 给出了更精细的证据:由 engine/tests/es_api_compat_test.py 驱动、同时对 xerj(:9800)与 ES(:9300)执行的 31 项测试 31/31 全部 PASS(100%),覆盖:

  • 集群 API:GET /、GET /_cluster/health、GET /_cat/indices;
  • 索引管理:建索引(含 mapping)、_mapping、_settings;
  • 文档 CRUD:_count、GET _doc/{id}、PUT _doc/{id}、DELETE _doc/{id};
  • 搜索:match_all、term、match、range、bool、exists、ids、sort、_source 过滤;
  • 聚合:terms、stats、avg、min/max、value_count、histogram;
  • 批量与维护:_bulk、_delete_by_query、_aliases。

该测试对状态码差异做了工程化宽容:200 与 201 均视为成功(ES 的 PUT 新建返回 201,而 xerj 返回 200),这正对应下面要讨论的 HTTP 状态码细节问题。

失败项全景:13 项失败的原因与分类

报告将 13 项失败归为四类。逐项拆解如下,并结合当前源码说明各自的底层成因。

1. 查询正确性缺陷(最需关注,直接影响搜索质量)

bool+range 查询返回 0 而非 100。报告给出的线索是"doc_values shortcut bug on combined bool+range with small segments"——在小型 segment 上,bool + range 组合查询走了一条基于 doc_values 的计数捷径(shortcut),该捷径在小 segment 场景下漏掉了命中。从当前源码看,这类捷径确实广泛存在于查询执行路径中:例如 engine/crates/xerj-engine/src/index.rs 中的 try_shortcut_count Bool 交集分支与 shortcut_count_cache(Range 的 doc_values 预过滤计数),以及 engine/crates/xerj-engine/src/fast_aggs.rs 中大量围绕 per_ord_count 整段计数捷径的注释(如"matching docs — the whole-segment per_ord_count shortcut")。捷径的价值是性能,代价是必须在所有 segment 形态(含小 segment、未刷盘数据)下保持正确,而 v0.1.0 时期显然还有缝隙。报告明确判定这是两类"影响搜索质量、需要调查"的问题之一。

terms 聚合返回 0 个桶。原因标注为"agg on unflushed data path empty"——对尚未刷盘(仍驻留内存 memtable)的数据执行聚合时,聚合路径为空。源码中聚合实现同样存在"segment 的 per_ord_count + memtable 列式目录(columnar folder)"的双路径结构(见 engine/crates/xerj-engine/src/fast_aggs.rs),也就是说 memtable 数据需要被正确纳入聚合计数,v0.1.0 时该路径尚未打通。值得注意的是,后续路线图 PATH_TO_100_PCT_v0.6.0_to_v1.0.md 在 v1.0-rc 目标中仍保留"terms-agg / date_histogram 多 segment 正确性"为待办,且 v1.0.0-rc.1 发布说明 的已知限制列表中明确列出"Terms-agg / date_histogram correctness on multi-segment indexes"为 v1.0-rc.2 回归项——说明这类聚合正确性问题经历了一个较长的收敛过程。

2. 功能缺口(stub 或未接入)

  • KNN 搜索返回 0 结果:报告注明"vector search not indexed for these test docs"。v0.1.0 的向量链路尚未覆盖到"测试文档被向量化索引"这一环节。而到 v1.0.0-rc.1 发布说明 时,:9200 端口的兼容面已明确包含 "kNN, hybrid, semantic";engine/crates/xerj-api/src/es_compat.rs 中已存在完整的 dense_vector 映射解析与顶层 knn 折叠逻辑(body.knn、peel_knn_query、compound_bool_direct_knn 等),说明该缺口在后继版本中被补上。
  • SQL 端点返回非 JSON:报告注明"SQL is a stub"。当前源码已存在完整实现:engine/crates/xerj-engine/src/sql.rs 提供词法分析(tokenise)与 parse_sql 解析器(支持 SELECT、DISTINCT、聚合函数、LIMIT、SORT),engine/crates/xerj-api/src/es_compat.rs 的 sql_query 处理器将解析结果转换为 SearchRequest 并返回 columns + rows 结构——已从 stub 演进为真实实现。
  • _analyze 端点返回 -1 tokens:同样标注为"analyzer API not fully implemented"。当前源码中 engine/crates/xerj-api/src/es_compat.rs 已实现 POST /_analyze 与 POST /{index}/_analyze 的完整链路:支持 ad-hoc 分析链(_analyze_adhoc)、normalizer 参数、字段级分析("analysing field [{f}] requires an index")、自定义分词器注册,并提供 tokenize_for_analyze 生成与 ES 一致的 token 对象。

3. HTTP 状态码细节:_update 返回 201 而非 200

失败项 4-6 共 3 项同源:POST /{index}/_update/{id} 对已存在文档做更新时返回 201 (created),而 ES 语义要求返回 200 (updated)。从当前源码看,更新响应的构造逻辑已具备区分能力:engine/crates/xerj-api/src/responses.rs 中 EsDocResponse::created(result: "created")与 EsDocResponse::updated(result: "updated")是两个独立构造函数,且 update_doc 处理器会根据更新结果选择性地携带 get 块(兼容 Kibana SavedObjectsRepository 读取 body.get._source 的习惯,见 engine/crates/xerj-api/src/es_compat.rs 的 update_wants_get)。这属于典型的"响应细节对齐"问题:功能已存在,但 HTTP 状态码与 ES 8.x 的语义仍需逐字节校准。

4. 运维与安全路径(连锁失败)

  • LICENSE 文件缺失(失败项 1):测试要求 engine/LICENSE 存在且包含 OSI 认可许可文本(Apache/MIT/BSD/MPL/GPL),并检查响应头无 X-License-Required / X-Feature-Gate 之类授权门禁头。仓库根目录目前存在 LICENSE 文件,可满足许可声明需求,但 battle 脚本检查的路径是 engine/LICENSE。
  • TLS 证书自动生成未在 15 秒内启动(失败项 7):安全实例(--config 开启 auth、不带 --insecure)启动超时。结合路线图看,进程内 TLS(rustls 集成)在 PATH_TO_100_PCT 中是 v0.9 里程碑的 9-P1 项,且 v1.0.0-rc.1 发布说明 仍将其列为 "scaffolded; v1.0 final"——即 v0.1.0 时 TLS 自动签发尚不具备,该失败符合预期。仓库同期产出的 SECURITY_DEPLOYMENT_MODEL.md 记录了配套的部署安全模型(xerj 默认部署在 TLS 终止反代之后)。
  • Auth 401 检查无法执行(失败项 8-9):由于安全实例未启动,无凭据 401 与错误密钥 401 两项检查连锁失败。这套检查本身的设计可从 engine/tests/battle_sla.sh 的 TEST 09 看到:启用 [auth] enabled = true 与 admin_api_key,然后分别用无凭据、错误 Authorization: ApiKey、正确密钥请求 _cluster/health,断言返回 401 / 401 / 200。当前 engine/xerj.default.toml 的 [auth] 节注释显示:auth 默认开启,首次启动自动生成 admin key 写入 <data_dir>/admin.key,所有请求(含 xerj autoindex)都必须携带 Authorization: ApiKey <key>。
  • 时间范围查询返回 0(失败项 11):@timestamp 范围查询在动态映射下未被索引为日期类型。这类问题同样属于动态映射类型推断的边界情况,后续在 es_api_compat 对照测试中,预定义 date 字段的 range 查询已稳定通过。

从失败到修复:两条验证证据链

对这份报告最有价值的后续证据,是仓库里两条独立的验证链:

证据链一:次日对照测试全绿。 2026-04-16 的 es_api_compat 报告 显示 31 项核心 API 对照测试 100% 通过,且 xerj 与 ES 的 HTTP 状态码、hits.total.value、聚合桶等关键字段逐一对齐。这印证了 SLA 报告中"核心 ES 兼容面已成型、失败集中在边缘特性"的自我评估。

证据链二:路线图把失败项显式转化为里程碑。 PATH_TO_100_PCT_v0.6.0_to_v1.0.md 以"Production-first / Enterprise-POV"双轨划分修复优先级:v0.6.1"Stop lying"要求将 stub 端点的 200-OK 替换为 501 Not Implemented(对应 SQL 等 stub 类失败);v0.6.2 聚焦 HNSW 持久化与软删除(对应 KNN 可用性);v0.9 落地进程内 TLS(9-P1)与密钥哈希轮换(9-P3)。到 v1.0.0-rc.1 发布说明,:9200 兼容面已覆盖 38 种查询类型、全部聚合、bulk、scroll、索引模板、别名、kNN、hybrid、semantic,并新增 tamper-evident 审计日志(SHA-256 哈希链)与 RBAC 角色体系——v0.1.0 报告中的大部分"功能缺口"在此已转化为正式能力。

需要说明的事实边界:_analyze、SQL、kNN 在当前源码中已有实现,且发布说明将其列为兼容面能力;但本文未找到它们在后继版本中的独立对照测试记录,因此这些结论以源码与发布文档为准,而非"已通过某次回归测试"。

如何复现这场 SLA 对战

复现步骤如下(基于 engine/tests/battle_sla.sh 的用法说明):

# 1. 确保已构建 release 二进制(脚本首次运行会自动执行)
cargo build --release -p xerj-server

# 2. 运行 14 场景 SLA 对战(要求 curl、python3、ps、awk、wc)
./tests/battle_sla.sh

脚本会自动:生成临时数据目录与配置文件 → 以 --insecure 启动主实例(:19200)→ 逐场景执行 curl 断言 → 输出 BATTLE_SLA_RESULTS_<时间戳>.md 报告,并在结束时汇总 PASS/FAIL/TOTAL 与通过率。若要对照真实 ES:

# 将报告/脚本中的 19200 全部替换为 9200;
# ES 8.x 需要额外附加 Basic 认证头:
#   -H "Authorization: Basic $(echo -n elastic:password | base64)"

值得注意的是,脚本在部分检查(如 TEST 10 的配置键计数)中记录了明确的边界声明:它统计的是 engine/xerj.default.toml 文件中实际赋值的 key=value 行数(当前文件头注释显示该文件设置 55 个键、总计 132 个用户可见设置),并强调"不引用没人统计过的数字"——这份对断言边界的自律,与报告本身"只陈述测试所见"的风格一致。

结语

v0.1.0 的这场 SLA 对战,用 57 项真实 HTTP 检查把 xerj 的 ES 兼容层照了个透:77.2% 的通过率说明核心数据面(CRUD、Bulk、Search、Scroll、Aggs)已经能让既有 ES 客户端跑起来,而 13 项失败则精准标注了四个待补区域——查询正确性捷径、stub 功能、HTTP 状态码细节、运维安全路径。这份报告的价值不在于一个数字,而在于它把"兼容性"分解成了可逐项追踪的检查清单:每一项都有 curl 命令、有预期值、有对照 ES 的回放方法。后续的 31/31 对照全绿与按里程碑推进的路线图证明,这种"把差距写进报告、把修复排进计划"的工程方法,正是 xerj 兼容层从 77% 走向生产可用的路径。

登录后查看全文
xerj