跳转到主要内容
本指南介绍如何从内联模板 ClickStack Helm 图表 (v1.x) 迁移到基于子图表的架构 (v2.x) 。这是一次破坏性变更：它将把手动维护的 Kubernetes 资源替换为由 Operator 管理的 MongoDB 和 ClickHouse 自定义资源，并使用官方的 OpenTelemetry Collector Helm 图表。
破坏性变更v2.x 图表与 v1.x 不向后兼容，不支持就地执行 helm upgrade。我们建议在现有部署旁边进行一次全新安装并迁移数据，而不是尝试就地升级。

​
前置条件

  • 升级前请先备份数据 (MongoDB、ClickHouse PVC)
  • 检查当前的 values.yaml 覆盖配置——大多数键已迁移或重命名

​
分两阶段安装

v2.x chart 采用分两阶段的安装方式。必须先安装 Operator (用于注册 CRD) ，再安装主 chart (用于创建 CR) ： 
# 阶段 1：安装 operators 和 CRDs
helm install clickstack-operators clickstack/clickstack-operators

# 阶段 2：安装 ClickStack
helm install my-clickstack clickstack/clickstack
按相反顺序进行卸载： 
helm uninstall my-clickstack
helm uninstall clickstack-operators

​
数据持久化

由 MongoDB 和 ClickHouse Operator 创建的 PersistentVolumeClaims 在执行 helm uninstall 时不会被删除。这是有意为之，旨在防止意外的数据丢失。要在卸载后清理 PVC，请参阅：

​
存储类

global.storageClassName 和 global.keepPVC 已移除。现在可直接在各个 Operator 的 CR spec 中配置存储类： 
mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - spec:
              storageClassName: "fast-ssd"

clickhouse:
  keeper:
    spec:
      dataVolumeClaimSpec:
        storageClassName: "fast-ssd"
  cluster:
    spec:
      dataVolumeClaimSpec:
        storageClassName: "fast-ssd"

​
变更内容

ComponentBefore (v1.x)After (v2.x)
MongoDB内联部署 + Service + PVC由 MongoDB Kubernetes Operator (MCK) 管理 MongoDBCommunity CR
ClickHouse内联部署 + Service + ConfigMaps + PVCs由 ClickHouse Operator 管理 ClickHouseCluster + KeeperCluster CR
OTel collector内联部署 + Service (otel.* 块)官方 OpenTelemetry Collector Helm 图表 (otel-collector: 子图表)
HyperDX valueshyperdx.* 下的扁平键，以及顶层 tasks: 和 appUrl在 hyperdx.* 下按 K8s 资源类型重新组织 (见下文)
hdx-oss-v2已弃用的旧版 Helm 图表已完全移除

​
HyperDX Values 重组

hyperdx: 块现已按 Kubernetes 资源类型重新组织： 
hyperdx:
  ports:          # 共享端口号（Deployment、Service、ConfigMap、Ingress）
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"   # 替代已移除的 appUrl

  config:         # → clickstack-config ConfigMap（非敏感环境变量）
    APP_PORT: "3000"
    HYPERDX_LOG_LEVEL: "info"

  secrets:        # → clickstack-secret Secret（敏感环境变量）
    HYPERDX_API_KEY: "..."
    CLICKHOUSE_PASSWORD: "otelcollectorpass"
    CLICKHOUSE_APP_PASSWORD: "hyperdx"
    MONGODB_PASSWORD: "hyperdx"

  deployment:     # K8s Deployment 规范（镜像、副本、探针等）
  service:        # K8s Service 规范（类型、注解）
  ingress:        # K8s Ingress 规范（主机、TLS、注解）
  podDisruptionBudget:  # K8s PDB 规范
  tasks:          # K8s CronJob 规范（之前为顶层 tasks:）

​
关键调整

之前 (v1.x)之后 (v2.x)
appUrl已移除。请改用 hyperdx.frontendUrl (默认为 http://localhost:3000)
tasks.* (顶层)hyperdx.tasks.*
mongodb.passwordhyperdx.secrets.MONGODB_PASSWORD
clickhouse.config.users.appUserPasswordhyperdx.secrets.CLICKHOUSE_APP_PASSWORD
clickhouse.config.users.otelUserPasswordhyperdx.secrets.CLICKHOUSE_PASSWORD
otel.* 环境变量覆盖hyperdx.config.* (非敏感) 和 hyperdx.secrets.* (敏感)

​
统一的 ConfigMap 和 Secret

现在，所有环境变量都会通过两个名称固定的资源统一传递，HyperDX 部署 以及 OTel collector 都通过 envFrom 共享这两个资源：
  • clickstack-config ConfigMap — 从 hyperdx.config 填充
  • clickstack-secret Secret — 从 hyperdx.secrets 填充
不再单独提供 OTel 专用的 ConfigMap。两个工作负载都从相同的来源读取。

​
MongoDB 迁移

​
已移除的配置值

以下 mongodb.* 配置值已被移除： 
# 已移除 — 请勿使用
mongodb:
  image: "..."
  port: 27017
  strategy: ...
  nodeSelector: {}
  tolerations: []
  livenessProbe: ...
  readinessProbe: ...
  persistence:
    enabled: true
    dataSize: 10Gi

​
新增配置值

MongoDB 现在由 MCK operator 通过 MongoDBCommunity 自定义资源管理。CR 的 spec 部分会直接从 mongodb.spec 原样渲染： 
mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    users:
      - name: hyperdx
        db: hyperdx
        passwordSecretRef:
          name: '{{ include "clickstack.mongodb.fullname" . }}-password'
        roles:
          - name: dbOwner
            db: hyperdx
          - name: clusterMonitor
            db: admin
        scramCredentialsSecretName: '{{ include "clickstack.mongodb.fullname" . }}-scram'
    additionalMongodConfig:
      storage.wiredTiger.engineConfig.journalCompressor: zlib
MongoDB 密码在 hyperdx.secrets.MONGODB_PASSWORD 中设置 (而不是 mongodb.password) 。密码 Secret 和 mongoUri 模板会自动引用该值。 如需启用持久化，请在 mongodb.spec 中添加一个 statefulSet 块： 
mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi
MCK Operator 子图表 在 mongodb-operator: 下配置 (不是 mongodb-kubernetes:) 。有关所有可用的 CRD 字段，请参阅 MCK 文档。

​
ClickHouse 迁移

​
已移除的配置值

以下 clickhouse.* 配置值已被移除： 
# 已移除 — 请勿使用
clickhouse:
  image: "..."
  terminationGracePeriodSeconds: 90
  resources: {}
  livenessProbe: ...
  readinessProbe: ...
  startupProbe: ...
  nodeSelector: {}
  tolerations: []
  service:
    type: ClusterIP
    annotations: {}
  persistence:
    enabled: true
    dataSize: 10Gi
    logSize: 5Gi
  config:
    clusterCidrs: [...]
    users:
      appUserPassword: "..."
      otelUserPassword: "..."
      otelUserName: "..."

​
新增配置项

ClickHouse 现由 ClickHouse Operator 通过 ClickHouseCluster 和 KeeperCluster 自定义资源进行管理。两个 CR 的 spec 部分都会根据 配置值 原样渲染： 
clickhouse:
  enabled: true
  port: 8123
  nativePort: 9000
  prometheus:
    enabled: true
    port: 9363
  keeper:
    spec:
      replicas: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
  cluster:
    spec:
      replicas: 1
      shards: 1
      keeperClusterRef:
        name: '{{ include "clickstack.clickhouse.keeper" . }}'
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi
      settings:
        extraUsersConfig:
          users:
            app:
              password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_APP_PASSWORD }}'
            otelcollector:
              password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_PASSWORD }}'
        extraConfig:
          max_connections: 4096
          keep_alive_timeout: 64
          max_concurrent_queries: 100
ClickHouse 用户凭据现在从 hyperdx.secrets 获取 (而不是 clickhouse.config.users) 。集群规范通过模板表达式引用这些凭据。 ClickHouse Operator 子图表 在 clickhouse-operator: 下配置。Webhooks 和 cert-manager 默认处于禁用状态。有关所有可用的 CRD 字段，请参阅operator 配置指南。

​
OTEL Collector 迁移

​
已移除的配置值

整个 otel: 块已被移除： 
# 已移除 — 请勿使用
otel:
  enabled: true
  image: ...
  replicas: 1
  resources: {}
  clickhouseEndpoint: ...
  clickhouseUser: ...
  clickhousePassword: ...
  clickhouseDatabase: "default"
  opampServerUrl: ...
  port: 13133
  nativePort: 24225
  grpcPort: 4317
  httpPort: 4318
  healthPort: 8888
  env: []
  customConfig: ...

​
新增配置值

OTel collector 现通过官方 OpenTelemetry Collector Helm 图表作为 otel-collector: 子图表进行部署。不再提供父图表 otel: 包装层——请直接配置该子图表。 环境变量 (ClickHouse 端点、OpAMP URL 等) 通过统一的 clickstack-config ConfigMap 和 clickstack-secret Secret 共享。该子图表的 extraEnvsFrom 已预先配置好： 
otel-collector:
  enabled: true
  mode: deployment
  image:
    repository: docker.clickhouse.com/clickhouse/clickstack-otel-collector
    tag: ""
  extraEnvsFrom:
    - configMapRef:
        name: clickstack-config
    - secretRef:
        name: clickstack-secret
  ports:
    otlp:
      enabled: true
      containerPort: 4317
      servicePort: 4317
    otlp-http:
      enabled: true
      containerPort: 4318
      servicePort: 4318
如需设置资源 (此前为 otel.resources) ： 
otel-collector:
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
要设置副本 (此前为 otel.replicas) ： 
otel-collector:
  replicaCount: 3
要设置 nodeSelector/tolerations (此前为 otel.nodeSelector/otel.tolerations) ： 
otel-collector:
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule
有关所有可用的子图表配置值，请参阅 OpenTelemetry Collector Helm 图表。

​
保持不变的配置值

以下部分不会受到此次迁移的影响：
  • global.* (imageRegistry, imagePullSecrets)

​
全新安装与就地升级

对于全新安装，无需任何特殊步骤。默认值开箱即用。 对于现有版本执行就地升级时，请注意：
  1. 这些 Operator (MCK、ClickHouse Operator) 会作为新的部署安装到你的命名空间中
  2. 现有的 MongoDB 部署和 ClickHouse 部署会被 Helm 删除 (它们已不再包含在 chart 的模板中)
  3. 这些 Operator 会创建新的 StatefulSets 来管理 MongoDB 和 ClickHouse
  4. 旧 chart 中的 PVC 不会被这些 Operator 管理的 StatefulSets 自动复用
我们建议在现有部署旁进行一次全新安装并迁移数据，而不是执行就地升级。

​
后续步骤

最后修改于 2026年6月10日