Supabase 连接器

将您的 Supabase 项目连接起来,同步数据库记录、用户认证数据、文件存储事件和实时变更,用于客户互动自动化。

概览

属性
平台Supabase
类别数据库与后端
设置复杂度简单
官方集成
同步数据用户、表、存储、事件
可用技能11
API 类型REST (PostgREST) + Realtime WebSocket
官方文档supabase.com/docs

功能

  • 自动生成 REST API,通过 PostgREST 对任何 Postgres 表进行 CRUD 操作,无需编写代码
  • 认证用户同步,将 Supabase Auth 用户(邮箱、手机、社交登录)同步到您的用户互动平台
  • 实时订阅,实时监听任意表上的 INSERT、UPDATE、DELETE 事件
  • 行级安全,所有 API 访问遵守 Postgres RLS 策略,确保多租户数据安全
  • 存储集成,跨存储桶追踪文件上传和管理资产
  • 边缘函数,调用无服务器 Deno 函数处理自定义逻辑和 Webhook
  • 全文搜索,通过 API 利用 Postgres 全文搜索功能

前提条件

开始之前,请确保您已具备:

  1. Supabase 项目(app.supabase.com
  2. 项目的 API URLAPI 密钥(在设置 → API 中找到)
  3. 具有 API 访问权限的 Tajo 账户

API 密钥

Supabase 提供两种密钥:anon(公共,遵守 RLS)和 service_role(绕过 RLS,管理员访问)。服务端集成使用 service_role,客户端使用 anon

认证

Supabase 使用 API 密钥认证。每个请求都需要 apikey 头部,可选附带用于用户范围访问的 Authorization Bearer 令牌。

Terminal window
# Using anon key (respects RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
-H "apikey: <SUPABASE_ANON_KEY>" \
-H "Authorization: Bearer <SUPABASE_ANON_KEY>"
# Using service_role key (bypasses RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
-H "apikey: <SUPABASE_SERVICE_ROLE_KEY>" \
-H "Authorization: Bearer <SUPABASE_SERVICE_ROLE_KEY>"

配置

基础设置

connectors:
supabase:
enabled: true
project_url: "https://xyzcompany.supabase.co"
api_key: "${SUPABASE_SERVICE_ROLE_KEY}"
# Data sync options
sync:
users: true
tables:
- customers
- orders
- products
storage: true
realtime: true
# Map Supabase Auth users to contacts
user_mapping:
email: email
phone: SMS
user_metadata.full_name: FIRSTNAME
created_at: SIGNUP_DATE

字段映射

将 Supabase 表列映射到用户互动平台属性:

默认用户映射

Parameter Type Description
email required
string

来自 Supabase Auth 的用户邮箱(唯一标识符)

phone optional
string

用于 SMS/WhatsApp 互动的手机号码

user_metadata.full_name optional
string

来自 Auth 用户元数据的显示名称

user_metadata.avatar_url optional
string

个人资料图片 URL

created_at optional
timestamp

账户创建时间戳

last_sign_in_at optional
timestamp

最近登录时间,用于互动评分

app_metadata.provider optional
string

认证提供商(email、google、github 等)

confirmed_at optional
timestamp

邮箱确认时间戳

自定义表映射

table_mapping:
customers:
# Column → Attribute mapping
email: email
full_name: FIRSTNAME
company: COMPANY
plan: SUBSCRIPTION_PLAN
mrr: MONTHLY_REVENUE
created_at: SIGNUP_DATE
orders:
# Track as events
sync_as: events
event_name: "order_placed"
properties:
total: amount
status: order_status
items: line_items

API 端点

Supabase REST API 在 https://<ref>.supabase.co/rest/v1/ 根据您的数据库架构自动生成。

端点方法描述
/rest/v1/{table}GET查询带过滤、排序、分页的行
/rest/v1/{table}POST插入行(支持批量和 upsert)
/rest/v1/{table}PATCH更新匹配过滤条件的行
/rest/v1/{table}DELETE删除匹配过滤条件的行
/rest/v1/rpc/{function}POST调用 Postgres 函数
/auth/v1/signupPOST创建新用户
/auth/v1/token?grant_type=passwordPOST使用密码登录
/auth/v1/userGET获取当前用户
/auth/v1/admin/usersGET列出所有用户(service_role)
/storage/v1/object/{bucket}/{path}POST上传文件
/storage/v1/object/list/{bucket}POST列出存储桶中的文件
/functions/v1/{function_name}POST调用边缘函数

过滤运算符

运算符描述示例
eq等于?status=eq.active
neq不等于?status=neq.deleted
gt, gte大于?amount=gt.100
lt, lte小于?created_at=lt.2024-01-01
like, ilike模式匹配?name=ilike.%john%
in在数组中?status=in.(active,trial)
is空值检查?deleted_at=is.null

事件

认证事件

事件触发条件使用场景
user.signed_up新用户注册欢迎序列
user.signed_in用户登录活动追踪
user.updated档案变更数据同步
user.deleted账户删除清理工作流

数据库事件(实时)

事件触发条件使用场景
INSERT新行添加新订单/客户通知
UPDATE行被修改状态变更工作流
DELETE行被删除流失检测

Webhook 事件

事件触发条件使用场景
auth.user.created通过 Webhook 用户注册触发引导流程
storage.object.created文件上传资产处理

代码示例

初始化连接器

import { TajoClient } from '@tajo/sdk';
import { createClient } from '@supabase/supabase-js';
const tajo = new TajoClient({
apiKey: process.env.TAJO_API_KEY,
});
// Connect Supabase project
await tajo.connectors.connect('supabase', {
projectUrl: process.env.SUPABASE_URL,
serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
});

将用户同步到联系人

// Sync all Supabase Auth users as contacts
await tajo.connectors.sync('supabase', {
type: 'full',
resources: ['users'],
});
// Incremental sync (new/changed users only)
await tajo.connectors.sync('supabase', {
type: 'incremental',
resources: ['users'],
since: '2024-01-01T00:00:00Z',
});

监听实时变更

// Subscribe to new orders for engagement triggers
const supabase = createClient(
process.env.SUPABASE_URL,
process.env.SUPABASE_SERVICE_ROLE_KEY
);
supabase
.channel('orders')
.on('postgres_changes',
{ event: 'INSERT', schema: 'public', table: 'orders' },
async (payload) => {
// Forward to Tajo as an event
await tajo.events.track({
email: payload.new.customer_email,
event: 'order_placed',
properties: {
order_id: payload.new.id,
total: payload.new.total,
items: payload.new.line_items,
},
});
}
)
.subscribe();

查询和细分

// Query customers by plan for targeted campaigns
const { data: proUsers } = await supabase
.from('customers')
.select('email, full_name, plan, mrr')
.eq('plan', 'pro')
.gt('mrr', 100)
.order('mrr', { ascending: false });
// Sync to a Brevo list for campaign targeting
await tajo.lists.addContacts(PRO_LIST_ID, proUsers);

速率限制

API 速率限制

Supabase 速率限制取决于您的套餐。免费套餐:500 请求/分钟。专业版:1,000 请求/秒。企业版限制请联系 Supabase。

套餐速率限制实时连接数
免费500 请求/分钟200 并发
专业1,000 请求/秒500 并发
团队2,000 请求/秒1,000 并发
企业自定义自定义

故障排除

常见问题

问题原因解决方案
401 UnauthorizedAPI 密钥无效或已过期在 Supabase 控制台 → 设置 → API 中检查 API 密钥
403 ForbiddenRLS 策略阻止访问使用 service_role 密钥进行管理员操作,或检查 RLS 策略
无实时事件表未启用实时在数据库 → 复制 → 将表添加到发布中启用
查询结果为空RLS 过滤所有行验证 RLS 策略允许认证角色读取
存储上传失败存储桶策略检查存储桶是否设置为公共或具有正确的 RLS 策略

调试模式

connectors:
supabase:
debug: true
log_level: verbose
log_queries: true
log_realtime: true

测试连接

Terminal window
tajo connectors test supabase
# ✓ API connection successful
# ✓ Auth endpoint accessible
# ✓ Tables readable (12 tables found)
# ✓ Storage accessible (3 buckets)
# ✓ Realtime connection established
# ✓ Edge Functions available (4 functions)

最佳实践

  1. 仅在服务端使用 service_role 密钥,切勿在客户端代码中暴露
  2. 为所有表启用 RLS,即使使用 service_role,也应以 RLS 作为纵深防御
  3. 使用实时进行事件驱动同步,比轮询变更更高效
  4. 批量操作,对大量操作使用批量插入和 in 过滤器
  5. 映射用户元数据,注册时在 user_metadata 中存储互动相关字段
  6. 使用边缘函数处理 Webhook,使用 Supabase 边缘函数以低延迟处理传入 Webhook

安全

  • API 密钥认证,所有请求需要有效 API 密钥
  • 行级安全(RLS),Postgres 原生每行访问控制
  • JWT 验证,Auth 令牌是在每次请求时验证的签名 JWT
  • SSL/TLS,所有传输中连接加密
  • SOC 2 Type II,Supabase 通过 SOC 2 合规
  • 网络限制,付费套餐可选 IP 白名单

相关资源

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AI 助手

你好!关于文档有任何问题都可以问我。