Supabase 开源架构全景解读：以 Postgres 为核心的开发平台如何由开源组件组装而成

本篇技术指南围绕 Supabase 官方仓库自述文档（i18n/README.ar.md，即主 README.md 的阿拉伯语译本）展开，系统性梳理 Supabase 的定位、功能矩阵、底层组件架构与多语言客户端生态，并结合本仓库的 Docker 编排、Supabase CLI 配置与 pnpm monorepo 结构，逐一把文档中宣称的组件落到真实代码与配置上。读完本文，你将理解"Postgres 开发平台"是如何由 PostgreSQL、PostgREST、GoTrue、Realtime、Storage 等开源模块组装而成的，也知道如何在本仓库中按图索骥找到每个模块对应的实现与使用入口。

一、Supabase 是什么：定位与技术路线

按项目官方 README 的自述，Supabase 是一个 Firebase 的开源替代品（Open Source Firebase Alternative）——更准确地说是"The Postgres development platform"：以一套高质量的、企业级的开源工具，去构建 Firebase 所提供的能力。它并不是 Firebase 的 1:1 复刻，目标是用开源工具给开发者带来"类 Firebase"的开发体验（详见 i18n/README.ar.md 与 README.md）。

其技术选型遵循一条非常清晰的原则：

• 如果某个能力已经有成熟的开源工具与社区，且采用 MIT、Apache 2 或等价宽松许可证，Supabase 就直接采用并支持该工具；
• 如果不存在这样的工具，Supabase 就自己构建并开源。

例如 PostgreSQL 与 PostgREST 属于前者，而 Realtime、postgres-meta 等属于后者。这一策略直接决定了仓库的形态：本仓库更多是"把这些组件编排成完整平台"的工程化产物，同时把平台自研部分（如 Dashboard、文档、示例）全部开源在同一个 monorepo 中。

在实际使用层面，README 给出了三种接入方式（README.md）：

1. 托管平台（Hosted Platform）：注册即用，无需安装任何东西；
2. 自托管（Self-hosted）：使用仓库内的 docker/README.md 所述 Docker Compose 方案部署在自己的基础设施上；
3. 本地开发（Local Development）：通过 Supabase CLI 在本地起一套完整后端，仓库根部的 supabase/config.toml 即是 CLI 驱动本地栈的配置示例。

二、核心功能全景：从数据库到 AI 工具箱

官方自述文档用一张特性清单概括了当前已实现的功能模块（README.md）。下表按"功能 → 文档说明 → 仓库内对应落点"整理，方便读者后续逐一深入：

功能	官方描述要点	仓库内可查阅的对应位置
托管 Postgres 数据库	平台核心，Postgres 即数据库	docker/docker-compose.yml 的 db 服务；supabase/migrations 存放大量 SQL 迁移
认证与授权	用户注册、登录、会话管理	Compose 中 auth 服务（GoTrue），docker/docker-compose.yml
自动生成 API：REST	把 Postgres 直接暴露为 RESTful API	Compose 中 rest 服务（PostgREST）
自动生成 API：GraphQL	通过 Postgres 扩展暴露 GraphQL	supabase/config.toml 中 api.schemas 含 graphql_public
自动生成 API：Realtime 订阅	WebSocket 实时监听数据库变更	Compose 中 realtime 服务
函数：Database Functions	Postgres 内的函数	supabase/migrations 中大量 RPC 函数
函数：Edge Functions	边缘运行时的 JS/TS/WASM 服务	Compose 中 functions 服务；supabase/functions 内如 og-images、search-embeddings 等真实示例
文件存储	基于 S3 的文件管理与权限	Compose 中 storage 服务与 imgproxy；supabase/config.toml 的 [storage] 配置
AI + Vector/Embeddings 工具包	向量检索、嵌入等 AI 能力	supabase/migrations 中 *_search*.sql、hybrid search 等迁移；packages/ai-commands
Dashboard（控制台）	Web 管理界面	apps/studio/README.md

从"功能已勾选完成"的清单可以看出，Supabase 覆盖的是后端即服务（BaaS）的完整闭环：数据库、鉴权、API、函数、存储、AI 检索与管理后台一应俱全。其中值得强调的两点是：

• API 是"生成"的而非"手写"的：Postgres 的表、视图、函数在配置的 schema 下自动获得 REST/GraphQL/Realtime 端点，开发者不需要单独写服务端 CRUD 代码（这一机制的底层原理见下一节各组件说明）。
• AI 能力建立在 Postgres 之上：向量检索同样以数据库迁移与 SQL 函数形态存在于 supabase/migrations（例如以 vector_search、hybrid_search 命名的迁移文件），印证了"以 Postgres 为内核扩展 AI 能力"的产品路线。

Dashboard 的定位说明

README 把 Dashboard 列为独立特性。仓库内的 apps/studio/README.md 给出了它的边界：Dashboard 面向已有部署（托管、Docker 或 CLI 起的本地栈），提供表/SQL 编辑器、数据库管理（策略、角色、扩展、复制）、API 文档等能力，但不负责项目部署与管理的部分——那些由 docker compose 文件或云端的密钥管理负责。换句话说，它是一个"数据库工作台"，而非"运维控制面"。

三、工作原理：核心组件逐一拆解

README 的"How it works"章节明确点出：Supabase 是多个开源工具的组合。因此理解 Supabase 的关键，是理解每个开源组件负责什么、以及它们如何被编排在一起。本节结合官方说明与仓库编排文件逐层拆解。

1. PostgreSQL：一切的地基

官方文档对 Postgres 的评价是：一个"对象-关系型数据库系统，历经 30 余年持续开发，以可靠、功能健壮与高性能著称"。在本仓库中：

• 自托管编排里，db 服务使用 supabase/postgres 镜像（docker/docker-compose.yml）；
• 本地开发默认 Postgres 主版本为 15（supabase/config.toml 中 major_version = 15，并提示远程库需一致）；
• supabase/migrations 用 SQL 迁移承载文档搜索、向量检索等平台级能力，是"Postgres 即平台"最直接的证据。

2. Realtime：监听数据库变更的 WebSocket 服务

Realtime 是一个 Elixir 编写的服务，允许客户端通过 WebSocket 监听 Postgres 的插入、更新与删除事件。其工作链条是（README.md）：轮询 Postgres 内置的复制（replication）功能 → 把变更转为 JSON → 通过 WebSocket 广播给授权客户端。

在仓库编排中对应 realtime 服务（docker/docker-compose.yml）。如果你关心它的客户端用法，官方 README 也指明客户端库为 realtime-js 等（见第四节生态表）。

3. PostgREST：数据库直出 RESTful API

PostgREST 是一个 Web 服务器，把 PostgreSQL 数据库直接变成 RESTful API——不需要额外编写业务层，表结构即接口。仓库的 rest 服务即运行 PostgREST（docker/docker-compose.yml），相关行为由 PGRST_DB_SCHEMAS、PGRST_DB_MAX_ROWS 等环境变量控制（可对照 supabase/config.toml 中 api 段的 schemas、max_rows 等概念理解）。

4. GoTrue：认证与授权 API

GoTrue 是 Supabase 认证体系的实现，负责用户的注册、登录与会话管理。官方 README 强调它是 JWT（JSON Web Token）基础的认证 API（README.md）。从编排配置可以印证：auth 服务运行 supabase/gotrue 镜像，且暴露大量 GOTRUE_JWT_* 配置项，如 GOTRUE_JWT_SECRET、GOTRUE_JWT_EXP（过期时间）、GOTRUE_JWT_ISSUER 等（docker/docker-compose.yml），并支持邮箱、手机短信、OAuth 社交登录、TOTP/手机 MFA、SAML SSO 等开关配置。需要说明的是，阿拉伯语译本中该组件被描述为"SWT 令牌"，而仓库主 README 与当前编排事实均以 JWT 为准，本文采用 JWT 表述。

5. Storage + imgproxy：S3 文件存储与图片处理

Storage 提供管理 S3 中文件的 RESTful API，权限由 Postgres 管理（行级安全策略作用于 storage 元数据）。配套的 imgproxy 负责快速、安全的图片实时处理（docker/docker-compose.yml）。本地配置中还可见存储限额与公开 bucket 的写法（supabase/config.toml：file_size_limit = "50MiB"，[storage.buckets.fonts] 声明公开 bucket 及其对象路径）。

6. postgres-meta：支撑 Dashboard 的元数据 API

postgres-meta 是一个用于管理 Postgres 的 RESTful API：允许抓取表结构、添加角色、执行查询等。它的典型消费者就是 Dashboard：Studio 通过 STUDIO_PG_META_URL: http://meta:8080 指向 meta 服务（docker/docker-compose.yml），由此获得表编辑器、SQL 编辑器等能力。仓库内 packages/pg-meta 还提供了与 postgres-meta 交互的类型化客户端封装。

7. GraphQL：pg_graphql 扩展

README 功能清单中的"自动生成 GraphQL API"由 Postgres 扩展实现（主 README 架构段落列出 pg_graphql，README.md）。本地配置把 graphql_public 纳入 API 暴露的 schemas（supabase/config.toml），说明 GraphQL 与 REST 同享"数据库即接口"的设计哲学。

8. API 网关：Kong 与 Envoy

各服务之间需要一个统一入口。阿拉伯语译本与早期架构清单中列出的网关是 Kong（云原生 API 网关）；而当前仓库的默认编排已切换为 Envoy——api-gw 服务默认运行 envoyproxy/envoy 镜像（docker/docker-compose.yml），对外端口默认 8000。不过 docker/README.md 明确说明 Kong 仍可作为一个可选项，通过 sh run.sh config add kong 覆盖启用。

编排视角：一套 Docker Compose 看到完整拓扑

把以上组件拼到一起，就是自托管（也是本地栈）的完整拓扑。仓库根部的 docker/docker-compose.yml 一次性定义了全部服务：studio（Dashboard）、api-gw（Envoy 网关）、auth（GoTrue）、rest（PostgREST）、realtime、storage、imgproxy、meta（postgres-meta）、functions（Edge Runtime）、db（Postgres）、supavisor（Postgres 连接池）。启动与停止分别对应 docker compose up -d / docker compose down，重置可执行 sh reset.sh（docker/docker-compose.yml）。

本地 CLI 开发栈的端口映射也遵循同一拓扑（supabase/config.toml）：API 54321、数据库 54322、Studio 54323、Inbucket 邮件测试界面 54324。这意味着无论你是自托管还是本地开发，面对的都是同一套组件架构，只是入口与运维方式不同。

四、模块化客户端库生态：一种语言一条完整链路

README 详细阐述了客户端库的设计哲学（README.md）：客户端库是模块化的——每个子库都是对某个外部系统的独立实现（例如独立的 PostgREST 客户端、独立的 GoTrue/Auth 客户端），而聚合的 Supabase 客户端把这些子库捆绑起来。这样做的好处是能最大化复用以支持既有工具生态。

阿拉伯语译本在项目自述中保留了完整的生态表格，覆盖官方与社区两大梯队。下表汇总语言与各能力客户端的关系（"-"表示该语言当前无对应实现）：

语言	聚合客户端	PostgREST	GoTrue / Auth	Realtime	Storage
JavaScript (TypeScript)	supabase-js（官方）	postgrest-js	auth-js	realtime-js	storage-js
C#	supabase-csharp（社区）	postgrest-csharp	gotrue-csharp	realtime-csharp	-
Flutter	supabase-flutter / supabase-dart（社区）	postgrest-dart	gotrue-dart	realtime-dart	storage-dart
Go	-	postgrest-go（社区）	-	-	-
Java	-	-	gotrue-java（社区）	-	-
Kotlin	supabase-kt（社区）	postgrest-kt	gotrue-kt	realtime-kt	storage-kt
Python	supabase-py（社区）	postgrest-py	gotrue-py	realtime-py	-
Ruby	supabase-rb（社区）	postgrest-rb	-	-	-
Rust	-	postgrest-rs（社区）	-	-	-
Swift	supabase-swift（社区）	postgrest-swift	gotrue-swift	realtime-swift	storage-swift

上表所列客户端项目大多维护在独立的官方/社区仓库中；本仓库虽然本身不托管这些客户端源码，但作为最大的消费方之一，通过 pnpm 工作区的 catalog 统一锁定其版本——例如 pnpm-workspace.yaml 中对 @supabase/supabase-js、@supabase/auth-js、@supabase/postgrest-js、@supabase/realtime-js 等依赖的版本目录化声明。

从表中可以读出两层信息：

1. 覆盖率最完整的是官方 JavaScript/TypeScript 客户端：它由五个功能子库（REST/认证/实时/存储/函数）组合而来，一份代码覆盖全部能力；
2. 社区客户端往往"按需补齐"：例如 Go/Rust/Java 生态目前仅实现它们最需要的 PostgREST 或 Auth 部分，而 Kotlin、Flutter、Swift 等移动端语言则把 REST、Auth、Realtime、Storage 全部打通，这与它们的应用场景（移动/跨端应用）高度吻合。

如果读者想在实际仓库中看到这些客户端的使用形态，可以浏览 examples 目录下的各类官方示例，例如 examples/user-management 中按技术栈划分的 nextjs、vue3、flutter、swift 等用户管理应用，它们演示了认证与数据读写的最小闭环。

五、把组件放回仓库：monorepo 代码阅读地图

README 描述的是"产品组合的逻辑架构"，而要把这些认知落到实处，还需要理解仓库本身的物理组织。本仓库是一个 pnpm 管理的 monorepo（见 package.json 与 pnpm-workspace.yaml，工作区包含 apps/*、packages/*、blocks/*、e2e/*），主要目录与文档中各模块的对应关系如下：

• apps/studio：Dashboard 前端（对应功能清单的 Dashboard，Next.js + Tailwind 构建，见 apps/studio/README.md）；
• apps/docs：官方文档站源码，README 中每一项功能（数据库、Auth、API、Functions、Storage、AI 等）都有对应文档内容（见 apps/docs/README.md）；
• docker：自托管编排，是"架构章节"的物理载体（compose、配置、升级脚本，见 docker/README.md 与 docker/CONFIG.md）；
• supabase：Supabase CLI 工作目录配置与示例——supabase/config.toml 是本地开发配置；supabase/migrations 与 supabase/functions 分别是数据库迁移与 Edge Functions 的真实样例；
• packages：共享代码，如 packages/shared-data（计费/区域等共享数据）、packages/ui-patterns 与 packages/ui（UI 组件）、packages/ai-commands（AI 命令能力）；
• examples：官方示例应用，覆盖 auth、realtime、storage、AI、用户管理等多个主题；
• i18n：README 的多语言译本目录（本文所依据的 i18n/README.ar.md 即位于此处）。

推荐的阅读路线是：先读 README.md 建立功能与组件心智模型 → 打开 docker/docker-compose.yml 对照服务清单看真实拓扑 → 针对感兴趣的服务到 supabase/config.toml 与 supabase/migrations 里看配置与 SQL 细节 → 最后到 apps/docs/README.md 找对应使用文档。若想参与开发，仓库根的 DEVELOPERS.md 与 CONTRIBUTING.md 提供了环境搭建与贡献规范；自托管升级/版本回滚可参考 docker/CHANGELOG.md 与 docker/versions.md。

六、社区支持与多语言生态

项目的自述文档同时交代了社区与支持渠道及其适用场景，大体划分为四类：面向"帮助构建、讨论数据库最佳实践"的社区论坛；面向"使用中遇到的 Bug 与错误"的 Issues 追踪；面向"数据库或基础设施问题"的商务邮件支持；以及面向"分享应用、日常交流"的实时聊天社区。这些渠道的具体地址维护在各平台侧，仓库内不重复保存（见 README.md）。

值得一提的还有本仓库独特的多语言 README 生态：官方 README 说明部分被翻译为数十种语言，统一维护在 i18n 目录，完整的语言清单见 i18n/languages.md。本文所基于的 i18n/README.ar.md 正是其中阿拉伯语版本——各译本均保持与主 README.md 一致的结构，因此无论阅读哪个语言版本，获得的都是同一套组件架构与生态信息。这也是该项目面向全球开发者做技术布道的一种方式：让"Postgres 开发平台"的架构叙述以开发者母语触达。

---

综上所述，Supabase 的故事可以浓缩为一句话：它没有重新发明后端，而是把 Postgres 生态里最优秀的开源组件——PostgreSQL、PostgREST、GoTrue、Realtime、Storage、postgres-meta 等——编排成一套具备"类 Firebase"体验的完整平台，并把缺失的拼图自己补上、开源出来。 本文覆盖的能力清单、组件架构、客户端生态与仓库阅读路径，均直接继承自其官方自述文档，并逐一对应到了 docker/docker-compose.yml、supabase/config.toml 与各 apps / packages 目录下的真实实现，读者可以据此从"文档描述的 Supabase"一路深入到底层代码。