企业官网建设流程全解析

• 可观测性
• 云原生
• 运维

本篇技术指南以开源可观测性平台 HyperDX 的 Web 前端包@hyperdx/app的 发布记录（v1.1.0 → v2.39.1，共 66 个版本、3000+ 行条目）为骨架，系统梳理该包在图表编辑器、告警系统、LLM 可观测性、ClickHouse 查询优化、主题体系与工程化工具链上的连续演进。读完本文，你将理解 HyperDX 前端各核心模块（Dashboard 瓦片、告警、搜索、会话回放、MCP）近年来的关键能力与实现原理，并能沿着源码路径进一步深入验证。

说明：本文所有功能描述与性能数字均直接取自 packages/app/CHANGELOG.md 及各版本对应源码；标注的路径为当前仓库内真实存在的文件，便于读者对照阅读。

一、版本脉络与发布结构：读懂 Changelog 的组织方式

@hyperdx/app的 CHANGELOG 采用 Changesets 生成的语义化版本结构，每个版本分Minor Changes（新功能）与Patch Changes（修复与小型改进），并在版本末尾列出本轮依赖的@hyperdx/api与@hyperdx/common-utils版本号——这直接反映了仓库的 monorepo 依赖关系（根目录 nx.json、package.json 可佐证多包结构）。

从版本序列看，演进可分为三个清晰阶段：

• v1.x（早期）：v1.1.0 → v1.9.0，奠定搜索、会话回放与基础仪表盘能力；
• v2.0（重构期）：v2.0.0-beta.x 系列到 v2.0.0 正式版，是 UI 与架构的大版本重构；
• v2.3 → v2.39（能力爆发期）：持续叠加 LLM 可观测性、告警细节页、Terraform 导入、PromQL、指标名浏览优化等重磅能力。

最近几个版本（v2.36 → v2.39.1）的迭代密度尤其高，是观察该项目当前技术方向的窗口。下面按主题域深入展开。

二、LLM 可观测性 Dashboard：读时（Query-Time）Schema 无关解析

v2.38.0（commit38e99a37）为应用引入了位于/llm的 LLM 可观测性 Dashboard（beta，从仪表盘列表进入）。它的核心设计是无需任何采集侧改动：

• 在查询时解释已按 OTel GenAI 语义约定、OpenLLMetry、OpenInference 或 Vercel AI SDK 埋点的 Trace，绘制流量、Token 拆分（uncached / cached / cache-write / output / reasoning）、按模型的估算成本（内置价格目录，支持 cache-read 折扣与 cache-write 溢价；若探针自带成本属性则优先采用）、延迟 / TTFT、工具调用分析、逐会话时间线（懒加载对话视图），以及并排的 LLM Span / 日志搜索；
• 当同一应用并行发出多种埋点方言（例如 opencode 同时发 OpenInference 与 Vercel AI Span）时，聚合会选取应用自己的成本上报 Span 作为每次调用的权威上报者，确保只计一次——CHANGELOG 记录该逻辑与 opencode 自报的会话成本完全一致。

后续 v2.39.0 又为 LLM 仪表盘增加了按最终用户过滤（34d829c7）：在原有会话过滤旁新增用户下拉框，列出搜索范围内 LLM Span 上出现的去重用户，并作用于每个 Tab（含 Errors Tab 的相关日志事件）。用户解析复用与 "Top Users" 图相同的跨方言表达式（user.email、enduser.id、user.id、ai.telemetry.metadata.userId），且选择状态保存在 URL 中可分享。

v2.39.0 还附带了一个关键的查询性能修复（同样在34d829c7）：LLM 仪表盘原先用SpanAttributes['key'] != ''测试属性存在性，而 trace 表的mapKeys(SpanAttributes)跳过索引只能服务mapContains。改为以mapContains领头后，staging 表上 LLM Span 谓词的规划时间从36 秒降到 7ms，两键过滤从 1306 个 granule 降到 3 个。有配套 Group By 值表达式的门控保留非空检查但用indexHint包裹，使谓词进入跳过索引分析而不按行重算。从源码结构看，该功能的完整实现集中在 packages/app/src/llm/（dashboard、hooks、components、lib子目录），并有独立测试目录__tests__与__fixtures__。

三、图表编辑器的进化：指标名浏览、Formula、PromQL 与系列上限

图表编辑器是@hyperdx/app迭代最频繁的模块之一，v2.29 → v2.39 期间出现了一批值得注意的设计。

3.1 指标名选择器：从聚合扫描到主键流式浏览

v2.39.0（3876d6b9）重写了指标名下拉框。原先靠全表聚合发现指标名，在有约 4,900 个 gauge 指标的源上，首个选项约770ms才出现；现在通过mergeTreeIndex表函数从稀疏主键流式读取MetricName（每个 granule mark 一行，而非整列扫描），首个选项约30ms出现且渐进式到达。

该选择器因此有两种模式：

• 浏览模式（Browsing）：从稀疏主键索引流式读取，列表是子集，偏向真正有数据的指标（CHANGELOG 提到索引可见指标的中位数据点约 32k，其余约 14 个）；
• 输入模式（Typing）：切换为穷举、按相关性排序的GROUP BY搜索，保证索引遗漏的指标仍可按名找到；下拉框渲染上限提到 500 以匹配服务端分页。

浏览在无法读取索引时自动回退到穷举列表（服务器早于 24.2、Distributed 或非 MergeTree 指标表、主键不含MetricName的 schema）。配套基建：Metadata新增泛型异步生成器streamDistinctIndexValues（任何主键列如ServiceName都能同样列举），streamToAsyncIterator从 app 的 session 代码移入common-utils的 ClickHouse 客户端旁，新增useStreamingQueryhook 把异步迭代器累积进 React Query 缓存并按节流发布部分结果。

3.2 指标资源管理器与 Formula

v2.37.0（8f3126f0）加入图表编辑器的指标资源管理器（Metrics Explorer）：不再需要先知道指标名才能制图。浏览控件打开一个带命名空间前缀层级（system→cpu→utilization）的模态框，支持跨全部名称与描述搜索；每行显示指标 kind 与描述，详情面板展示单位（由 UCUM 代码渲染）、上报服务与 tag 键。名称按指标拆分分隔符（OpenTelemetry 按.，Prometheus exporter 按_），单子链折叠避免树退化成走廊，未过滤树不截断。

v2.36.0（e153f46d）与b1d8dc14引入并扩展了公式（Formula）：事件源（日志、Trace）与指标源的时间序列/表格/数字图都可定义派生序列，通过字母引用运算（如A / (A + B) * 100），支持内联结构化校验、每公式别名与数字格式、"Show input series" 开关；事件源公式内联编译进图表的单次扫描 SELECT，无逐序列查询扇出。系列行显示引用字母徽章，公式与 "As Ratio" 开关互斥，并持久化到仪表盘瓦片与独立图表。

3.3 PromQL 支持与系列上限

• v2.28.0（3123db53）引入实验性 PromQL 支持；v2.29.0（973d1201b）、v2.32.0、v2.33.0、v2.37.0 相继补齐 label 过滤自动补全、label dashboard filters、serviceVersionExpression、变量替换、生成式 PromQL 预览、无效用法警告等；
• 系列上限：v2.29.0（81e524c2）为 group-by 时间图引入 top-N 系列上限（默认 100，团队级设置）防止高基数导致浏览器内存耗尽；v2.29.0（bf6e1f29）把该限制改为每图配置（Display Settings 抽屉），默认关闭，不发射__hdx_series_limitCTE，且分块查询把排名钉在最新块窗口，保证跨块并集恰好等于上限；v2.34.0（3d61cf92）进一步实现时间图系列的封顶绘制，含 "+N more" 与 "load all series" 逃生口、每帧渲染行数封顶，外部仪表盘 API 暴露三态系列限制（省略=默认、0=不限、正数=前 N）。

3.4 多序列图：UNION ALL 单查询合成与浮点归一

v2.35.0（aedb514f）将多序列指标图从"每序列一查询、客户端合并"改为单一组合 ClickHouse 查询：逐序列查询通过 UNION ALL 合并并在 SQL 内透视回一行 (group, time bucket)，覆盖 ratio 图及两种ratioMode；列名（含同名__{index}消歧）、缺口语义与 ratio 语义不变，但大幅减少往返，"View SQL" 现在展示完整查询。v2.36.0（9c7742fa）修复了混合浮点/整数聚合（如 histogram quantile + count）在 UNION ALL 中的类型问题：现在把所有序列值归一为 Float64，避免NO_COMMON_TYPE或依赖use_variant_as_common_type产生Variant(Float64, Int64)。

四、告警系统：从单一通知到评估详情与 Webhook 模板变量

告警是最近版本中扩展最深的功能域，核心组件集中在 packages/app/src/components/alerts/（含AlertDetails.tsx、AlertEvaluationsTable.tsx、AlertHistoryCards.tsx、EditAlertModal.tsx等）。

4.1 告警细节页与评估流

v2.35.0（88f62274+05a3fd81）新增/alerts/:id告警细节页：告警查询对照阈值绘制、加宽的评估历史条、分页评估事件流（group-by 告警的分组明细、评估分析列、时间范围游标分页），后端配套 AlertHistory evaluations 读模型与GET /alerts/:id/evaluations（时间范围钳制在保留窗口内、ERROR 状态窗口去重错误呈现、游标分页跨间隙推进），由 packages/api/src/controllers/alerts.ts 提供服务。该页默认由NEXT_PUBLIC_ENABLE_ALERT_DETAILS门控（默认关闭）。v2.39.0（482d2cb0）又为告警列表本身加分页。

4.2 多通知渠道与按目标计时的投递分析

• v2.36.0（fb284465）：保存搜索/仪表盘瓦片告警可发送到多个 webhook（最多 10 个），内联增删渠道，重复被拒绝；
• v2.37.0（0558f77e）：webhookDurationMs原本是覆盖整个投递的单一数字（并发分发下最慢目标决定该值）。现在每次分发单独计时并按目标聚合存储（每个 distinct 目标一条：webhook id、显示名、累计时长、分发次数、失败数），数组按最慢优先排序并受ALERT_NOTIFICATION_TARGETS_LIMIT封顶；评估历史的 "Notification duration" 单元格可原地展开明细；
• v2.39.1（84c67f4b）：通知时长列改为只计投递本身，不再把构建消息标题/链接、查询正文日志、渲染模板等耗时混入。

4.3 Webhook 模板变量：完整条件上报

v2.39.0（972634d2）修复了{{sourceQuery}}模板变量只读图表顶层where的问题——按序列aggCondition定义的告警此前渲染为空。现在该变量上报告警查询实际应用的完整条件：图表的where+ 告警读取序列的aggCondition，保存搜索的where+ 其固定过滤器（图表固定过滤器被刻意排除），值截断至 2000 字符。配套修复：编辑between/outside比较器时清除残留的thresholdMax；Webhook 表单变量列表与 API 回退正文模板都派生自 common-utils 中同一份列表（buildWebhookTemplateVariables类型绑定）；可选数字的守卫改为{{#unless (eq thresholdMax undefined)}}而非{{#if thresholdMax}}（后者把合法的0当作缺失）。v2.38.0（25a3b015）还列出了全部受支持变量（{{alertId}}、{{status}}、{{alertType}}、{{comparator}}、{{threshold}}、{{thresholdMax}}、{{value}}、{{groupKey}}、{{sourceQuery}}、{{teamId}}、{{note}}、ISO-8601{{startTimeISO}}/{{endTimeISO}}），每个变量带一行说明，可在表单内直接写正文。

4.4 连续窗口与 PENDING 状态

v2.30.0（0c7254360）引入告警的连续窗口配置（如"条件连续满足 N 个窗口才触发"）以减少抖动告警与噪音，并新增PENDING告警状态表示"按当前趋势将要触发"。v2.39.0（f007c37f）的 onboarding 清单与 v2.35.0（72269ece）之后，告警相关的评估标记也被叠加到仪表盘瓦片图上。

五、基础设施即代码：Terraform 导入导出

v2.34.0（1af1998c）加入面向 ClickHouse Provider 的 Terraform 采纳工具："Export to Terraform" 按钮（仪表盘、保存搜索、保存搜索告警）生成可粘贴的import {}块与可折叠的 provider 配置；团队设置（"API & Agents"）可下载覆盖仪表盘、告警、保存搜索、源、连接、webhook 的导入文件。关键设计：

• 仅导入设计：资源配置由terraform plan -generate-config-out经 provider 读取生成，而非由 HyperDX 生成——因为外部 API 的仪表盘序列化是字段白名单，直接生成dashboard_json可能在 apply 时静默丢瓦片设置；
• Terraform 地址由资源 id 派生而非名称，重命名资源不会产生 destroy-and-recreate 计划；生成器位于@hyperdx/common-utils，API 与 UI 产出同一工件；manifest 端点每个列表封顶 1000 行并报告被截断的类型；
• v2.35.0（8508b6c7）把导入 id 改为团队作用域（<team_id>/<resource_id>），provider 下限升到>= 3.25.0（导入时丢弃仅服务端的仪表盘 id）；
• v2.39.0（e31e5d8d）让clickhouse_clickstack_alert支持source = "tile"（dashboard_id/tile_id，provider 3.28.0），批量导出与单告警菜单现在都包含瓦片告警；携带瓦片告警的文件要求>= 3.28.0并在生成配置中解释所需的手工编辑；瓦片名空白或重复时、或仪表盘由 ProvisionDashboardsTask 托管时该瓦片告警被剔除（provider 的tile_idsmap 以瓦片名为键，空白/重复名会丢失映射；provisioned 仪表盘的瓦片会被任务整体重写）。这些决策在服务端做出（导入清单与告警列表两侧），因为两个响应都不携带同仪表盘其它瓦片名。

六、MCP 服务器：denoise 与静态过滤

@hyperdx/app与 MCP 服务器的联动在 v2.36.0 后持续增强：

• v2.36.0（750b8afe）：clickstack_search工具新增denoise布尔参数，镜像 Web 应用的 "Denoise Results" 功能——采样 10k 随机事件，用 Drain 算法挖掘模式，识别噪音模式（>10% 采样），从结果行中过滤并返回被移除模式及估算计数的元数据；共享常量DENOISE_SAMPLE_SIZE、DENOISE_NOISE_THRESHOLD提取到@hyperdx/common-utils，Web 应用与 MCP 服务器使用同一组值（可对照 packages/common-utils/src/queryParser.ts 与 common-utils 源码树中的 drain 目录）；
• v2.38.0（55db91fa、cff6388c、0a187457、83c1b57f）：MCP 支持静态过滤器，schema 与 API 同步扩展，UI 支持创建/编辑静态列表过滤器与展示静态值过滤器；
• v2.38.0（8e52cef4所在版本附近）"Connect your AI assistant" 团队设置区：按 Claude Code、Cursor、VS Code + Copilot、Codex CLI 或任意 MCP 兼容宿主提供安装片段，片段携带用户个人访问键，直连现有/api/mcp路由；v2.32.0（4372c78c）更新了 Codex CLI 安装片段到codex mcp add --url ... --bearer-token-env-var ...语法。

七、ClickHouse 查询优化前线：mapContains、direct_read 与子列成本

多个版本围绕 ClickHouse 查询计划与跳过索引展开优化，值得单独梳理：

• mapContains 优先（v2.39.034d829c7）：见上文 LLM 部分。Map 下标是子列引用，在 ClickHouse 26.3+ 每个下标在 PREWHERE 规划期都增加 per-part 大小查找；mapContains由mapKeys索引服务且无 per-part 查找成本；
• direct_read map 列优化（v2.28.0dcab1cb6）：全文搜索日志 schema（00002_otel_logs.sql）与 trace schema（00005_otel_traces.sql）新增ResourceAttributeItems/ScopeAttributeItems/LogAttributeItems/SpanAttributeItemsALIAS 列与text(tokenizer='array')跳过索引。查询时按连接服务器版本门控Map['key'] = 'value'→has(<MapItems>, concat('key','=','value'))重写：26.2 线 ≥ 26.2.19.43、26.3 线 ≥ 26.3.12.3、26.4 线 ≥ 26.4.3.37、26.5+ 恒支持；MATERIALIZED items 列则始终可用（物理存储，任何支持 text 索引的版本都能直接读）；8810ff0f提供强制启用/禁用文本索引支持的选项。相关实现可对照 packages/common-utils/src/queryParser.ts 中的mapContains生成与 direct_read 重写逻辑；
• 禁用 per-part 子列大小计算（v2.39.096ac6b1b）：ClickHouse 26.3 默认开启allow_calculating_subcolumns_sizes_for_merge_tree_reading，使 PREWHERE 规划为查询引用的每个 map 键拉取 per-part 大小——SharedMergeTree 上等于每个 (键 × 活跃 part) 一次 S3 GET，且在读取任何行之前执行，max_execution_time无法中断（LLM 仪表盘约读 64 个属性键，可能花费数分钟在规划上）。查询在服务器支持时显式发送该设置为0；
• 智能路由 rollup（v2.32.07a4ad986）：过滤器与自动补全升级为智能路由到最佳 rollup 的查询。

八、主题体系与图表调色板：chart-N 到 hue-named Token 迁移

v2.29.0（e03971b0）是主题体系的一次大规模重构：图表调色板 token 从chart-1..10重命名为按色相命名（chart-blue、chart-orange…），并在 HyperDX 与 ClickStack 两套主题间统一分类调色板（基于 Observable 10，chart-blue换成品牌蓝#437eef）。迁移设计非常工程化——五处互补的迁移点全部组合在一个共享遍历器walkRawDashboardTileColors（common-utils）之上，保证逐瓦片遍历保持一致：

1. 取/写时（React）：normalizeDashboardTileColors（packages/app/src/dashboard.ts）在读取与写入时修复旧值；无法解析的色值被保留（而非静默丢弃），让严格的服务端 schema 在下一次保存时给出清晰错误；
2. JSON 导入：DBDashboardImportPage在严格 schemasafeParse之前先跑normalizeRawDashboardTileColors，旧部署导出的模板可干净导入；
3. 服务端 GET 响应修复：getDashboards/getDashboard（packages/api/src/controllers/dashboard.ts）在出线上改写旧瓦片颜色，使非 React HTTP 客户端（CI 脚本、滚动部署中的旧 bundle、外部 API）能 GET → PATCH 往返而不复活chart-N；
4. 服务端写 shim：dashboards POST/PATCH 路由挂载请求体预处理器，在validateRequest运行ChartPaletteTokenSchema之前改写旧颜色，覆盖非 React 调用方；
5. 渲染时兜底：DBNumberChart与ColorSwatchInput对取与存之间内存构造的瓦片也调用resolveChartPaletteToken。

文档还记录了 ClickStack 旧槽位顺序与 HyperDX 不同带来的已知取舍（旧 ClickStack 的chart-1迁移后从蓝变绿），以及LEGACY_CHART_PALETTE_TOKEN_MAP放在 common-utils（与 API 共享）且迁移一次性持久化、不与浏览器 DOM 状态耦合的原因。语义 token（--color-chart-success等）在两套主题上解析一致，保证成功填充、info 级日志与多序列槽位跨品牌一致。v2.32.0（ce8fb022）继续为设计 token 增加语义组件变体（Text的warning/success、Alert的info/success/warning/danger）与满足 WCAG AA 的文字对比度调整，并配套 Storybook stories（Components/Alert、Design Tokens/Semantic Variants）。

九、会话回放：rrweb 升级与确定性重组

v2.36.0（59b96e99）把回放播放器从rrweb@2.0.0-alpha.8升级到稳定版rrweb@2.1.1，与当前@hyperdx/browser记录器对齐，并验证了旧 SDK（rrweb@1.1.3）与新 SDK（rrweb@2.1.1）录制的会话回放保真度。

v2.37.0（9155b436）修复了一个隐蔽的数据一致性 bug：当单个 rrweb 事件超过记录器约950KB 块大小时，事件会被拆分，而所有块共享同一时间戳；旧回放查询只按时间戳排序，ClickHouse 可能以任意顺序返回块，导致重组失败——被丢弃的往往是携带全部内联 CSS 的完整 DOM 快照。修复方案：

• 回放流按确定性顺序排序（rr-web.offset与rr-web.chunk作为 tiebreak）；
• 块按每事件的显式块索引重组；
• 丢弃的事件在控制台报告并在播放器中以警告指示器标记，而非静默吞掉；
• 已录制的会话无需重新采集即可正确回放；
• 被替换的回放流改为取消而非后台流完；
• 播放器从@rrweb/replay导入Replayer（rrweb 官方推荐的回放专用包，取代废弃的组合rrweb包）。

十、工程化与构建：React 19、Recharts 3、TypeScript 6、Turbopack

@hyperdx/app近年完成了一系列基础工具链升级，适合作为"渐进式升级"的参考案例：

• React 19（v2.36.0905d1941）：全面采用 React 19 的 Context 与 ref API——直接渲染<Context>而非<Context.Provider>、用usehook 替代useContext、ref 作为普通 prop 传递替代forwardRef；相应 ESLint 规则（@eslint-react/no-context-provider、no-use-context、no-forward-ref）提升为error并下调--max-warnings上限；
• Recharts 3.x（v2.31.0d137eaab）：重写图表事件处理器到 Recharts 3 事件 API（缩放刷选、点击 drill-down），把 histogram 的命令式chart.setStatetooltip 钉住 hack 换成受控的active/defaultIndexTooltip props，更新TooltipContentProps、BarProps等类型，并抑制 Recharts 3 默认accessibilityLayer的焦点环；
• TypeScript 6.0（v2.30.0bb7ae21e8跨包升级；v2.30.10dd23e86d修复css.d.ts未复制进 Docker 构建导致next build失败）；@eslint-react/naming-convention/ref-name提升为 error（v2.35.090729734）；
• Turbopack（v2.29.05e8af09be）：本地开发服务器从 Webpack 迁移到 Turbopack，显著提升构建性能与热重载速度；
• 类型检查：no-unused-vars与@typescript-eslint/ban-ts-comment提升为 error，@ts-ignore全部转为带描述的@ts-expect-error（v2.35.0018a6486）。

工程层面的发布基建也值得一提：v2.37.0（e0d29328）将 Help 菜单的 "What's new" 重建为基于发布说明的渲染——所有内容来自根 CHANGELOG.md 的发布级摘要，构建期由 next.config.mjs 解析并输出精简的public/whats-new.json，不再以资源形式打包整个 changelog；v2.39.0（25695c1a）修复了该指示器以NEXT_PUBLIC_APP_VERSION为键导致每次部署都闪 sparkle 的问题，改为以 changelog 中最新发布版本（构建期内联）为键，仅当严格新于浏览器已确认版本时提示，回滚也不会再次打扰。v2.30.0 的66f6cf0b还加入了window.hdx浏览器控制台调试句柄与 Help 菜单的 "Copy debug info" 动作（前端版本、/api/health后端版本、部署模式、用户/团队 id、特性开关、URL、屏幕信息与 RUM session id，async 字段经 getter 实时读取）。

十一、运行环境与采集侧协同：otel-collector 处理器覆盖

v2.28.0（cb6a74ce）修复了CUSTOM_OTELCOL_CONFIG_FILE无法覆盖默认memory_limiter/batch处理器的问题：管线processors:列表原本定义在 OpAMP 远端配置（packages/api/src/opamp/controllers/opampController.ts），会覆盖用户自定义配置中的processors:。现在处理器列表移入 bootstrap 配置（supervisor 模式为 docker/otel-collector/config.yaml，standalone 模式为 docker/otel-collector/config.standalone.yaml），OpAMP 远端配置不再设置这些管线的processors:，bootstrap+自定义合并生效；receivers/exporters 仍由 OpAMP 控制器动态配置。

CHANGELOG 给出了完整的覆盖示例，可直接套用——例如自定义 memory_limiter：

processors: memory_limiter/custom: check_interval: 5s limit_percentage: 75 spike_limit_percentage: 25 service: pipelines: traces: processors: [memory_limiter/custom, batch] metrics: processors: [memory_limiter/custom, batch] logs/out-default: processors: [memory_limiter/custom, transform, batch] logs/out-rrweb: processors: [memory_limiter/custom, batch]

默认memory_limiter块仍留在合并配置中但不再被任何管线引用，collector 运行时只实例化memory_limiter/custom。同一模式适用于batch（例如降低导出超时：batch/lowlatency，send_batch_size: 1000、send_batch_max_size: 2000、timeout: 500ms）。轻量级调优无需自定义配置文件：HYPERDX_OTEL_BATCH_SEND_BATCH_SIZE、HYPERDX_OTEL_BATCH_SEND_BATCH_MAX_SIZE、HYPERDX_OTEL_BATCH_TIMEOUT三个环境变量可直接调节默认 batch 处理器。同版本还将 bundled ClickHouse 升级到 clickhouse-server 26.5（b8f51ed9）。

十二、其它值得关注的修复模式

@hyperdx/app的 Patch 修复中隐藏着大量可复用的工程经验，举几例：

• SQL 注入防护（v2.39.0c98be91f）：onboarding 清单的 has-data 探针转义源表/数据库名，防止恶意命名数据源注入 SQL；
• 浮点/整数聚合合并（v2.36.09c7742fa）：UNION ALL 序列值归一为 Float64 并防御性归类纯数值Variant(...)列；
• 分块流式查询（v2.34.0d059cb20）：流式 ClickHouse 头跨块分片时保留结果行；
• 解析器括号深度追踪（v2.36.08be68100）：共享过滤器解析器在引号深度之外新增括号深度追踪，正确处理if(SeverityText IN ('error', 'fatal'), 'Errors', 'Non-errors')这类含运算符/关键字嵌套的表达式；
• 瀑布图缩放保真（v2.30.0ea27c1241）：span 条最小宽度从"事件区百分比"改为固定像素minWidth，避免缩放时短 span 被放大到与多秒 span 等宽；
• Map 列数字键下标（v2.29.021307756）：mergePath为 Map 父列输出字符串下标（Map['1']），修复Map(String, String)列上LogAttributes[2]被 ClickHouse 拒绝的问题，新增useMapColumnshook 镜像useJsonColumns；
• Lucene 语法限制（v2.28.055926e5c）：JSON 列 "Add to Filters" 不再用toString(...)包裹字段路径（Lucene 语法禁止字段名内括号），改为传干净的点号路径（JSONColumn.foo）。

十三、结语与后续跟进路径

从 v1.1.0 到 v2.39.1，@hyperdx/app的演进呈现出几条清晰主线：查询性能（mergeTreeIndex 流式浏览、mapContains/direct_read、子列成本管控）、告警体系（多目标投递、评估详情、Webhook 模板变量、连续窗口）、LLM 可观测性（读时 schema 无关解释）、基础设施即代码（Terraform 导入导出）与工程化（React 19、Recharts 3、TS 6、Turbopack、ESLint 严格化）。

若你想跟进或验证本文所述内容，建议按以下路径深入：

• 完整逐版本细节：packages/app/CHANGELOG.md（与 packages/api/CHANGELOG.md、packages/common-utils/CHANGELOG.md 对照阅读，可还原每次跨包改动）；
• LLM Dashboard 实现：packages/app/src/llm/（含测试与 fixtures）；
• 告警组件族：packages/app/src/components/alerts/；
• 查询解析与 direct_read 重写：packages/common-utils/src/queryParser.ts；
• 仪表盘瓦片颜色归一化：packages/app/src/dashboard.ts 与 packages/api/src/controllers/dashboard.ts；
• 内置仪表盘模板：packages/app/src/dashboardTemplates/（含 browser-rum.json 等）；
• Collector 管线配置：docker/otel-collector/config.yaml 与 docker/otel-collector/config.standalone.yaml。

需要说明的是：以上功能描述均以当前仓库的 CHANGELOG 与源码为据；部分性能数字（如 30ms vs 770ms、36s → 7ms、1306 → 3 granules）来自项目自身的发布记录，属于特定环境下的测量结果，不应推广为普适基准。

• 可观测性
• 云原生
• 运维