supabase 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

supabase 是面向 PostgreSQL 的开发平台，仓库 README 将其描述为“Postgres development platform”。项目把托管 PostgreSQL 数据库、身份认证、自动生成 API、实时订阅、函数、文件存储、向量与嵌入工具以及管理面板组合为一套开发平台。

根据给定 GitHub 元信息，仓库当前默认分支为 master，主要语言为 TypeScript，许可证为 Apache-2.0，Star 数为 108049，Fork 数为 13553。仓库根目录的 package.json 将项目标记为私有工作区，使用 pnpm 与 Turborepo 管理构建、开发、检查和测试任务。

• 项目定位：以 PostgreSQL 为核心的数据应用开发平台。
• 核心能力：数据库、认证授权、REST、GraphQL、实时订阅、数据库函数、边缘函数、对象存储、AI 与向量工具、Dashboard。
• 部署形态：README 明确提供托管平台、自托管和本地开发三种路径。
• 仓库形态：以 TypeScript 为主，包含多个应用和包，并通过 Turborepo 编排任务。

定位与目标用户

Supabase 的核心价值在于把 PostgreSQL 作为应用数据层，同时提供围绕数据库构建的认证、API、实时和文件能力。它不是对某一闭源后端平台的逐项复制，而是使用开源组件提供类似的开发体验。

README 明确指出，项目目标是“使用企业级开源工具构建 Firebase 的功能”，但同时强调 Supabase 并不是 Firebase 的一对一映射。这个定位意味着使用者需要理解 PostgreSQL、数据库权限和服务边界，而不能只把它视为一个与数据库无关的托管接口。

主要使用场景

• 需要关系型数据库、表结构、SQL 能力和数据库级权限控制的 Web 应用。
• 需要用户注册、登录、会话管理以及基于 JWT 的认证流程的应用。
• 需要把数据库表暴露为 REST 或 GraphQL 接口，并让客户端订阅数据变化的应用。
• 需要文件上传、对象管理，或需要把 PostgreSQL 与向量、嵌入能力结合起来的 AI 应用。
• 需要在托管环境使用，也希望保留本地开发或自托管路径的团队。

核心功能

Supabase 的能力边界围绕 PostgreSQL 展开：数据库保存数据，其他服务根据数据库状态、权限和客户端请求提供访问能力。每项能力都有独立的 README 文档入口，实际接口字段、认证策略和部署参数应以对应文档为准。

PostgreSQL 数据库

托管 PostgreSQL 数据库是平台的基础。应用数据、权限关系以及部分服务元数据以 PostgreSQL 为中心组织，其他组件通过数据库访问或监听数据库变化完成工作。

README 将 PostgreSQL 描述为具有长期持续开发历史、可靠性、功能完整性和性能特征的对象关系数据库系统。给定资料没有提供具体数据库版本、实例规格、连接参数、备份策略或性能基准，因此这些内容不能从本文推导。

身份认证与授权

认证和授权由 GoTrue 提供。README 将 GoTrue 定义为基于 JWT 的认证 API，用于简化用户注册、登录和会话管理；输入是应用发起的身份操作，输出包括认证结果和会话相关数据，具体请求格式由官方认证文档定义。

认证并不等于数据授权。应用仍需根据数据库权限和平台提供的授权机制限制用户可以读取或修改的记录。资料没有给出具体策略语法、默认角色或密钥轮换流程，部署前应查阅认证与数据库安全文档。

自动生成 REST 与 GraphQL API

PostgREST 将 PostgreSQL 数据库直接转换为 REST API。其工作依据是数据库中的表、视图、函数和权限配置，客户端发出 HTTP 请求后，服务根据数据库结构和授权结果读取或写入数据。

GraphQL 能力由 PostgreSQL 扩展 pg_graphql 提供。README 将其描述为“exposes a GraphQL API”的 PostgreSQL 扩展，说明 GraphQL API 的数据来源与数据库模型存在直接关系。具体查询语法、暴露规则和扩展配置，官方仓库资料未完整提供。

实时订阅

Realtime 是一个 Elixir 服务，允许客户端通过 WebSocket 监听 PostgreSQL 的插入、更新和删除事件。根据 README，Realtime 会轮询 PostgreSQL 内置复制能力获取数据库变化，将变化转换为 JSON，再通过 WebSocket 广播给已授权客户端。

因此，实时订阅的触发条件是数据库发生符合监听范围的变更，输出是面向客户端的 JSON 变化消息；消息能否发送还取决于授权。资料没有提供订阅通道命名、事件过滤表达式、重连策略或消息保留时间。

数据库函数与边缘函数

平台区分数据库函数和 Edge Functions。数据库函数在 PostgreSQL 侧执行，适合把数据校验、聚合或事务相关逻辑放在数据库边界内；边缘函数属于独立的函数能力，README 将其单独列为 Edge Functions。

仓库脚本包含生成 TypeScript 数据库类型的命令，输出路径为 ./supabase/functions/common/database-types.ts。这表明仓库自身的本地工作流会把数据库类型用于函数代码，但给定资料未提供函数运行时版本、部署命令、请求签名或超时配置。

文件存储

Storage 通过 RESTful API 管理 S3 中的文件，并由 PostgreSQL 处理权限。文件内容和数据库权限因此处于不同的职责层：Storage 负责文件管理接口，PostgreSQL 负责权限判断及相关元数据关系。

资料未提供默认存储桶、对象大小限制、生命周期策略、访问 URL 格式或兼容的 S3 配置项。生产环境需要按照官方 Storage 文档确认这些参数，而不能直接套用未在仓库资料中出现的默认值。

AI、向量与嵌入工具

README 将 AI + Vector/Embeddings Toolkit 列为平台能力，但没有在给定片段中展开其组件组成、数据模型、索引类型、模型提供方或查询接口。可以确认的是，该能力属于围绕 PostgreSQL 数据开发的工具集合，而不是本文资料足以完整描述的独立模型服务。

系统架构与关键模块

Supabase 的架构是多个开源服务围绕 PostgreSQL 组合而成，而不是单个 TypeScript 服务。README 同时说明平台支持托管、自托管和本地开发，部署方式会改变运维责任，但不会改变这些核心模块的职责划分。

组件职责

客户端库

项目采用模块化客户端库方案。README 说明每个子库对应一个外部系统的独立实现，Supabase 客户端则把 PostgREST、GoTrue、Realtime、Storage 和 Functions 等功能客户端组合起来。

• JavaScript（TypeScript）客户端为 supabase-js，包含 postgrest-js、auth-js、realtime-js、storage-js 和 functions-js。
• Flutter 客户端为 supabase-flutter，对应 PostgREST、GoTrue、Realtime、Storage 和 Functions 的 Dart 客户端。

README 片段还展示了官方客户端与各功能客户端的对应关系，但未提供其他语言客户端的完整列表。选择客户端时，应以官方客户端仓库和当前文档的支持状态为准。

依赖与运行环境

根目录 package.json 给出了仓库开发环境的明确约束：pnpm 版本为 11.13，Node.js 版本要求为 >=22.13，包管理器声明为 pnpm@11.13.1。安装阶段通过 preinstall 脚本限制使用 pnpm。

构建任务由 Turborepo 编排，代码检查使用 ESLint 和 Prettier，类型检查使用 TypeScript。仓库脚本还包含 Docker 构建 Studio 的命令，但给定资料没有声明 Docker 版本、操作系统要求或完整的本地基础设施清单。

快速开始（含最小可运行示例）

以下流程只针对仓库本地开发，命令均来自根目录 package.json 的脚本或其声明。由于本地启动依赖的容器运行条件未在给定资料中完整列出，执行前应先阅读仓库 README 和本地开发文档。

安装

node --version
pnpm --version
pnpm install

其中 Node.js 版本应满足 >=22.13，pnpm 应使用仓库声明的版本范围。pnpm install 会触发 preinstall，该脚本通过 npx only-allow pnpm 拒绝其他包管理器。

启动本地服务

pnpm setup:cli

根据 package.json，该脚本执行 supabase start -x studio，随后运行 supabase status --output json > keys.json，最后调用 node scripts/generateLocalEnv.js。这一步会准备本地服务状态和开发环境文件；资料没有给出生成文件的具体字段，因此不应手工猜测其内容。

运行与验证

pnpm dev:studio-local
supabase status --output json

dev:studio-local 会先调用 pnpm setup:cli，再以 NODE_ENV=test MODE=test 启动 apps/studio。验证步骤使用 CLI 输出本地服务状态；命令输出中的密钥属于本地测试环境信息，不应提交到公共仓库或复制到生产环境。

生成 TypeScript 数据库类型

pnpm generate:types

该脚本执行 supabase gen types typescript --local > ./supabase/functions/common/database-types.ts，输入来源是本地数据库，输出为 TypeScript 类型文件。它适合在本地数据库结构变更后更新函数侧类型，但资料没有说明该文件是否应纳入业务项目的版本控制。

配置说明

给定资料没有提供完整的 .env.example、Docker Compose 配置或平台配置文件，因此能够严格确认的配置项主要来自根目录 package.json。下表只列出文件中真实出现的字段，未提供的默认值明确标记为“未提供”。

具体服务密钥、数据库连接地址、认证密钥、Storage 参数和自托管配置在给定资料中没有列出。官方仓库未提供该信息，建议以最新 README 和官方文档为准；不要根据示例环境自行推断生产配置。

进阶用法

仓库脚本覆盖了构建、开发、格式化、类型检查、单元测试和端到端测试，适合将 Supabase 平台仓库作为多包工作区进行开发。进阶使用的重点是按应用筛选任务，并区分 Studio、文档站点、官网和测试环境。

按应用启动开发任务

• pnpm dev：并行执行工作区中的开发任务。
• pnpm dev:studio：通过 Turborepo 过滤并行启动 Studio。
• pnpm dev:docs：过滤 docs 应用并行开发。
• pnpm dev:www：过滤 www 应用并行开发。
• pnpm dev:design-system：过滤 design-system 开发任务。

构建与质量检查

pnpm build 会执行工作区构建，pnpm build:studio、pnpm build:docs 和 pnpm build:design-system 用于缩小构建范围。代码质量方面，仓库提供 pnpm lint、pnpm typecheck、pnpm test:prettier 和 pnpm format。

测试脚本还覆盖 docs、UI、Studio 和多个端到端场景。端到端测试包括 e2e:setup:cli、e2e:setup:selfhosted、e2e:setup:platform 以及 e2e、e2e:ui 等命令；这些命令会启动测试服务或构建 Studio，适合隔离环境执行。

本地性能脚本的边界

package.json 提供 perf:kong 和 perf:meta 两个本地压测脚本，分别针对 http://localhost:8000/ 和 http://localhost:5555/tables 使用 ApacheBench。它们只能说明仓库存在这些测试入口，不能据此推导平台性能、吞吐量或生产容量。

可观测性与运维

从仓库资料能够确认的运维入口包括 CLI 状态查询、Dashboard、自托管文档和本地启动脚本。README 建议通过仓库的 Releases 关注重大更新，但没有在给定资料中提供日志字段、指标名称、告警规则、备份恢复流程或服务等级承诺。

• 本地状态：使用 supabase status --output json 查看本地服务状态。
• 管理面板：平台包含 Dashboard，README 提供了 Dashboard 截图，但本文不引用外部图片。
• 更新跟踪：可以关注 GitHub 仓库的 Releases，以接收重大更新通知。
• 问题反馈：功能故障适合提交 GitHub Issues，构建和数据库实践讨论可进入 Community Forum。

托管环境与自托管环境的责任边界不同。资料没有给出托管服务的 SLA、数据保留周期、区域可用性或灾备承诺，相关决策必须以官方当前服务条款和支持文档为准。

安全与合规边界

Supabase 涉及身份、会话、数据库和文件权限，因此安全重点是授权模型、密钥管理和数据隔离，而不是简单地把 API 暴露到公网。所有示例和操作都应限定在本人拥有或已获授权的本地、测试或生产环境内。

• 不要把 keys.json 或 CLI 输出中的密钥提交到公共仓库；该文件由仓库本地脚本生成，具体字段以实际环境为准。
• 不要把服务端密钥、数据库凭据或认证密钥放入客户端代码、公开日志和工单附件。
• 数据库表、REST、GraphQL、Realtime 和 Storage 的权限应分别核验，认证成功不能替代数据级授权。
• 涉及个人信息、医疗数据、财务数据或跨境数据时，应由组织的合规人员确认适用法律、数据处理协议、留存和删除要求。
• 自托管时，数据库、代理、认证、存储和实时服务的补丁、访问控制、备份和监控由部署方承担；资料未给出具体责任清单。

本文不提供针对未授权目标的扫描、攻击、绕过检测或账号自动化教程。若要验证权限，应使用专门的本地测试项目和非生产数据，并记录测试授权范围。

许可证与商用条款

仓库 LICENSE 文件为 Apache License 2.0。该许可证授予全球、永久、非独占、免版税的版权许可，并在许可证规定的范围内授予相关专利许可；同时保留对许可证、版权和归属声明的具体要求。

根据 LICENSE 第 4 节，分发原始作品或衍生作品时，需要向接收者提供许可证副本；修改文件需要带有明确的修改说明；分发源代码形式的衍生作品时，需要保留相关版权、专利、商标和归属声明。若作品包含 NOTICE 文件，还需要按许可证要求提供其中的归属声明。

Apache-2.0 允许在满足许可证条件的前提下进行商业使用、复制、修改和分发，但商标条款不授予使用许可方商品名、商标、服务标志或产品名称的权利。实际商业发行还需检查仓库中各组件及第三方依赖的独立许可证，以仓库 LICENSE 和相应组件许可证为准。

局限性与已知限制

给定资料足以确认平台组成和仓库开发脚本，但不足以形成完整的生产部署手册。以下限制来自资料缺口或架构边界，不应被扩展解释为未提供的产品缺陷结论。

• 未提供完整的服务版本矩阵、数据库版本、操作系统兼容性和容器运行要求。
• 未提供正式的性能基准、最大连接数、并发级别、数据规模上限或容量规划数据。
• 未提供完整的环境变量清单、密钥命名、认证提供商配置和 Storage 生产配置。
• 未提供备份、恢复、故障转移、升级回滚和灾难恢复的完整操作步骤。
• 实时服务依赖数据库变化捕获和授权判断，具体事件过滤、顺序保证与断线恢复语义需要查阅最新文档。
• 托管平台与自托管平台的功能差异、计费、SLA 和支持范围未在给定 README 片段中说明。

根据本文作者的经验判断，如果团队只需要一个极简的键值存储接口，却不准备维护数据库结构和权限规则，Supabase 的能力面会带来额外学习和治理成本；这是场景判断，不是仓库声明。

适合谁

适合性可以通过数据模型、部署责任和团队技术栈判断，而不是只看功能数量。出现以下信号时，Supabase 的架构方向与项目需求较为匹配。

1. 应用以关系型数据为中心，需要表、查询、数据库函数和 PostgreSQL 权限模型。
2. 团队希望同时获得认证、自动生成 API、实时数据和文件存储，而不想为每项能力分别设计服务边界。
3. 客户端主要使用 JavaScript（TypeScript）或 Flutter，并希望使用 README 列出的官方客户端库。
4. 项目需要托管使用，同时保留本地开发或自托管选项，以便在不同环境中复现服务。
5. 团队能够承担数据库迁移、授权策略、密钥保护、备份和运行监控等工程职责。

不适合谁

不适合性主要来自治理要求和技术栈约束。出现以下信号时，应先验证能力覆盖范围，不能仅因平台提供多个功能就直接采用。

1. 团队不愿管理关系型数据结构、数据库权限或 SQL 逻辑，而需求只包含极少的数据读写。
2. 项目有明确的合规、驻留、审计或隔离要求，但无法确认托管平台或自托管方案是否满足这些要求。
3. 团队的主要技术栈不在资料列出的 JavaScript（TypeScript）和 Flutter 客户端范围内，且无法接受自行评估其他客户端。
4. 项目要求已验证的高并发、超大数据量或特定 SLA，但当前资料没有提供相应基准和服务承诺。
5. 组织不具备维护自托管 PostgreSQL、认证、实时、代理和对象存储链路的运维能力，同时又不能使用托管平台。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分依赖安装、CLI 本地环境、Studio、数据库权限和客户端请求五类问题。下面的判断均基于仓库脚本和 README 提供的入口。

为什么安装时提示包管理器不被允许

根目录 package.json 的 preinstall 脚本是 npx only-allow pnpm，仓库明确要求使用 pnpm。请检查 Node.js 是否满足 >=22.13，并使用 pnpm@11.13.1 对应的包管理器声明。

本地启动后如何确认服务状态

使用 supabase status --output json 查询状态。pnpm setup:cli 和 dev:studio-local 都包含本地启动和状态准备逻辑；如果仍然失败，需检查本地 CLI、容器运行条件以及仓库最新本地开发文档，给定资料没有列出更细的错误码映射。

为什么生成的类型与代码不一致

pnpm generate:types 使用 --local 从本地数据库生成类型。如果数据库结构尚未应用到本地环境，或连接的本地项目不是当前代码对应的项目，生成结果就不能代表目标环境。应先确认本地数据库状态，再检查输出文件 ./supabase/functions/common/database-types.ts。

Realtime 没有收到变化消息怎么办

根据 README，Realtime 依赖 PostgreSQL 的变化捕获、JSON 转换、WebSocket 广播和客户端授权。排查时应依次核对数据库是否发生插入、更新或删除，客户端是否建立 WebSocket 连接，以及授权规则是否允许该客户端接收变化；具体日志和订阅配置字段未在资料中提供。

REST 或 GraphQL 请求失败如何定位

REST 由 PostgREST 根据 PostgreSQL 数据库提供，GraphQL 由 pg_graphql 扩展提供。应先检查目标表或函数是否存在、数据库权限是否允许访问，再确认客户端使用的 API 类型与对应服务是否已启用；实际错误响应格式请以官方 API 文档为准。

项目开发与贡献

仓库 README 将 DEVELOPERS.md 作为贡献入门入口，说明贡献者应先阅读该文件。根目录脚本覆盖格式化、Lint、类型检查、单元测试和端到端测试，提交变更前应根据受影响的应用选择对应检查命令。

• 修改 Studio 时，可使用 pnpm dev:studio、pnpm test:studio 和 pnpm build:studio。
• 修改文档时，可使用 pnpm dev:docs、pnpm test:docs 以及文档端到端测试脚本。
• 修改共享代码时，应执行 pnpm lint、pnpm typecheck 和格式检查。
• 涉及用户界面时，仓库提供 pnpm test:ui 和 pnpm test:ui-patterns。

问题报告与讨论应区分渠道：README 建议将 GitHub Issues 用于使用过程中的错误和缺陷，将 Community Forum 用于构建帮助与数据库实践讨论，并提供 Discord 和邮件支持入口。

项目地址与资源

以下链接均来自仓库元信息或 README 中列出的项目官方资源，适合用于源码、文档、社区支持和问题反馈。

• supabase GitHub 仓库
• Supabase 官网
• Supabase 官方文档
• 数据库文档
• 认证文档
• REST API 文档
• GraphQL 文档
• Realtime 文档
• Edge Functions 文档
• Storage 文档
• AI 与向量工具文档
• 自托管文档
• Supabase Community Forum
• GitHub Issues
• Supabase Discord
• Supabase 邮件支持说明
• supabase-js 客户端
• Realtime 服务
• GoTrue 认证服务
• Storage API
• postgres-meta
• pg_graphql