xerj SLA 兼容性对战测试解读:44/57 通过率背后的 ES 兼容策略与修复路线
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% 走向生产可用的路径。