SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场supabase

supabase

部署与运维

查看项目

更新于 10-16 05:30

技能介绍

Supabase 是一个开源的后端即服务平台，涵盖数据库、认证（Auth）、边缘函数（Edge Functions）、实时（Realtime）、存储（Storage）、向量（Vectors）、定时任务（Cron）与队列（Queues）等产品。本技能用于在涉及 Supabase 的任何任务中提供操作指导。

核心原则

  1. Supabase 变化频繁，实施前应核对当前文档。不要依赖训练数据中的 Supabase 功能信息，函数签名、config.toml 设置与 API 约定会随版本变化。实施前应通过下述文档访问方式查找相关主题。

  2. 验证你的工作。实施任何修复后，运行测试查询确认改动生效。未经验证的修复不算完成。

  3. 从错误中恢复，不要循环重试。若某方法失败 2-3 次，应停止并重新考虑：换一种方法、查阅文档、更仔细地检查错误，并在可用时查看相关日志。Supabase 问题并非总能通过重复同一命令解决，答案也不总在日志中，但继续之前查看日志往往值得。

  4. 暴露的 schema 默认启用 RLS。在任何暴露 schema（尤其是 public）的每张表上启用 RLS。这在 Supabase 中至关重要，因为暴露 schema 中的表可通过 Data API 访问。对于私有 schema，建议以 RLS 作为纵深防御。启用 RLS 后，应创建与实际访问模型匹配的策略，而不是把每张表都默认套用同一个 auth.uid() 模式。

  5. 安全清单。处理任何涉及认证、RLS、视图、存储或用户数据的 Supabase 任务时，应逐项核对以下 Supabase 特有的安全陷阱：

认证与会话安全

  • 绝不要在基于 JWT 的授权决策中使用 user_metadata 声明。在 Supabase 中，raw_user_meta_data 可由用户编辑并可能出现在 auth.jwt() 中，因此用于 RLS 策略或任何授权逻辑都不安全。授权数据应存放在 raw_app_meta_data / app_metadata 中。
  • 删除用户不会使现有访问令牌失效。应先登出或撤销会话，敏感应用保持较短的 JWT 过期时间；如需严格保证，在敏感操作中对照 auth.sessions 校验 session_id。
  • 若使用 app_metadata 或 auth.jwt() 进行授权，请记住在用户令牌刷新前，JWT 声明并不总是最新的。

API 密钥与客户端暴露

  • 绝不要在公开客户端暴露 service_role 或 secret key。前端代码优先使用 publishable keys。旧版 anon keys 仅用于兼容。在 Next.js 中，任何 NEXT_PUBLIC_ 环境变量都会发送到浏览器。

RLS、视图与特权数据库代码

  • 视图默认绕过 RLS。在 Postgres 15 及以上，使用 CREATE VIEW ... WITH (security_invoker = true)。在更早的 Postgres 版本中，通过撤销 anon 与 authenticated 角色的访问权限，或将视图放入未暴露的 schema 来保护。
  • UPDATE 需要 SELECT 策略。在 Postgres RLS 中，UPDATE 需要先 SELECT 该行。没有 SELECT 策略时，更新会静默返回 0 行——没有错误，只是没有变化。
  • 不要把 security definer 函数放在暴露的 schema 中。应放在私有或未暴露的 schema 中。

存储访问控制

  • 存储 upsert 需要 INSERT + SELECT + UPDATE。只授予 INSERT 允许新上传，但文件替换（upsert）会静默失败。三者都需要。

对于上述未涵盖的任何安全问题，请获取 Supabase 产品安全索引：https://supabase.com/docs/guides/security/product-security.md

Supabase CLI

始终通过 --help 发现命令——绝不要猜测。CLI 结构会随版本变化。

supabase --help # 所有顶层命令 supabase <group> --help # 子命令（例如 supabase db --help） supabase <group> <command> --help # 特定命令的标志

Supabase CLI 已知注意事项：

  • supabase db query 需要 CLI v2.79.0+ → 回退使用 MCP execute_sql 或 psql
  • supabase db advisors 需要 CLI v2.81.3+ → 回退使用 MCP get_advisors
  • 需要新的迁移 SQL 文件时，始终先用 supabase migration new <name> 创建。绝不要臆造迁移文件名或凭记忆猜测预期格式。

版本检查与升级：运行 supabase --version 检查。CLI 变更日志与版本特定功能请查阅 CLI 文档或 GitHub releases。

Supabase MCP Server

设置说明、服务器 URL 与配置见 MCP 设置指南。

连接问题排障——按顺序执行以下步骤：

  1. 检查服务器是否可达： curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp 返回 401 是预期的（无令牌），表示服务器正常。超时或“connection refused”表示可能宕机。

  2. 检查 .mcp.json 配置： 确认项目根目录有有效的 .mcp.json 且服务器 URL 正确。若缺失，创建一个指向 https://mcp.supabase.com/mcp。

  3. 认证 MCP 服务器： 若服务器可达且 .mcp.json 正确但工具不可见，用户需要认证。Supabase MCP 服务器使用 OAuth 2.1——告知用户在 agent 中触发认证流程，在浏览器中完成，并重新加载会话。

Supabase 文档

实施任何 Supabase 功能前，先找到相关文档。按优先级使用以下方法：

  1. MCP search_docs 工具（首选——直接返回相关片段）
  2. 以 markdown 获取文档页面——任何文档页面都可通过在 URL 路径后追加 .md 获取。
  3. 当不知道查看哪个页面时，对 Supabase 特定主题进行网络搜索。

进行与提交 schema 变更

要进行 schema 变更，使用 execute_sql（MCP）或 supabase db query（CLI）。这些直接在数据库上运行 SQL，不创建迁移历史条目，因此可以自由迭代，并在准备好时生成干净的迁移。

不要使用 apply_migration 更改本地数据库 schema——它每次调用都会写入迁移历史条目，意味着无法迭代，且 supabase db diff / supabase db pull 会产生空或冲突的 diff。若使用它，你将受困于首次尝试时传入的 SQL。

准备好将变更提交到迁移文件时：

  1. 运行 advisors → supabase db advisors（CLI v2.81.3+）或 MCP get_advisors。修复任何问题。
  2. 若变更涉及视图、函数、触发器或存储，请回顾上述安全清单。
  3. 生成迁移 → supabase db pull <descriptive-name> --local --yes
  4. 验证 → supabase migration list --local

参考指南

技能反馈 → references/skill-feedback.md 当用户报告本技能给出错误指导或缺少信息时，必须阅读。