Supabase 是什么：基于 PostgreSQL 的开源 Firebase 替代方案与核心架构全解析

本文以 i18n/README.nb-no.md（仓库官方的挪威语 Bokmål 版主 README）为主线，结合当前仓库中真实的源码与部署配置，系统讲解 Supabase 的定位、功能矩阵、分层架构、自托管部署方式与模块化客户端库设计。读完本文，你将理解 Supabase「用企业级开源组件拼出 Firebase 体验」的核心思想，知道托管平台上每一个数据请求会经过哪些服务，并掌握如何在本地用 Docker 完整拉起这套栈。

Supabase 的定位：Postgres 上的 Firebase 替代品

挪威语版 README 开篇即给出项目定义：Supabase er et open source-alternativ til Firebase——Supabase 是一个开源 Firebase 替代方案，但实现手段并非重写一套云服务，而是用企业级（enterprise-klare）开源工具拼装出 Firebase 的功能。这与当前仓库根目录 README.md 中 "The Postgres development platform" 的表述一脉相承：Postgres 是整条技术链路的锚点，其余一切（API、实时订阅、认证、存储、函数）都围绕这一数据库展开。

同时文档强调一个容易被误读的点：Supabase 不是 Firebase 的 1:1 映射（Supabase er ikke en 1-til-1-mapping av Firebase）。它的取舍原则被原样写进文档，今天仍是项目的开源策略基石：

1. 若某个能力已存在成熟的社区工具，且采用 MIT、Apache 2 或同等开放许可，则直接采用并支持它；
2. 若这样的工具不存在，就自行构建并开放源代码。

这一原则决定了仓库的结构——它不是一个单一代码库，而是一个承载多应用、多包的 monorepo（由 pnpm-workspace.yaml 与 turbo.jsonc 管理），apps 与 packages 目录中每一层都能回溯到对应的开源上游。

核心功能矩阵：文档列的七项能力在仓库中的落点

README.nb-no.md 用一张清单概括了项目当前构建的全部核心能力，表中每一项都能在当前仓库找到对应实现（apps/studio、apps/docs 均为本仓库子应用）：

文档所述能力（挪威语）	中文释义	仓库中的对应落点
Hostet Postgres-database	托管 Postgres 数据库	docker/docker-compose.yml 中的 db 服务（supabase/postgres），迁移脚本见 supabase/migrations
Sanntidsabonnementer	实时订阅	Realtime 服务（Elixir，WebSocket 推送数据库变更）
Autentisering og autorisasjon	认证与授权	Auth 服务（GoTrue，签发与管理 JWT）
Autogenererte APIer	自动生成的 API	PostgREST（REST）+ pg_graphql（GraphQL）
Dashboard	管理控制台	apps/studio（源码即仪表盘本体）
Lagring	文件存储	Storage 服务（S3 兼容 + 图片处理 imgproxy）
Funksjoner	函数	Edge Functions（基于 docker 中 edge-runtime 容器）

对照更新版本的英文主 README（README.md），能力清单已进一步细分：自动生成的 API 拆为 REST、GraphQL 与 Realtime subscriptions；函数拆为 Database Functions 与 Edge Functions；并新增了 AI + Vector/Embeddings 工具集——本仓库 supabase/migrations 中大量 embedding、vector、search 命名的迁移文件（如 20250430202653_return_meta_vector_search.sql、20250714120000_hybrid_search.sql）正是这一方向的实现证据。理解时可把挪威语版清单视为同一项目的早期表述，两者描述的是同一平台的不同演进阶段。

工作原理与架构：一次请求穿越的服务链路

从「自建一切」到「组合一切」

README.nb-no.md 的 Slik fungerer det（工作原理）章节点明了平台本质：Supabase 是一个托管平台（hosted plattform），开发者注册后即可使用，无需自行安装任何东西。而整个架构的精神是"组合而非发明"——选用围绕 Postgres 的最佳开源组件，由 API 网关统一对外暴露。

原文档绘制过一张经典架构示意图，反映当时的服务编排关系；仓库 apps/www/public/images/blog/supabase-architecture.png 中保留的同主题架构图清晰地展示了各层协作方式：

说明：图中网关标注为 Kong。从当前仓库的 docker/docker-compose.yml 看，默认网关已演进为 Envoy（并保留 kong 网络别名以兼容内部引用），Kong 仍可通过 override 启用，详见下文"自托管"章节——架构层级关系未变，变的只是网关实现。

逐个拆解核心组件

结合 README.nb-no.md 的组件清单，以及当前仓库 docker/docker-compose.yml 中各服务容器的真实配置，可以还原出完整调用链：

• PostgreSQL（db 服务，supabase/postgres:17.x）——拥有 30 余年持续演进历史的开源对象关系型数据库，是平台的可靠性底座。除业务数据外，认证用户、存储元数据、实时订阅的 _realtime schema 等都落在其中。仓库 docker/volumes/db 下的多个 SQL（roles.sql、jwt.sql、realtime.sql 等）会在容器首次启动时完成角色、密钥与扩展的初始化。
• Realtime（Elixir 服务）——文档精确描述了其机制：Supabase 监听 Postgres 内置的复制（replication）功能，把复制字节流转换成 JSON，再通过 WebSocket 推送给已授权的客户端。也就是说开发者订阅的"实时"本质上是数据库级变更的广播。
• PostgREST（rest 服务）——一个 Web 服务器，把 PostgreSQL 数据库直接变成 RESTful API，自动依据表结构暴露 CRUD 端点。容器配置中的 PGRST_DB_ANON_ROLE: anon、PGRST_JWT_SECRET 等环境变量即对应 README 中"autogenererte APIer"的认证与行级安全接缝。
• Auth / GoTrue（auth 服务）——负责用户注册、登录与会话管理的认证 API。需要特别指出：README.nb-no.md 将其描述为 SWT-basert（签发 SWT token），这属于早期版本表述；当前英文主 README 与仓库实际配置均表明其已演进为 JWT 体系——docker-compose.yml 中 GOTRUE_JWT_SECRET、GOTRUE_JWT_AUD、GOTRUE_JWT_ISSUER 等即为证。
• Storage + imgproxy（storage、imgproxy 服务）——文件存储的 RESTful 接口：文件可落盘或放入 S3 后端，权限判断仍在 Postgres 中完成；imgproxy 则负责图片的动态处理与缩放（容器中可见 ENABLE_IMAGE_TRANSFORMATION 开关）。
• postgres-meta（meta 服务）——管理数据库本身用的 RESTful API：拉取表结构、增删角色、执行查询等均由它承接。Studio 控制台通过 STUDIO_PG_META_URL 指向它，实现"浏览器里管理数据库"。
• API 网关（api-gw 服务）——统一流量入口，按路径把请求分发到上述各服务。README.nb-no.md 记载的是 Kong；当前默认实现为 Envoy，见下节。

此外，当前编排还包含 functions（Edge Functions，基于 edge-runtime 运行 Deno）与 supavisor（Postgres 连接池），它们让平台从"后端即服务"扩展到"边缘函数 + 高并发连接"场景。

从托管到自托管：用仓库里的 Docker 栈拉起完整平台

文档所述"托管平台"对应的是云端服务；若要在本地或自有基础设施复现同样的架构，仓库的 docker/README.md 与 docker/docker-compose.yml 提供了官方 Docker Compose 自托管方案，其中几乎涵盖托管版的全部服务：Studio、API 网关、Auth、PostgREST、Realtime、Storage、imgproxy、postgres-meta、PostgreSQL、Edge Runtime、Logflare、Vector 与 Supavisor。

关于网关，docker/README.md 与 docker/docker-compose.kong.yml 说明：默认网关是 Envoy（对应 compose 中 api-gw 服务），若需切回文档所述的 Kong，可用 sh run.sh config add kong 后重启，Kong 会以 override 方式原地替换 api-gw 并额外提供 8443 HTTPS 监听。

基础启停命令（源自 docker-compose.yml 头部注释与 docker/README.md）：

# 启动
docker compose up -d

# 停止
docker compose down

# 开发模式（叠加 dev override）
docker compose -f docker-compose.yml -f ./dev/docker-compose.dev.yml up -d

# 重置全部数据
sh reset.sh

# 更新到最新镜像（建议先备份数据库）
sh update.sh --dry-run   # 可选：预览将执行的变更
sh update.sh

安全提醒：docker/README.md 明确警告默认配置不适用于生产——部署前必须更新 .env（根目录未见该文件，需按官方安装指引自行生成）中的全部默认密码与密钥、复查 CORS 与反向代理设置、建立备份流程。组件间复杂的密钥注入关系（如 JWT_SECRET/JWT_JWKS、ANON_KEY、SERVICE_ROLE_KEY 在多个服务间的流转）可参见各服务的 environment 段落与 docker/CONFIG.md。

模块化客户端库：一个主包聚合多个子客户端

README.nb-no.md 的 Klient-biblioteker（客户端库）章节揭示了官方 SDK 的组织哲学：模块化。每个子库是对单一外部系统的独立实现，这既便于复用社区既有工具，也让开发者按需组合。文档给出的结构为：

• supabase-{lang}：组合各子库并加入增强能力的统一入口；
  • postgrest-{lang}：PostgREST（数据 REST API）客户端；
  • realtime-{lang}：Realtime（实时订阅）客户端；
  • gotrue-{lang}：GoTrue（认证）客户端。

主 README README.md 中维护着更完整的语言覆盖表，可作横向参考：**官方（Official）**支持 JavaScript/TypeScript（supabase-js，将 postgrest-js、auth-js、realtime-js、storage-js、functions-js 打包在一起）、Flutter、Swift 与 Python；**社区（Community）**则覆盖 C#、Go、Kotlin、Ruby、Rust、Godot Engine（GDScript）等，且同样遵循"每个子模块独立实现"的模式。

实际开发中，一条典型链路是：通过 supabase-js 创建客户端 → 调用 .auth（gotrue-js）拿 token → 用 .from('table')（postgrest-js）发起 REST 请求 → 用 .channel()（realtime-js）订阅变更广播。token 校验最终落在各服务侧的 JWT 解析上，与上文自托管配置中的密钥环境变量一一对应。

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

README.nb-no.md 保留了项目早期的发布状态追踪（Alpha → Offentlig Alpha → Offentlig Beta → Produksjonsklar/生产就绪），并注明当时处于公开 Beta，可通过关注仓库 releases 获取大版本通知。需要注意这是该翻译版冻结时点的快照；当前仓库中 apps/studio、apps/docs、apps/www 等已构成完整产品矩阵，版本阶段应以官方最新发布为准。

在社区与支持渠道上，文档区分了三类诉求：开发帮助与最佳实践讨论走 Community-forum；使用中遇到的 bug 与错误提 GitHub Issues；数据库或基础设施问题走官方邮件支持。

多语言是该仓库的特色之一：根 README 的翻译列表与 i18n/languages.md 记录了全部翻译文件，其中即包含本文依据的 i18n/README.nb-no.md，以及简体中文 i18n/README.zh-cn.md、繁体中文 i18n/README.zh-tw.md 等五十余个语种版本，便于非英语开发者以母语理解项目全貌。

小结

以 i18n/README.nb-no.md 为纲可以看出，Supabase 的工程哲学始终如一：Postgres 为核心，成熟开源组件为零件，缺失能力就自建并开源。托管平台负责把复杂度收敛在网关之后，自托管场景则可通过仓库 docker 目录将整条服务链原样复现。理解它的架构——客户端 → API 网关 →（PostgREST / GoTrue / Realtime / Storage / postgres-meta / edge-runtime）→ PostgreSQL——是上手云端 API、实时订阅、行级安全乃至二次开发的基础；而模块化客户端库又保证了这套后端能力能以最贴合各语言生态的方式被消费。