用 Kibana 风格 Dashboard 直连 XERJ:一次针对 ES 兼容层的逐请求兼容性体检
用 Kibana 风格 Dashboard 直连 XERJ:一次针对 ES 兼容层的逐请求兼容性体检
本文将一份真实 Agent 现场报告(xerj v1.0.0-rc.93,2026-10-09)拆解为可复用的工程经验:一个未发布的 Dashboard / Discover / Dev Tools 前端,仅通过 _msearch、_search、_mapping、_cat/indices 等 ES 兼容端点接入 XERJ 后端,在 4 文档 repro 索引上与 Elasticsearch 8.13.4 逐请求交叉比对。读完后你会知道:哪些聚合与查询能力可以直接承载真实看板(date_histogram + extended_bounds、percentiles、cardinality、按单值指标排序的 terms、match_phrase、track_total_hits),哪些缺口属于"HTTP 200 但输出错误或缺失"的静默失败,以及浏览器直连时如何正确配置 [cors]。
测试环境与验证方法
现场报告的关键约束值得原样保留,因为它们定义了结论的边界:
- 执行方:Claude Code(Claude Opus 5.5),以 @Vinz2168 的名义执行;
- 版本与平台:
xerj v1.0.0-rc.93,macOS 27 / aarch64; - 接入对象:一个通过
_msearch、_search、_mapping、_cat/indices与任意 ES 兼容端点通信的前端,数据缩减为 4 文档的repro索引; - 交叉基准:与 Elasticsearch 8.13.4 逐请求比对。用户 dashboard 的 54 个不同查询在相同数据上与参考实现一致(由报告方报出,未复跑);而 issue 中的每一个分歧都由报告方在干净数据目录上对 rc.93 与 ES 8.13.4 重新执行确认。
这套"干净数据目录 + 双引擎复跑"的方法论,是把"用户反馈"升级为"实现事实"的关键一步。
数据面:能直接承载看板的 ES 能力
报告的结论是 Good — 数据面能够承载真实 dashboard。具体通过比对验证为"行为与 ES 一致"的能力包括:
_msearch的逐项错误(per-item errors):单条 item 失败不拖垮整个批次;date_histogram聚合叠加extended_bounds;percentiles与cardinality指标聚合;terms聚合按单值指标(single-value metrics)排序;match_phrase查询;track_total_hits的 total 语义。
源码侧印证:_msearch 的逐项错误是显式设计
当前仓库的路由注册中,/_msearch 与索引作用域变体 /:index/_msearch 均挂在同一 handler 上(见 engine/crates/xerj-api/src/router.rs,/:index/_msearch 的作用是让路径中的 index 作为未指定 index 的 header 行的默认值)。engine/crates/xerj-api/src/es_compat.rs 中存在专门测试 msearch_refuses_the_offending_item_and_runs_its_sibling,明确断言"ES 的逐项错误形态":违规 item 单独被拒,同批次其余请求照常执行——这正是 dashboard 多面板并发取数所依赖的容错模型。
源码侧印证:cardinality 与 percentiles 是精确计算
聚合执行器的模块头注释(见 engine/crates/xerj-engine/src/aggs.rs)说明了一个实现选择:Elasticsearch 用 HyperLogLog++ 做 cardinality、对高基数 terms 可返回近似桶数,而 xerj 的 cardinality 返回真实去重计数而非 HLL 估计值。报告在"Also noticed, not filed"一节独立观察到了同一点:percentiles/cardinality 在 ES 做近似的地方是精确的——更准,但在大数据量上可能与 ES 结果不同。对做 A/B 对拍的团队,这是一条必须提前写进验收标准的语义差异。
静默失败:对 UI 最危险的一类缺口
报告对缺口性质的判断很尖锐:这些 gap 都很小,但每一个都静默失败(HTTP 200、输出错误或干脆缺失),"这是对 UI 最坏的一类问题"。因为浏览器端拿不到错误码,只能画出错误的图,且极难排查。现场确认并归档(Filed alongside)的缺口共 7 项:
| Issue | 现象 | 为什么对 dashboard 危险 |
|---|---|---|
| #1281 | 通配符 highlight 字段没有任何高亮返回 | 高亮缺失不报错,搜索页静默失去关键功能 |
| #1282 | percentiles 上的 order 路径被丢弃 | 排序错误但不报错,桶顺序悄悄乱 |
| #1283 | 拼错一个 order 路径同样被丢弃而非报错 | 配置笔误零反馈,难以定位 |
| #1284 | 类型错误变成 "0 hits" | 字段类型不匹配时面板显示空,而非明确失败 |
| #1285 | 每个响应都带空 Warning: 299 头 |
官方客户端把每个 header 变成一次弃用告警(如 elasticsearch-py 会将其转为 ElasticsearchWarning),日志被刷爆 |
| #1286 | --help 缺少 CORS 与默认 native 端口说明 |
发现 [cors] 只能靠 grep 二进制,文档不可发现 |
| #1288 | _msearch 响应缺顶层 took |
批次级计时字段缺失,性能观测断档 |
这些编号对应仓库上游 issue tracker,现场报告方对每一项都在 rc.93 与 ES 8.13.4 上复跑确认。
当前仓库中的修复痕迹
值得注意的是,当前代码库已能看到部分缺口的修复痕迹(即报告所述 rc.93 之后的演进),引用时需注意版本前提:
- 空
Warning头(#1285)已修复。ES 兼容响应中间件现在只为 Elasticsearch 形态的调用方发送X-Elastic-Product,并且明确注释"NoWarningheader here (#1285)":ES 只有在请求真的触发弃用行为时才发送带消息的Warning: 299 …,每个响应都发一个空的会让官方客户端每次都冒出一条空白弃用告警(见 engine/crates/xerj-api/src/router.rs)。配套测试elastic_caller_gets_no_empty_warning_header断言 Elastic 形态调用方在无弃用时不应收到Warning头,且注释中记录了"过去它曾在每个响应上发299 Elasticsearch-8.13.0 "",而 ES 8.13.4 在/、_search、_cluster/health、_cat/indices上都不发"。 _msearch顶层took已存在。当前msearchhandler 的响应体构造为{"took": <批次耗时 ms>, "responses": <a href="https://link.gitcode.com/i/a0a92d3f9dc93156ee72bcf2dc25df7f" target="_blank">...]}(见 [engine/crates/xerj-api/src/es_compat.rs),即报告指出的 #1288 缺口在当前代码中已有对应实现。
这两处证据说明:现场报告的 issue 列表与代码演进是咬合的,引用此类差距清单时务必注明针对的构建版本。
浏览器直连的正确姿势:[cors] 配置
报告提到"CORS 通过 TOML 里的 [cors] 生效,但我只能靠 grep 二进制才找到它"——这既是 #1286 的由来,也值得在这里展开成可直接操作的配置说明。
XERJ 的 CORS 策略是默认收紧(default restrictive):开箱即用的节点不发送任何 Access-Control-Allow-Origin 头,浏览器因此只允许同源请求;非浏览器客户端(curl、SDK、服务端与 ES 通信的 Kibana)完全不受影响。配置模型定义在 engine/crates/xerj-common/src/config.rs 的 CorsConfig 中,只有两个键:
[cors]
# 显式放行列表:必须是完整 origin(scheme + host + 可选端口)。
# 空列表 = 收紧默认:不发任何 CORS 头,浏览器仅同源可访问。
allowed_origins = ["https://app.example.com"]
# 开发逃生舱:恢复 Access-Control-Allow-Origin: * 的宽开放策略。
# 仅在本地开发使用;公网节点开启后会被任意网页脚本化读写。
allow_any_origin = false
三条策略行为(与 engine/crates/xerj-api/src/router.rs 的 cors_layer 实现及同文件单元测试一一对应):
allow_any_origin = true→ 旧式宽开放策略(任意 origin/method/header),仅限本地开发;allowed_origins非空 → 仅反射列表内的精确 origin,方法集固定;列表外的 origin 拿不到Access-Control-Allow-Origin;- 两者皆默认 → 不发任何 CORS 头。无法解析为 HTTP header 值的条目会在构建期被丢弃并记一次告警,而不是悄悄放宽策略。
对应的测试 cors_default_restrictive_emits_no_acao、cors_allowlist_reflects_only_listed_origins、cors_any_origin_optin_is_wildcard 分别固化了上述三种行为。服务器 --help 文本(见 engine/crates/xerj-server/src/main.rs)也明确提示:浏览器应用直连节点需要在 [cors] 中设置 allowed_origins,allow_any_origin = true 仅用于本地开发。
其他观察与注意事项
报告中"未单独建 issue"的观察也一并保留,因为它们影响对拍结论:
_cat/indices会列出 14 个.xerj_*系统索引,与用户索引并列展示。在全新节点上无法与 ES 侧做同条件比较,但任何解析_cat/indices的 Discover 类 UI 需要自己过滤.前缀索引,否则会看到"凭空多出的索引"。- 精确 vs 近似聚合(前文已述):
percentiles/cardinality在 xerj 中是精确值。这意味着"与 ES 完全一致"在大数据集上不是正确的验收标准,应改为"语义一致、数值在近似误差内"。
结论:拿什么标准验收一个 ES 兼容后端
这份现场报告给出了一个可迁移的验收框架,适用于任何"现有 ES 客户端/前端直连替代后端"的场景:
- 逐项错误语义:
_msearch的失败必须隔离到 item 粒度,批次其余部分照常执行——dashboard 多面板取数的基础容错; - 静默失败清单:200 + 错误输出比 4xx/5xx 更难排查。验收时应专门构造"配置笔误"用例(拼错聚合路径、错误类型),确认后端报错而非吞掉;
- 响应头卫生:
Warning头、产品标识头(X-Elastic-Product等)是官方客户端敏感的元数据,空告警头会污染整个应用日志; - 响应信封完整性:
took、timed_out、_shards、hits.total等字段逐一对齐参考实现; - 对拍方法论:干净数据目录、双引擎复跑、每个分歧独立确认——这是把"UI 行为异常"归因到具体兼容层缺陷的前提。
对 XERJ 使用者而言,本文所有"已修复"结论均以当前仓库源码为准(如 es_compat.rs、router.rs 中的注释与测试);若在 rc.93 或更早构建上复现,请以该版本行为为基线,逐项对照上述缺口清单。