trench

一条命令部署，快速搭建产品分析平台

Trench 是一个开源的轻量级分析基础设施，旨在帮助开发者快速构建产品分析、LLM RAG、可观测性平台等分析类应用。它基于 ClickHouse、Kafka 和 Node.js 构建，提供单个生产就绪的 Docker 镜像，简化了事件追踪和分析管道的搭建。Trench 解决了从零搭建分析后端的高成本问题，核心能力包括事件数据采集、流式处理、存储与查询，并支持通过 API 或 SDK 灵活接入。其设计强调易用性和可扩展性，适合需要自托管分析功能的团队。

开源 free 搜索知识

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1663

维护状态低维护

是否开源是

定价模式 free

项目数据

分类搜索知识

开发团队FrigadeHQ

所属国家

官网地址https://trench.dev

GitHubhttps://github.com/FrigadeHQ/trench

定价模式free

价格说明开源项目，MIT许可证，可自行部署，完全免费。

访问状态

是否开源是

开源协议MIT

主要语言TypeScript

技术栈/模型analytics,clickhouse,clickhouse-database,clickhouse-server,dashboard,dashboards,event-replay,kafka,kafka-engine,llm,matomo,matomo-analytics,nodejs,open-source,plausible-analytics,posthog,product-analytics,rag,tracking,tracking-events

GitHub 星标★ 1663

30天Star增速

HF 下载量

上线时间2024-09-30 00:00:00

最近更新2026-09-16 00:00:00

维护状态低维护

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数3

使用教程

难度：入门约 15 分钟部署方式：Docker 7 步

环境要求

已安装 Docker 与 Docker Compose（唯一前置条件）
生产环境建议至少 4GB 内存和 4 个 CPU 核心
本地需能访问 4000 端口，并能拉取 git 仓库与 Docker 镜像

安装与启动步骤

1克隆仓库

把 Trench 源码克隆到本地，URL 来自 README。克隆完成后目录名为 trench。
```
git clone https://github.com/frigadehq/trench.git
```
2准备配置文件

进入服务目录（apps/trench），把示例环境变量文件复制为 .env，后续可在这里改配置和 API Key。
```
cd trench/apps/trench
cp .env.example .env
```
3启动 Dev 服务

用 dev compose 文件启动，会自动构建镜像并拉起本地 ClickHouse 与 Kafka，首次构建耗时较长。
```
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build --force-recreate --renew-anon-volumes
```

4发送示例事件

用 .env 中的 public API Key 以 Bearer 方式向 /events 发送一条 ConnectedAccount 事件。

curl -i -X POST -H "Authorization:Bearer public-d613be4e-di03-4b02-9058-70aa4j04ff28" -H "Content-Type:application/json" -d "{"events":[{"userId":"550e8400-e29b-41d4-a716-446655440000","type":"track","event":"ConnectedAccount","properties":{"totalAccounts":4,"country":"Denmark"}}]}" 'http://localhost:4000/events'

5查询事件

用 private API Key 调用 GET /events 并按事件名过滤，可看到刚发送的事件返回。

curl -i -X GET -H "Authorization: Bearer private-d613be4e-di03-4b02-9058-70aa4j04ff28" 'http://localhost:4000/events?event=ConnectedAccount'

6执行 SQL 查询

调用 /queries 端点直接跑 ClickHouse SQL 做统计分析，示例统计某 userId 的事件条数。

curl -i -X POST -H "Authorization:Bearer public-d613be4e-di03-4b02-9058-70aa4j04ff28" -H "Content-Type:application/json" -d "{"queries":["SELECT COUNT(*) FROM events WHERE userId = '550e8400-e29b-41d4-a716-446655440000'"]}" 'http://localhost:4000/queries'

7SASL 方式启动

如需 Kafka SASL 认证，改用专用 compose 文件在后台构建启动；SSL+SASL 用 docker-compose.ssl-sasl.yml。
```
docker compose -f docker-compose.sasl.yml up -d --build
```

关键配置

配置项	必填	说明	示例
`public API key（.env 内）`	是	公共 Key，用于发送事件与执行查询的 Bearer 鉴权	`public-d613be4e-di03-4b02-9058-70aa4j04ff28`
`private API key（.env 内）`	是	私有 Key，用于读取事件等需要更高权限的请求	`private-d613be4e-di03-4b02-9058-70aa4j04ff28`
`KAFKA_SASL_MECHANISM`	否	SASL 认证机制，SASL compose 启动时使用	`PLAIN`
`KAFKA_SASL_USERNAME`	否	Kafka SASL 用户名，SASL compose 启动时使用	`kafka_user`
`KAFKA_SASL_PASSWORD`	否	Kafka SASL 密码，SASL compose 启动时使用	`kafka_password`

如何确认成功

浏览器打开 http://localhost:4000，页面显示 “Trench server is running” 即启动成功；再发一次示例事件应能查询到。

常见问题

Q：启动服务需要什么配置？

A：唯一前置条件是安装 Docker 和 Docker Compose；生产环境建议至少 4GB 内存和 4 个 CPU 核心，单节点可处理每秒数千事件。

Q：如何修改 API Key 或端口等配置？

A：README 说明所有配置都在 apps/trench 目录下的 .env 文件中修改，改完重启容器生效。

Q：发送事件后查询不到数据怎么办？

A：事件是流式经 Kafka 写入 ClickHouse 的，会有短暂延迟；可稍后重试 GET /events，并确认用的是对应 public/private Key。

Q：Kafka 需要账号密码时怎么启动？

A：使用 README 提供的 docker compose -f docker-compose.sasl.yml up -d --build（SASL_PLAINTEXT，端口 9095）；需要 SSL+SASL 时改用 docker-compose.ssl-sasl.yml。

注意事项

发送事件用 public API Key，查询事件用 private API Key，两者都在 .env 中修改，示例值仅作演示。
生产环境建议至少 4GB 内存与 4 个 CPU 核心。
dev compose 会同时启动本地 ClickHouse 与 Kafka，首次 --build 构建时间较长。
SASL 与 SSL+SASL 部署使用不同的 compose 文件，ClickHouse 端需配套的 Kafka 认证配置文件。

核心亮点

单个 Docker 镜像，集成 ClickHouse 和 Kafka，部署简单
基于 ClickHouse，查询性能强，适合大规模事件数据分析
支持事件追踪 API，易于集成到现有应用

不足之处

文档/社区待观察
项目较新，生态和周边工具尚不成熟

适用场景

自建产品分析仪表盘
构建 LLM 应用的数据追踪与评估
搭建内部可观测性平台

替代项目

PostHog、Matomo、Umami

项目介绍

trench 是基础设施领域的开源项目，由 FrigadeHQ 开发，2024 年首次发布。

在全站 13,109 个收录项目中，它的 GitHub 星标数（1,663）位列前 30%，在基础设施分类中处于中上游。

项目已超过三个月没有代码更新，维护节奏明显放缓，最近一次代码更新于 2026-09-16。MIT许可证，可自行部署，完全免费。

它主要面向的使用场景是：自建产品分析仪表盘。同类可对比的替代方案包括 PostHog、Matomo、Umami。

上一篇：extractous

下一篇：EmbedAnything