Supabase 架构深度解析：以 Postgres 为核心的开源 Firebase 替代方案

【免费下载链接】supabase The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications. 【免费下载链接】supabase 项目地址: https://gitcode.com/GitHub_Trending/supa/supabase

本文以仓库国际化文档 i18n/README.pt-PT.md（根 README 的葡萄牙语版本）为主线，系统拆解 Supabase 的能力清单、开源组件架构、客户端库生态与自托管运行方式，并把这些声明逐一映射到仓库内可验证的源码与配置。读完你不仅能理解 "Postgres 为内核、组合成熟开源组件" 的平台构建哲学，还能掌握各功能模块在本仓库中的实际落点与部署入口。

文档定位与阅读坐标

i18n/README.pt-PT.md 是仓库根目录 README.md 的葡萄牙语（葡萄牙，区别于巴西葡萄牙语）翻译副本，与其他四十余个语种版本一起存放于 i18n/ 目录。它与根 README 描述的是同一个项目——Supabase，一个以 PostgreSQL 为内核的开源后端开发平台。

阅读该国际化文档时需要注意两点：

  1. 它以整个项目为叙述对象，给出的特性列表、架构组件与客户端库生态描述，均可与本仓库的源码、自托管 Compose 配置相互印证。
  2. 翻译副本在内容上滞后于当前代码演进（例如：文档把 API 网关表述为 Kong、把 GoTrue 的令牌表述为 SWT，而当前仓库的 docker/docker-compose.yml 已默认采用 Envoy 网关、认证按 JWT 会话实现）。因此撰写与阅读时，凡涉及版本、配置与运行环境，均以当前仓库实际内容为准。

项目定位：把 Firebase 的功能建在 Postgres 之上

文档开门见山：Supabase 是 Firebase 的开源替代方案，采用"企业级开源工具"来复刻 Firebase 的能力。它不是 Firebase 的 1:1 映射，目标只是让开发者获得类似 Firebase 的开发体验，但底层由开源工具组合而成。

其方法论可以概括为两条：

  • 如果某个能力已有成熟的开源实现（MIT、Apache 2.0 或同等宽松许可证），就采用并支持该工具；
  • 如果没有合适的工具，就自行构建并开源。

这一哲学直接决定了仓库的组织形态：真正"自研并开源"的部分（Dashboard 控制台、文档站、官网、共享包等）沉淀在 monorepo 内，而 PostgREST、Postgres、Realtime 等服务则以镜像或外部仓库的形式被编排进来。开发者可以免费获得托管平台体验，也可以把整条技术栈拉到自己的基础设施上运行。

能力清单：文档宣称的功能在仓库中的落点

文档用带勾选项的形式列出的能力，都能在本仓库中找到对应物，映射关系如下：

文档能力（葡萄牙语原文要点）对应实现事实仓库内可验证位置
Postgres 托管数据库自托管栈以 supabase/postgres 镜像承载数据库，并附带 roles.sql、jwt.sql、realtime.sql、pooler.sql 等初始化脚本docker/docker-compose.yml、docker/volumes/db
认证与授权auth 服务基于 supabase/gotrue 镜像实现用户、会话与令牌管理docker/docker-compose.yml
自动生成的 API：RESTrest 服务由 PostgREST 把 Postgres 直接暴露为 RESTful APIdocker/docker-compose.yml
自动生成的 API：GraphQL通过 pg_graphql 这一 Postgres 扩展暴露 GraphQL 接口见根 README.md 架构清单
自动生成的 API：实时订阅realtime 服务（Elixir 实现）把数据库变更广播为 websocket 消息docker/docker-compose.yml
数据库函数由 Postgres 本身承载，仓库内亦存在大量迁移 SQL 佐证（如 supabase/migrations）supabase/migrations
Edge Functions（边缘函数）functions 服务基于 supabase/edge-runtime（Deno 运行时）执行 JS/TS/WASMdocker/docker-compose.yml、docker/volumes/functions
文件存储storage 服务（supabase/storage-api）以 REST 接口管理文件，权限由 Postgres 判定docker/docker-compose.yml
Dashboard 控制台管理面板即本仓库 apps/studio 所对应的前端应用apps/studio

从这份映射可以看出：文档中"勾选完成"的每一项都并非空谈，它们在自托管编排文件里都有具体的镜像服务与之对应，这正是仓库"组合开源工具"方法论的可执行体现。

需要补充说明的是，国际版文档（README.md）还额外把 AI + Vector/Embeddings 工具箱列入能力清单，而葡萄牙语版本尚未包含此项——这同样是翻译版本滞后于主线文档的又一佐证。

"如何工作"：组件化架构逐一拆解

文档用一张架构示意图 + 组件清单说明平台的组合方式，架构图在仓库中的对应文件是 apps/docs/public/img/supabase-architecture.svg：

Supabase 开源组件架构示意图

图中每个组件都承担明确职责，文档的描述与当前仓库的编排配置可以相互印证：

组件文档描述仓库中的编排证据与补充说明
PostgreSQL对象-关系型数据库，30 余年持续演进，以可靠性与性能著称自托管 db 服务使用 supabase/postgres 镜像；初始化脚本见 docker/volumes/db
Realtime基于 Elixir 的服务器：轮询 Postgres 内建的复制机制感知变更，转成 JSON 后经 websocket 推送给已授权客户端realtime 服务使用 supabase/realtime 镜像；其数据库初始化脚本为 docker/volumes/db/realtime.sql
PostgREST把 Postgres 数据库直接变为 RESTful API 的 Web 服务器rest 服务使用 postgrest/postgrest 镜像，环境变量中可配置 PGRST_DB_SCHEMAS、PGRST_DB_MAX_ROWS 等行为
pg_graphql暴露 GraphQL API 的 Postgres 扩展根 README 架构清单中列出的官方组件
Storage面向 S3 中文件的 RESTful 管理接口，权限由 Postgres 处理storage 服务使用 supabase/storage-api 镜像；另有 imgproxy 处理图片缩放与安全转换
postgres-meta管理 Postgres 的 RESTful API：可取表、加角色、执行查询meta 服务使用 supabase/postgres-meta 镜像；仓库内亦有其 TypeScript 参考实现 packages/pg-meta
GoTrue（认证）文档称其为管理用户、签发令牌的 API（原文为 SWT，属早期措辞；当前按 JWT 会话管理实现）auth 服务使用 supabase/gotrue 镜像，环境变量覆盖 GOTRUE_DB_DATABASE_URL、GOTRUE_SITE_URL、GOTRUE_DISABLE_SIGNUP 等配置
API 网关文档（旧译版）点名 Kong 为云原生 API 网关当前编排默认启用 Envoy（见 docker/docker-compose.yml 注释），同时保留 Kong 作为可选覆盖：docker-compose.kong.yml 与 docker/volumes/api/kong.yml、docker/volumes/api/kong-entrypoint.sh

从源码结构看，当前自托管栈的编排其实已经超出葡萄牙语文档列出的组件范围：除上述核心外，还包括连接池器 Supavisor（supabase/supavisor）、日志分析 Logflare、可观测性管道 Vector、边缘运行时 Edge Runtime，以及本仓库对应的 Studio 控制台镜像。这说明文档代表的是平台的"主干心智模型"，而编排文件才是当前完整边界的最终事实。

三种运行形态：托管、自托管与本地开发

文档明确指出平台的三种使用方式，全部有据可查：

  1. 托管平台：在 Dashboard 注册后无需安装任何东西即可使用（对应 apps/studio 所代表的云端控制台体验）；
  2. 自托管：官方 Docker Compose 方案即本仓库 docker 目录，完整服务栈见 docker/docker-compose.yml，使用说明见 docker/README.md；
  3. 本地开发：可在自己机器上把同一套栈跑起来做功能验证。

自托管的基本操作（来自 docker/docker-compose.yml 头部注释与 docker/README.md）：

# 启动全部服务
docker compose up -d

# 停止全部服务
docker compose down

# 开发模式（叠加 dev 专用配置）
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
sh run.sh pull && sh run.sh recreate

# 叠加 Kong 网关（默认网关为 Envoy）
sh run.sh config add kong

两个与运维强相关的注意点：

  • 编排文件中使用嵌套变量插值 ${A:-${B}}，对 podman-compose 有版本要求（需不低于 1.6.0），使用前请核对本机工具版本；
  • docker/README.md 明确警告：默认配置不安全，不可直接用于生产。上线前必须替换 .env 中的默认密码与密钥、复核 CORS、在前方架设安全代理，并建立备份机制；完整环境变量参考见 docker/CONFIG.md。

客户端库生态：模块化组合的设计

文档强调客户端库采用"模块化"策略：每个子库是面向单一外部系统的独立实现，再被打包进统一的 Supabase 客户端，这是其支持既有工具生态的重要方式。下表是文档原样列出的语言矩阵（官方 vs 社区）：

语言客户端PostgRESTGoTrueRealtimeStorageFunctions
官方
JavaScript (TypeScript)supabase-jspostgrest-jsauth-jsrealtime-jsstorage-jsfunctions-js
Fluttersupabase-flutterpostgrest-dartgotrue-dartrealtime-dartstorage-dartfunctions-dart
社区
C#supabase-csharppostgrest-csharpgotrue-csharprealtime-csharpstorage-csharpfunctions-csharp
Go—postgrest-gogotrue-go—storage-gofunctions-go
Java——gotrue-java—storage-java—
Kotlinsupabase-ktpostgrest-ktgotrue-ktrealtime-ktstorage-ktfunctions-kt
Pythonsupabase-pypostgrest-pygotrue-pyrealtime-pystorage-pyfunctions-py
Rubysupabase-rbpostgrest-rb————
Rust—postgrest-rs————
Swiftsupabase-swiftpostgrest-swiftgotrue-swiftrealtime-swiftstorage-swiftfunctions-swift
Godot Engine (GDScript)supabase-gdscriptpostgrest-gdscriptgotrue-gdscriptrealtime-gdscriptstorage-gdscriptfunctions-gdscript

需要说明的是：这些语言客户端大多以独立仓库形态维护（文档中标注为官方或社区仓库），并不都包含在当前 monorepo 内。本仓库自身聚焦于 Dashboard、文档、官网以及共享包（如 packages/shared-data、packages/ui-patterns、packages/marketing 等），并通过 pnpm-workspace.yaml 与根 package.json 统一管理，采用 Turborepo 组织（见 DEVELOPERS.md）。

项目状态：从 Alpha 到当前演进

葡萄牙语文档保留了早期 README 才有的"项目状态"清单，按顺序逐项勾选为：Alpha（封闭测试）→ 公开 Alpha（可在 Dashboard 注册，但仍有瑕疵）→ 公开 Beta（已足以支撑多数非企业场景），而"公开可用（GA）"一项当时未勾选；文档声称彼时正处于公开 Beta 阶段，并建议关注仓库 releases 以获知重大更新。

这属于翻译副本的历史快照信息。就当前仓库而言：自托管编排文件固定了相当具体的镜像版本（如 supabase/studio:2026.08.03-*、envoyproxy/envoy:v1.39.0），镜像版本历史与变更记录分别维护在 docker/versions.md 与 docker/CHANGELOG.md，可供回滚与排障参考；根 README.md 已不再保留该 Alpha/Beta 状态清单。因此，判断项目所处阶段请以官方发布信息为准，而不要依赖这份旧译文。

贡献与社区：进入仓库的入口

文档的"社区与支持"章节按用途划分了不同渠道：构建求助与最佳实践讨论、Bug 反馈、数据库/基础设施问题、应用分享与社区交流。对应到本仓库内部，实操层面的进入点是：

  • DEVELOPERS.md：开发者上手指南，列明前置依赖（Git、Node.js、pnpm、make、Docker），说明 Turborepo 组织方式、fork/clone、依赖安装、本地运行、提交 PR 与 issue 认领流程；
  • CONTRIBUTING.md 与根 AGENTS.md、CLAUDE.md：分别描述常规协作规范与面向 AI 编码代理的仓库指引；
  • docker/README.md：自托管相关的问题排查与社区支持说明。

仓库还通过 i18n/ 目录维护 40 余种语言的 README 翻译（含简体中文 i18n/README.zh-cn.md、繁体中文、巴西葡萄牙语等），完整翻译清单见 i18n/languages.md。翻译文件在结构上保持一致：保留特性与架构描述，仅更换语言，社区渠道链接则统一指向各自语言的讨论入口。

小结

透过葡萄牙语 README 这份"翻译快照"，可以最清晰地看到 Supabase 的方法论骨架：一切以 Postgres 为内核，用成熟开源组件拼出 Firebase 级别的开发者体验，缺什么就自研什么并开源。当你需要从概念走向实操时，本仓库的 docker/docker-compose.yml 与 docker/CONFIG.md 是理解运行时拓扑的第一手资料，apps/studio 是理解控制台交互的起点，而根 README.md 与 DEVELOPERS.md 则分别给出最新的能力清单与开发入口。

【免费下载链接】supabase The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications. 【免费下载链接】supabase 项目地址: https://gitcode.com/GitHub_Trending/supa/supabase

Logo
乐奇 Rokid 开放社区

更多推荐

cover

TestStar | AIUI 数据库客户端测试Case执行实录

avatar 乐奇 Rokid 开放社区
cover

AR巡检哪家好

avatar 乐奇 Rokid 开放社区
cover

具身智能 | Ego数采设备与选择标准一文理清，避开无效采集

avatar 乐奇 Rokid 开放社区