Helm

图表迁移

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

ClickStack 的 Helm 图表可以在这里找到，是生产环境部署的推荐方式。

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

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

不过，您可以轻松自定义它，以集成到现有的 ClickHouse 部署中——例如托管在 ClickHouse Cloud 上的部署。

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

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

适用场景

概念验证
生产环境

部署步骤

前提条件

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

添加 ClickStack Helm 仓库

添加 ClickStack Helm 仓库:

helm repo add clickstack https://clickhouse.github.io/ClickStack-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 secrets。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 实例，并配置 Cloud 凭据：

# specify ClickHouse Cloud credentials
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # full https url
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# how to overwrite default connection
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": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]

helm install my-clickstack clickstack/clickstack -f values.yaml
# or if installed...
# 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 设置以及特定 Cloud 提供商（GKE、EKS、AKS）相关配置在内的生产环境部署，请参见：

Configuration Guide - 入口、TLS 与 Secret 管理
Cloud Deployments - Cloud 专用设置与生产环境检查清单

任务配置

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

Parameter	Description	Default
`tasks.enabled`	在集群中启用/禁用 cron 任务。默认情况下，HyperDX 镜像会在进程内运行 cron 任务。如果你更希望在集群中使用单独的 cron 任务，请将其设置为 true。	`false`
`tasks.checkAlerts.schedule`	`check-alerts` 任务的 cron 调度计划	`/1 * * *`
`tasks.checkAlerts.resources`	`check-alerts` 任务的资源请求和限制（requests 和 limits）	参见 `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 问题或 Cloud 部署的故障排查，请参阅：

Ingress 故障排查 - 资源服务、路径重写、浏览器相关问题
Cloud 部署 - GKE OpAMP 问题和特定于 Cloud 的问题

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（仅适用于 ClickStack 开源版）- 在 ClickStack UI 应用中启用支持，允许查询 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 密钥、机密信息和入口（Ingress）配置
Cloud 部署 - GKE、EKS、AKS 配置及生产环境最佳实践

其他资源

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

适用场景​

部署步骤​

前提条件​

添加 ClickStack Helm 仓库​

安装 ClickStack​

验证安装​

端口转发​

访问 UI 界面​

自定义配置值(可选)​

使用 Secret(可选)​

使用预配置的 Secret​

创建自定义 Secret​

引用 Secret​

使用 ClickHouse Cloud​

生产环境注意事项​

任务配置​

升级 chart​

卸载 ClickStack​

故障排查​

查看日志​

排查安装失败问题​

验证部署​

JSON 类型支持​

相关文档​

部署指南​

其他资源​