HyperDX 2.41.0 介绍与选型指南

目标：讲清 HyperDX（ClickStack）是什么、由哪些组件构成、有哪些功能特性，并以量化数据给出与 SigNoz、Grafana LGTM 栈、Jaeger 的选型对比结论。本篇为纯联网溯源篇，全部版本号、星数、功能描述均标注来源与查询日期（2026-10-23），不含本地实测数据；本专栏的部署、配置、CLI 实测见 《HyperDX 2.41.0 Docker Compose 部署指南》、《HyperDX 2.41.0 配置参数详解》、《HyperDX 2.41.0 常用 CLI 命令详解》 三篇。

一、环境信息

本篇是「认知与选型」篇，不依赖具体实验环境，所有事实均来自官方公开渠道的联网溯源，逐项标注来源与查询日期：

• 溯源对象：HyperDX，官方仓库 hyperdxio/hyperdx，官网 hyperdx.io，产品文档托管于 ClickHouse 官方文档站 clickhouse.com/docs/clickstack
• 版本取证：GitHub Releases Atom 流 https://github.com/hyperdxio/hyperdx/releases.atom，查询日期 2026-10-23，当前稳定版 2.41.0（发布于 2026-10-13）。注意该仓库是多子项目单仓：@hyperdx/app（UI+API）、@hyperdx/api、otel-collector 镜像按同一版本号波次同步发版，@hyperdx/cli（hdx 命令行）则独立按 0.x 版本演进（当前 v0.7.0，npm @hyperdx/cli，2026-10-23 查询）
• 星数取证：shields.io 实时徽章数据，查询日期 2026-10-23，hyperdxio/hyperdx 约 10k stars
• 许可证取证：MIT（仓库 LICENSE 与 badgen.net 许可徽章一致），查询日期 2026-10-23；项目为单仓全 MIT，无 CE/EE 双轨
• 项目归属：HyperDX 于 2025 年 6 月被 ClickHouse Inc. 收购，其 v2 版本以 ClickStack（"The ClickHouse Observability Stack"）品牌与 ClickHouse 官方文档体系一同发布，镜像发布通道从早期的 docker.hyperdx.io/hyperdx/* 迁移为 clickhouse/clickstack-*（来源：ClickHouse 官方博客与 ClickStack 文档 All-in-One 页的镜像更名说明，查询日期 2026-10-23）；GitHub 仓库仍为 hyperdxio/hyperdx，HyperDX 作为 ClickStack 的查询与可视化组件继续独立演进

二、软件概述

HyperDX 是一个开源的全栈可观测性平台：把**日志、指标、链路追踪、会话回放（Session Replay）**四类遥测数据放进同一个 ClickHouse 存储与同一个查询界面，定位是帮助工程师"快速弄清生产环境为什么出问题"。官方 README 对它的自述非常直白——"search & visualize logs and traces on top of any ClickHouse cluster (imagine Kibana, for ClickHouse)"，即「ClickHouse 界的 Kibana」。它有两个鲜明的技术特征：

1. OpenTelemetry 原生接入 + ingest key 认证：数据接入层内建官方 OTel Collector 发行版（clickhouse/clickstack-otel-collector），应用侧只需对接 OTLP 协议（gRPC 4317 / HTTP 4318），请求头携带团队级 ingest key 即可写入，无厂商锁定。
2. ClickHouse 单一宽事件存储：四类信号统一落 ClickHouse 表（otel_logs / otel_traces / otel_metrics 等），属性以 Map(LowCardinality(String), String) 列存储；依托列存与高压缩比（官方宣称可观测数据压缩比 ≥10x）实现"亚秒级检索、低成本长留存"。

关键事实速览（全部为联网溯源，查询日期 2026-10-23）：

💡 说明：HyperDX 与 SigNoz 同属「OpenTelemetry 原生 + ClickHouse 统一存储」路线，是选型时最常被放在一起对比的两个候选，完整对比见第七节；站内 SigNoz 全系列见《SigNoz v0.146.0 介绍与选型指南》。

三、核心架构

ClickStack 开源版的单机部署由 4 类服务构成（来源：clickhouse.com/docs/clickstack 架构页与官方仓库 docker-compose.yml，查询日期 2026-10-23）：

架构上有两个值得注意的设计（来源：ClickStack 官方文档，查询日期 2026-10-23）：

• collector 配置动态化（OpAMP）：静态配置文件只声明 processors，OTLP receiver 由 HyperDX app 通过 OpAMP 通道在运行时下发——这是它与"手写 receiver 配置"的传统 OTel 部署最大的差别，也意味着对 collector 做 validate 静态校验时动态 receiver 部分必然缺席（校验三场景的实测见 《HyperDX 2.41.0 常用 CLI 命令详解》第六章）。
• 状态与数据分离：事件数据全在 ClickHouse，应用状态全在 MongoDB，二者各自独立备份；ClickHouse 数据默认带 30 天 TTL（2.41.0 默认 schema），留存策略一张表一条语句可调。

部署形态（来源：clickhouse.com/docs/clickstack/deployment，查询日期 2026-10-23）：

• All-in-One 单容器：clickhouse/clickstack-all-in-one 把四个组件打包进一个容器，官方明确定位为演示与本地测试，不建议生产使用；
• Docker Compose：官方仓库提供 docker-compose.yml 起 4 服务栈，是自托管的标准形态（本专栏 B2 篇即按此部署）；
• Helm：chart 名 hdx-oss-v2，面向 Kubernetes；
• Local Mode：去掉认证的纯本地 UI 形态，用于快速体验。

四、功能特性

（来源：clickhouse.com/docs/clickstack 功能说明与官方仓库 README，查询日期 2026-10-23；部署/配置细节的实测验证见本专栏 《Docker Compose 部署指南》、《配置参数详解》、《常用 CLI 命令详解》 三篇）

1. 四类信号一体接入：OTLP 统一收 logs/metrics/traces，加上浏览器 SDK 采集的 Session Replay 会话回放——会话回放与后端日志/追踪在同一个界面里互跳，是 HyperDX 区别于 SigNoz/LGTM 栈的招牌能力。
2. Lucene 风格 + 自然语言搜索：搜索栏支持 Lucene 语法（level:error AND service:checkout 一类），同时提供自然语言查询入口，由界面把自然语言翻译成结构化查询/SQL。
3. Live Tail 实时尾随：日志视图内建实时流式尾随，部署后可直接观察新到数据。
4. 属性级互跳（Property Drilldown）：日志/追踪/指标共享 ClickHouse 属性模型，任意属性值点击即可下钻、反向过滤、跳转到关联追踪或会话，"从一条报错日志跳到所属 trace"是内建路径而非插件拼装。
5. 仪表盘与告警：查询构建器驱动的仪表盘，图表可直接转为告警规则；告警支持指标、日志频次等类型，状态存 MongoDB。
6. SQL 直查：内置 ClickHouse SQL 查询面板，绕过构建器直接写 SQL 分析四类数据表——对已有 ClickHouse 经验的团队，这是"零学习成本"的兜底分析通道。
7. Schema 兼容既有 ClickHouse：官方定位 "schema agnostic"，可对接已有 ClickHouse 集群与表结构（UI 侧通过 Connection + Source 两级配置映射表与时间列）；默认 Map 列 schema 之外提供 JSON 类型 schema（beta，官方不推荐作为默认）。
8. hdx CLI 与外部 API：@hyperdx/cli（hdx 命令）提供 auth/connections/sources/query/chart/team 等子命令，终端内直接查询与画 ANSI 图；平台暴露 /api/v2 外部 API（Bearer accessKey 认证），可编程检索数据与管理 Source。
9. OpAMP 动态配置 collector：collector 的 receiver 在运行时由 HyperDX app 通过 OpAMP 下发，UI 侧改配置无需手工改 collector 文件重启。

五、快速开始（最小可用示例）

官方推荐的最低成本路径是 all-in-one 单容器（来源：clickhouse.com/docs/clickstack/deployment/all-in-one 与 getting-started/oss 页，查询日期 2026-10-23；以下命令为官方文档原文，本专栏 B2 篇已对完整流程做了逐条实测）：

1. 启动 all-in-one 容器（UI 8080、OTLP 4317/4318）：

docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest

2. 浏览器访问 http://localhost:8080，注册首个用户（官方密码策略要求 ≥12 位、含大小写与特殊字符），点击 Create 后自动创建连接内置 ClickHouse 的四类数据源；
3. 在左侧 Add Data 页复制 Ingestion API Key——发往内置 collector 的遥测必须携带它；
4. 用 curl 向 OTLP HTTP 端点发一条测试日志（authorization 头直接填 ingest key，注意不是 Bearer 前缀）：

curl -i "http://localhost:4318/v1/logs" \
  -H "Content-Type: application/json" \
  -H "authorization: ${CLICKSTACK_API_KEY}" \
  --data-binary @- <<EOF
{
  "resourceLogs": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "clickstack-docs-test"}
      }]
    },
    "scopeLogs": [{
      "scope": {"name": "clickstack-docs-test"},
      "logRecords": [{
        "timeUnixNano": "$(date +%s)000000000",
        "severityText": "INFO",
        "body": {"stringValue": "ClickStack ingestion test"}
      }]
    }]
  }]
}
EOF

5. 在 Search 视图搜索 ClickStack ingestion test，看到该条日志即完成接入闭环。

💡 说明：以上为官方文档的标准流程摘录。生产形态的 4 服务 Compose 部署（ClickHouse/HyperDX/collector/MongoDB 分容器、数据持久化、端口规划、排障实录）见本专栏《HyperDX 2.41.0 Docker Compose 部署指南》。

六、适用场景与限制

适合：

• 已有 ClickHouse 运维经验或已在使用 ClickHouse 做分析的团队——HyperDX 可以直接建在现有集群上，不引入第二套存储；
• 想用一个自托管平台同时管日志、指标、追踪，且前后端问题需要联合排查（会话回放 + 后端 trace 互跳）的业务团队；
• 对 Datadog/New Relic 账单敏感、向 OpenTelemetry 标准迁移的团队；
• 喜欢终端工作流的团队——hdx CLI 可以在终端里完成查询与出图。

需要再评估：

• 社区规模：10k stars 相比 SigNoz 32k、Jaeger 23k 仍属年轻项目，ClickHouse 收购后发版与文档建设明显加速，但大规模生产案例积累相对少；
• 纯单信号诉求：只需要分布式追踪选 Jaeger，只需要 Prometheus 长期存储选 Thanos/Mimir，都不必引入整套 ClickStack；
• 多组件运维成本：栈内含 ClickHouse + MongoDB 两个有状态组件，最小生产集 4 容器，比单二进制的方案重；
• MongoDB 版本：官方 Compose 固定 mongo:5.0.32-focal，自有 MongoDB 运维规范若已统一到更高版本，需要评估兼容与升级路径。

七、同类选型对比

自托管可观测平台最常见的四个候选路线对比如下（星数均取自 shields.io，查询日期 2026-10-23；其余维度取自各项目官方文档，查询日期同）：

量化判断依据：

1. 同为 ClickHouse 路线时看信号广度与许可：HyperDX 与 SigNoz 都是"OTLP 原生 + ClickHouse 存储"，核心差异有三——HyperDX 多会话回放、许可为纯 MIT（SigNoz EE 部分企业特性另算）、组件少两个（SigNoz 额外引入 Keeper 与 PostgreSQL）；SigNoz 社区规模更大（32k vs 10k）、告警与仪表盘生态更成熟。二者都是"一个平台管四类/三类数据"的整层替代方案。
2. 追踪单独诉求：只解决分布式追踪、已有 Grafana 展示层时，Jaeger（23k stars、Apache-2.0）更轻，不必为会话回放与日志检索引入 ClickStack 全栈。
3. 存量 Grafana 团队：已深度绑定 Grafana 生态且 Loki/Tempo 运维成熟的团队，迁移到 LGTM 栈之外的整栈（HyperDX/SigNoz）意味着查询语言（LogQL/TraceQL）与仪表盘资产的双重迁移成本；HyperDX 的 SQL 直查对分析型团队是加分项，对看板驱动型团队则是习惯切换。
4. 前端问题排查占比高的业务（电商、SaaS、内容站点）：会话回放与后端日志/追踪同界面互跳，这一项能力在开源整栈里只有 HyperDX 内建，可直接按"是否需要回放"做一票决策。

结论：HyperDX（ClickStack）是"ClickHouse 统一存储 + 四信号一体 + 会话回放"路线中目前唯一成熟的开源整栈，MIT 许可与官方 collector 发行版使其在合规与接入标准化上无负担；它与 SigNoz 的选择本质是「会话回放 + 更简组件 + 纯 MIT」对「更大社区 + 更成熟告警生态」的取舍。若两者都在候选，建议用一小时的 all-in-one 容器分别跑通各自的最小闭环再做决定——部署路径与实测请继续阅读本专栏《HyperDX 2.41.0 Docker Compose 部署指南》。

八、参考链接

• 官方网站：https://hyperdx.io
• ClickStack 产品文档：https://clickhouse.com/docs/clickstack
• GitHub 仓库：https://github.com/hyperdxio/hyperdx
• Releases 订阅：https://github.com/hyperdxio/hyperdx/releases.atom
• 星数徽章接口：https://img.shields.io/github/stars/hyperdxio/hyperdx.json
• All-in-One 部署文档：https://clickhouse.com/docs/clickstack/deployment/all-in-one
• 官方 Docker Compose 编排：https://github.com/hyperdxio/hyperdx/blob/main/docker-compose.yml
• 以上外部链接查询日期均为 2026-10-23
• 本专栏系列：《HyperDX 2.41.0 Docker Compose 部署指南》、《HyperDX 2.41.0 配置参数详解》、《HyperDX 2.41.0 常用 CLI 命令详解》
• 站内同类对比：《SigNoz v0.146.0 介绍与选型指南》