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应用的基础。
