supabase

Supabase

应将 Supabase 视为以 Postgres 为中心、由多个独立版本化服务组成的系统，而不是一个不透明的后端。托管平台、CLI 本地堆栈和官方自托管 Compose 堆栈共享一些概念，但属于不同的运行环境。选择命令前，先确认任务针对哪一种环境。

操作约定

1. 更改前先确认目标和当前状态：托管项目、CLI 本地堆栈或自托管 Compose；CLI 和服务版本；项目链接状态；数据库和迁移状态；已启用的服务；公开 URL；备份和回滚路径。
2. 首次修改前，确认目标、范围和回滚路径。只读检查无需确认即可进行。用户明确指示部署或更改指定目标，即满足此要求。
3. 可发布密钥仅用于客户端；密钥／服务角色密钥仅用于服务端。切勿在报告中打印或提交密钥、数据库密码、JWT 签名材料、SMTP 凭据，或包含密码的连接字符串。
4. 通过版本化迁移更改数据库。将生成的差异作为草稿进行审查，按顺序重放完整迁移链，测试 RLS 的反向案例，并在部署前重新生成客户端类型。
5. 对于自托管，请使用官方 supabase/supabase Docker 目录及其 setup.sh、run.sh、更新说明和测试。除非用户明确要求并接受功能损失，否则不要自行设计精简版 Compose 堆栈。
6. 在交付时验证：容器健康不等于 API 健康；API 响应不等于授权证明；有备份不等于有恢复证据。

选择路径

需求	优先阅读
了解服务、信任边界、密钥和环境差异	架构与边界
安装／使用 CLI、建立本地工作流，或管理托管 Functions、密钥、分支、SSL 强制、CIDR 限制和网络封禁	本地开发与 CLI
创建架构、迁移、种子数据、RLS 策略、测试和生成的类型	数据库开发与测试
使用 Auth、REST、Realtime、Storage 和 Edge Functions 进行构建	应用服务
部署或加固官方 Docker 堆栈	自托管部署
备份、恢复、更新、升级、监控或恢复自托管实例	管理与恢复
诊断容器异常、URL 错误、身份验证失败、配置漂移或迁移失败	故障排除
通过带评分的场景评估 Agent 使用 Supabase 的能力	Agent 评估测试框架
检查声明的时效性或权威来源覆盖情况	来源索引

首轮只读检查

supabase --version
supabase status --output json       # CLI local project; may fail when stopped
supabase migration list            # linked/local migration comparison when configured
docker compose config --quiet       # self-hosted project directory
docker compose ps --format json

对于托管项目，还应确认项目引用、链接状态、目标环境，以及直接更改生产环境是否造成了配置漂移。对于自托管环境，更新前应检查 docker/CHANGELOG.md、docker/versions.md、当前生效的 COMPOSE_FILE、磁盘／内存余量和备份证据。

开发流程

每个项目只使用一种架构编写模式：

# Declarative: edit supabase/schemas/*.sql first
supabase db diff -f change-name

# Imperative: write the generated migration directly
supabase migration new change-name

# Both paths converge on the same checks
supabase db reset
supabase test db
supabase gen types --lang typescript --local > database.types.ts

审查每个生成的迁移。db diff 不会捕获 DML，且在策略重命名、视图和某些权限方面存在已知缺漏。db reset 会破坏本地数据库，但可证明迁移的可复现性：按顺序执行迁移，然后加载种子数据。

在链接环境中部署前：

supabase migration list
supabase db push --dry-run
supabase db push

切勿对生产环境使用 db reset --linked 或 db push --include-seed。如果命令可能误操作错误的数据库，请明确传入 --local 或 --linked；不同命令的默认值各不相同。

自托管生命周期

使用部署目录中已签入的官方辅助脚本：

sh run.sh config
sh run.sh compose-config >/dev/null
docker compose config --quiet
sh run.sh start
sh run.sh status
sh tests/test-self-hosted.sh http://localhost:8000

生产环境需要真实密钥、正确的外部 URL、TLS 终止、WebSocket 转发、受保护的数据库端口、按需配置 SMTP／提供商、备份和恢复测试。官方默认堆栈将 Kong 暴露在 8000，将 Kong TLS 暴露在 8443，并将 Supavisor 暴露在 5432／6543；请谨慎配置绑定或防火墙规则。

验证矩阵

层级	最低验证依据
配置	docker compose config --quiet；没有占位密钥；URL 与代理／身份验证回调一致
运行时	所有必需服务均在运行且健康；有限范围内的日志未显示当前故障循环
数据库	Postgres 版本符合预期；迁移历史一致；代表性查询成功
API 网关	Studio 身份验证边界、Auth 健康状态、使用正确密钥角色的 REST、JWKS 端点
授权	以 anon／authenticated 用户执行正向和负向 RLS 测试；绝不使用 service-role 绕过作为证明
存储	存储桶／对象上传、下载、完整性、签名 URL 和清理
Realtime	WebSocket 订阅和数据库变更交付，而不只是 HTTP 路由
Functions	通过 /functions/v1 调用真实函数；验证身份验证行为和日志
恢复	独立的逻辑／物理备份，以及恢复到单独测试目标的结果

重要边界和注意事项

• CLI 本地堆栈仅用于开发：使用默认凭据、没有 TLS，也没有生产级速率限制。不要将其公开暴露。
• 暴露的架构中的每张表都必须启用 RLS。只有在授权和 RLS 策略正确时，发布密钥才可安全地用于客户端。请测试拒绝路径。
• Secret／service-role 密钥会绕过 RLS。绝不能将其放入浏览器包、移动应用、日志、示例或聊天输出中。
• 在当前自托管配置中，API_EXTERNAL_URL 包含 /auth/v1。SITE_URL 是应用的落地页 URL，不一定是 Supabase 主机名。
• 将 Compose 配置作为经过测试的发布集进行更新。分别拉取任意 latest 镜像可能导致服务组合不兼容。
• Postgres 17 是新自托管部署的当前默认版本。绝不要将其指向 Postgres 15 数据目录。请同时保留数据库数据和包含 pgsodium 根密钥的 db-config 卷。
• docker compose down -v、reset.sh、远程重置、密钥重新生成和迁移历史修复都可能破坏数据、访问权限或会话。请将它们视为需要单独确认并提供恢复依据的操作。
• 自托管的功能对等性不等于托管平台的对等性。备份、可用性、升级、滥用控制、SMTP、可观测性和支持均由运营方负责。

完成标准

只有在请求的产物或状态已存在且相关边界已经过验证时，任务才算完成：本地项目可从迁移重放并通过测试；部署通过配置、健康状态和服务级冒烟测试；更新有回滚依据和更新后检查；备份已恢复到单独目标；并且已提交或报告的输出中没有任何密钥材料。