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 全文搜索功能
前提条件
开始之前,请确保您已具备:
- Supabase 项目(app.supabase.com)
- 项目的 API URL 和 API 密钥(在设置 → API 中找到)
- 具有 API 访问权限的 Tajo 账户
API 密钥
Supabase 提供两种密钥:anon(公共,遵守 RLS)和 service_role(绕过 RLS,管理员访问)。服务端集成使用 service_role,客户端使用 anon。
认证
Supabase 使用 API 密钥认证。每个请求都需要 apikey 头部,可选附带用于用户范围访问的 Authorization Bearer 令牌。
# 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_itemsAPI 端点
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/signup | POST | 创建新用户 |
/auth/v1/token?grant_type=password | POST | 使用密码登录 |
/auth/v1/user | GET | 获取当前用户 |
/auth/v1/admin/users | GET | 列出所有用户(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 projectawait tajo.connectors.connect('supabase', { projectUrl: process.env.SUPABASE_URL, serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY,});将用户同步到联系人
// Sync all Supabase Auth users as contactsawait 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 triggersconst 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 campaignsconst { 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 targetingawait tajo.lists.addContacts(PRO_LIST_ID, proUsers);速率限制
API 速率限制
Supabase 速率限制取决于您的套餐。免费套餐:500 请求/分钟。专业版:1,000 请求/秒。企业版限制请联系 Supabase。
| 套餐 | 速率限制 | 实时连接数 |
|---|---|---|
| 免费 | 500 请求/分钟 | 200 并发 |
| 专业 | 1,000 请求/秒 | 500 并发 |
| 团队 | 2,000 请求/秒 | 1,000 并发 |
| 企业 | 自定义 | 自定义 |
故障排除
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 401 Unauthorized | API 密钥无效或已过期 | 在 Supabase 控制台 → 设置 → API 中检查 API 密钥 |
| 403 Forbidden | RLS 策略阻止访问 | 使用 service_role 密钥进行管理员操作,或检查 RLS 策略 |
| 无实时事件 | 表未启用实时 | 在数据库 → 复制 → 将表添加到发布中启用 |
| 查询结果为空 | RLS 过滤所有行 | 验证 RLS 策略允许认证角色读取 |
| 存储上传失败 | 存储桶策略 | 检查存储桶是否设置为公共或具有正确的 RLS 策略 |
调试模式
connectors: supabase: debug: true log_level: verbose log_queries: true log_realtime: true测试连接
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)最佳实践
- 仅在服务端使用 service_role 密钥,切勿在客户端代码中暴露
- 为所有表启用 RLS,即使使用 service_role,也应以 RLS 作为纵深防御
- 使用实时进行事件驱动同步,比轮询变更更高效
- 批量操作,对大量操作使用批量插入和
in过滤器 - 映射用户元数据,注册时在
user_metadata中存储互动相关字段 - 使用边缘函数处理 Webhook,使用 Supabase 边缘函数以低延迟处理传入 Webhook
安全
- API 密钥认证,所有请求需要有效 API 密钥
- 行级安全(RLS),Postgres 原生每行访问控制
- JWT 验证,Auth 令牌是在每次请求时验证的签名 JWT
- SSL/TLS,所有传输中连接加密
- SOC 2 Type II,Supabase 通过 SOC 2 合规
- 网络限制,付费套餐可选 IP 白名单