Supabase 匿名密钥与服务角色密钥详细对比文档

Supabase 匿名密钥与服务角色密钥详细对比文档

1. 密钥类型概述

特性	匿名密钥 (Anon Key)	服务角色密钥 (Service Role Key)
环境变量名	VITE_SUPABASE_ANON_KEY	VITE_SUPABASE_SERVICE_ROLE_KEY
使用场景	前端客户端	服务端或管理功能
安全等级	低（可公开）	高（需保密）
RLS策略限制	受限	不受限（绕过所有策略）

2. 匿名密钥 (Anon Key)

2.1 定义与用途

匿名密钥是一种受限制的公开密钥，设计用于前端应用程序，允许未登录用户或已登录用户进行受控访问。

2.2 权限特点

• 所有操作都受到行级安全(RLS)策略的约束
• 只能访问显式设置为公开的数据
• 登录后，只能访问该用户有权限的数据
• 无法绕过数据库的安全规则

2.3 代码示例

// src/utils/supabase.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from '../types/supabase'

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

export const supabase = createClient<Database>(supabaseUrl, supabaseAnonKey, {
  auth: {
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: true
  }
})

2.4 典型使用场景

• 公开数据查询
• 用户注册与登录
• 个人数据管理（登录后）
• 移动应用和Web前端
• 公开API访问

2.5 安全考虑

• 可以安全地包含在前端代码中
• 即使被提取出来，也只能访问公开数据
• 敏感操作需要正确设置RLS策略保护
• 用户只能访问属于自己的数据

3. 服务角色密钥 (Service Role Key)

3.1 定义与用途

服务角色密钥是一种高权限密钥，拥有绕过所有安全限制的能力，设计用于服务器端操作或管理功能。

3.2 权限特点

• 完全绕过所有RLS策略
• 可以访问数据库中的所有表和数据
• 可以执行任何数据库操作，包括创建、修改和删除表
• 可以管理用户、角色和权限

3.3 代码示例

// src/utils/admin-supabase.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from '../types/supabase'

const adminSupabaseUrl = import.meta.env.VITE_SUPABASE_URL
const adminSupabaseKey = import.meta.env.VITE_SUPABASE_SERVICE_ROLE_KEY

export const adminSupabase = createClient<Database>(adminSupabaseUrl, adminSupabaseKey, {
  auth: {
    autoRefreshToken: false,  // 禁用令牌自动刷新
    persistSession: false     // 禁用会话持久化
  }
})

3.4 典型使用场景

• 管理后台功能
• 用户管理与权限分配
• 批量数据处理
• 数据迁移和备份
• 系统维护操作
• 跨用户数据分析

3.5 安全考虑

• 绝不能包含在前端代码中
• 应仅在服务器端或安全环境中使用
• 泄露会导致数据库完全暴露
• 应使用环境变量存储，避免硬编码
• 应定期轮换密钥提高安全性

4. 技术实现细节对比

特性	匿名密钥客户端	服务角色密钥客户端
令牌自动刷新	autoRefreshToken: true	autoRefreshToken: false
会话持久化	persistSession: true	persistSession: false
URL会话检测	detectSessionInUrl: true	通常未启用
客户端用途	面向用户的操作	管理员级别操作

5. 安全最佳实践

5.1 匿名密钥

• 总是配合完善的RLS策略使用
• 为每个表设置明确的访问规则
• 定期审查公开数据的访问模式
• 在前端使用时，考虑API请求节流防止滥用

5.2 服务角色密钥

• 永远不要在客户端代码中使用
• 限制拥有密钥的人员数量
• 实施最小权限原则，仅在必要时使用
• 考虑为不同管理功能创建不同的角色密钥
• 在生产环境中设置密钥使用审计
• 实施IP限制，只允许特定服务器使用

6. 常见使用陷阱与解决方案

6.1 常见错误

• 在前端代码中使用服务角色密钥
• 未正确设置RLS策略依赖匿名密钥保护数据
• 在版本控制系统中硬编码密钥
• 过度依赖服务角色密钥而不是正确设计RLS

6.2 解决方案

• 使用环境变量管理所有密钥
• 为匿名访问实现严格的RLS策略
• 创建中间层API处理需要服务角色密钥的操作
• 实施密钥轮换策略
• 使用监控系统检测异常密钥使用

7. 开发与生产环境考虑

7.1 开发环境

• 可使用不同密钥用于开发和生产
• 开发环境应模拟生产环境的RLS策略
• 考虑使用模拟服务进行本地开发

7.2 生产环境

• 严格控制生产环境密钥访问
• 实施密钥轮换机制
• 监控密钥使用情况及异常访问
• 针对服务角色密钥实施附加安全措施

8. 结论

匿名密钥(Anon Key)和服务角色密钥(Service Role Key)代表了Supabase中两种截然不同的访问级别。匿名密钥适用于前端安全操作，受RLS保护；而服务角色密钥提供最高权限访问，应该仅在受控服务端环境中使用。正确理解和使用这两种密钥，是构建安全Supabase应用的基础。