开源分析基础设施 Trench 发布

文档 · 网站 · Slack 社区 · Demo

Trench 是建立在 Apache Kafka 和 ClickHouse 之上的事件追踪系统。它能够处理大量事件并提供实时分析。Trench 无需 Cookie，符合 GDPR 和 PECR 规范。用户对其数据拥有完全控制权，可以访问、纠正或删除数据。

我们团队开发 Trench 是为了扩展 Frigade 的实时事件追踪管道。

🤝 符合 Segment API（Track、Group、Identify）

🐳 通过单个生产就绪的 Docker 镜像快速部署

💻 在单个节点上每秒处理数千个事件

⚡ 实时查询数据

🔗 通过 Webhooks 将数据连接到其他目的地

👥 开源且采用 MIT 许可证

实时演示：https://demo.trench.dev

观看以下演示，了解如何使用 Trench 和 Grafana 构建 Google Analytics 的基础版本。

Trench 有两种部署方式：

Trench Self-Hosted：一个开源版本，可在自己的基础设施上部署和管理 Trench。

Trench Cloud：完全托管的无服务器解决方案，具有零运维、自动扩展和 99.99% 的 SLA。

1. Trench Self-Hosted 💻

按照下面和快速入门指南中的自托管说明来开始使用 Trench Self-Hosted。

如果您有任何问题或需要帮助，可以加入我们的 Slack 组获得支持。

部署 Trench Dev Server：Trench 的唯一前提条件是系统已安装 Docker 和 Docker Compose，见安装指南。如果运行生产环境，我们建议至少配置 4GB RAM 和 4 个 CPU 内核以获得最佳性能。安装 Docker 后，可以通过运行以下命令启动本地开发服务器：

git clone https://github.com/frigadehq/trench.git
cd trench/apps/trench
cp .env.example .env
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build --force-recreate --renew-anon-volumes

上面的命令将启动 Trench 服务器，包括本地 ClickHouse 和 Kafka 实例，访问地址为 http://localhost:4000。您可以在浏览器中打开此 URL，应该会看到 Trench server is running 的消息。您应该更新 .env 文件来更改任何配置选项。

发送示例事件：您可以在 .env 文件中找到并更新默认的公共和私有 API 密钥。使用公共 API 密钥，可以将示例事件发送到 Trench，如下所示：

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'

查询事件：可以使用 /events 端点查询事件（更多详情请参考 API 参考）。

您也可以直接从本地 Trench 服务器查询事件。例如，要查询 ConnectedAccount 类型的事件，可以使用以下 URL：

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

这将返回刚刚发送的事件的 JSON 响应：

{
  "results": [
    {
      "uuid": "25f7c712-dd86-4db0-89a8-d07d11b73e57",
      "type": "track",
      "event": "ConnectedAccount",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "properties": {
        "totalAccounts": 4,
        "country": "Denmark"
      },
      "timestamp": "2024-10-22T19:34:56.000Z",
      "parsedAt": "2024-10-22T19:34:59.530Z"
    }
  ],
  "limit": 1000,
  "offset": 0,
  "total": 1
}

执行原始 SQL 查询：使用 queries 端点来分析数据。示例：

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'

示例查询结果：

{
  "results": [
    {
      "count": 5
    }
  ],
  "limit": 0,
  "offset": 0,
  "total": 1
}

Trench 支持连接到需要 SASL 和/或 SSL 的 Kafka 集群。通过以下环境变量进行配置（全部可选）：

KAFKA_SSL_ENABLED：连接到 broker 时启用 SSL/TLS。值：true/false（默认：false）。

KAFKA_SSL_REJECT_UNAUTHORIZED：是否验证 broker 证书。值：true/false（默认：true）。在开发中使用自签名证书时设置为 false。

KAFKA_SSL_CA：CA 证书内容（PEM）。当 broker 使用自定义 CA 时使用。

KAFKA_SSL_CERT：客户端证书内容（PEM），如果需要相互 TLS。

KAFKA_SSL_KEY：客户端私钥（PEM），如果需要相互 TLS。

KAFKA_SASL_MECHANISM：plain、scram-sha-256 或 scram-sha-512 之一。

KAFKA_SASL_USERNAME：SASL 用户名（设置 KAFKA_SASL_MECHANISM 时必需）。

KAFKA_SASL_PASSWORD：SASL 密码（设置 KAFKA_SASL_MECHANISM 时必需）。

对于 SSL 证书变量，直接提供 PEM 内容（包括页眉/页脚）或挂载文件并在启动前加载到环境变量中。

在本地使用 Bitnami Kafka 镜像时，默认的 docker-compose.yml 使用 PLAINTEXT；如果需要，在 Kafka 部署中设置适当的 broker 监听器并公告 SSL/SASL 端点。

ClickHouse 的 Kafka 认证应在 ClickHouse 服务器配置文件中配置，而不是在 SQL 迁移中。

ClickHouse Kafka 认证

要使 ClickHouse 连接到经过身份验证的 Kafka 集群，需要在 ClickHouse 服务器配置文件中配置身份验证。

如果您不想自托管，可以通过以下方式在几分钟内开始使用 Trench：

• 我们的 Cloud 网页界面

• 我们的 Cloud 快速入门指南

Kafka 认证示例

Trench 支持通过 SASL 和 SSL 进行 Kafka 身份验证。以下是配置 Node.js KafkaJS 客户端和 ClickHouse 用于经过身份验证的 Kafka 连接的示例。

SASL-only：docker compose -f docker-compose.sasl.yml up -d --build

SSL+SASL：首先使用 ./scripts/generate-kafka-certs.sh 生成证书，然后运行 compose 文件

# Run with SASL authentication (no SSL)
docker compose -f docker-compose.sasl.yml up -d --build

Node.js KafkaJS：KAFKA_SASL_MECHANISM=PLAIN, KAFKA_SASL_USERNAME=kafka_user, KAFKA_SASL_PASSWORD=kafka_password

ClickHouse：预配置了 clickhouse-kafka-auth-config-example/clickhouse-sasl.xml 用于 Kafka 身份验证

Kafka：端口 9095 上的 SASL_PLAINTEXT 监听器

# Step 1: Generate SSL certificates
./scripts/generate-kafka-certs.sh

# Step 2: Set environment variables for SSL certificates
export KAFKA_SSL_CA=$(cat ./certs/ca.pem)
export KAFKA_SSL_CERT=$(cat ./certs/client.pem)
export KAFKA_SSL_KEY=$(cat ./certs/client-key.pem)

# Step 3: Run with both SSL and SASL authentication
docker compose -f docker-compose.ssl-sasl.yml up -d --build

Node.js KafkaJS：通过环境变量进行 SSL+SASL 身份验证

ClickHouse：预配置了 clickhouse-kafka-auth-config-example/clickhouse-ssl-sasl.xml 用于 Kafka 身份验证

Kafka：端口 9095 上的 SASL_SSL 监听器，带有 SSL 证书

Trench 是由 Frigade 构建的项目。