多租户架构：Supabase 的多租户最佳实践应用

多租户（Multi-tenancy）是现代软件即服务（SaaS）应用的架构基石，它允许单个应用程序实例为多个不同的客户群体（即“租户”）提供服务 。对于许多开发者而言，应用初期可能并未考虑多租户设计，导致在后续扩展高级功能、实现数据隔离或满足客户需求时遇到瓶颈。本报告旨在为面临此挑战的开发团队提供一份权威的路线图，指导如何为现有的 Supabase 和 Vue.js 应用实现关键的  

tenant_id（租户 ID）功能。

在众多实现方案中，行业最佳实践明确指向一种兼具效率、安全性和可维护性的模型。对于绝大多数从初创公司到规模化企业的 Supabase 和 Vue 应用而言， “单一数据库，共享 Schema，结合行级安全（RLS）” 的模型是推荐的标准方案 。本报告将深入剖析并主导这一方法的实践，提供一个可直接用于生产环境的蓝图。我们将从关键的架构决策开始，逐步构建后端 SQL 基础，利用 RLS 锁定数据访问权限，最终将所有部分集成到一个使用 Pinia 进行状态管理的响应式 Vue.js 前端应用中。  

第 1 节：选择多租户架构：一项奠基性决策

在着手编写任何代码之前，必须首先做出一个基础性的架构选择。对于像 Supabase 这样基于 Postgres 的环境，存在三种标准的多租户模型 。这个初步选择将对应用的长期维护成本、可扩展性和运营复杂性产生深远影响。  

模型 1：单一数据库，共享 Schema 与 RLS（推荐标准）

此模型将所有租户的数据存储在同一套表中，通过一个 tenant_id 列来区分数据归属。数据的隔离并非通过物理结构，而是在数据库层面，由 Postgres 强大且灵活的行级安全（Row-Level Security, RLS）特性来强制执行 。  

该模型在简易性、资源效率和细粒度安全性之间取得了最佳平衡 。由于其较低的运营开销和简化的 Schema 管理，它已成为初创公司和大多数 SaaS 产品的标准方法 。其主要优点在于，数据库 Schema 的任何变更（例如添加新列）只需执行一次，便可应用于所有租户。其挑战在于需要精心设计和配置 RLS 策略，以确保数据隔离万无一失 。  

模型 2：单一数据库，租户独享 Schema

在此模型中，单个 Postgres 数据库包含多个 Schema，每个租户拥有一个专属的 Schema。每个 Schema 内都有一套结构完全相同的表 。  

这种方法提供了更强的逻辑数据隔离。然而，它也引入了显著的维护复杂性。每当需要进行数据库迁移时，例如为一个表添加新列，该变更必须在每个租户的 Schema 中重复执行，这极大地增加了部署的风险和复杂性 。尽管 Supabase 的  

pg_graphql 针对此模型进行了性能优化 ，但随着租户数量增长至数千级别，Postgres 在连接数和 Schema 管理上的限制可能会导致扩展性问题 。  

架构选择的影响远不止于数据库层面，它直接关系到整个组织的开发和运维流程。选择“租户独享 Schema”模型的团队会发现，他们的持续集成/持续部署（CI/CD）流水线变得异常复杂。一次简单的 Schema 变更不再是一个原子性的 ALTER TABLE 命令，而是一个需要遍历所有租户 Schema 并可靠地应用变更的脚本。如果这个脚本在处理第 57 个租户（共 200 个）时失败，整个系统将处于不一致的状态，这带来了巨大的、在初期架构设计时不易察觉的隐性成本。相比之下，RLS 模型将隔离逻辑集中化，虽然要求开发者对 RLS 策略有更深入的理解，但极大地简化了开发和部署工作流。

模型 3：租户独享数据库

这是隔离级别最高的模型，每个租户都拥有一个完全独立的 Supabase 项目或 Postgres 数据库实例 。  

该模型提供了终极的数据隔离，有时是满足特定行业法规（如 HIPAA、金融业）的必要条件 。然而，它的管理复杂性和成本也是最高的，需要通过程序化方式自动配置和管理基础设施，并需要更成熟的 DevOps 策略支持 。除非有严格的法律或企业级要求，否则这种方法通常被认为是大材小用。  

表 1：多租户模型对比

为了直观地总结各种模型的权衡，下表提供了一个清晰的对比，以巩固我们对 RLS 模型的推荐。

特性	RLS (共享 Schema)	租户独享 Schema	租户独享数据库
数据隔离	逻辑隔离 (通过 RLS 实现，极佳)	逻辑隔离 (强)	物理隔离 (最高)
可扩展性	高 (可达数千租户)	中 (受 Postgres 限制)	低 (成本与管理复杂性高)
性能开销	低 (需正确索引)	中 (可能存在缓存/连接问题)	低 (专用资源)
维护复杂性	低	高	非常高
成本效益	高	中	低
理想用例	初创公司、通用 SaaS	需要一定定制化的 B2B 应用	受监管行业、大型企业

第 2 节：后端基础：数据库 Schema 与自动化设置

在确定采用 RLS 模型后，下一步是构建支持多租户的数据库基础。一个健壮的 Schema 包含三大支柱：一个用于定义租户的表，一个用于关联用户与租户的表，以及一套在用户注册时自动完成关联的机制。

第 1 步：创建 tenants 表

首先，需要一个表来存储关于每个租户组织的信息，例如公司名称或订阅计划。

-- 创建一个用于存储租户信息的表
CREATE TABLE public.tenants (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

第 2 步：创建 profiles 表以关联用户和租户

profiles 表是连接用户身份和租户归属的关键枢纽。它存储了用户的公开信息，并明确了每个用户所属的租户。

-- 创建一个用于存储用户公开信息的表，并关联到租户
CREATE TABLE public.profiles (
  id uuid PRIMARY KEY REFERENCES auth.users ON DELETE CASCADE,
  tenant_id uuid REFERENCES public.tenants ON DELETE SET NULL,
  full_name TEXT,
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

此表的设计要点包括：

• id 列既是主键，也是一个外键，直接引用 auth.users(id)。ON DELETE CASCADE 确保当 Supabase Auth 中的用户被删除时，其对应的 profile 记录也会被自动清除，从而保持数据完整性 。  
• tenant_id 列是一个外键，引用 public.tenants(id)，明确了该用户所属的租户。

第 3 步：通过 Postgres 函数和触发器实现自动化

为了提供无缝的用户体验，当新用户注册时，系统应自动为其创建个人资料和初始租户。这可以通过在 auth.users 表上设置一个触发器来实现 。  

一个简单的触发器仅仅创建 profile 是不够的。新用户不仅需要一个租户，其 JWT（JSON Web Token）也必须在首次请求时就包含这个租户信息，这样 RLS 策略才能立即生效。这需要一个在触发器内部执行的多步骤事务，并安全地更新用户的元数据。

首先，当一个新用户在 auth.users 表中被创建时，触发器启动。它必须先在 public.tenants 表中插入一条新记录，例如，可以暂时使用用户的电子邮件作为租户名称。然后，利用新创建的租户 ID，在 public.profiles 表中为该用户创建一条记录。最关键的一步是，触发器需要将这个新的 tenant_id 注入到用户的 app_metadata 中。由于触发器本身无法直接修改 JWT，它必须更新 auth.users 表中的 raw_app_meta_data 字段。这需要使用 SECURITY DEFINER 函数来提升权限，从而安全地完成此操作。这样，用户注册后收到的第一个 JWT 就包含了后续 RLS 策略所需的所有信息，完美解决了新用户引导流程中的“先有鸡还是先有蛋”的问题。

以下是实现这一完整流程的 SQL 代码：

-- 创建一个函数，用于在新用户注册时自动创建租户和 profile
CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS TRIGGER
LANGUAGE plpgsql
SECURITY DEFINER SET search_path = public
AS $$
DECLARE
  new_tenant_id uuid;
BEGIN
  -- 1. 为新用户创建一个新的租户
  INSERT INTO public.tenants (name)
  VALUES (NEW.raw_user_meta_data->>'full_name' |

| '''s Team')
  RETURNING id INTO new_tenant_id;

  -- 2. 在 public.profiles 表中为新用户创建一条记录
  INSERT INTO public.profiles (id, tenant_id, full_name)
  VALUES (NEW.id, new_tenant_id, NEW.raw_user_meta_data->>'full_name');

  -- 3. 将新的 tenant_id 更新到用户的 app_metadata 中
  UPDATE auth.users
  SET raw_app_meta_data = raw_app_meta_data |

| jsonb_build_object('tenant_id', new_tenant_id)
  WHERE id = NEW.id;

  RETURN NEW;
END;
$$;

-- 创建一个触发器，在 auth.users 表每次插入新行后调用上述函数
CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE PROCEDURE public.handle_new_user();

第 4 步：在 app_metadata 中存储 tenant_id

Supabase 的用户对象中有两个用于存储元数据的字段：user_metadata 和 app_metadata。理解它们的区别至关重要：

• user_metadata：客户端可读写。用户可以通过 Supabase 的客户端库自行修改。因此，它绝不能用于存储权限控制相关的数据 。  
• app_metadata：只能通过具有服务角色的后端或 SECURITY DEFINER 函数进行修改。这是存储敏感或权限相关信息的安全位置 。  

因此，tenant_id 必须存储在 app_metadata 中，以防止用户恶意篡改该值，从而非法访问其他租户的数据。

第 3 节：使用行级安全（RLS）强制数据隔离

行级安全（RLS）是 Supabase 实现多租户的“秘密武器”。它是一种深度防御机制，直接在数据库层面强制执行数据访问规则，成为保护数据安全的最终防线 。  

启用 RLS

为一个表启用 RLS 非常简单，但其效果是深远的。执行以下命令后，默认情况下，对该表的所有访问（SELECT, INSERT, UPDATE, DELETE）都将被拒绝，直到创建了明确允许访问的策略为止 。  

-- 为一个名为 'projects' 的示例表启用 RLS
ALTER TABLE public.projects ENABLE ROW LEVEL SECURITY;

为 projects 表制定 RLS 策略

假设我们有一个 projects 表，其中包含一个 tenant_id 列。以下是如何为该表创建一套完整的 RLS 策略。

子查询方法（简单但性能较低）

一种直观的策略编写方式是在每次查询时都去 profiles 表中查找当前用户的 tenant_id 。  

-- 允许用户访问其所属租户的所有项目
CREATE POLICY "Allow full access based on tenant"
ON public.projects
FOR ALL
USING (
  tenant_id = (SELECT tenant_id FROM public.profiles WHERE id = auth.uid())
)
WITH CHECK (
  tenant_id = (SELECT tenant_id FROM public.profiles WHERE id = auth.uid())
);

USING 子句用于 SELECT, UPDATE, DELETE 操作，而 WITH CHECK 子句用于 INSERT 和 UPDATE 操作，确保写入的数据也符合租户隔离规则。

JWT 方法（高性能标准）

每次查询都访问 profiles 表会增加不必要的开销。最佳实践是直接从用户的 JWT 中读取 tenant_id，因为这个信息在用户登录时就已经被安全地嵌入其中 。  

-- 性能更优的策略，直接从 JWT 的 app_metadata 中读取 tenant_id
CREATE POLICY "Allow full access based on JWT tenant"
ON public.projects
FOR ALL
USING (
  tenant_id = (auth.jwt()->'app_metadata'->>'tenant_id')::uuid
)
WITH CHECK (
  tenant_id = (auth.jwt()->'app_metadata'->>'tenant_id')::uuid
);

使用可复用辅助函数简化策略

为了避免在每个策略中重复复杂的 JSON 提取逻辑，可以创建一个简单的、可复用的 SQL 函数 auth.tenant_id() 。  

-- 创建一个辅助函数，用于从当前用户的 JWT 中提取 tenant_id
CREATE OR REPLACE FUNCTION auth.tenant_id()
RETURNS uuid
LANGUAGE sql
STABLE
AS $$  SELECT (auth.jwt()->'app_metadata'->>'tenant_id')::uuid$$;

现在，策略可以被极大地简化，提高了可读性和可维护性：

-- 使用辅助函数重写策略
CREATE POLICY "Allow full access based on JWT tenant (simplified)"
ON public.projects
FOR ALL
USING (tenant_id = auth.tenant_id())
WITH CHECK (tenant_id = auth.tenant_id());

RLS 并非没有性能成本，一个设计不佳的 RLS 系统可能成为性能瓶颈。可扩展 RLS 的关键不仅在于策略逻辑，更在于底层的数据表索引。当应用的用户和数据量增长时，一个看似简单的查询 SELECT * FROM projects 可能会因为 RLS 策略 WHERE tenant_id = auth.tenant_id() 的隐式应用而变慢。如果没有合适的索引，Postgres 必须对整张表进行全表扫描，以找出属于当前租户的行，然后才能执行后续操作。解决方案是创建一个复合索引，其中 tenant_id 是第一列。例如，CREATE INDEX ON public.projects (tenant_id, created_at DESC);。这个索引允许 Postgres 几乎瞬间定位到正确租户的数据块，然后在规模小得多的数据集上执行排序等操作，这是实现高性能 RLS 的关键 。因此，一条重要的实践准则是：  

每个受 tenant_id RLS 策略保护的表，都必须为常用查询字段建立以 tenant_id 开头的复合索引。

第 4 节：前端集成：使用 Vue.js 和 Pinia 管理租户状态

后端设置完成后，前端需要一个可靠的机制来管理用户的认证状态和租户上下文，为整个应用提供单一的数据源。

第 1 步：Supabase 客户端设置

在 Vue 3 应用中，首先需要初始化 Supabase 客户端。通常在 /src/supabase.js 文件中完成，并使用环境变量来存储 API URL 和公钥 。  

// src/supabase.js
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY

export const supabase = createClient(supabaseUrl, supabaseAnonKey)

第 2 步：使用 Pinia 构建 useAuthStore

Pinia 是 Vue 官方推荐的状态管理库。我们将创建一个 auth store 来集中管理用户状态 。  

// src/stores/auth.js
import { defineStore } from 'pinia'
import { supabase } from '../supabase'

export const useAuthStore = defineStore('auth', {
  state: () => ({
    user: null,
    session: null,
    profile: null,
    tenantId: null,
  }),
  getters: {
    isLoggedIn: (state) =>!!state.user,
  },
  actions: {
    // 登录、注册、登出等 actions
    async signIn(credentials) {
      const { data, error } = await supabase.auth.signInWithPassword(credentials)
      if (error) throw error
      // onAuthStateChange 会处理状态更新
    },
    async signOut() {
      const { error } = await supabase.auth.signOut()
      if (error) throw error
    },
    //... 其他 actions
  },
})

第 3 步：使用 onAuthStateChange 进行响应式会话管理

这是前端集成的核心。通过监听 onAuthStateChange 事件，应用可以实时响应用户的登录、登出和会话刷新，并相应地更新 Pinia store 。  

一个健壮的认证状态同步流程至关重要。SIGNED_IN 事件是填充用户完整上下文的关键时刻。一个简单的实现可能只存储会话信息，但这很脆弱。一个稳健的实现必须在继续之前验证 tenant_id 是否存在，并处理用户首次注册时的边缘情况。

当 onAuthStateChange 监听到 SIGNED_IN 事件时，Pinia store 的一个 action（例如 handleAuthStateChange）被调用。在这个 action 中，首先从 session 对象中设置 user 和 session 状态。然后，进行关键检查：从 session.user.app_metadata 中尝试获取 tenant_id。如果 tenant_id 存在，则直接将其存入 Pinia state，并可以进一步获取完整的用户 profile。如果 tenant_id 不存在——这通常发生在用户刚注册后，JWT 尚未刷新的瞬间——这意味着后端触发器已经运行，但前端的令牌是旧的。此时，该 action 必须执行一次性数据库查询，从 profiles 表中获取 tenant_id。获取后，再更新 Pinia state，并可以考虑调用 supabase.auth.refreshSession() 来更新 JWT，以备后续请求使用。这种双重保障机制确保了无论时序如何，Pinia store 最终都能获得正确的 tenantId，从而使应用的其他部分逻辑更简单、更可靠。

以下是在 App.vue 中设置监听器的示例：

<script setup>
import { onMounted } from 'vue'
import { useAuthStore } from './stores/auth'
import { supabase } from './supabase'

const authStore = useAuthStore()

onMounted(() => {
  supabase.auth.onAuthStateChange(async (event, session) => {
    authStore.session = session
    authStore.user = session?.user?? null

    if (event === 'SIGNED_IN' && session) {
      const tenantId = session.user.app_metadata?.tenant_id
      if (tenantId) {
        authStore.tenantId = tenantId
        // 获取完整的 profile
        const { data: profileData } = await supabase
         .from('profiles')
         .select('*')
         .eq('id', session.user.id)
         .single()
        authStore.profile = profileData
      } else {
        // 兜底逻辑：处理 JWT 可能尚未刷新的情况
        const { data: profileData } = await supabase
         .from('profiles')
         .select('tenant_id')
         .eq('id', session.user.id)
         .single()
        if (profileData?.tenant_id) {
          authStore.tenantId = profileData.tenant_id
          // 可以在这里强制刷新 session 以更新 JWT
          await supabase.auth.refreshSession()
        }
      }
    } else if (event === 'SIGNED_OUT') {
      authStore.user = null
      authStore.session = null
      authStore.profile = null
      authStore.tenantId = null
    }
  })
})
</script>

第 4 步：在 Vue 组件中使用 Store

一旦 Pinia store 设置完成并能正确同步状态，在任何组件中使用租户信息都变得非常简单。

<script setup>
import { ref, onMounted } from 'vue'
import { supabase } from '../supabase'
import { useAuthStore } from '../stores/auth'

const authStore = useAuthStore()
const projects = ref()
const loading = ref(true)

async function fetchProjects() {
  if (!authStore.tenantId) return
  try {
    loading.value = true
    const { data, error } = await supabase
     .from('projects')
     .select('*')
     .eq('tenant_id', authStore.tenantId) // 使用 store 中的 tenantId

    if (error) throw error
    projects.value = data
  } catch (error) {
    console.error('Error fetching projects:', error)
  } finally {
    loading.value = false
  }
}

onMounted(() => {
  fetchProjects()
})
</script>

第 5 节：实际应用与高级场景

端到端用户旅程演练

现在，我们可以完整地描绘一个新用户的旅程：

1. 注册：用户在 Vue 应用中填写注册表单并提交。
2. 后端自动化：Supabase Auth 创建新用户，触发 on_auth_user_created。handle_new_user 函数执行，为用户创建一个新租户、一个 profile，并将 tenant_id 安全地写入 app_metadata。
3. 前端响应：Vue 应用中的 onAuthStateChange 监听到 SIGNED_IN 事件。Pinia store 被可靠地填充了 user、session 和 tenantId。
4. 无缝体验：用户被重定向到仪表盘。仪表盘组件从 Pinia store 获取 tenantId，并用它来请求数据。Supabase 后端接收到请求，RLS 策略自动应用，仅返回属于该租户的数据。

Vue 组件示例：一个租户专属的项目列表

为了让整个概念更具体，以下是一个完整的 ProjectList.vue 组件代码，它展示了加载状态、使用 Pinia store 获取当前租户的项目，并将其显示出来。

<template>
  <div>
    <h2>My Projects</h2>
    <div v-if="loading">Loading...</div>
    <div v-else-if="error">{{ error }}</div>
    <ul v-else-if="projects.length">
      <li v-for="project in projects" :key="project.id">
        {{ project.name }}
      </li>
    </ul>
    <div v-else>No projects found.</div>
  </div>
</template>

<script setup>
import { ref, onMounted, watch } from 'vue'
import { supabase } from '../supabase'
import { useAuthStore } from '../stores/auth'

const authStore = useAuthStore()
const projects = ref()
const loading = ref(false)
const error = ref(null)

async function fetchProjects() {
  if (!authStore.tenantId) {
    projects.value =
    return
  }
  try {
    loading.value = true
    error.value = null
    const { data, error: fetchError } = await supabase
     .from('projects')
     .select('id, name')
     .eq('tenant_id', authStore.tenantId)
     .order('created_at', { ascending: false })

    if (fetchError) throw fetchError
    projects.value = data
  } catch (err) {
    error.value = 'Failed to load projects.'
    console.error(err)
  } finally {
    loading.value = false
  }
}

// 当 tenantId 可用时立即获取数据
onMounted(fetchProjects)

// 当用户切换租户（高级场景）或登录时，重新获取数据
watch(() => authStore.tenantId, fetchProjects)
</script>

高级主题 1：邀请用户加入现有租户

此场景需要更复杂的逻辑。通常，一个现有用户（如管理员）发起邀请。这可以通过一个 Supabase Edge Function 实现，该函数使用服务角色密钥在数据库中创建一个带有唯一令牌的邀请记录。新用户通过一个包含此令牌的特殊链接注册。注册后，另一个函数或客户端逻辑会验证令牌，并将新用户的 profile 与邀请中指定的现有 tenant_id 关联起来，同时更新该用户的 app_metadata。

高级主题 2：支持用户拥有多个租户

对于需要用户在多个工作空间或组织之间切换的应用，架构需要进行调整。app_metadata 可以存储一个包含所有租户 ID 的数组（tenant_ids）和一个 current_tenant_id。profiles 表将演变为一个多对多的连接表（例如 memberships），用于连接用户和租户。前端需要提供一个租户切换的 UI。当用户切换租户时，会调用一个后端函数来更新 app_metadata 中的 current_tenant_id，并强制刷新会话，以使包含新 current_tenant_id 的 JWT 生效。

结论与实施清单

成功地为 Supabase 和 Vue.js 应用添加多租户功能，依赖于遵循一套核心原则：选择 RLS 模型作为架构基础，通过触发器自动化租户和 profile 的创建，利用基于 JWT 的 RLS 策略来保障数据安全，并在 Vue 前端通过一个健壮的 Pinia store 来响应式地管理状态。

在部署您的多租户应用之前，请使用以下清单进行最终审查：

• 架构选择：已选择并实施了基于 RLS 的多租户模型。
• Schema 设计：所有租户专属的数据表都包含一个非空的 tenant_id 列。
• 自动化：已部署 handle_new_user 触发器，用于在新用户注册时创建 profile 和默认租户。
• 安全元数据：触发器安全地将 tenant_id 更新到 auth.users.app_metadata 中。
• RLS 启用：所有租户专属的数据表都已启用行级安全（RLS）。
• 高性能策略：RLS 策略使用高效的 auth.jwt() 或辅助函数来检查 tenant_id。
• 索引优化：所有受 RLS 保护的表都已根据常用查询创建了以 tenant_id 开头的复合索引。
• 前端状态管理：已建立一个 Pinia store 来管理用户会话、profile 和 tenantId。
• 响应式同步：onAuthStateChange 监听器能够正确且稳健地填充 Pinia store。
• 客户端数据请求：所有客户端的数据请求都使用来自 Pinia store 的 tenantId 来限定查询范围。