Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Helm（v1.x）

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

自定义值 (可选)

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

使用 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

生产注意事项

默认情况下，此 图表 也会安装 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

任务配置

默认情况下，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

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

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 文档

其他资源

Navigation