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 问题和云环境专用问题

schema 选择：Map 与 JSON

默认情况下，ClickStack 将属性存储为 Map(LowCardinality(String), String) 列。这是可观测性工作负载的推荐 schema。结合分桶化 Map 序列化以及 Map 键和值上的文本索引，它可以实现有选择的查找，而无需承担动态 JSON 子列为每个键带来的额外摄取开销。

JSON 类型的 schema 提供 Beta 版本，可用于评估属性键集合较小且稳定的工作负载。不建议将其作为默认选项。有关完整对比以及启用 JSON 支持所需的环境变量，请参见 Map 与 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 入门指南 - ClickStack 简介
• ClickStack Helm 图表代码仓库 - 图表源码和 values 参考
• Kubernetes 文档 - Kubernetes 参考文档
• Helm 文档 - Helm 参考文档