跳转到主要内容
已弃用 — 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 和入口配置
  • Secrets 管理和身份验证设置

​
适用场景

  • 概念验证
  • 生产环境

​
部署步骤


1

​
前置条件

  • Helm v3+
  • Kubernetes 集群 (推荐使用 v1.20+)
  • 已配置为与你的集群进行交互的 kubectl
2

​
添加 ClickStack 的 Helm 仓库

添加 ClickStack 的 Helm 仓库：
helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
helm repo update
3

​
安装 ClickStack

要使用默认值安装 ClickStack Chart：
helm install my-clickstack clickstack/clickstack
4

​
验证安装

确认安装是否成功：
kubectl get pods -l "app.kubernetes.io/name=clickstack"
当所有 Pod (容器组) 都就绪后，即可继续。
5

​
端口转发

通过端口转发，我们可以访问并配置 HyperDX。部署到生产环境时，建议改为通过入口或负载均衡器暴露该服务，以确保网络访问、TLS 终止和可扩展性都得到妥善保障。端口转发最适合用于本地开发或一次性的管理操作，不适用于长期运行或高可用环境。
kubectl port-forward \
  pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
  8080:3000
生产环境入口设置在生产环境中，建议使用启用 TLS 的入口配置，而不是端口转发。详细设置说明请参阅入口配置指南。
6

​
进入 UI

访问 http://localhost:8080 以打开 HyperDX UI。创建用户时，请提供符合要求的用户名和密码。点击 Create 后，将为通过 Helm 图表部署的 ClickHouse 实例创建数据源。
覆盖默认连接你可以覆盖集成的 ClickHouse 实例的默认连接。详情请参见 “Using ClickHouse Cloud”。
7

​
自定义值 (可选)

您可以使用 --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
8

​
使用 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 实例，并指定 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": "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
# 或者如果已经安装过...
# 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) ，请参阅：

​
任务配置

默认情况下，Chart 配置中有一个以 CronJob 形式运行的任务，负责检查是否应触发告警。以下是它的配置选项：
ParameterDescriptionDefault
tasks.enabled在集群中启用/禁用 cron 任务。默认情况下，HyperDX 镜像会在进程内运行 cron 任务。如果你更希望在集群中使用独立的 cron 任务，请将其设为 true。false
tasks.checkAlerts.schedulecheck-alerts 任务的 Cron 调度计划*/1 * * * *
tasks.checkAlerts.resourcescheck-alerts 任务的资源请求与限制参见 values.yaml

​
升级 Helm 图表

要升级到更新的版本： 
helm upgrade my-clickstack clickstack/clickstack -f values.yaml
查看可用的 图表 版本： 
helm search repo clickstack
升级到 v2.x如果你想迁移到基于子 图表 的 v2.x 图表，请参阅升级指南获取迁移说明。这是一项破坏性变更——不支持就地执行 helm upgrade。

​
卸载 ClickStack

要删除该部署： 
helm uninstall my-clickstack
这将删除与该 release 关联的所有资源，但持久化数据 (如有) 可能仍会保留。

​
故障排查

​
查看日志

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 部署故障排查需求，请参阅：

​
schema 选择：Map 与 JSON

默认情况下，ClickStack 将属性存储为 Map(LowCardinality(String), String) 列。这是可观测性 workloads 推荐使用的 schema。结合 bucketed map serialization 以及针对 map 键和值的文本索引，它可以实现有针对性的 lookup，同时避免动态 JSON 子列逐键摄取带来的额外开销。 JSON 类型的 schema 也已提供，目前处于 Beta 阶段，适合在属性键集合较小且稳定的 workloads 上进行评估。不建议将其作为默认选项。有关完整对比以及启用 JSON 支持所需的环境变量，请参见 Map vs JSON type。

​
v1.x 部署指南

​
v2.x 文档

​
其他资源

最后修改于 2026年6月10日