Supabase 开源仓库解析：Postgres 开发平台的架构组成、部署形态与客户端库生态

Supabase 是一个 Postgres 开发平台（Postgres development platform），其核心思路是"用企业级开源工具拼出 Firebase 式的能力组合"。本文以仓库根目录的 README.md 为主体，结合 docker/docker-compose.yml、DEVELOPERS.md 等仓库实证材料，讲清 Supabase 的功能全景、各组件的架构分工、三种使用形态（托管 / 自托管 / 本地开发）、多语言客户端库矩阵以及仓库自身的工程组织方式，读完后可以建立起对 Supabase 技术栈的完整认知并复现本地环境。

一、项目定位：一套"开源工具组合"的 Postgres 平台

README.md 对 Supabase 的定义非常直接："Supabase is the Postgres development platform. We're building the features of Firebase using enterprise-grade open source tools." 它把平台能力拆成一张特性清单，全部以开源组件实现：

• 托管 Postgres 数据库：核心就是一个专用的 PostgreSQL 实例，支持数据库函数（Database Functions）；
• 认证与授权：基于 GoTrue 的 JWT 认证 API，覆盖注册、登录、会话管理；
• 自动生成 API：不写业务代码即可从数据库直接得到三类接口——REST API、GraphQL API（通过 pg_graphql 扩展）、Realtime 订阅（WebSocket 推送数据变更）；
• Functions：包括数据库函数和运行在 Deno 上的 Edge Functions；
• 文件存储：RESTful 文件管理 API，权限由 Postgres 承担；
• AI + 向量/Embedding 工具集：依托 Postgres 的向量能力（pgvector）提供嵌入与相似度搜索；
• Dashboard：即 Studio，用于管理项目的可视化管理台。

README 同时明确了一个边界："Supabase is not a 1-to-1 mapping of Firebase"——它不是 Firebase 的功能逐项对标，而是用 MIT / Apache 2 许可的开源工具组合出"类 Firebase 的开发者体验"。这一条决定了理解 Supabase 的关键：它的每个功能背后都是一个可单独使用、可单独替换的开源项目。

二、架构解析：每个能力背后的开源组件

README 的 "How it works" 一节列出了构成平台的八个核心组件，docker/docker-compose.yml 则给出了它们在自托管栈中的真实镜像与端口，两者对照可以精确理解架构：

组件	职责	自托管栈中的证据（docker-compose.yml）
Postgres	对象关系数据库，所有功能的地基	supabase/postgres:17.6.1.136 镜像（db 服务），启动时挂载 docker/volumes/db/ 下的初始化 SQL（roles.sql、jwt.sql、realtime.sql 等）
Realtime	Elixir 编写的 WebSocket 服务器，轮询 Postgres 的复制（replication）功能捕获 INSERT/UPDATE/DELETE，转成 JSON 广播给授权客户端	supabase/realtime:v2.102.3（realtime 服务，端口 4000），通过 DB_AFTER_CONNECT_QUERY: 'SET search_path TO _realtime' 接入数据库
PostgREST	把 PostgreSQL 直接变成 RESTful API 的 Web 服务器	postgrest/postgrest:v14.12（rest 服务），配置了 PGRST_DB_SCHEMAS、PGRST_DB_MAX_ROWS、匿名角色 PGRST_DB_ANON_ROLE: anon 等
GoTrue	JWT 认证 API，简化注册、登录与会话管理	supabase/gotrue:v2.189.0（auth 服务，端口 9999），暴露大量 GOTRUE_* 环境变量：邮箱/手机注册开关、SMTP 配置、OAuth 提供商、MFA、SAML SSO 与 Auth Hooks
Storage	管理 S3 文件的 RESTful API，权限交给 Postgres	supabase/storage-api:v1.60.4（storage 服务），STORAGE_BACKEND: file 默认本地文件后端，可叠加 docker/docker-compose.s3.yml 切换为 S3
pg_graphql	PostgreSQL 扩展，暴露 GraphQL API	以 Postgres 扩展形式随数据库镜像提供
postgres-meta	管理 Postgres 本身的 RESTful API：取表、加角色、执行查询	supabase/postgres-meta:v0.96.6（meta 服务，端口 8080），Studio 通过 STUDIO_PG_META_URL: http://meta:8080 与其通信
Envoy	云原生边缘/服务代理，作为 API 网关	envoyproxy/envoy:v1.39.0（api-gw 服务，端口 8000），并设置了 envoy/kong 双网络别名，便于在两种网关之间切换

从 docker-compose.yml 的完整服务列表还可以看到两个 README 未逐一展开、但属于自托管栈的组件：imgproxy（图像处理，Storage 的图片变换依赖它，IMGPROXY_BIND: ":5001"）与 supavisor（supabase/supavisor:2.9.5，Postgres 连接池，默认 POOLER_POOL_MODE: transaction 事务级连接池，对外暴露 5432 与 6543 端口）。docker/README.md 的 "What's Included" 还补充了 Logflare（日志）与 Vector（日志管道）两个可观测性组件。

README 中引用的架构图文件位于 apps/docs/public/img/supabase-architecture.svg，展示了上述组件（Postgres 居中、Auth/REST/Realtime/Storage 等围绕其后、经由网关对外提供能力）的连接关系，适合对照上文的服务表理解整体数据流。

组件协作方式

各组件并非孤立交互，而是通过统一的 JWT 体系串联。以自托管栈为例：数据库初始化脚本（JWT_SECRET、JWT_EXP 环境变量注入）为 authenticator 等角色写入 JWT 校验参数；GoTrue 签发的用户 JWT 被 PostgREST（PGRST_JWT_SECRET）、Realtime（API_JWT_SECRET）、Storage（AUTH_JWT_SECRET）、Edge Functions（JWT_SECRET）各自验证；行级安全（RLS）策略则消费 JWT 里的 role 声明来控制数据访问。这意味着"认证"与"授权"在 Supabase 中是同一套令牌贯穿所有服务的，而不是每个组件各管一段。

三、三种使用形态：托管、自托管与本地开发

README 指出 Supabase 是一个托管平台：可以直接注册使用，也可以自托管（self-host）或本地开发。仓库对后两条路径提供了完整可复现的入口。

自托管：Docker Compose 全家桶

docker/ 目录是官方自托管栈。docker/README.md 给出了标准操作流程：

cd docker
cp .env.example .env     # 复制并修改所有密钥
docker compose up

docker/docker-compose.yml 头部注释还提供了常用运维命令：

docker compose up -d                                  # 启动
docker compose down                                   # 停止
docker compose -f docker-compose.yml -f ./dev/docker-compose.dev.yml up -d  # 开发模式
sh reset.sh                                           # 重置一切

镜像版本有专门的变更历史可查：docker/versions.md 记录每次更新的镜像版本及前一版本（例如 2026-06-17 将 Postgres 从 15.8.1 升到 17.6.1，2026-06-03 一批升级了 gotrue、postgrest、realtime、storage-api 等），配合 docker/CHANGELOG.md 可完成回滚参考。升级既有部署的官方流程是：

sh update.sh --dry-run   # 可选：预览
sh update.sh
sh run.sh pull && sh run.sh recreate

安全方面，docker/README.md 有明确警告：默认配置不面向生产安全。上生产前必须替换 .env 中所有默认密码与密钥、审查 CORS 配置、在前面架设安全代理、调整网络 ACL，并建立备份流程。

本地开发前端站点：Turborepo Monorepo

如果要开发 Supabase 自身的前端站点（www / studio / docs），按 DEVELOPERS.md 的环境要求操作。依赖版本由 package.json 锁定：Node.js >=22.13、pnpm 11.13（"packageManager": "pnpm@11.13.1"），仓库通过 preinstall: npx only-allow pnpm 强制包管理器。完整流程：

git clone <你的 fork 地址>.git
cd supabase
pnpm install                                # 安装依赖
cp apps/www/.env.local.example apps/www/.env.local   # www 站点需要环境变量
pnpm dev                                    # 并行启动所有站点

站点	目录	Scope	说明	本地地址
主站	apps/www	www	官网	http://localhost:3000
Studio	apps/studio	studio	管理台（需要 Docker 起的后端）	http://localhost:8082
Docs	apps/docs	docs	指南与 API 参考（Next.js）	http://localhost:3001/docs

也可以用 scope 单独启动某个站点，如 pnpm dev:www（package.json 的 scripts 中还定义了 dev:studio、dev:docs、dev:kb 等）。让 Studio 连上本地后端，则回到自托管流程：cd docker && cp .env.example .env && docker compose up，完成后 Studio 即可在 http://localhost:8082 访问。

四、仓库工程结构：从 README 到代码的对应关系

从源码结构看，这是一个以 Turborepo 组织的 pnpm monorepo，顶层目录与 README 所述功能的对应关系相当直观：

• apps/：各前端应用。apps/studio 即 Dashboard（管理台），apps/docs 是文档站（含 guides 与 reference 内容），apps/www 是官网，另有 apps/learn、apps/kb、apps/design-system、apps/lite-studio 等；
• packages/：跨应用共享包。DEVELOPERS.md 列出了核心几个：packages/common（共享 React 组件）、packages/ui（UI 组件库）、packages/config（共享配置）、packages/shared-data（跨应用共享数据）、packages/tsconfig（共享 TS 配置）、packages/ai-commands（AI 相关功能助手）；仓库中还有 packages/pg-meta（postgres-meta 的 TS 实现，对应 README 架构表中的 postgres-meta 组件）等；
• docker/：自托管 Docker Compose 栈（上文已详述），含 volumes/ 下的 API 网关配置（volumes/api/）、数据库初始化 SQL（volumes/db/）、示例 Edge Functions（volumes/functions/）以及运维脚本（reset.sh、update.sh、run.sh）；
• e2e/：Playwright 端到端测试，按 studio / docs / www 分目录组织；
• examples/：大量跨框架示例（auth、realtime、storage、user-management 等），可作为各功能客户端用法的参考；
• i18n/：README 的多语言翻译（见下文）；
• 根目录 Makefile：提供了 github.contributors 等辅助脚本与 dev 任务。

根 package.json 的 scripts 展示了日常开发命令面：pnpm build / pnpm lint / pnpm typecheck 走 turbo 流水线，pnpm test:studio、pnpm test:ui 等按包过滤测试，pnpm e2e 系列驱动端到端验证，pnpm setup:cli 则用 Supabase CLI 启动本地实例并生成 keys.json 供 Studio 本地联调。

五、客户端库矩阵：模块化设计

README 对客户端库的设计原则是模块化（modular）：每个子库（sub-library）都是针对单一外部系统的独立实现，例如单独对接 PostgREST 的库、单独对接 GoTrue 的库。这套模块化正是"支持现有工具"的方式之一——你既可以用打包好的 Supabase 官方客户端，也可以只用其中某一个能力。

官方库（⚡ Official），每个都打包在 Supabase 主客户端内，同时提供按功能的独立子库：

语言	Supabase 主客户端	REST	Auth	Realtime	Storage	Functions
JavaScript (TypeScript)	supabase-js	postgrest-js	auth-js	realtime-js	storage-js	functions-js
Flutter	supabase-flutter	postgrest-dart	gotrue-dart	realtime-dart	storage-dart	functions-dart
Swift	supabase-swift	postgrest-swift	auth-swift	realtime-swift	storage-swift	functions-swift
Python	supabase-py	postgrest-py	gotrue-py	realtime-py	storage-py	functions-py

社区库（💚 Community） 覆盖了 C#、Go、Java、Kotlin（supabase-kt 及 postgrest-kt / auth-kt / realtime-kt / storage-kt / functions-kt）、Ruby、Rust、Godot Engine (GDScript) 等语言；部分语言只有部分子库（如 Rust 仅有 postgrest-rs，Java 仅有 gotrue-java 与 storage-java）。README 中保留了新增语言行的 HTML 模板注释（START ROW / END ROW），供翻译与维护时按模板扩表。

从仓库内部看，客户端能力在仓库内的"影子"是 packages/ 与各示例：例如 examples/ 下的 auth（Next.js、SvelteKit、TanStack 等多框架认证示例）、realtime（多人协作、在线状态）、storage（断点续传 Uppy 示例）等，展示了各功能客户端的实际调用形态；packages/ai-commands 与 supabase/functions/（Deno 环境，含 deno.json）则对应 AI 与 Edge Functions 侧的实现。

六、国际化、社区支持与徽章

• 多语言翻译：README 提供约 45 种语言译本，全部位于 i18n/ 目录（如 i18n/README.zh-cn.md、i18n/README.ja.md 等，README 中写作 README.jp.md），完整清单见 i18n/languages.md；
• 社区与支持渠道：GitHub Discussions（构建求助、数据库最佳实践讨论）、GitHub Issues（Bug 与错误）、Discord（社区交流）、商业邮件支持（数据库与基础设施问题）；
• 徽章：官方提供 "Made with Supabase" 徽章的 Markdown / HTML 两种插入方式，图片源文件为 apps/www/public/badge-made-with-supabase.svg 及其暗色版 badge-made-with-supabase-dark.svg（168×30），README 原文给出了可直接复制的 Made with Supabase 与 <img width="168" height="30" ...> 两种写法；
• 贡献入口：README 的 "Documentation" 一节指向完整文档站点与 DEVELOPERS.md；后者补充了依赖清单（Git、Node.js、pnpm、make、Docker）、Fork/Clone 流程、共享包说明、PR 与 Issue 认领策略（不强制认领，鼓励提前沟通避免重复 PR），以及两个常见任务：在主站 lib/redirects.js 中添加重定向，以及"联邦文档"（Federated docs）机制——通过 Next.js 构建期 getStaticProps() 拉取外部仓库的 Markdown 并自动转换为原生文档页，外部仓库（如客户端库文档）可以零重复地嵌入官方文档体系；
• 许可证：仓库整体为 Apache-2.0（见 LICENSE 与 docker/README.md 的说明），这也是 README 所述"MIT、Apache 2 或同等许可工具优先"策略的自我适用。

七、小结

以 README.md 为主线可以概括 Supabase 的三层事实：

1. 能力层：Postgres + Auth + 自动生成 API（REST/GraphQL/Realtime）+ Functions + Storage + AI 向量工具 + Dashboard，全部由成熟开源组件构成；
2. 部署层：托管平台开箱即用；docker/ 提供带版本记录（versions.md）与升级脚本（update.sh）的完整自托管栈；仓库自身前端则用 pnpm + Turborepo 在本地 pnpm dev 起站；
3. 生态层：模块化客户端库覆盖主流语言，配合 examples/ 与 i18n/ 形成跨语言、跨框架的接入面。

对开发者而言，理解这一结构的实际价值在于：任何单一能力（比如只想用 PostgREST 的 REST 接口，或只关心 Realtime 的 WebSocket 订阅）都能在仓库内找到对应的组件定义、自托管配置与示例代码，而不必把 Supabase 当作一个黑盒整体。