深入解读 Supabase：以 PostgreSQL 为核心的开源 Firebase 替代方案的架构与技术实现

Supabase 定位为"Postgres 开发平台"，以开源组件拼装出数据库托管、身份认证、自动生成 API、文件存储、函数计算与可视化后台等一系列对标 Firebase 的后端能力。本文基于仓库中 i18n/README.ro.md（该项目主 README 的罗马尼亚语翻译）展开，结合本仓库自托管编排文件与目录结构，逐层拆解其功能全景、组件化技术架构、部署形态与模块化客户端库设计，帮助读者理解这套后端平台"由哪些开源构件组成、每个构件解决什么问题、如何协同工作"。

项目定位：用企业级开源工具重写 Firebase 的功能

文档开篇即给出明确的项目定义：Supabase 是一个开源 Firebase 替代方案，目标是使用企业级的开源工具，逐一实现 Firebase 的核心能力。

这里有一个容易被忽略的关键主张——Supabase 并不是 Firebase 的 1:1 映射。它遵循两条选型原则（见 i18n/README.ro.md 的 "Cum funcționează" 一节）：

• 如果某个领域已存在采用 MIT、Apache 2 或同等宽松许可证的优秀开源工具，就优先"选用并支持"该工具；
• 如果找不到合适的开源工具，就自己构建并同样以开源方式发布。

这种"尽量复用、缺什么造什么"的策略，直接决定了整个平台的形态：它不是一个单体应用，而是一组可以独立演进、独立部署、彼此通过标准 HTTP/WebSocket 协议协作的开源服务集合。这一点在当前仓库的根 README.md 与自托管编排文件 docker/docker-compose.yml 中都能得到印证。

功能全景：文档列出的核心能力清单

原文档以核对清单（checklist）的形式列出了平台已具备的核心能力。为保留原文信息并补充仓库依据，整理如下：

能力	说明	仓库内对应证据
托管 PostgreSQL 数据库	提供开箱即用的 Postgres 托管实例	自托管编排中 db 服务使用 supabase/postgres 镜像（见 docker/docker-compose.yml）
身份认证与授权（Auth）	用户注册、登录、会话与权限管理	编排中 auth 服务即 GoTrue（supabase/gotrue 镜像）
自动生成的 API	REST、GraphQL、Realtime 实时订阅三类 API	编排中 rest（PostgREST）与独立的 Realtime 服务
函数	数据库函数 + Edge Functions（边缘函数）	supabase/functions 存放 Deno 边缘函数源码，functions 服务使用 edge-runtime 镜像
文件存储（Storage）	基于 S3 的对象存储 + Postgres 权限控制	编排中 storage 与 imgproxy 两个服务
控制台（Dashboard）	可视化后台	仓库中 apps/studio 目录即是 Studio 应用源码

其中"自动生成 API"在文档中被细分为三部分：

• REST：由 PostgREST 直接把数据库表结构暴露为 RESTful 接口；
• GraphQL：由 pg_graphql 这一 PostgreSQL 扩展直接暴露 GraphQL API；
• Realtime 实时订阅：通过 WebSocket 向已授权的客户端推送数据库变更。

可以看到：文档中每一行"✓"背后，都能在当前仓库的自托管编排文件里找到对应的可运行服务，功能清单与实际代码/镜像是一一对应的。

组件化架构：每个开源构件承担一个职责

原文档的架构一节是全文技术含量最高的部分，它逐项介绍了组成 Supabase 的每个开源组件。下面按文档顺序逐个展开，并补充编排文件中的配置证据（参考 docker/docker-compose.yml 与 docker/docker-compose.kong.yml）。

PostgreSQL：一切能力的地基

文档指出，PostgreSQL 是一个经过 30 余年持续演进的对象-关系型数据库，其可靠性、功能健壮性与性能为其赢得了良好声誉。

在自托管环境中，这个角色由 docker/docker-compose.yml 中的 db 服务承担，使用 supabase/postgres 定制镜像，并且会在初始化阶段挂载多份 SQL 脚本（roles、jwt、realtime、logs、pooler 等扩展脚本均位于 docker/volumes/db/ 下）。换言之，围绕数据库的角色划分、JWT 密钥注入、实时通道扩展、日志表结构等，都是在镜像初始化 SQL 中预先编排好的。仓库 supabase/migrations 也保留了数十个长期演进的数据库迁移文件（从文档向量化搜索到混合检索 hybrid_search），直观展示了"数据库本身就是产品核心"这一事实。

Realtime：监听 Postgres 变更的 Elixir 服务

原文档对 Realtime 的描述非常具体：

Realtime 是一个 Elixir 服务器，允许你通过 WebSocket 监听 PostgreSQL 的插入、更新与删除。它轮询 Postgres 内建的复制（replication）能力来获取数据库变更，将变更转换为 JSON，再通过 WebSocket 广播给已授权的客户端。

这段描述点出了实时功能的两大技术关键：

1. 利用 Postgres 内建逻辑复制（WAL）机制监听变更，而不是在应用层写侵入式触发器；
2. 鉴权后广播，客户端必须持有有效凭证才能订阅。

在 docker/docker-compose.yml 的 realtime 服务中可以看到对应证据：容器名刻意命名为 realtime-dev.supabase-realtime（注释说明 Realtime 通过解析子域名构造 tenant id），环境变量 DB_AFTER_CONNECT_QUERY: 'SET search_path TO _realtime' 表明它使用独立的 _realtime schema，SEED_SELF_HOST: "true" 表示会在自托管模式下自动完成种子初始化，同时通过 API_JWT_SECRET/JWT_JWKS 完成令牌校验——与文档"向授权客户端广播"的表述一致。

PostgREST 与 pg_graphql：自动生成 REST 与 GraphQL API

• PostgREST：文档称之为"把 PostgreSQL 数据库直接转成 RESTful API 的 Web 服务器"。这消除了传统后端中最繁琐的 CRUD 样板代码：建好表结构后，API 就自动存在。
• pg_graphql：一个 PostgreSQL 扩展，直接向数据库暴露 GraphQL API，让 GraphQL 能力同样"内生"于数据库层。

编排文件中的 rest 服务（镜像 postgrest/postgrest）展示了 PostgREST 的实际配置方式：

PGRST_DB_URI: postgres://authenticator:...  # 连接专用 authenticator 角色
PGRST_DB_SCHEMAS: ${PGRST_DB_SCHEMAS}        # 暴露哪些 schema
PGRST_DB_MAX_ROWS: ${PGRST_DB_MAX_ROWS:-1000} # 单次查询行数上限
PGRST_DB_ANON_ROLE: anon                      # 匿名请求映射到 anon 角色
PGRST_JWT_SECRET: ${JWT_JWKS:-${JWT_SECRET}}  # 用于校验请求 JWT

这些环境变量揭示了其权限模型：请求经过网关鉴权后，PostgREST 会以 anon（匿名）或用户 JWT 中携带的角色连接数据库，实现"行级/列级安全策略（RLS）即 API 权限"的设计。仓库的 examples 目录中大量示例（如 nextjs、react、user-management 系列）都直接展示了这种"建表 + 设 RLS → 客户端查询"的开发模式。

Storage：Postgres 管权限、S3 管文件的存储服务

文档对存储组件的描述是："为管理 S3 中存储的文件提供 RESTful 接口，权限由 Postgres 管理。"

将"对象存取"与"权限判定"分离是一个精巧的架构决策：文件二进制本体存放在 S3（自托管默认使用本地文件后端，STORAGE_BACKEND: file），而谁能读、谁能写等授权逻辑下沉到 Postgres，借助数据库既有的 RLS 能力完成。在 docker/docker-compose.yml 的 storage 服务里可以看到：

POSTGREST_URL: http://rest:3000          # storage 自身通过 REST 访问权限判断
DATABASE_URL: postgres://supabase_storage_admin:...
FILE_SIZE_LIMIT: 52428800                # 默认单文件 50MB 上限
ENABLE_IMAGE_TRANSFORMATION: "true"      # 开启图片实时处理
IMGPROXY_URL: http://imgproxy:5001       # 图片处理由 imgproxy 承担

紧随其后的 imgproxy 服务（镜像 darthsim/imgproxy）负责图片裁剪/缩放/格式转换等能力，这解释了 Supabase Storage 控制台中图片 URL 变换参数的底层实现。

postgres-meta：管理 Postgres 的 RESTful API

postgres-meta 的职责在文档中被概括为："一个用于管理 Postgres 的 RESTful API，允许你获取表列表、添加角色、执行查询等。"

它是 Studio 控制台能够"在浏览器里操作数据库结构"的关键。编排中 meta 服务使用 supabase/postgres-meta 镜像、监听 8080 端口；而 studio 服务通过环境变量 STUDIO_PG_META_URL: http://meta:8080 指向它——两者在部署上的这种"调用"关系，恰好是文档描述的职责分工在运行层面的直接体现。仓库内的 packages/pg-meta 则包含大量对 Postgres 系统表与信息架构的查询实现与测试。

GoTrue：认证与用户管理

文档将其描述为"用于管理用户与签发令牌的认证 API"，负责处理应用中的用户注册、登录与会话管理（最新英文 README 将其准确描述为 JWT 基础的认证 API）。

在编排文件的 auth 服务中，配置全部以 GOTRUE_* 前缀环境变量注入，可以看到完整的认证系统能力边界：

GOTRUE_DB_DATABASE_URL: postgres://supabase_auth_admin:...  # 独立的 auth schema
GOTRUE_SITE_URL / GOTRUE_URI_ALLOW_LIST                     # 站点与重定向白名单
GOTRUE_JWT_SECRET / GOTRUE_JWT_EXP                          # 令牌签名与有效期
GOTRUE_EXTERNAL_EMAIL_ENABLED / GOTRUE_MAILER_AUTOCONFIRM   # 邮箱注册开关
GOTRUE_EXTERNAL_PHONE_ENABLED                                # 手机号注册开关
GOTRUE_SMTP_*                                                # 邮件投递配置
GOTRUE_SAML_ENABLED                                          # 企业 SSO（SAML）
GOTRUE_MFA_*                                                 # 多因素认证参数

（这些配置位于 docker/docker-compose.yml 的 auth 服务段。）其中 postgres://supabase_auth_admin:... 说明用户数据存储于数据库的专用 auth 相关 schema，并依靠 JWT_SECRET 与其他服务共享同一套令牌体系。从"邮箱/手机号密码登录、OAuth 社交登录、匿名登录、SMS/OTP、MFA、SAML SSO 乃至 auth hooks"等完整注释分支可以看出，认证模块实际是一个独立且功能完整的子系统。

网关：从 Kong 到 Envoy 的演进

罗马尼亚语文档快照将 Kong 列为云原生 API 网关组件。值得注意的细节是：仓库根目录的最新英文 README.md 已将网关描述更新为 Envoy，而当前默认编排（docker/docker-compose.yml 中的 api-gw 服务）默认使用 envoyproxy/envoy 镜像，并通过容器网络别名同时保留 envoy 与 kong 两个主机名，以保证旧配置兼容。

但这并不代表 Kong 被弃用——仓库专门提供了 docker/docker-compose.kong.yml 作为可选的 Kong 覆盖方案（启用方式为 sh run.sh config add kong），使用 kong/kong:3.9.3 镜像并开启 8443 HTTPS 监听。配套的 Kong 声明式路由配置 有数百行，完整定义了网关如何把流量分发给后端服务，例如：

• /auth/v1/* 路由到 auth 服务（GoTrue），/auth/v1/verify、/auth/v1/callback 等开放接口仅挂 CORS 插件；
• 受保护的路由通过 key-auth、acl 插件校验请求携带的 anon / service_role API Key，并映射到不同的 ACL 分组；
• /rest/v1/* 一类路径被路由到 PostgREST，/storage/v1/* 路由到 Storage 服务。

这也从侧面印证了网关在整个架构中的位置：它是所有内部服务对外的统一入口，负责 API Key 鉴权、路由分发与跨域处理，而后端各服务本身不直接暴露在公网。

部署形态：托管平台、自托管与本地开发

原文档在架构部分同时澄清了 Supabase 的三种使用形态：

1. 托管平台（hosted）：直接注册即可开始使用，无需安装任何软件；
2. 自托管（self-host）：把整套组件部署到自己的基础设施上；
3. 本地开发（local development）：在开发者机器上运行完整环境。

本仓库对后两种形态给出了"第一手"的实现载体。自托管环境就是根目录 docker 目录下的 Docker Compose 编排全家桶，除默认的 docker-compose.yml 外，还提供 docker-compose.pg15.yml/pg17.yml（Postgres 版本切换）、s3.yml/rustfs.yml（存储后端切换）、logs.yml（日志与可观测性）、caddy/nginx/envoy/kong（反向代理或网关变体）等组合文件，辅以 docker/CONFIG.md 与 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

（以上命令摘自 docker/docker-compose.yml 顶部注释，实际需先在 docker/ 目录下执行，并按 docker/README.md 准备 .env 环境变量文件。）

整套编排由 11 个核心服务组成，下表按"功能域"归纳，读者可对照 docker/docker-compose.yml 逐一定位：

服务名	技术镜像	对应文档中的组件
studio	supabase/studio	Dashboard 控制台
api-gw	envoy（或可选 kong）	API 网关
auth	supabase/gotrue	GoTrue 认证服务
rest	postgrest/postgrest	PostgREST（REST API）
realtime	supabase/realtime	Realtime 实时服务
storage	supabase/storage-api	Storage 文件存储
imgproxy	darthsim/imgproxy	图片实时处理
meta	supabase/postgres-meta	postgres-meta 管理 API
functions	supabase/edge-runtime	Edge Functions 运行时
db	supabase/postgres	PostgreSQL 数据库
supavisor	supabase/supavisor	连接池（Pooler）

由此可见，原文档描述"平台由多个开源组件组合而成"，在仓库层面直接体现为可一键拉起的一组容器——每一行文档描述背后都有确切的镜像与配置可查。

模块化的客户端库设计：一个后端、一个库

文档还专门阐述了客户端库（client libraries）的模块化设计哲学：

每个子库都是针对单一外部系统的独立实现，这是 Supabase 支持既有工具生态的方式之一。

也就是说，客户端并非一个大而全的 SDK，而是"PostgREST 客户端、GoTrue 客户端、Realtime 客户端、Storage 客户端、Functions 客户端"各自独立实现，再由聚合库统一打包。各语言中只要某个后端组件已有成熟社区实现，就可以按需接入，不必等待官方重写。

原文档中给出的语言覆盖情况整理如下（官方 / 社区划分以原文表格为准）：

语言	官方聚合客户端	社区支持情况
JavaScript / TypeScript	官方（聚合后包含 REST / Auth / Realtime / Storage / Functions 子客户端）	—
Flutter / Dart	官方	—
C#	—	社区聚合 + PostgREST / GoTrue / Realtime / Storage / Functions 子库
Go	—	PostgREST / GoTrue / Storage / Functions（无聚合、无 Realtime）
Java	—	GoTrue / Storage
Kotlin	—	社区聚合 + 各功能子库
Python	—	社区聚合 + 各功能子库
Ruby	—	社区聚合 + PostgREST
Rust	—	PostgREST
Swift	—	社区聚合 + 各功能子库
Godot Engine (GDScript)	—	社区聚合

这种"主库 + 子库"的粒度设计带来的实际收益是：语言社区可以独立迭代自己负责的那一层。需要说明的是，这些客户端仓库大多独立维护、不在本仓库内；但本仓库的 examples 目录收录了大量配套示例（覆盖 user-management、realtime、storage、auth、edge-functions、ai 等主题），可作为各语言客户端实际用法的参考实现。

社区、支持渠道与多语言文档生态

原文档为读者规划了四条社区与支持路径，按其建议场景区分：

• 社区论坛：适合求助构建问题、讨论数据库最佳实践；
• GitHub Issues：适合反馈使用 Supabase 时遇到的 Bug 与错误；
• 邮件支持：适合数据库或基础设施类问题；
• Discord：适合分享应用、与社区交流。

与社区策略相呼应的是其国际化文档生态。原文档专门列出了 40 余种语言的 README 翻译清单，而本仓库的 i18n 目录就是这份生态的实物：其中 languages.md 维护语言清单，i18n/README.ro.md（本文依据）、i18n/README.zh-cn.md、i18n/README.ja.md 等则是各自语言的翻译版本，供不同语言背景的开发者以母语快速了解项目。文档还提示读者关注仓库 releases 以获取重大更新通知。

对希望进一步了解或参与项目的开发者，可参阅根目录的 DEVELOPERS.md（即原文档中 "Getting Started" 链接指向的文件，路径已从文档自身位置转换为仓库根路径）以及本仓库 apps/docs 下的完整产品文档源码。

版本阶段与阅读建议

原文档末尾以进度条形式公开了项目所处的发布阶段，这在开源项目的 README 中较为少见，属于对社区透明度的重要实践：

阶段	状态
Alpha（封闭客户集测试）	已完成
Public Alpha（任何人可注册，仍存在部分问题）	已完成
Public Beta（对多数非企业场景足够稳定）	已完成
Public / 正式可用（GA）	该文档快照中尚未勾选

该文档快照明确声明项目当时处于 Public Beta。需要提醒的是，这一表述属于该翻译文档对应的历史时点；当前仓库的编排文件（如 docker/docker-compose.yml 中镜像版本已迭代至 2026 年、数据库升级至 PostgreSQL 17 并支持 S3 后端）表明自托管生态仍在持续演进。若要核对最新状态与细节，应以仓库根目录 README.md、docker/README.md 与各模块源码为准。

小结：从一张 README 到一套可运行的平台

回顾 i18n/README.ro.md 这份文档，可以发现它虽然只是一份项目介绍，却精确地描绘了一幅"组件化开源后端平台"的蓝图：PostgreSQL 提供数据与权限基石，PostgREST 与 pg_graphql 把数据库变成 API，Realtime 借助 Postgres 复制机制打通实时通道，GoTrue 承载认证，Storage 结合 S3 与 Postgres 实现文件管理与鉴权，postgres-meta 驱动可视化后台，网关统一收敛所有流量。而这份蓝图在当前仓库中并非停留在纸面——docker/docker-compose.yml 可以一次性拉起对应每个组件容器，apps/studio、supabase/functions、packages/pg-meta、examples 等目录则为每个能力域提供了可读、可运行的源码级参考。理解这张"组件地图"，是使用、自托管乃至二次开发 Supabase 的第一步。