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

signoz 4小时前 · 2026-10-09 03:58:51 · 1 阅读

在 Minikube、Kind 或 K3s 中安装 SigNoz - 自托管指南

本指南介绍如何使用 SigNoz 的 Helm chart，通过 Foundry 或直接用 Helm，在 Minikube、Kind 或 K3s 等本地 Kubernetes 集群上安装 SigNoz。

前提条件

kubectl 已配置好并能连接集群，同一台机器上已安装 Helm 3。
集群有足够的资源运行 SigNoz。容量规划可参考资源规划文档。

搭建本地 Kubernetes 集群

从以下方式中选择一种来搭建本地 Kubernetes 集群：

MinikubeKindK3S

按照Minikube 官方安装指南操作
SigNoz 推荐配置： Copy
```
minikube start --memory=8g --cpus=4
```

按照Kind 官方安装指南操作

将以下集群配置保存为 kind-config.yaml： Copy

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 8080
    hostPort: 8080

创建集群： Copy

kind create cluster --config kind-config.yaml

按照K3s 官方安装指南操作

提示

也可以使用 k3d，它通过 Docker 运行 K3s，可以快速创建和删除测试集群。安装步骤与普通 K3s 集群相同。

创建集群： Copy
```
k3d cluster create
```

HelmFoundry

安装 SigNoz

第 1 步：添加 Helm 仓库

在运行 kubectl 的机器上执行：

Copy

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

第 2 步（可选）：选择 StorageClass

SigNoz 将数据存储在持久化卷上，StorageClass 决定了集群为这些卷创建什么类型的磁盘。不做这一步的话，SigNoz 会使用集群的默认 StorageClass。本地集群自带默认 StorageClass（Minikube 和 Kind 上是 standard，K3s 上是 local-path），所以这一步通常可以跳过。查看集群提供的 StorageClass：

Copy

kubectl get storageclass

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

Copy

global:
  storageClass: <storage-class>

请确认以下配置值：

<storage-class>：取自 kubectl get storageclass 输出的存储类别名称，例如 standard。

其他 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

默认情况下，日志和 Trace 的保留期为 7 天，指标的保留期为 30 天。如需修改，请前往 SigNoz UI 的 Settings 页面，点击 General 选项卡进行设置。

更多详情请参见数据保留期指南。

向 SigNoz 发送数据

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

Copy

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

在你的 instrumentation（埋点/探针）中，将此地址设置为 OTLP endpoint，例如作为 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 或内存不足，则需要更多的节点容量。请参阅资源规划。在 Minikube 上，请使用更多资源启动集群：minikube start --memory=8g --cpus=4。

修复后，kubectl get pods -n signoz 显示 pod 状态为 Running。

某个 pod 不断重启

查看它的日志：

Copy

kubectl logs -n signoz <pod-name>

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

安装 SigNoz

什么是 Foundry？

Foundry 是一个开源 CLI 工具，可以像管理代码一样运行自托管的可观测性栈。一份声明式配置就能完成基础设施搭建、SigNoz 后端安装，以及在裸机、容器或 Kubernetes 上配置 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，部署到名为 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 将数据存储在持久卷上。存储类决定了集群为这些数据创建哪种类型的磁盘。若跳过此步，SigNoz 将使用集群的默认存储类。本地集群自带默认存储类（Minikube 和 Kind 为 standard，K3s 为 local-path），因此此步骤通常无需操作。查看集群可用存储类：

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 输出的存储类名称，例如 standard。

步骤 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-telemet

 原始来源： signoz 
    
  评论 (0)