Helm 部署

Helm 图表迁移

如果您当前正在使用 hdx-oss-v2 Helm 图表，请迁移到 clickstack Helm 图表。hdx-oss-v2 图表目前处于维护模式，将不再新增功能。所有新的开发工作都集中在 clickstack 图表上，它在提供相同功能的同时改进了命名并具有更清晰的结构组织。

HyperDX 的 Helm 图表可以在此处获取，这是生产环境部署的推荐方式。

默认情况下，Helm 图表会部署所有核心组件，包括：

ClickHouse
HyperDX
OpenTelemetry (OTel) collector
MongoDB（用于持久化应用状态）

同时，您也可以轻松自定义该图表，以集成到已有的 ClickHouse 部署中——例如托管在 ClickHouse Cloud 上的部署。

该 Helm 图表支持标准的 Kubernetes 最佳实践，包括：

通过 values.yaml 进行按环境配置
资源限制和 pod（容器组）级别的扩缩容
TLS 和入口配置
Secrets 管理和认证设置

适用场景

概念验证（PoC）
生产环境

部署步骤

前提条件

Helm v3 及以上版本
Kubernetes 集群（建议使用 v1.20 及以上版本）
已配置好用于与集群交互的 kubectl

添加 ClickStack Helm 仓库

添加 ClickStack Helm 仓库：

helm repo add clickstack https://hyperdxio.github.io/helm-charts
helm repo update

安装 ClickStack

使用默认值安装 ClickStack Chart：

helm install my-clickstack clickstack/clickstack

验证安装

验证安装:

kubectl get pods -l "app.kubernetes.io/name=clickstack"

当所有 Pod（容器组）就绪后，继续操作。

转发端口

端口转发可用于访问和配置 HyperDX。生产环境部署时,应通过入口或负载均衡器暴露服务,以确保正确的网络访问、TLS 终止和可扩展性。端口转发仅适用于本地开发或临时管理任务,不适合长期运行或高可用性环境。

kubectl port-forward \
  pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
  8080:3000

生产环境入口配置

在生产环境部署时,应配置带 TLS 的入口,而非使用端口转发。详细配置说明请参阅入口配置指南。

导航至 UI 界面

访问 http://localhost:8080 以访问 HyperDX UI。

创建用户，提供符合要求的用户名和密码。

点击 Create 后,将为使用 Helm 图表部署的 ClickHouse 实例创建数据源。

覆盖默认连接

您可以覆盖集成 ClickHouse 实例的默认连接。详情请参阅"使用 ClickHouse Cloud"。

有关使用其他 ClickHouse 实例的示例，请参阅"创建 ClickHouse Cloud 连接"。

自定义配置值(可选)

您可以通过 --set 标志自定义设置。例如：

helm install my-clickstack clickstack/clickstack --set key=value

或者,编辑 values.yaml 文件。获取默认值的方法如下:

helm show values clickstack/clickstack > values.yaml

配置示例：

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

helm install my-clickstack clickstack/clickstack -f values.yaml

使用 Secret(可选)

对于处理 API 密钥或数据库凭据等敏感数据,请使用 Kubernetes Secret。HyperDX Helm 图表提供了默认的 Secret 文件,您可以修改并应用到集群中。

使用预配置的 Secret

该 Helm 图表包含一个默认的 secret 模板，位于 charts/clickstack/templates/secrets.yaml。该文件提供了管理 secret 的基础结构。

如果需要手动应用 Secret,请修改并应用所提供的 secrets.yaml 模板:

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

将 Secret 应用到集群：

kubectl apply -f secrets.yaml

创建自定义 Secret

如果需要,您也可以手动创建自定义 Kubernetes Secret:

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

引用 Secret

在 values.yaml 中引用 Secret：

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

API 密钥管理

有关 API 密钥设置的详细说明（包括多种配置方法和 pod（容器组）重启步骤），请参阅 API 密钥设置指南。

使用 ClickHouse Cloud

如果使用 ClickHouse Cloud，应禁用由 Helm 图表部署的 ClickHouse 实例，并配置 ClickHouse Cloud 凭证：

# 指定 ClickHouse Cloud 凭证
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # 完整的 HTTPS URL
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# 如何覆盖默认连接配置
helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} \
  --set clickhouse.config.users.otelUser=${CLICKHOUSE_USER} \
  --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD}

或者使用 values.yaml 文件：

clickhouse:
  enabled: false
  persistence:
    enabled: false
  config:
    users:
      otelUser: ${CLICKHOUSE_USER}
      otelUserPassword: ${CLICKHOUSE_PASSWORD}

otel:
  clickhouseEndpoint: ${CLICKHOUSE_URL}

hyperdx:
  defaultConnections: |
    [
      {
        "name": "外部 ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]

helm install my-clickstack clickstack/clickstack -f values.yaml
# 或者如果已安装...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

高级外部配置

对于在生产环境中使用基于 Secret 的配置、外部 OTel collector，或精简部署方案的场景，请参阅 Deployment Options 指南。

生产环境说明

默认情况下，该 chart 还会安装 ClickHouse 和 OTel collector。不过，在生产环境中，建议分别单独管理 ClickHouse 和 OTel collector。

要禁用 ClickHouse 和 OTel collector，请设置以下参数：

helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false

生产环境最佳实践

有关生产环境部署（包括高可用配置、资源管理、入口/TLS 配置以及云平台特定配置（GKE、EKS、AKS）），请参阅：

配置指南 - 入口、TLS 和 Secrets 管理
云上部署 - 云平台特定设置与生产环境检查清单

任务配置

默认情况下，chart 中配置了一个以 CronJob 形式运行的任务，用于检查是否需要触发告警。以下是其配置选项：

参数	描述	默认值
`tasks.enabled`	在集群中启用或禁用 cron 任务。默认情况下，HyperDX 镜像会在进程内运行 cron 任务。如希望在集群中使用单独的 cron 任务，请将其设置为 true。	`false`
`tasks.checkAlerts.schedule`	`check-alerts` 任务的 cron 调度表达式	`/1 * * *`
`tasks.checkAlerts.resources`	`check-alerts` 任务的资源请求和限制	参见 `values.yaml`

升级 chart

要升级到较新版本：

helm upgrade my-clickstack clickstack/clickstack -f values.yaml

查看可用的 chart 版本：

helm search repo clickstack

卸载 ClickStack

若要移除该部署：

helm uninstall my-clickstack

这将删除与该发布关联的所有资源，但持久化数据（如有）可能会保留。

故障排查

查看日志

kubectl logs -l app.kubernetes.io/name=clickstack

排查安装失败

helm install my-clickstack clickstack/clickstack --debug --dry-run

验证部署

kubectl get pods -l app.kubernetes.io/name=clickstack

其他故障排查资源

针对 Ingress 相关问题、TLS 问题或云端部署故障排查，请参阅：

Ingress 故障排查 - 静态资源服务、路径重写、浏览器问题
云端部署 - GKE OpAMP 问题和云环境特有的问题

JSON 类型支持

Beta feature. Learn more.

Beta 功能 - 尚未准备好用于生产环境

ClickStack 中的 JSON 类型支持目前为 Beta 功能。虽然 JSON 类型本身在 ClickHouse 25.3+ 中已经可以用于生产环境，但其在 ClickStack 中的集成仍在积极开发中，可能存在功能限制、未来变更或缺陷。

从 2.0.4 版本开始，ClickStack 对 JSON 类型提供 Beta 支持。

关于此类型的优势，请参见 JSON 类型的优势。

要启用对 JSON 类型的支持，用户必须设置以下环境变量：

OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' - 在 OTel collector 中启用支持，确保使用 JSON 类型创建模式（schema）。
BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true - 在 HyperDX 应用中启用支持，允许查询 JSON 数据。

用户可以通过参数或 values.yaml 文件来设置这些环境变量，例如：

values.yaml

hyperdx:
  ...
  env:
    - name: BETA_CH_OTEL_JSON_SCHEMA_ENABLED
      value: "true"

otel:
  ...
  env:
    - name: OTEL_AGENT_FEATURE_GATE_ARG
      value: "--feature-gates=clickhouse.json"

也可以通过 --set：

helm install my-clickstack clickstack/clickstack \
  --set "hyperdx.env[0].name=BETA_CH_OTEL_JSON_SCHEMA_ENABLED" \
  --set "hyperdx.env[0].value=true" \
  --set "otel.env[0].name=OTEL_AGENT_FEATURE_GATE_ARG" \
  --set "otel.env[0].value=--feature-gates=clickhouse.json"

部署指南

部署选项 - 外部 ClickHouse、OTel collector 和最小部署
配置指南 - API 密钥、Secrets 和入口设置
云端部署 - GKE、EKS、AKS 配置和生产环境最佳实践

其他资源

ClickStack 入门指南 - ClickStack 简介
ClickStack Helm 图表仓库 - 图表源码和值配置参考
Kubernetes 文档 - Kubernetes 参考文档
Helm 文档 - Helm 参考文档

适用场景​

部署步骤​

前提条件​

添加 ClickStack Helm 仓库​

安装 ClickStack​

验证安装​

转发端口​

导航至 UI 界面​

自定义配置值(可选)​

使用 Secret(可选)​

使用预配置的 Secret​

创建自定义 Secret​

引用 Secret​

使用 ClickHouse Cloud​

生产环境说明​

任务配置​

升级 chart​

卸载 ClickStack​

故障排查​

查看日志​

排查安装失败​

验证部署​

JSON 类型支持​

相关文档​

部署指南​

其他资源​