跳转到主要内容
已弃用 — v1.x 图表本页介绍 v1.x 内联模板 Helm 图表的配置，该图表目前处于维护模式。有关 v2.x 图表的信息，请参见 Helm 配置。如需迁移，请参见升级指南。
本指南介绍 ClickStack Helm 部署的配置选项。有关基本安装，请参见 Helm 部署主指南。

​
API 密钥设置

成功部署 ClickStack 后，请配置 API 密钥以启用遥测数据采集：
  1. 通过已配置的入口或服务端点访问你的 HyperDX 实例
  2. 登录 HyperDX 仪表板，然后前往团队设置，生成或获取你的 API 密钥
  3. 使用以下任一方法更新你的部署，添加 API 密钥：

​
方法 1：通过 Helm upgrade 使用 values 文件更新

将 API 密钥 添加到您的 values.yaml 中： 
hyperdx:
  apiKey: "your-api-key-here"
然后升级部署： 
helm upgrade my-clickstack clickstack/clickstack -f values.yaml

​
方法 2：通过 Helm upgrade 命令结合 —set 参数更新

helm upgrade my-clickstack clickstack/clickstack --set hyperdx.apiKey="your-api-key-here"

​
重启 Pod (容器组) 以使更改生效

更新 API 密钥后，重启 Pod (容器组) 以加载新的配置： 
kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector
该 Chart 会自动使用您的 API key 创建一个 Kubernetes secret (<release-name>-app-secrets) 。除非您想使用外部 secret，否则无需额外配置 secret。

​
Secret 管理

对于 API 密钥或数据库凭据等敏感数据，请使用 Kubernetes 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

​
在 values.yaml 中引用 Secret

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

​
入口设置

若要通过域名公开 HyperDX UI 和 API，请在 values.yaml 中启用入口。

​
通用入口配置

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # 必须与入口主机一致
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
重要配置说明hyperdx.frontendUrl 应与入口的主机名保持一致，并包含协议 (例如 https://hyperdx.yourdomain.com) 。这样可确保所有生成的链接、Cookie 和重定向都能正常工作。

​
启用 TLS (HTTPS)

要通过 HTTPS 保护您的部署： 1. 使用您的证书和私钥创建一个 TLS Secret： 
kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key
2. 在入口配置中启用 TLS： 
hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

​
示例入口配置

供参考，生成的入口资源如下： 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hyperdx-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
    - host: hyperdx.yourdomain.com
      http:
        paths:
          - path: /(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: my-clickstack-clickstack-app
                port:
                  number: 3000
  tls:
    - hosts:
        - hyperdx.yourdomain.com
      secretName: hyperdx-tls

​
常见入口问题

路径与重写配置：
  • 对于 Next.js 和其他 SPA，务必像上文所示那样使用正则路径和重写注解
  • 不要仅使用 path: / 而不配置重写，否则会导致静态资源无法正常提供
frontendUrl 与 ingress.host 不匹配：
  • 如果两者不一致，可能会导致 cookie、重定向和资源加载出现问题
TLS 配置不当：
  • 确保你的 TLS secret 有效，并且在入口中被正确引用
  • 如果已启用 TLS，却仍通过 HTTP 访问应用，浏览器可能会拦截不安全内容
入口控制器版本：
  • 某些功能 (如正则路径和重写) 需要较新的 nginx 入口控制器版本
  • 使用以下命令检查你的版本：
kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

​
OTel collector 入口

如果需要通过入口公开 OTel collector 的端点 (用于链路追踪、指标和日志) ，请使用 additionalIngresses 配置。这在需要从集群外发送遥测数据，或为 collector 使用自定义域名时非常有用。 
hyperdx:
  ingress:
    enabled: true
    additionalIngresses:
      - name: otel-collector
        annotations:
          nginx.ingress.kubernetes.io/ssl-redirect: "false"
          nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
          nginx.ingress.kubernetes.io/use-regex: "true"
        ingressClassName: nginx
        hosts:
          - host: collector.yourdomain.com
            paths:
              - path: /v1/(traces|metrics|logs)
                pathType: Prefix
                port: 4318
                name: otel-collector
        tls:
          - hosts:
              - collector.yourdomain.com
            secretName: collector-tls
  • 这会为 OTel collector 端点创建一个单独的入口资源
  • 你可以使用不同的域名、配置特定的 TLS 设置，并添加自定义 annotations
  • 正则表达式路径规则允许你通过单条规则转发所有 OTLP 信号 (链路追踪、指标、日志)
如果你不需要将 OTel collector 对外暴露，可以跳过此配置。对于大多数用户，通用的入口配置已经足够。

​
入口故障排查

检查入口资源： 
kubectl get ingress -A
kubectl describe ingress <ingress-name>
检查入口控制器日志： 
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx
测试资源 URL： 使用 curl 验证静态资源返回的是 JS 而不是 HTML： 
curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# 应返回 Content-Type: application/javascript
浏览器开发者工具：
  • 检查 Network 选项卡中是否有 404，或资源返回的是 HTML 而不是 JS
  • 在控制台中查找类似 Unexpected token < 的错误 (说明本应返回 JS 的请求却返回了 HTML)
检查路径重写：
  • 确保入口不会剥离资源路径，或错误地重写资源路径
清除浏览器和 CDN 缓存：
  • 更改后，清除浏览器缓存以及所有 CDN/代理缓存，以免继续使用过期资源

​
自定义配置值

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

hyperdx:
  ingress:
    enabled: true
    host: hyperdx.example.com
应用自定义配置值： 
helm install my-clickstack clickstack/clickstack -f values.yaml

​
后续步骤

最后修改于 2026年6月10日