Helm（v1.x） - ClickHouse Documentation

已弃用 — 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 管理和身份验证设置

适用场景

概念验证
生产环境

部署步骤

前置条件

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 实例的默认连接。详情请参见 “Using 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 实例，并指定 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) ，请参阅：

配置指南 - 入口、TLS 和 Secret 管理
Cloud 部署 - 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 任务的资源请求与限制	参见 `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 部署故障排查需求，请参阅：

入口故障排查 - 静态资源服务、路径重写、浏览器问题
Cloud 部署 - GKE OpAMP 问题和 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 部署指南

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

v2.x 文档

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

其他资源

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

​适用场景

​部署步骤

​使用预配置的 Secret

​创建自定义 Secret

​引用 Secret

​使用 ClickHouse Cloud

​生产注意事项

​任务配置

​升级 Helm 图表

​卸载 ClickStack

​故障排查

​查看日志

​调试安装失败问题

​验证部署

​schema 选择：Map 与 JSON

​相关文档

​v1.x 部署指南

​v2.x 文档

​其他资源

适用场景

部署步骤

使用预配置的 Secret

创建自定义 Secret

引用 Secret

使用 ClickHouse Cloud

生产注意事项

任务配置

升级 Helm 图表

卸载 ClickStack

故障排查

查看日志

调试安装失败问题

验证部署

schema 选择：Map 与 JSON

相关文档

v1.x 部署指南

v2.x 文档

其他资源