Trench：把 Kafka 和 ClickHouse 装进一个 Docker 镜像的事件采集层
Trench — Open-Source Analytics Infrastructure. A single production-ready Docker image built on ClickHouse, Kafka, and Node.js for tracking events. Easily build product analytics dashboards, LLM RAGs, observability platforms, or any other analytics product.
秒懂
- 它是什么？
- Trench 是 Frigade 开源的实时事件追踪系统，用单个 Docker 镜像封装了 Kafka 与 ClickHouse，对外暴露兼容 Segment 的 Track/Group/Identify 接口。它解决的是采集管道自建成本问题，代价是查询能力目前基本等同于手写 SQL。
- 适合谁用？
- Trench 适合已经决定自建事件管道、并且愿意自己写 SQL 和前端图表的团队：它把 Kafka、ClickHouse 和 HTTP 接入层打包成一个镜像，省掉的是组件拼装和运维样板，不是分析产品本身。不适合指望开箱即得漏斗、留存、会话回放的人，README 里没有任何可视化界面的描述，dashboard 要靠 Grafana 或自己写。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 162 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
Trench 要替代的是自建采集管道，不是分析工具
多数团队做产品分析时的第一步不是选 BI 工具，而是搭一条从客户端到存储的采集链路：接收入口、消息队列、列式存储、查询接口，四段都要自己拼。Trench 把这条链路固化成一个镜像。README 的说法是，团队当初做它是为了扩展 Frigade 自己的实时事件追踪管道，也就是说它先是被内部生产环境逼出来的，再开源。
目标读者因此比较明确：手里已经有 Kafka 或 ClickHouse 使用经验、打算自建而不是买 SaaS 的工程团队。它对外只承诺三件事：兼容 Segment 的 Track、Group、Identify 三种调用；单个生产可用的 Docker 镜像；单节点每秒处理数千事件。最后一条是 README 里的自述，仓库材料没有给出压测方法或硬件规格，只能当作量级参考。
如果你的需求是「装上就能看漏斗和留存」，Trench 不在这个位置。它提供的是数据落地和查询入口，可视化要另接。
数据从 /events 进来，经 Kafka 落到 ClickHouse
从 README 的部署说明和接口示例能看出的数据流是：HTTP 请求打到 4000 端口的 /events，服务把事件写入 Kafka，再由消费端落到 ClickHouse，查询走 /events 或 /queries。quickstart 里那一条 docker-compose 命令会同时起本地 ClickHouse 和 Kafka，所以这三段在开发环境里是同一台机器上的三个进程。
写入接口接受批量结构，请求体是 events 数组，每个元素带 userId、type、event 和 properties。示例里 type 取 track，event 是自定义的 ConnectedAccount，properties 是任意键值对，示例中是 totalAccounts 和 country。这种结构意味着 Trench 不预设事件语义，属性怎么定义完全由调用方决定，代价是查询阶段没有 schema 帮你兜底。
查询返回的字段里有一个细节值得注意：除了 timestamp，还有 parsedAt。示例数据中 timestamp 是 2024-10-22T19:34:56.000Z，parsedAt 是 19:34:59.530Z，相差约三秒。README 没有解释这个字段的语义，从命名推测是落库处理时间，但如果要做端到端延迟监控，这个差值是否稳定、是否包含批处理等待，需要自己验证。
部署路径：一条 compose 命令和一个 .env
README 给出的前置条件只有 Docker 和 Docker Compose，生产环境建议至少 4GB 内存和 4 核 CPU。完整流程是克隆仓库、进入 apps/trench 目录、复制 .env.example 为 .env，然后执行：
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build --force-recreate --renew-anon-volumes
注意这里叠加了 dev 覆盖文件，并带了 --renew-anon-volumes，等于每次重建都清空匿名卷。这是开发环境的用法，直接照搬到生产会把数据一起清掉。README 把这条命令放在 Quickstart 标题下，没有单独区分生产部署命令，文档在这一块是偏薄的，上线前需要自己判断哪些参数该去掉。
服务起来后访问 http://localhost:4000 会看到 Trench server is running。API key 在 .env 里，示例用的是 public-d613be4e-... 和 private-d613be4e-... 这种带前缀的形式，读写分别对应 public 和 private 两个 key。示例 key 出现在 README 里，说明它是默认值，部署后第一件事就是替换。
Kafka 认证通过环境变量配置，README 列出的有 KAFKA_SSL_ENABLED、KAFKA_SSL_REJECT_UNAUTHORIZED、KAFKA_SSL_CA、KAFKA_SSL_CERT、KAFKA_SSL_KEY、KAFKA_SASL_MECHANISM、KAFKA_SASL_USERNAME、KAFKA_SASL_PASSWORD。SASL 机制支持 plain、scram-sha-256、scram-sha-512 三种。其中 KAFKA_SSL_REJECT_UNAUTHORIZED 默认 true，用自签证书的开发环境要显式改成 false。证书类变量填的是 PEM 内容本身而不是文件路径，这点容易踩坑。
/queries 端点把 ClickHouse 的 SQL 直接暴露给了调用方
Trench 最有意思也最需要想清楚的设计是 /queries 端点。README 的示例是 POST 一个 queries 数组，里面是字符串形式的 SQL，比如 SELECT COUNT(*) FROM events WHERE userId = '...'。返回结构是 results、limit、offset、total 四个字段。
这意味着 Trench 没有做语义层：不解析事件名，不生成漏斗查询，不做指标定义。它把 ClickHouse 的表结构当作公开契约，events 表名和 userId 这类列名直接出现在调用方的代码里。好处是灵活，任何 ClickHouse 能表达的聚合都能跑；坏处是表结构一旦调整就是破坏性变更，而 README 没有给出 schema 版本化或迁移策略的说明。
另一个问题是权限。示例中执行 /queries 用的是 public key，也就是那个用于上报事件的 key。如果这个行为在生产中保持一致，任何持有前端 key 的人都能向数据库发任意 SQL。README 没有说明 public 和 private 两个 key 在服务端是否被区别对待，这是部署前必须自己确认的一点，不能靠示例反推。
它不做可视化，也不做身份识别
README 的 Feature 列表里有 dashboard 和 dashboards 两个 topic，但正文没有任何内置界面的描述。演示部分说的是用 Trench 加 Grafana 搭一个基础版 Google Analytics，方向是外接 Grafana 而不是自带图表。所以「开源版 Plausible」这类联想是不准确的：Plausible 交付的是一个成品分析站点，Trench 交付的是数据层。
身份识别同样不在范围内。接口兼容 Segment 的 Identify 和 Group，意味着你可以把用户属性发进来，但 README 没有描述身份合并、匿名到登录态的 stitching，或者跨设备识别。no-cookie 和 GDPR、PECR 合规的说法出现在介绍段落里，具体怎么实现（是否依赖 userId 而非 cookie、删除请求走哪个接口）在给出的材料中看不到，文档站可能有，但仓库 README 没写。
所以选型时要分清：Trench 省掉的是 Kafka 加 ClickHouse 的搭建和接入层代码，不是分析产品的全部工作量。剩下的图表、指标定义、权限、用户界面，仍然是你的活。
和 PostHog 的差别在于交付边界
同样面向自建产品分析的 PostHog，走的是另一条路：它把采集、存储、查询、可视化、会话回放、特性开关都做进一套可自托管的产品里，代价是组件多、资源占用高、升级路径复杂。Trench 只做前半段，镜像更小，组件更少，但你得自己补上后半段。
这个差别决定了迁移成本的方向。从 Segment 迁到 Trench，改动主要在 SDK 和上报地址，因为接口是按 Track、Group、Identify 对齐的，仓库里也有 analytics-plugin-trench 这个包，说明它接入了 analytics 这类客户端库的插件体系。从 PostHog 迁到 Trench 则要重写所有看板，因为 PostHog 的查询是产品化的，Trench 的查询是 SQL。
反过来说，如果你已经有 Grafana 或 Metabase，并且团队习惯写 SQL，Trench 的边界反而更合适：它不试图接管你的展示层，你也不用为了一个事件表去跑一整套功能开关服务。
版本节奏与许可：MIT，但客户端包还很早期
仓库是 MIT 许可，自托管和修改都不需要额外授权，商业使用也没有附加条款。需要注意的只是 MIT 本身不提供任何担保，README 里「生产可用」是项目方的定位描述，不是法律或运维承诺。
版本方面，给出的最近三个 release 都集中在 2024 年 12 月 4 日前后：trench-js@0.0.17、trench-js@0.0.16、analytics-plugin-trench@0.0.9。全部是 0.0.x，按语义化版本的惯例属于未稳定阶段，接口可能随时调整。仓库最后一次 push 是 2026 年 4 月，说明项目仍在维护，但发布记录里没有 1.0 级别的节点。
升级成本取决于你依赖哪一层。只用 Docker 镜像和 HTTP 接口的话，升级是换镜像加跑迁移；一旦引入 trench-js 或 analytics-plugin-trench，0.0.x 的包在次版本之间出现破坏性改动是常见做法，锁版本并准备读 changelog 是必要的。README 没有提到 ClickHouse schema 的迁移机制，跨版本升级时数据兼容性如何，材料里无法确认。
编辑结论
Trench 适合已经决定自建事件管道、并且愿意自己写 SQL 和前端图表的团队：它把 Kafka、ClickHouse 和 HTTP 接入层打包成一个镜像，省掉的是组件拼装和运维样板，不是分析产品本身。不适合指望开箱即得漏斗、留存、会话回放的人，README 里没有任何可视化界面的描述，dashboard 要靠 Grafana 或自己写。采用前先确认三件事：默认 .env 里的 public/private API key 是否已替换、/queries 端点打算向谁开放、以及你的 Kafka 是否需要 SASL 或 mTLS（对应 KAFKA_SASL_MECHANISM、KAFKA_SSL_ENABLED 等变量）。
社区笔记