---
title: "Supabase 连接器"
description: "完整的 Supabase 集成指南，将数据库记录、用户认证、文件存储和实时事件与您的用户互动平台同步。"
url: https://tajo.io/zh-cn/docs/connectors/custom/supabase/
markdown: https://tajo.io/zh-cn/docs/connectors/custom/supabase.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Supabase 连接器

连接器状态: 计划中 尚未构建。Tajo 目前不运行此连接器。

| 来源字段 | 目标字段 | 示例值 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

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

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Supabase |
| **类别** | 数据库与后端 |
| **设置复杂度** | 简单 |
| **官方集成** | 否 |
| **同步数据** | 用户、表、存储、事件 |
| **可用技能** | 11 |
| **API 类型** | REST (PostgREST) + Realtime WebSocket |
| **官方文档** | [supabase.com/docs](https://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](https://app.supabase.com/)）
2. 项目的 **API URL** 和 **API 密钥**（在设置 → API 中找到）
3. 具有 API 访问权限的 Tajo 账户

API 密钥

Supabase 提供两种密钥：`anon`（公共，遵守 RLS）和 `service_role`（绕过 RLS，管理员访问）。服务端集成使用 `service_role`，客户端使用 `anon`。

## 认证

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

```bash
# 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>"
```

## 配置

### 基础设置

```yaml
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 | 邮箱确认时间戳 |

#### 自定义表映射

```yaml
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/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` | 文件上传 | 资产处理 |

## 代码示例

### 初始化连接器

```javascript
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,
});
```

### 将用户同步到联系人

```javascript
// 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',
});
```

### 监听实时变更

```javascript
// 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();
```

### 查询和细分

```javascript
// 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 Unauthorized | API 密钥无效或已过期 | 在 Supabase 控制台 → 设置 → API 中检查 API 密钥 |
| 403 Forbidden | RLS 策略阻止访问 | 使用 `service_role` 密钥进行管理员操作，或检查 RLS 策略 |
| 无实时事件 | 表未启用实时 | 在数据库 → 复制 → 将表添加到发布中启用 |
| 查询结果为空 | RLS 过滤所有行 | 验证 RLS 策略允许认证角色读取 |
| 存储上传失败 | 存储桶策略 | 检查存储桶是否设置为公共或具有正确的 RLS 策略 |

### 调试模式

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

### 测试连接

```bash
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 白名单

## 相关资源

- [Shopify 连接器](https://tajo.io/zh-cn/docs/connectors/ecommerce/shopify)
- [Stripe 连接器](https://tajo.io/zh-cn/docs/connectors/ecommerce/stripe)
- [Auth0 连接器](https://tajo.io/zh-cn/docs/connectors/custom/auth0)
- [Supabase 官方文档](https://supabase.com/docs)
- [Supabase REST API 指南](https://supabase.com/docs/guides/api)
- [Supabase Auth 指南](https://supabase.com/docs/guides/auth)