← 文章 / 云原生与基础设施

signoz 1小时前 · 2026-10-09 00:29:42 · 0 阅读

在任何 Kubernetes 集群上安装 SigNoz - 自托管指南

本指南介绍如何使用 SigNoz Helm Chart，在任何 Kubernetes 集群、其他云或自有服务器上安装 SigNoz，可选用 Foundry 或直接使用 Helm。

前置条件

必须有一个 Kubernetes 集群
已配置 kubectl 可访问集群，且同一台机器上已安装 Helm 3。
集群容量足以运行 SigNoz。关于容量规划，请参阅资源规划。

HelmFoundry

安装 SigNoz

步骤 1：添加 Helm 仓库

在配置了 kubectl 的机器上运行以下命令：

Copy

helm repo add signoz https://charts.signoz.io
helm repo update

步骤 2（可选）：选择存储类

SigNoz 将数据存储在持久卷上。存储类决定了集群为这些卷创建何种类型的磁盘。若跳过此步骤，SigNoz 将使用集群的默认存储类。要查看集群提供的存储类：

Copy

kubectl get storageclass

请选择一个允许卷扩展的存储类，以便日后通过调整声明大小来扩展 SigNoz 的卷。

允许在默认存储类上扩展

如果默认存储类是唯一选项且目前不允许扩展，请将其开启。在配置了 kubectl 的机器上运行以下命令：

Copy

DEFAULT_STORAGE_CLASS=$(kubectl get storageclass -o=jsonpath='{.items[?(@.metadata.annotations.storageclass\.kubernetes\.io/is-default-class=="true")].metadata.name}')
 
kubectl patch storageclass "$DEFAULT_STORAGE_CLASS" -p '{"allowVolumeExpansion": true}'

此时运行 kubectl get storageclass，该存储类的 ALLOWVOLUMEEXPANSION 字段将显示为 true。

若要使用特定存储类，请创建一个名为 values.yaml 的文件：

Copy

global:
  storageClass: <storage-class>

请核实这些参数：

<storage-class>：来自 kubectl get storageclass 输出的存储类名称。

其他 Chart 参数也可写入同一文件。详见Chart 配置参考。

步骤 3：安装 Chart

在包含 values.yaml 的目录下运行以下命令：

helm install signoz signoz/signoz \
   --namespace signoz --create-namespace \
   --wait --timeout 1h \
   -f values.yaml

如果跳过了步骤 2，请省略 -f values.yaml。--wait 参数会让命令在所有 Pod 就绪后返回。

步骤 4：验证安装

检查 Pod 是否正在运行：

kubectl get pods -n signoz

输出结果应与以下内容相似。注意 Pod 的后缀会有所不同：

NAME                                         READY   STATUS      RESTARTS   AGE
chi-signoz-clickhouse-cluster-0-0-0          1/1     Running     0          3m
signoz-0                                     1/1     Running     0          3m
signoz-clickhouse-operator-7f8c9d6b5-q4w2z   2/2     Running     0          3m
signoz-otel-collector-6d9c7b8f5c-k2x9p       1/1     Running     0          3m
signoz-telemetrystore-migrator-x7h3k         0/1     Completed   0          2m
signoz-zookeeper-0                           1/1     Running     0          3m

当所有 Pod 都在运行时，对 SigNoz UI 进行端口转发，然后在浏览器中打开 http://localhost:8080/：

kubectl port-forward -n signoz svc/signoz 8080:8080

在另一个终端中，检查健康端点：

curl -X GET http://localhost:8080/api/v1/health

响应内容如下：

{"status":"ok"}

Info

默认情况下，日志和追踪数据的保留期设置为7 天，指标数据的保留期设置为30 天。若要更改此设置，请前往 SigNoz UI 的 Settings（设置）页面，并点击 General（常规）选项卡。

更多细节请参阅保留期指南。

向 SigNoz 发送数据

应用程序会将追踪数据、指标和日志发送到 SigNoz 收集器。在集群内部，收集器监听以下地址：

http://signoz-otel-collector.signoz.svc.cluster.local:4318

请将此地址用作插桩代码中的 OTLP 端点，例如作为 OTEL_EXPORTER_OTLP_ENDPOINT 的值。如果使用 gRPC，请改用端口 4317。该地址中的第二个 signoz 代表命名空间。如果将 SigNoz 安装到了其他命名空间，请替换为对应的命名空间名称。

集群外的应用，请参考自托管数据接入指南。

自定义安装

每次修改都遵循同样的流程：编辑 values.yaml，然后升级 release：

Copy

helm upgrade signoz signoz/signoz --namespace signoz -f values.yaml

Chart 配置项：所有配置项可查看 chart 配置参考文档。
Chart 版本：在 helm install 和 helm upgrade 命令中添加 --version <chart-version>。可用版本见 SigNoz charts releases。

请确认以下值的含义：

<chart-version>：SigNoz charts releases 中的某个 chart 版本，例如 0.144.0。

故障排查

helm install 超时

--wait 参数会等待所有 Pod 变为就绪状态。如果命令超时，先用 kubectl get pods -n signoz 列出 Pod，再按下面两节排查。

Pod 一直处于 Pending 状态

用 describe 命令查看 Pod 未能调度的原因：

Copy

kubectl describe pod -n signoz <pod-name>

把 <pod-name> 替换为 kubectl get pods -n signoz 输出中的 Pod 名称。

如果显示 CPU 或内存不足，说明节点资源不够，请参考资源规划文档。

问题解决后，kubectl get pods -n signoz 会显示 Pod 处于 Running 状态。

Pod 反复重启

查看日志：

Copy

kubectl logs -n signoz <pod-name>

如需查看上次重启前的日志，加上 --previous 参数。

安装 SigNoz

什么是 Foundry？

Foundry 是一个开源 CLI，可以把自托管的可观测性栈当作代码来运行。只需一份声明式配置，就能在裸机、容器或 Kubernetes 上完成基础设施配置、SigNoz 后端安装和 OpenTelemetry 采集设置。了解更多请见 Foundry。

步骤 1：安装 foundryctl

在配置好 kubectl 的机器上运行此命令：

Copy

curl -fsSL https://signoz.io/foundry.sh | bash

如需手动安装（如 Windows PowerShell、离线环境等）或配置 PATH，请参阅 foundry 入门指南。

步骤 2：创建 casting.yaml

创建一个名为 casting.yaml 的文件。该文件描述安装配置：通过 Helm Chart 在名为 signoz 的命名空间（namespace）中安装 SigNoz：

Copy

apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: helm
    mode: kubernetes
  telemetrykeeper:
    kind: zookeeper

其中 telemetrykeeper 字段指定使用 ZooKeeper，这是 Helm Chart 用于协调 ClickHouse 的组件。

所有选项详情，请参见 casting 文件参考和 Kubernetes Helm 示例。

更改命名空间或固定 Chart 版本

metadata 下的注解（annotations）用于设置 SigNoz 的安装位置及使用的 Chart。默认值如下：

Copy

metadata:
  name: signoz
  annotations:
    foundry.signoz.io/kubernetes-namespace: signoz            # 安装到的命名空间，若不存在则自动创建
    foundry.signoz.io/kubernetes-helm-chart: signoz           # Chart 名称、归档 URL 或本地路径
    foundry.signoz.io/kubernetes-helm-repo-url: https://charts.signoz.io
    foundry.signoz.io/kubernetes-helm-chart-version: latest   # 或固定版本，如 0.144.0

casting 文件参考中详细说明了每一项配置。

步骤 3（可选）：选择存储类

SigNoz 将数据存储在持久卷上。存储类（storage class）决定了集群为它们创建何种类型的磁盘。若跳过此步骤，SigNoz 将使用集群默认的存储类。查看集群提供的选项：

Copy

kubectl get storageclass

请选择支持卷扩展（volume expansion）的存储类，以便后续通过调整申领（claim）大小来扩容 SigNoz 卷。

允许在默认存储类上进行扩展

如果默认存储类是唯一选项且目前不支持扩展，请启用它。在你使用 kubectl 的机器上运行以下命令：

Copy

DEFAULT_STORAGE_CLASS=$(kubectl get storageclass -o=jsonpath='{.items[?(@.metadata.annotations.storageclass\.kubernetes\.io/is-default-class=="true")].metadata.name}')

kubectl patch storageclass "$DEFAULT_STORAGE_CLASS" -p '{"allowVolumeExpansion": true}'

kubectl get storageclass 随后会显示该类的 ALLOWVOLUMEEXPANSION 为 true。

若要使用特定存储类，请在 casting.yaml 中添加以下内容：

Copy

spec:
  patches:
    - target: deployment/values.yaml
      operations:
        - op: add
          path: /global
          value:
            storageClass: <storage-class>

请确认以下取值：

<storage-class>：来自 kubectl get storageclass 输出的存储类名称。

步骤 4：部署

在包含 casting.yaml 的目录中运行以下命令：

Copy

foundryctl cast -f casting.yaml

此命令会将 SigNoz Helm chart 安装到 signoz 命名空间，若命名空间不存在则自动创建。修改 casting.yaml 后，重新运行相同命令即可应用变更。

手动运行 Helm

若要直接运行 Helm，请生成 values 文件并将其传递给 Helm：

Copy

foundryctl forge -f casting.yaml   # 写入 pours/deployment/values.yaml
helm repo add signoz https://charts.signoz.io
helm repo update
helm upgrade --install signoz signoz/signoz \
   --namespace signoz --create-namespace \
   -f pours/deployment/values.yaml

步骤 5：验证安装

检查 Pod 是否正在运行：

Copy

kubectl get pods -n signoz

输出应类似于以下内容。Pod 后缀可能不同：

Copy

NAME                                                        READY   STATUS      RESTARTS   AGE
chi-signoz-telemetrystore-clickhouse-cluster-0-0-0          1/1     Running     0          3m
signoz-0                                                    1/1     Running     0          3m
signoz-ingester-6d9c7b8f5c-k2x9p                            1/1

 原始来源： signoz 
    
  评论 (0)