Helm（v1.x）

已弃用 — v1.x 图表

本页面介绍 v1.x 内联模板 Helm 图表。该图表目前处于维护模式，不会再增加新功能。对于新部署，请使用 v2.x 图表。如需迁移现有的 v1.x 部署，请参阅升级指南。

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 的入口，而不要使用端口转发。有关详细设置说明，请参阅入口配置指南。

进入界面

访问 http://localhost:8080 以打开 HyperDX 界面。

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

点击 Create 后，将为通过 Helm 图表部署的 ClickHouse 实例创建数据源。

重写默认连接

您可以重写连接到集成 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 凭据：

# 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 或精简部署的生产环境，请参阅部署选项指南。

生产环境说明

默认情况下，此图表还会安装 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) ，请参阅：

配置指南 - 入口、TLS 及密钥管理
Cloud 部署 - Cloud 特定设置和生产环境检查清单

任务配置

默认情况下，图表配置中有一个以 CronJob 形式运行的任务，负责检查是否应触发告警。以下是其配置选项：

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

升级图表

要升级到新版本：

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

要查看可用的图表版本：

helm search repo clickstack

升级到 v2.x

如果要迁移到基于 v2.x 子图表的图表，请参阅升级指南获取迁移说明。这是一项破坏性变更，不支持原地执行 helm upgrade。

卸载 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

更多故障排查资源

对于入口相关问题、TLS 问题或云部署故障排查，请参阅：

入口故障排查 - 静态资源服务、路径重写、浏览器问题
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"

v1.x 部署指南

部署选项 (v1.x) - 外部 ClickHouse、OTel collector 和精简部署
配置指南 (v1.x) - API 密钥、Secrets 和入口配置
Cloud 部署 (v1.x) - GKE、EKS、AKS 配置和生产环境最佳实践

v2.x 文档

Helm (v2.x) - v2.x 部署指南
升级指南 - 从 v1.x 升级到 v2.x

适用场景​

部署步骤​

前提条件​

添加 ClickStack Helm 仓库​

安装 ClickStack​

验证安装​

端口转发​

进入界面​

自定义值 (可选)​

使用 Secret (可选)​

使用预配置的 Secret​

创建自定义 Secret​

引用 Secret​

ClickHouse Cloud 的使用​

生产环境说明​

任务配置​

升级 图表​

卸载 ClickStack​

故障排查​

查看日志​

调试安装失败​

验证部署​

JSON 类型支持​

相关文档​

v1.x 部署指南​

v2.x 文档​

更多资源​