自托管分析服务

Supabase 分析服务器是一个可自托管的 Logflare 实例，负责管理用于搜索和聚合结构化分析事件的摄入和查询管道。

当自托管分析服务器时，Studio 实例中将提供与 Supabase 平台完全匹配的完整日志体验，从而实现集成和增强的开发体验。 但需要注意的是，由于平台基础设施的差异，可能会出现某些不同之处。

支持的数据库后端

Analytics 服务器支持使用 Postgres 或 BigQuery 作为后端。supabase-cli 默认使用 Postgres 后端。而 Supabase 平台则使用 BigQuery 后端来存储所有平台日志。

当使用 BigQuery 后端时，系统会在提供的 Google Cloud 项目中创建一个 BigQuery 数据集，并为每个日志源创建对应的表。日志事件会被流式传输到各个表中，所有由 Studio 或日志浏览器生成的查询都会通过 BigQuery API 执行。该后端需要互联网连接才能工作，无法完全在本地运行。

当使用 Postgres 后端时，系统会在指定模式中为每个日志源创建表（对于 supabase-cli，该模式为 _analytics）。Logflare 接收到的日志事件会直接插入到相应的表中。来自 Studio 的所有 BigQuery 方言 SQL 查询将由 Analytics 服务器内的翻译层处理。该翻译层会将查询转换为 PostgreSQL 方言，然后在 Postgres 数据库上执行。

目前 Postgres 后端尚未针对高频率插入或大量查询使用进行优化。当前的翻译层仅支持 BigQuery 方言的有限子集。因此，当使用 Postgres 后端时，日志浏览器对于更复杂的查询可能会产生错误。

入门指南

在熟悉和实验自托管 Supabase 时，推荐使用 Postgres 后端。对于生产环境，我们建议使用 BigQuery 后端。更多信息请参阅生产环境建议。

要设置自托管 Supabase 的日志记录，请参考 docker-compose 示例。 需要两个 compose 服务：Logflare 和 Vector。Logflare 是 HTTP 分析服务器，而 Vector 是日志管道，用于将所有 compose 服务的系统日志路由到 Logflare 服务器。

无论选择哪种后端，以下环境变量必须为 supabase/logflare docker 镜像设置：

• LOGFLARE_SINGLE_TENANT=true：启用 Logflare 单租户模式的特性标志。必须设置为 true
• LOGFLARE_SUPABASE_MODE=true：用于植入 Supabase 相关数据的特性标志。必须设置为 true

其他所有配置环境变量，请参考 Logflare 自托管文档。

Postgres 后端设置#

示例 docker-compose 默认使用 Postgres 后端。

1
2
3
# 克隆 supabase/supabase 仓库，并运行以下命令cd dockerdocker compose -f docker-compose.yml up

配置与要求

• supabase/logflare:1.4.0 或更高版本
• 相关环境变量：
  • POSTGRES_BACKEND_URL：必需。Postgres 数据库的连接字符串。
  • POSTGRES_BACKEND_SCHEMA：可选。允许自定义用于限定所有后端操作范围的数据库模式。

BigQuery 后端设置#

BigQuery 后端是一个更强大、可扩展的后端选项，经过实战检验且生产就绪。如果您预计会有大量日志使用需求，并需要如日志浏览器等高级查询功能，请使用此后端。

配置与要求

创建项目后需满足以下要求：

• 已启用结算功能的 Google Cloud 项目
• 项目 ID
• 项目编号
• 服务账号密钥

设置 BigQuery 服务账号#

使用的服务账号必须具有足够的权限来向 Google Cloud BigQuery 插入数据。请确保服务账号具有以下任一权限：

• BigQuery 管理员角色；或
• 以下具体权限：
  • bigquery.datasets.create
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
  • bigquery.datasets.update
  • bigquery.jobs.create
  • bigquery.routines.create
  • bigquery.routines.update
  • bigquery.tables.create
  • bigquery.tables.delete
  • bigquery.tables.get
  • bigquery.tables.getData
  • bigquery.tables.update
  • bigquery.tables.updateData

您可以通过网页控制台或 gcloud CLI 创建服务账号，具体操作请参考 Google Cloud 文档。在网页控制台中，可通过导航至 IAM > 服务账号 > 操作（下拉菜单）> 管理密钥 来创建密钥。

我们建议设置 BigQuery 管理员角色，这样可以简化权限配置。

下载服务账号密钥

创建服务账号后，您需要为该账号创建密钥。该密钥将用于为 Analytics 服务器与 BigQuery 交互的 API 请求签署 JWT。此操作可通过 Google Cloud 控制台的 IAM 部分完成。

Docker 镜像配置#

使用基于 docker-compose 的自托管示例栈时，您可以通过以下命令包含日志相关服务：

1. 更新 .env.example 文件，添加必要的环境变量：

   • GOOGLE_PROJECT_ID
   • GOOGLE_PROJECT_NUMBER

2. 将您的服务账户密钥文件以 gcloud.json 为名放置在当前工作目录中。

3. 在 docker-compose.yml 文件中，取消注释 # Uncomment to use Big Query backend for analytics 注释下方的配置块。

4. 在 docker-compose.yml 文件中，注释掉 # Comment variables to use Big Query backend for analytics 注释下方的配置块。

完成上述步骤后，您可以使用以下命令启动示例栈：

1
2
3
# 假设您已克隆 supabase/supabase 仓库cd dockerdocker compose -f docker-compose.yml

BigQuery 数据集存储位置#

目前，无论是通过 CLI 还是自托管方式，Analytics 服务存储和管理的所有 BigQuery 数据集默认都会位于美国区域。

Vector 使用说明#

在 Docker Compose 示例中，Vector 被用于日志管道，将日志事件转发至 Analytics API 进行数据摄取。

在自定义配置时，请参考 Vector 配置文件。

必须确保日志负载符合预期的事件模式结构。若结构不正确，将导致 Studio 日志界面的功能异常。

与平台版的差异

API日志依赖于Kong而非Supabase云API网关。来自Kong的日志不会包含平台专有的数据增强信息。

在自托管部署中，所有日志都通过Vector路由到Logflare。由于Kong将API请求路由到PostgREST，自托管或本地部署会产生Kong请求日志而非平台版日志。 这将导致自托管API请求与Supabase平台请求的日志事件元数据存在差异。

生产环境建议

要在生产环境中自托管，我们建议执行以下操作以获得更好的体验。

确保Logflare位于防火墙后并限制除安全请求外的所有网络访问#

自托管版Logflare默认禁用UI身份验证，设计用于暴露在互联网上。我们建议限制对仪表板的访问（可通过/dashboard路径访问）。 如果需要通过仪表板管理数据源，建议添加认证层（如VPN）。

使用单独的Postgres数据库存储Logflare数据#

Logflare需要Postgres数据库才能运行。但如果自托管Postgres服务出现问题，您将无法进行调试，因为这会连带导致Logflare服务中断。

当前自托管示例仅作为运行完整技术栈的最小化示例，不建议将同一数据库服务器同时用于生产环境和可观测性系统。

使用Big Query作为Logflare后端#

当前Postgres摄取后端未针对生产环境使用进行优化。对于更重度的使用场景，我们推荐使用Big Query。

我们推荐在生产环境中使用 BigQuery 后端，它能提供更好的扩展性和查询/调试体验。