Supabase 项目全景指南：用 Postgres 与开源组件构建的完整开发平台

Supabase 是一个把 PostgreSQL 变成完整后端开发平台的托管型开源项目：开发者既可以在云端直接注册使用，也可以将整套后端自托管到自己的服务器上。本文围绕仓库中的官方巴西葡萄牙语项目介绍（i18n/README.pt-br.md）为核心骨架，结合当前仓库的 docker/docker-compose.yml 服务编排、apps/ 各前端应用与 examples/ 示例代码等源码证据，梳理 Supabase 的功能全景、架构组成、客户端生态以及自托管与本地开发的入门路径，帮助你理解「用 Postgres 驱动 Web、移动端与 AI 应用」这一平台式开发方案是如何落地为真实代码的。

Supabase 是什么：以 Postgres 为核心的开源后端平台

按仓库官方说明，Supabase 定位为 Firebase 的开源替代方案（alternativa de código aberto ao Firebase），其思路是使用 MIT、Apache 2.0 或同等宽松许可证的企业级开源组件，去复刻并扩展 Firebase 提供的一整套后端能力：托管式数据库、鉴权、自动生成的 API、函数、文件存储、实时订阅与 AI/向量工具包。

值得强调的是，Supabase 并非 Firebase 的 1:1 复刻。仓库 README 明确指出："Supabase não é um mapeamento 1 para 1 do Firebase. Nosso objetivo é oferecer aos desenvolvedores uma experiência semelhante à do Firebase usando ferramentas de código aberto."（Supabase 不是 Firebase 的一比一映射，目标是借助开源工具为开发者提供类似 Firebase 的开发体验）。其选择组件的策略也很直白：如果某个能力已有成熟的开源组件（MIT/Apache 2 等价许可），就直接采用并维护它；如果没有，就自己构建并开源。这条策略解释了为何仓库由 Postgres、PostgREST、GoTrue、Realtime、Storage 等大量既有开源项目组合而成。

功能全景清单

官方 README 用一张完成度清单（checklist）概括了整个平台当前提供的能力：

• [x] 托管式 Postgres 数据库（Hosted Postgres Database）
• [x] 身份认证与授权（Authentication & Authorization）
• [x] 自动生成的 API
  • [x] REST API
  • [x] GraphQL API
  • [x] 实时订阅（Realtime subscriptions）
• [x] 函数（Functions）
  • [x] 数据库函数（Database Functions）
  • [x] 边缘函数（Edge Functions）
• [x] 文件存储（File Storage）
• [x] AI + 向量/Embeddings 工具包（AI + Vector/Embeddings Toolkit）
• [x] 可视化控制台 Dashboard

这些能力并非停留在纸面上，在仓库中都能找到对应的落地实现：可视化控制台对应 apps/studio；数据库函数、边缘函数、向量检索分别有对应的 examples/edge-functions 示例集与 supabase/functions 中的边缘函数实现（如 og-images、search-embeddings）；AI 与向量相关的端到端示例集中在 examples/ai，涵盖图片生成检索、图像搜索、向量去重等场景；用于支撑数据库变更追踪的 SQL 迁移则完整保留在 supabase/migrations 中。

架构如何运转：开源组件的组合艺术

理解 Supabase 的关键，是看懂它如何用一组开源子系统拼装出「Firebase 式」体验。仓库 Docker 编排文件 docker/docker-compose.yml 中列出的服务，几乎就是官方架构描述的镜像实现。下表将官方 README 描述的架构组件与仓库内实际的容器服务一一对应：

官方架构组件	在 docker-compose 中的服务	仓库实际镜像	职责
PostgreSQL	db	supabase/postgres	数据底座，承载用户数据与元数据
Realtime	realtime	supabase/realtime	监听数据库变更并通过 WebSocket 广播
PostgREST	rest	postgrest/postgrest	把 Postgres 直接变成 RESTful API
GoTrue	auth	supabase/gotrue	用户注册、登录与会话管理
Storage	storage	supabase/storage-api	文件对象存储的 RESTful 接口
pg_graphql	随数据库提供	Postgres 扩展	暴露 GraphQL API
postgres-meta	meta	supabase/postgres-meta	管理 Postgres 的 RESTful API
API 网关	api-gw	Envoy / Kong	统一入口、鉴权与路由
（控制台）	studio	supabase/studio	Dashboard 前端
Edge Functions	functions	supabase/edge-runtime	运行边缘函数
连接池	pooler / supavisor	supabase/supavisor	Postgres 连接池

各子系统的职责拆解

PostgreSQL（数据核心）：面向对象的关系型数据库，官方介绍中特别强调了其超过三十年持续开发积累下的可靠性、功能健壮性与性能口碑。在仓库的编排中，数据库镜像使用 supabase/postgres（当前仓库编排文件锁定在 PostgreSQL 17 系列），所有上层服务都围绕它展开。

Realtime（实时能力）：由 Elixir 编写的服务，让客户端可以通过 WebSocket 监听 Postgres 中发生的插入、更新与删除操作。其工作原理是轮询 Postgres 内建的逻辑复制（replication）功能获取数据库变更，把变更序列化为 JSON，再通过 WebSocket 推送给经过授权的订阅客户端——也就是说，实时消息的「事实来源」仍然是 Postgres 自身。

PostgREST（REST API）：一个 Web 服务器，将你的 PostgreSQL 数据库直接转换为 RESTful API，表结构即接口资源，配合行级安全（RLS）即可完成细粒度授权。

GoTrue（认证）：负责用户注册、登录与会话管理的认证 API，是 Supabase Auth 的底层实现（镜像名 supabase/gotrue 佐证了这一点），通常签发 JWT 供上层 API 鉴权使用。

pg_graphql（GraphQL）：Postgres 扩展，安装后即可对数据库暴露 GraphQL 端点，让客户端按需声明式地查询数据。

Storage（文件存储）：提供管理 S3 中文件的 RESTful 接口，同时利用 Postgres 来管理文件访问权限——权限判断逻辑留在数据库层，而非散落在应用代码中。

postgres-meta（元数据管理）：面向 Postgres 管理的 RESTful API，支持拉取表结构、添加角色、执行查询等运维操作，是 Dashboard 里数据库管理页面的后端支撑。仓库中的 packages/pg-meta 即为该领域的 TypeScript 类型与工具包，用于与这套元数据 API 交互。

API 网关：负责把上面多个服务统一暴露到单一入口，并完成密钥校验与路由转发。值得注意的版本差异是：巴西葡萄牙语版 README（i18n/README.pt-br.md）仍写作 Kong，而当前仓库默认编排已改为以 Envoy 作为默认网关（服务名为 api-gw，别名同时暴露 envoy 与 kong 以便兼容内部配置）；Kong 方案仍完整保留在 docker/docker-compose.kong.yml 与 docker/volumes/api/kong.yml 中，可自行切换。这种细节正说明：架构介绍文档可能与最新编排存在小幅滞后，阅读时以仓库现状为准。

下图（apps/docs/public/img/supabase-architecture.svg）直观展示了这套「Postgres + 各开源组件」的系统架构关系，可结合上文的服务对照表阅读：

数据流的本质：始终围绕 Postgres

把上表连起来看，就能抓住 Supabase 架构的底层逻辑：数据库仍是唯一的系统事实来源。无论是 REST/GraphQL API（由 PostgREST / pg_graphql 即时映射表结构）、实时订阅（Realtime 轮询逻辑复制流），还是文件权限判定（Storage 查询 Postgres 授权），全部都以数据库为中心展开。应用层并不各自维护状态，而是由网关将请求路由到对应子系统，子系统再统一落到同一个 Postgres 实例上。这正是它能以「组合开源组件」方式逼近 Firebase 体验的核心原因。

模块化的客户端库生态

官方 README 特别说明了客户端库的模块化设计原则："Nossa abordagem para bibliotecas de clientes é modular. Cada sub-biblioteca é uma implementação autônoma para um único sistema externo."（我们对客户端库采取模块化方式，每个子库都是针对单一外部系统的独立实现）。因此每个语言生态都由「一个汇总主客户端 + 若干功能子客户端」组成：PostgREST、GoTrue、Realtime、Storage 各对应一个子库，主客户端则将它们打包在一起使用。

官方维护（⚡️ Oficial）

语言	主客户端	PostgREST	GoTrue	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

社区维护（💚 comunidade）

语言	主客户端	PostgREST	GoTrue	Realtime	Storage	Functions
C#	supabase-csharp	postgrest-csharp	gotrue-csharp	realtime-csharp	storage-csharp	functions-csharp
Go	—	postgrest-go	gotrue-go	—	storage-go	functions-go
Java	—	—	gotrue-java	—	storage-java	—
Kotlin	supabase-kt	postgrest-kt	gotrue-kt	realtime-kt	storage-kt	functions-kt
Python	supabase-py	postgrest-py	gotrue-py	realtime-py	storage-py	functions-py
Ruby	supabase-rb	postgrest-rb	—	—	—	—
Rust	—	postgrest-rs	—	—	—	—
Swift	supabase-swift	postgrest-swift	auth-swift	realtime-swift	storage-swift	functions-swift
Godot Engine (GDScript)	supabase-gdscript	postgrest-gdscript	gotrue-gdscript	realtime-gdscript	storage-gdscript	functions-gdscript

从这张表可以读出两条工程信息：其一，不同语言对功能的支持完整度并不相同——例如 Go、Rust 生态主要聚焦 REST/Storage，而 JS/TS 与 Flutter 是唯一获得全套「官方」功能客户端覆盖的语言；其二，官方与社区库的分工边界清晰，社区库大多围绕 PostgREST 与 GoTrue 这两个核心子系统展开，恰好印证了「模块化子库是独立实现、可独立演进」的仓库设计哲学。仓库中同样遵循模块化思想的实例还包括 packages/ui、packages/ui-patterns 与 packages/common 等共享包，它们通过 pnpm-workspace.yaml 组织在同一 workspace 内供各应用复用。

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

官方 README 明确指出 Supabase 是一套托管平台："Você pode se registrar e começar a usar o Supabase sem instalar nada."（注册后无需安装任何东西即可开始使用）；同时也支持两种开放使用方式——自托管（self-host） 与本地开发（local development）。

使用 Docker Compose 自托管

当前仓库在 docker 目录提供了完整、可运行的自托管编排。核心用法记录在 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

整套栈默认包含上节对照表中列出的服务：studio（控制台）、api-gw（网关，同时兼容 envoy/kong 别名）、auth、rest、realtime、storage、imgproxy（图片处理）、meta、functions（Edge Functions）、db 与 supavisor（连接池）。配套脚本还包括 setup.sh、update.sh、run.sh 等；若需在自托管场景启用不同的 API 网关方案，可直接选用同目录下的 docker-compose.kong.yml、docker-compose.envoy.yml、docker-compose.nginx.yml 或 docker-compose.caddy.yml 等变体。

在仓库内开发与贡献

本仓库同时是一个由多个应用组成的 monorepo，自托管与文档站点本身就在此迭代：Docker 编排对应的 Dashboard 是 apps/studio；官方产品文档站是 apps/docs（内含 apps/docs/content 文档内容、apps/docs/spec 接口规范）；此外还有 apps/www（官网）、apps/learn、apps/design-system 等。作为贡献者的上手路径详见根目录 DEVELOPERS.md（原文档对应链接即「Getting Started」入口），仓库构建与协作约定可进一步参考 CONTRIBUTING.md 与根目录 Makefile。

给项目加一个「Made with Supabase」徽章

README 提供了一组可直接复制的徽章资源，用于在项目 README 中标识「使用 Supabase 构建」。徽章静态资源即仓库内的 apps/www/public/badge-made-with-supabase.svg（浅色）与 apps/www/public/badge-made-with-supabase-dark.svg（深色，适配深色主题）。

Markdown 引用方式（深色版同理，仅替换文件名）：

[![Made with Supabase](https://raw.gitcode.com/GitHub_Trending/supa/supabase/raw/e0280cb650d29ded05c080e35a52d22bf9dd84b9/apps/www/public/badge-made-with-supabase.svg?utm_source=gitcode_repo_files)](https://gitcode.com/GitHub_Trending/supa/supabase?utm_source=gitcode_repo_files)

HTML 引用方式（可通过 width/height 控制显示尺寸）：

<a href="https://supabase.com">
  <img
    width="168"
    height="30"
    src="apps/www/public/badge-made-with-supabase.svg"
    alt="Made with Supabase"
  />
</a>

多语言维护与社区生态

本仓库对 README 做了广泛的多语言维护，巴西葡萄牙语版只是其中之一。各语言版本统一存放在 i18n 目录下，完整清单见 i18n/languages.md；除英语原版外还覆盖了简体中文 i18n/README.zh-cn.md、繁体中文 i18n/README.zh-tw.md、日语 i18n/README.jp.md、西班牙语 i18n/README.es.md、法语 i18n/README.fr.md 等数十个语种。官方 README 中也提示：若要翻译为其他语言，建议移除易过期的外部镜像/外链清单，只保留指向翻译列表的链接，以降低多文件同步维护成本。

与社区保持同步的方式还包括：关注仓库并订阅 Watch → releases 通知以获取重要更新；完整产品文档可访问官方文档站；代码层面可阅读本仓库源码中对应能力的具体实现，例如 apps/studio/components 中的控制台组件、examples/user-management 中各框架（Next.js、React、Flutter、Vue、Svelte、Swift 等）的完整用户管理示例，以及 supabase/migrations 中为文档检索、错误码、向量搜索等能力演进所沉淀的数据库迁移记录。想要快速动手体验整套本地开发环境，仓库根目录提供了 pnpm 多包工作区与脚本化构建流程，具体命令可在各应用各自的 package.json 及 workspace 配置中查阅。

<无法成文>此处为占位符，请忽略。</无法成文>