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

signoz 2小时前 · 2026-10-09 05:58:43 · 0 阅读

在 GCP GKE 集群上安装 SigNoz - 自托管指南

本指南介绍如何借助 SigNoz Helm chart，在 Google Kubernetes Engine（GKE）集群上安装 SigNoz，可配合 Foundry 或直接使用 Helm 完成。

前置条件

创建好 GKE 集群（更多说明见 GCP 官方文档）。
本机已配置好可访问该集群的 kubectl，并安装 Helm 3。
集群具备足够的资源配额，容量规划详见资源规划。

HelmFoundry

安装 SigNoz

第 1 步：添加 Helm 仓库

在使用 kubectl 的机器上运行以下命令：

Copy

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

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

SigNoz 将数据存放在持久卷上，存储类决定了集群为它们创建哪种磁盘。不设置时，SigNoz 默认使用集群的默认存储类；GKE 集群自带以持久磁盘为后端的默认存储类。可用以下命令查看当前集群提供的存储类：

Copy

kubectl get storageclass

如需指定某一种，创建名为 values.yaml 的文件：

Copy

global:
  storageClass: <storage-class>

确认以下取值：

<storage-class>：取自 kubectl get storageclass 输出中的某个存储类名称。

GKE Autopilot 请改用如下 values.yaml：它指定 gce-resizable 存储类，并告知 chart 当前运行在 Autopilot 上：

Copy

global:
  cloud: gcp/autogke
  storageClass: gce-resizable
clickhouse:
  installCustomStorageClass: true

其他 chart 参数也写入同一文件，完整参考 chart 配置文档。

第 3 步：安装 chart

在包含 values.yaml 的目录下执行：

Copy

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

如果跳过了第 2 步，请去掉 -f values.yaml。--wait 会在所有 Pod 就绪后返回。

第 4 步：验证安装

检查 Pod 是否正在运行：

Copy

kubectl get pods -n signoz

输出应类似于以下内容。Pod 名称后缀会有所不同：

Copy

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/：

Copy

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

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

Copy

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

响应内容为：

Copy

{"status":"ok"}

Info

默认情况下，日志和链路追踪的保留期为 7 天，指标数据的保留期为 30 天。如需修改，请前往 SigNoz UI 的 Settings 页面，点击 General 选项卡。

更多详情，请参阅保留期指南。

向 SigNoz 发送数据

您的应用将 traces（链路追踪）、metrics（指标）和 logs（日志）发送到 SigNoz 采集器。集群内部，采集器监听地址为：

Copy

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

将此地址作为 OTLP endpoint，配置到您的 instrumentation 中，例如作为 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 名称。

如果 Pod 报告 CPU 或内存不足，说明节点容量不够，请参考资源规划。在 GKE Autopilot 上，Pod 一直 Pending 通常意味着项目在该区域的资源配额已用完，详情见 Autopilot 资源请求文档。

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

Pod 不断重启

查看其日志：

Copy

kubectl logs -n signoz <pod-name>

如果想查看上次重启之前的日志，加上 --previous 参数即可。

安装 SigNoz

What is Foundry?

Foundry 是一个开源 CLI，可以把自托管的可观测性栈以代码方式运行。一份声明式配置即可完成基础设施搭建、SigNoz 后端安装，以及 OpenTelemetry 采集的配置，支持裸金属、容器或 Kubernetes 环境。了解更多关于 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，命名空间为 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 下的注解决定了 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 将数据保存在持久卷上。存储类决定了集群为这些数据创建什么类型的磁盘。如果跳过此步骤，SigNoz 将使用集群的默认存储类。GKE 集群自带基于持久磁盘的默认存储类。若要查看集群可用的存储类，执行：

Copy

kubectl get storageclass

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

Copy

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

确认以下参数值：

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

如果使用 GKE Autopilot，请改用此补丁。它指定使用 gce-resizable 存储类，并告知 Helm chart 运行在 Autopilot 模式上：

Copy

spec:
  patches:
    - target: deployment/values.yaml
      operations:
        - op: add
          path: /global
          value:
            cloud: gcp/autogke
            storageClass: gce-resizable
        - op: add
          path: /clickhouse/installCustomStorageClass
          value: true

第 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     Running     0          3m
signoz-metastore-postgres-0                                 1/1     Running     0          3m
signoz-telemetrykeeper-zookeeper-0                          1/1     Running

 原始来源： signoz 
    
  评论 (0)