SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 更新于 2026-11-06

Superlog 自托管部署与资源占用

了解 Superlog 自托管实际安装的 Postgres、ClickHouse、OTel Collector 和 4 个 Node 服务,掌握 VPS 资源占用、部署限制及未发布版本的固定方法。

自行托管 Superlog 实际安装的内容

要自行托管 Superlog,您需要克隆代码仓库,使用 Docker Compose 启动 Postgres、ClickHouse 和 OpenTelemetry collector,执行一次数据库迁移,然后从源代码启动 4 个 Node 服务。您的应用会将 OTLP(OpenTelemetry 协议)追踪、日志和指标发送到接收端口。Superlog 会为这些数据生成指纹,将重复事件归并为一个事件。默认的社区 agent runner 会记录本地事件摘要。安装过程需要一个下午。开始前,最值得了解的是资源占用和实际限制。

Superlog 使用 Apache 2.0 许可证,代码位于 github.com/superloglabs/superlog。截至 13 October 2026,它约有 1.5k 个 stars,在 main 上大约有 490 次提交,但完全没有 release tag。请自行固定一个 commit,不要直接运行克隆当天早上 main 中碰巧存在的版本。

Superlog 能回答哪些问题,而 Uptime Kuma 和 Langfuse 不能

从外部看,自托管监控工具似乎可以互相替代。实际并非如此。选错工具只会占用服务器资源,却无法带来任何收益。

Superlog 负责回答另一个问题:哪里出故障、具体是什么故障,以及原因是什么。它不处理 LLM 调用,也不会从外部探测您的服务。它从普通应用代码接收 OTLP,并在故障分诊环节加入代理。这正是值班人员通常首先执行的检查。

对于 VPS 预算,真正重要的区别在于存储。Superlog 使用列式存储,因为遥测数据写入一次后,需要跨数百万行按时间范围查询。ClickHouse 就是为此设计的,而 Postgres 不是。Postgres 仍在整个技术栈中,用于保存少量关系型数据:项目、用户、事件和摄取密钥。

docker compose up -d 实际启动了什么?

3 个容器,其中没有 Superlog。对于以为一条命令即可完成安装的人来说,这一点很容易令人意外。

  • postgres:16,发布到主机的 5434 端口
  • clickhouse/clickhouse-server:26.1,HTTP 使用 8123 端口,原生协议使用 9000 端口
  • otel/opentelemetry-collector-contrib:0.150.1,gRPC 使用 4317 端口,基于 HTTP 的 OTLP 使用 4318 端口

Superlog 应用在主机上从源代码运行,由 pnpm dev 启动。截至 13 October 2026,仓库中没有用于生产环境的 compose 文件。因此,长期运行的安装需要使用您自己的 systemd 单元,或者使用代码树中随附的各应用 Dockerfile。api、worker 和 proxy 应用各有一个 start 脚本,用于封装到单元中运行。web 应用没有该脚本:它是 Vite 应用,因此应使用其 build 脚本构建,然后由 nginx 或 Caddy 将输出作为静态文件提供;也可以运行其 preview 脚本,该脚本是 vite preview。

请记住请求经过的路径,因为下面的每个故障都表示其中一跳中断。您的应用将 OTLP 数据发送到 Superlog intake proxy。proxy 使用您的 ingest key 验证请求,为请求写入 project id,然后将其转发到 collector。collector 会移除客户端尝试设置的任何 superlog.* 属性,添加 proxy 从请求头提供的 superlog.project_id,进行批处理,然后写入 ClickHouse。web 应用和 API 从 ClickHouse 读取遥测数据,从 Postgres 读取其他所有数据。

移除这些属性是真正的多租户控制措施,而不是装饰。如果没有这一步,任何持有有效 ingest key 的人都可以自行设置 superlog.project_id,并将数据写入其他项目。

VPS 需要多大的配置?

对于低摄入量的单节点安装,建议配置为 4 vCPU、8 GB RAM 和 40 GB SSD。这只是规划下限,不是测量结果。请将其作为起始配置,并根据自身流量进行验证。

内存主要分配给四个部分。ClickHouse 面向内存充足的机器设计,其默认配置也基于这一假设。这里的 Postgres 16 资源需求不高,因为它保存的是元数据,而不是遥测数据。采集器的资源需求也不高。4 个 Node 进程包括一个 Vite 开发服务器和 3 个 tsx watch 进程。请在自己的服务器上测量它们的内存使用量。

磁盘是更容易被忽视的问题。在摄入第一个 span 之前,pnpm install 会在这个 monorepo 中拉取 AWS SDK、ClickHouse 客户端、OpenTelemetry SDK 和 React 工具链。之后,ClickHouse 会随着流量增长。请同时测量以下两项:

df -h /
free -m
docker stats --no-stream
docker compose exec clickhouse clickhouse-client --database superlog --query "SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE active AND database = 'superlog' GROUP BY table ORDER BY sum(bytes_on_disk) DESC"

真正造成压力的是突发流量:一次有问题的部署可能会在一分钟内产生数千条相同错误。指纹功能会将这些错误合并为读者看到的一个事件,但 ClickHouse 仍会在底层写入每一行数据。

保留期限由您设置。采集器的 ClickHouse exporter 会创建表、otel_traces、otel_logs 以及每种指标类型对应的一张表。只有当 infra/collector/config.yaml 中的配置设置了 TTL 时,它才会应用数据过期时间。数据不会自动过期,因此繁忙一个月后可能占满整个磁盘,除非您提前规划。

从固定提交安装

git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'

截至 13 October 2026,git tag -l不输出任何内容才是预期结果。选择已测试的提交并固定使用它:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

接下来准备工具链:

node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -v

package.json将 engines.node声明为 >=20.0.0,并将 packageManager声明为 pnpm@9.12.0。Node 版本不兼容不会自动阻止安装:引擎检查是否强制执行取决于配置;禁用 engineStrict 时,pnpm 9.12.0 会进入警告路径。Ubuntu 24.04 软件源中的 nodejs 版本低于 20,因此请从 NodeSource 或 nvm 安装 Node 20 或更高版本。该仓库提供了 .nvmrc,因此如果已安装 nvm,nvm use 会选择预期版本。

pnpm install
docker compose up -d
docker compose ps

请等待健康检查完成,不要把 up -d 单独视为服务已就绪。Postgres 和 ClickHouse 都在 compose 文件中声明了健康检查:

curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgres

ClickHouse 会响应 Ok.,而 pg_isready 会响应 accepting connections。8123 连接被拒绝表示容器仍在启动,或已经退出。docker compose logs clickhouse 可显示具体情况;如果内核因内存不足终止容器,docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled 会报告 true。这通常说明服务器配置过小,而不是配置文件有误。

接下来执行迁移并启动应用:

pnpm --filter @superlog/db db:migrate
pnpm dev

注意端口是 5434,而不是 5432。compose 文件将 Postgres 发布到 5434,以免与主机上已安装的 Postgres 发生冲突;应用的 .env.example 文件也与此匹配,并使用 DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog。如果在已运行 Postgres 的服务器上将迁移指向 5432,可能会得到连接被拒绝的错误;更严重时,迁移可能会应用到错误的数据库。

pnpm dev 会运行 turbo run dev,通过 Turborepo 启动每个应用的 dev 脚本,包括 api、web、worker 和 proxy,并将它们的输出混合显示在同一个终端中。仓库的 Procfile 列出了相同的四个进程,并将每个进程的输出通过 tee 写入 tmp/logs/。如果希望在 tail -f tmp/logs/proxy.log 中监控 ingest,请使用 overmind 或 foreman 等 Procfile 运行器启动它,而不要使用 pnpm dev。README 将 web 应用配置在 http://localhost:5173,API 配置在 http://localhost:4100,OTLP 接收端配置在 http://localhost:4101。

在将任何请求指向服务前,先确认实际监听的端口:

ss -lntp | grep -E '4000|4100|4101|5173'
curl -sS http://127.0.0.1:4101/health

这会在后续步骤中产生影响。代理从 PORT 环境变量读取自身端口;如果未设置 PORT,则回退到 4000。它加载的 apps/proxy/.env.example 也会设置 PORT=4000,但 README 将接收端列为 4101(两项均于 13 October 2026 检查)。请使用 ss 显示的端口。下面的示例使用 4101;如果实际监听的是 4000,请替换为 4000。自行编写的 systemd 单元不会自动设置任何变量,除非在其中加入 PORT。因此,如果代理监听 4000,而 exporter 指向 4101,连接会被拒绝,且不会提供其他线索。

发送一条追踪数据,产生一个错误,查看一个事件

在 Web 应用中创建项目并复制其 ingest key。接收端会使用该密钥验证每个请求,因此未携带密钥发送的遥测数据不会到达 ClickHouse。

使用标准环境变量,将任意 OpenTelemetry SDK 指向接收端:

export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4101
export OTEL_EXPORTER_OTLP_HEADERS='x-api-key=YOUR_INGEST_KEY'

接收端从 x-api-key 请求头读取密钥;如果您的 exporter 更便于以这种方式配置,也接受 authorization: bearer YOUR_INGEST_KEY。它提供 3 个标准 OTLP 路径:/v1/traces、/v1/logs 和 /v1/metrics,以及 /health。

有一个陷阱需要特别说明。OTEL_EXPORTER_OTLP_ENDPOINT 是基础 URL,SDK 会将信号路径追加到该 URL。OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 等信号专用变量会按原样使用,不会追加路径。将信号专用变量设置为 http://127.0.0.1:4101 后,每次导出都会向 / 发送请求。该地址不是路由,因此不会有数据到达;SDK 会记录导出失败,而您的应用看起来仍然正常。

对于 Node 服务,无代码路径就足以验证整个链路:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.js

现在故意制造一个故障。任何会抛出错误的路由都可以:

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boom

按顺序检查各个环节,因为第一个出现缺口的地方就是故障点:

tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'

如果 otel_traces 中的计数不断增加,但 Web 应用中没有数据,说明项目不匹配。请检查 ingest key 所属的项目。如果计数没有变化,但代理日志中有活动,问题可能出在 collector 或写入 ClickHouse 的环节。请查看 docker compose logs collector。如果代理日志完全没有活动,说明 exporter 从未到达接收端:可能是端口错误、路径错误或密钥被拒绝。

在 Web 应用中,这些重复失败会合并为一个事件,而不是每个请求对应一行。Superlog 会为传入信号生成指纹,并将匹配的信号分组。这样,收件箱中不会出现 4,000 条相同错误,而是只显示一个页面。默认的社区 agent runner 随后会为该分组记录本地事件摘要。

要执行由模型支持的调查,必须配置模型提供商和兼容的 agent runner;默认的社区 runner 会记录本地摘要。请从您固定的提交中每个应用目录内的 .env.example 文件获取这些变量名,不要参考外部文章,因为这些变量会随 main 变化。GitHub 和 Sentry 集成也同样如此:它们分别在 docs/github-app-setup.md 和 docs/sentry-app-setup.md 提供自己的配置文档,并在 docs/webhooks.md 记录 webhook payload。

保持接收端私有,并让代理仅具备只读权限

Docker 默认会将容器端口发布到 0.0.0.0,而且这些已发布端口会绕过 ufw。Docker 在 nat 表中路由容器流量,因此发往已发布端口的数据包会在到达 ufw 规则所在的 INPUT 和 OUTPUT 链之前被转发,ufw 根本无法介入。在具有公网 IP 的 VPS 上,随附的 compose 文件会将 ClickHouse HTTP 暴露在 8123 端口,并将 Postgres 暴露在 5434 端口,互联网可以直接访问这两个端口。该文件中的凭据是开发环境默认值:ClickHouse 用户为 default,密码为空;Postgres 的用户名和密码均为 postgres。

将它们绑定到 loopback。compose 文件中的每个已发布端口都从环境变量获取主机端,因此在仓库根目录创建一个 .env 即可:

POSTGRES_HOST_PORT=127.0.0.1:5434
CLICKHOUSE_HTTP_HOST_PORT=127.0.0.1:8123
CLICKHOUSE_TCP_HOST_PORT=127.0.0.1:9000
COLLECTOR_GRPC_HOST_PORT=127.0.0.1:4317
COLLECTOR_HTTP_HOST_PORT=127.0.0.1:4318

在信任结果之前先验证,然后重新创建容器:

docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'

docker compose config 会打印解析后的文件,因此你可以直接查看 127.0.0.1:5434:5432,而不是凭猜测判断。此时,ss 应显示 127.0.0.1:5434,且不应显示 0.0.0.0:5434。如果主机 IP 不同,仅在 Compose override 文件中重新声明 ports 会保留这两个绑定;Compose 2.24.4 及更高版本支持使用 ports: !override 替换该列表。

接收端同样需要谨慎处理。你的 ingest key 会通过请求头传输,因此前面必须使用 TLS(传输层安全):在代理前端使用 nginx 或 Caddy 终止 TLS,或者将 ingest 保留在私有网络或 WireGuard 隧道中。5173 端口上的 Web 应用是 Vite 开发服务器,根本不应暴露到互联网。

接下来是代理本身。Superlog 的定位是让代理调查问题并提出修复方案,关键在于“提出”。在观察它处理几起真实事件之前,应让它对生产环境保持只读权限。只读 GitHub App 无法推送修复分支或创建 pull request:该工作流的设置指南要求 Contents 和 Pull requests 的写入权限,并要求 Issues 的写入权限以发布评论。能够读取遥测数据并写入补丁的代理很有用。能够重启服务的代理则带来更高等级的风险;是否授予这种权限应由你有意决定,而不应继承默认配置。配置基于模型的运行器时,也应同样重视成本:先为 VPS 上的代理支出制定预算,再将其指向嘈杂的生产系统,并保留代理实际执行操作的记录,这样出现意外的 pull request 时,背后仍有审计轨迹。

会遇到的故障及其错误信息

  • 在 pnpm install 期间出现 ERR_PNPM_UNSUPPORTED_ENGINE,表示引擎要求不兼容。pnpm 9.12.0 会同时检查 Node 和 pnpm 的要求;查看错误信息中的所需版本和当前版本,然后检查 node -v 和 pnpm -v。
  • 迁移期间出现 ECONNREFUSED 127.0.0.1:5434,表示 compose 堆栈未启动,或 DATABASE_URL 指定了错误的端口。
  • 使用 docker compose logs clickhouse 检查 ClickHouse 是否重启,然后检查容器中的 OOMKilled 是否为 true。
  • 如果导出器报告成功,但 Web 应用仍为空,通常表示数据直接发送到了 4318 端口上的采集器,绕过了代理为项目添加标识的处理。
  • 连接 4101 被拒绝通常表示代理正在监听 4000 端口。这是代码的回退端口,也是其 .env.example 设置的端口。在单元文件或应用的 .env 中显式设置 PORT。
  • docker compose ps 显示 0.0.0.0:8123,表示回环绑定未生效。运行 docker compose config,然后读取解析后的端口。

Flawless、HyperProbe 以及 Superlog 的定位

这个类别还很新,各工具对代理可以接触的范围有不同限制。Flawless 存储库现在推出了 CISRE。这是一个面向 Kubernetes 和云基础设施的 AI SRE(站点可靠性工程)平台,采用 PolyForm Noncommercial 许可证。HyperProbe 将探针注入正在运行的进程,以捕获变量状态,并通过 MCP(模型上下文协议)将这些状态提供给助手。它还记录了使用 Docker Compose 自托管以及配置许可证密钥的方法。

Superlog 介于两者之间。它端到端负责整个流水线,从接收 OTLP 数据到将数据存储在 ClickHouse 中,并将代理放在故障分诊步骤,而不是修复步骤。正因如此,自托管 Superlog 是一项基础设施决策,而不是部署后可以置之不理的容器。运行 Superlog 后,您实际上运行的是列式存储系统,因此需要像维护其他自有数据库一样维护它。

FAQ

自托管 Superlog 需要多少 RAM?

对于低数据摄取量的单节点部署,准备 8 GB RAM、4 个 vCPU 和 40 GB 磁盘空间。该技术栈包括 Postgres、ClickHouse、一个 OpenTelemetry collector 和 4 个 Node 进程,而 ClickHouse 需要预留足够的资源余量。使用 docker stats --no-stream 和 free -m 测量您自己的数据,不要盲目采用任何已发布的数值,包括这里的数值。

OTLP exporter 应指向哪个端口?

指向 Superlog 的接收代理。README 将其配置在 http://localhost:4101。它提供 /v1/traces、/v1/logs 和 /v1/metrics,并使用从 x-api-key header 或 authorization: bearer header 获取的项目 ingest key 进行身份验证。4318 端口由底层 OpenTelemetry collector 使用。直接向该端口导出会绕过代理,而代理负责将项目 ID 写入数据。PORT 未设置时,代理会回退到 4000 端口;其 .env.example 也会将端口设置为 4000。因此,请运行 ss -lntp,确认实际绑定的端口后,再假定端口为 4101。

Superlog 能替代 Uptime Kuma 或 Zabbix 吗?

不能。Uptime Kuma 用于确认从网络外部访问某个端点时是否有响应。Zabbix 根据您设置的阈值监控主机和服务指标。Superlog 接收应用生成的 trace、日志和指标,并将重复故障归并为事件。请同时保留外部 uptime 探针,因为运行在其他位置的探针仍能报告故障,即使承载遥测流水线的服务器本身已经停止运行。

Superlog agent 能更改我的生产系统吗?

只能使用您授予它的权限。默认的社区 runner 只记录本地事件摘要;其他调查运行时取决于您配置的 runner。请将生产凭据限制为只读权限。创建 pull request 需要为分支和 pull request 单独授予 GitHub 写权限。请将生产环境写权限作为单独的决策,并明确评估其影响。能够重启服务的 agent,其权限承诺远大于只能读取遥测数据并生成供审核的补丁的 agent。

应固定某个 commit,还是跟踪 main?

固定某个 commit。截至 13 October 2026,该仓库没有 release tag。记录经过测试的 SHA,部署该版本,并在升级前阅读 diff。git log --oneline <old-sha>..main 是审核内容;每个应用的 .env.example 文件是升级后检查新增必需变量的首要位置。

这篇文章对您有帮助吗?