SigNoz v0.146.0 Docker Compose 部署指南

目标：在一台 Linux 服务器上用官方 Foundry 工具链渲染 Docker Compose，从零部署 SigNoz v0.146.0 全栈（SigNoz Server + OpenTelemetry Collector + ClickHouse 25.12.5 + Keeper + PostgreSQL 16），完成首次管理员注册、Web/API 登录取证，并用 OTLP 发送 trace/metric/log 三类数据完成端到端验证；全流程已在 Ubuntu 22.04 实测通过（2026-10-20），所有命令与回显均为实测原文。

一、环境信息

项目	实测环境
操作系统	Ubuntu 22.04（内核 6.x）
硬件	12 核 CPU / 32 GB 内存 / 数据盘余量 100 GB+（官方最低建议 4 核 8 GB）
Docker	29.8.1（daemon 已配置 HTTPS 代理与国内镜像源）
Docker Compose	v5.5.1
SigNoz	v0.146.0（2026-10-20 时 GitHub 最新稳定版，releases.atom 实查）
专用容器网段	10.89.63.0/24（预先核对过空闲，部署容器统一编排在 `signoz-network`）

对外端口规划（宿主机 8080 已被占用，故映射到 814x 段空闲端口）：

宿主端口	容器端口	用途
8143	8080	SigNoz Web UI + HTTP API
8147	4317	OTLP gRPC 接入
8148	4318	OTLP HTTP 接入
8146	8123	ClickHouse HTTP（可选，便于外部验证）

二、部署方式说明：v0.146 的官方正道是 Foundry

SigNoz 旧文档的 install.sh 与 deploy/ 目录自带 compose 文件自 v0.130.0 起已废弃，官方不再维护（来源：仓库 deploy/README.md，查询日期 2026-10-20）。v0.146.0 的官方路径是：

安装 Foundry CLI（foundryctl）；
编写 casting.yaml 声明部署形态；
foundryctl forge 渲染出 Compose 文件与配置文件；
docker compose up -d 起栈。

渲染产物包含 compose.yaml、ingester/ingester.yaml（collector 配置）、telemetrystore/clickhouse/config-0-0.yaml 等，后续 C1 篇的配置详解都基于这套产物。

三、安装 foundryctl 并编写 casting.yaml

3.1 安装 foundryctl

curl -fsSL https://signoz.io/foundry.sh -o foundry.sh
bash foundry.sh -y
foundryctl version
# Foundry v0.1.x（实测输出 0.1.10 系列）

3.2 编写 casting.yaml

在部署目录（本文以 /opt/signoz-stack 为例）创建 casting.yaml。最小可用只要三行，但本实录额外用官方 patches 机制做了四件事：指定 Compose 项目名、锁定专用子网、把端口映射到 8143/8147/8148、暴露 ClickHouse 8123：

apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: compose
    mode: docker
  patches:
    - target: deployment/compose.yaml
      operations:
        - op: replace
          path: /name
          value: signoz-0.146.0-stack
        - op: add
          path: /networks/signoz-network/ipam
          value:
            config:
              - subnet: 10.89.63.0/24
        - op: replace
          path: /services/ingester/ports
          value:
            - "8147:4317"
            - "8148:4318"
        - op: replace
          path: /services/signoz-signoz-0/ports
          value:
            - "8143:8080"
        - op: add
          path: /services/signoz-telemetrystore-clickhouse-0-0/ports
          value:
            - "8146:8123"

坑点（实测）：若不显式锁定子网，Foundry 渲染的 compose 使用默认网络策略，在共享宿主机上可能与并行栈的地址池冲突——本实录第一次启用 10.89.62.0/24 时即报 Pool overlaps with other one on this address space，改用 10.89.63.0/24 后正常。

四、渲染与启动

4.1 gauge 校验前置条件

cd /opt/signoz-stack
foundryctl gauge -f casting.yaml
# 实测无输出、退出码 0（docker/compose 均可用时静默通过）

4.2 forge 渲染

foundryctl forge -f casting.yaml
find pours -type f | sort
# pours/deployment/compose.yaml
# pours/deployment/ingester/ingester.yaml
# pours/deployment/ingester/opamp.yaml
# pours/deployment/telemetrykeeper/clickhousekeeper/keeper-0.yaml
# pours/deployment/telemetrystore/clickhouse/config-0-0.yaml
# pours/deployment/telemetrystore/clickhouse/functions.yaml

渲染出的 compose.yaml 共 6 个服务：

服务	镜像	说明
`signoz-signoz-0`	signoz/signoz:latest	Web+API（运行时 `/api/v1/version` 返回 v0.146.0）
`ingester`	signoz/signoz-otel-collector:latest	OTLP 接入 + 迁移前置检查
`signoz-telemetrystore-clickhouse-0-0`	clickhouse/clickhouse-server:25.12.5	遥测存储
`signoz-telemetrykeeper-clickhousekeeper-0`	clickhouse/clickhouse-keeper:25.12.5	分布式协调
`signoz-metastore-postgres-0`	postgres:16	元数据存储
`signoz-telemetrystore-migrator`	复用 collector 镜像	一次性迁移：`migrate ready → bootstrap → sync up → async up`

另有 signoz-telemetrystore-clickhouse-user-scripts 初始化容器，从 GitHub 下载 histogram-quantile 工具注入 ClickHouse 用户脚本目录。

4.3 拉取镜像并启动

cd /opt/signoz-stack/pours/deployment
docker compose up -d

坑点（实测）：本环境 daemon 走代理拉取时，signoz/signoz-otel-collector 与 clickhouse/clickhouse-server:25.12.5 的部分 blob 反复 unexpected EOF（代理对特定 CDN 连接断流）。处置顺序：

直接重试 docker compose up -d（层缓存可续传，多数情况能熬过去）；

仍失败则改用其他镜像源显式拉取后 retag：docker pull <mirror>/signoz/signoz-otel-collector:latest && docker tag <mirror>/signoz/signoz-otel-collector:latest signoz/signoz-otel-collector:latest；

极端断流时用 skopeo/手动分 blob 下载构建 OCI 布局再 docker load（本实录最终即用此法补齐两台镜像）。

启动成功后 docker compose ps（实测回显）：

NAME                                   IMAGE                                      STATUS
signoz-01460-stack-ingester-1          signoz/signoz-otel-collector:latest        Up
signoz-metastore-postgres-0            postgres:16                                Up 1 minute (healthy)
signoz-signoz-0                        signoz/signoz:latest                       Up 1 minute (healthy)
signoz-telemetrykeeper-clickhousekeeper-0  clickhouse/clickhouse-keeper:25.12.5   Up 1 minute (healthy)
signoz-telemetrystore-clickhouse-0-0   clickhouse/clickhouse-server:25.12.5       Up 1 minute (healthy)
signoz-telemetrystore-migrator         signoz/signoz-otel-collector:latest        Up (completed) 退出码 0

migrator 显示 completed 即 schema 迁移完成（ready/bootstrap/sync up/async up 四步全部成功后正常退出）。

五、首次初始化：注册管理员

v0.146 首个访问者即注册 root 管理员。Web 入口 http://<服务器>:8143/（SPA 登录页），命令行等价操作如下（实测）：

curl -s http://localhost:8143/api/v1/health
# {"status":"ok"}
curl -s http://localhost:8143/api/v1/version
# {"version":"v0.146.0","ee":"Y","setupCompleted":false}

curl -s -X POST http://localhost:8143/api/v1/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@signoz.local","name":"admin","password":"Q1w2e3r4#@$%","orgName":"signoz"}'
# {"status":"success","data":{}}

坑点（实测）：默认密码策略要求至少 12 位，且同时包含大写、小写、数字、符号。先用惯用的 q1w2e3r4 注册会被拒绝： {"status":"error","errorType":"invalid_input","error":"Password must be at least 12 characters long and contain at least one uppercase letter, one lowercase letter, one digit, and one special character"} 本实录示例账号 admin@signoz.local / Q1w2e3r4#@$%，生产环境请改用强口令并接入 SSO（EE 能力）。

注册成功后 setupCompleted 翻转为 true，再次调用 register 会返回 409 系错误——这是判断"是否已初始化"的判据。

六、登录取证（API 全链路）

curl -s -X POST http://localhost:8143/api/v2/sessions/email_password \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@signoz.local","password":"Q1w2e3r4#@$%","orgID":"01a15798-6dc6-7df0-99b4-0f940439d2a7"}'

实测回显（节选）：

{"status":"success","data":{"accessToken":"Tgf17gc0Y6qfI97xU0V3G8zqN5A8lNf3","tokenType":"Bearer","expiresIn":86400}}

用 token 验证身份与租户：

AT="Tgf17gc0Y6qfI97xU0V3G8zqN5A8lNf3"
curl -s http://localhost:8143/api/v2/users/me -H "Authorization: Bearer $AT"
# {"status":"success","data":{"details":{"id":"01a15799-4bd8-7df0-99b4-4b35962a72cb",
#  "email":"admin@signoz.local","displayName":"admin","role":"ROOT",...},
#  "userTenantMappings":[{"tenantId":"01a15798-6dc6-7df0-99b4-0f940439d2a7","role":"ROOT"}]}}

Web 端（浏览器打开 http://<服务器>:8143/）使用同一账号登录后进入 Dashboard；服务列表接口验证：

curl -s http://localhost:8143/api/v1/services/list -H "Authorization: Bearer $AT"
# {"status":"success","data":{"services":[{"name":"frontend-api","p99":355330438,...}]}}

说明：本实录部署于无图形界面的服务器，Web 登录取证以"首页 HTML + API 登录链路"组合完成：curl http://localhost:8143/ 返回 SigNoz SPA 首页（<title>SigNoz</title> 前端资源 /assets/index-*.js），登录态以 /api/v2/sessions/email_password + /api/v2/users/me 实测闭环。

七、端到端验证：发送 trace / metric / log

7.1 用 OTLP JSON 发三类数据

向 OTLP HTTP 端点（宿主 8148）直接 POST JSON（无需 SDK，适合部署后冒烟测试）：

NOW=$(date +%s%N)
cat > /tmp/trace.json <<EOF
{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"frontend-api"}}]},
 "scopeSpans":[{"scope":{"name":"manual-otlp-test"},"spans":[{"traceId":"5b8efff798038103d269b633813fc60c",
 "spanId":"eee19b7ec3c1b174","name":"POST /checkout","kind":2,
 "startTimeUnixNano":"$NOW","endTimeUnixNano":"$(( ($(date +%s%N) / 1000000 + 350) * 1000000 ))",
 "attributes":[{"key":"http.method","value":{"stringValue":"POST"}}],"status":{"code":1}}]}]}]}
EOF
curl -s -X POST http://localhost:8148/v1/traces -H 'Content-Type: application/json' -d @/tmp/trace.json
# {"partialSuccess":{}}   实测 HTTP 200

metric（/v1/metrics）与 log（/v1/logs）同理，实测均返回 {"partialSuccess":{}}。

7.2 ClickHouse 落库验证

ClickHouse 原生端口仅在容器网内，从服务器侧用 HTTP 口（8146）或进入容器执行（二选一，实测均通过）：

curl -s 'http://localhost:8146/?query=SELECT+1'
# 1.
docker exec signoz-telemetrystore-clickhouse-0-0 clickhouse-client \
  --query "SELECT trace_id, name, kind_string, duration_nano, hasError \
           FROM signoz_traces.distributed_signoz_index_v3 \
           WHERE trace_id='5b8efff798038103d269b633813fc60c' FORMAT Vertical"
# Result:
# trace_id: 5b8efff798038103d269b633813fc60c
# name: POST /checkout
# kind_string: Server
# duration_nano: 355330438
# hasError: 0

docker exec signoz-telemetrystore-clickhouse-0-0 clickhouse-client \
  --query "SELECT timestamp, severity_text, body FROM signoz_logs.distributed_logs_v2 \
           WHERE body LIKE '%checkout%' ORDER BY timestamp DESC LIMIT 1 FORMAT Vertical"
# body: order checkout completed amount=258.00

docker exec signoz-telemetrystore-clickhouse-0-0 clickhouse-client \
  --query "SELECT metric_name, count() FROM signoz_metrics.distributed_samples_v4 \
           WHERE metric_name='checkout_requests_total' GROUP BY metric_name"
# checkout_requests_total   1

7.3 查询 API 验证（等价于 Web 上"日志/追踪查询页"）

START=$(($(date +%s) - 900))000; END=$(date +%s)000
curl -s -X POST http://localhost:8143/api/v4/query_range \
  -H "Authorization: Bearer $AT" -H 'Content-Type: application/json' \
  -d "{\"start\":$START,\"end\":$END,\"formatForWeb\":true,\"compositeQuery\":{\"panelType\":\"graph\",
  \"queryType\":\"builder\",\"builderQueries\":{\"A\":{\"queryName\":\"A\",\"dataSource\":\"logs\",
  \"aggregateOperator\":\"count\",\"expression\":\"A\",\"disabled\":false,\"type\":\"builder-query\"}}}}"
# {"status":"success","data":{"result":[{"queryName":"A","series":[{"labels":[],"values":[[<ts>,"1"]]}]}]}}

dataSource 换 traces 同样返回 count=1；指标查询走 PromQL 形态（queryType:"promql"，如 sum(rate(checkout_requests_total[5m]))）实测返回成功。Web 控制台的 Logs / Traces 查询页即调用同一套 /api/v4/query_range，API 通过即页面可用。

八、数据持久化与日常运维

项	值
遥测数据卷	`signoz-telemetrystore-0-0-data`（ClickHouse 数据目录）
Keeper 数据卷	`signoz-telemetrykeeper-0-data`
元数据卷	`signoz-metastore-postgres-0-data`（PostgreSQL）
网络容器	`signoz-network`（10.89.63.0/24）

# 日常停止/启动/销毁（在 /opt/signoz-stack/pours/deployment 下）
docker compose down            # 保留数据卷
docker compose down -v         # 连数据卷一并销毁（遥测数据清零）
docker compose logs -f ingester    # 跟 collector 日志

九、常见问题排查

register 返回 409/已初始化：setupCompleted 已为 true，改用登录接口；如需重置，docker compose down -v 后重装（清库慎重）。
端口/子网冲突：Pool overlaps with other one on this address space → 换 casting.yaml 里的 subnet 重跑 forge；宿主端口被占 → 调整 patches 中的映射。
镜像 blob 反复 EOF：见 §4.3 三步处置。
migrator 反复重启：查 docker compose logs migrator，常见原因是 ClickHouse 未 healthy 时被拉起——compose 已用 service_healthy 依赖约束，若手工改过启动顺序需恢复。
指标 builder 查询报 error in builder queries：v0.146 对无聚合属性的简单指标 count/sum 存在生成空 SQL 的问题（服务端日志可见 SQL syntax error: Empty query），指标查询请用 PromQL 形态或带明确聚合属性。

十、验收清单

docker compose ps 6 服务全部 Up，存储/Keeper/Web 均 healthy，migrator completed
/api/v1/health 返回 {"status":"ok"}，/api/v1/version 返回 v0.146.0
首管理员注册成功（含密码策略拒绝路径实测），登录换发 accessToken，/api/v2/users/me 返回 ROOT 角色
OTLP 三端点（traces/metrics/logs）均 200，ClickHouse 三库均可查到对应数据
/api/v4/query_range 日志/追踪 builder 查询与指标 PromQL 查询实测返回成功