跳到主要内容
Supabase 实战指南:数据库、SDK 与本地部署 | 极客日志
SQL SaaS AI 大前端
Supabase 实战指南:数据库、SDK 与本地部署 Supabase 是基于 PostgreSQL 的开源后端服务框架,提供数据库、认证、存储等功能。介绍其核心功能,包括数据库管理、插件扩展、远程连接、SDK 接入、行级安全策略(RLS)、文件存储及边缘函数。同时涵盖本地 Docker 部署步骤,帮助开发者快速搭建前后端应用,实现数据安全性与便捷性的平衡。
FrontendX 发布于 2026/4/6 更新于 2026/5/22 27 浏览Supabase 实战教程
2025 年较火的后端开源项目是 Supabase。Supabase 是一个开源的后端服务框架,在强大的 PostgreSQL 数据库基础上,封装了用户认证、文件存储、可视化的运维面板等功能,为开发者提供了一整套开箱即用的后端基础设施。
总的来说,Supabase 为开发者提供了三大部分的能力:后端、前端与云服务。Supabase 在后端提供数据库、文件存储、边缘函数、用户鉴权等各种基础设施。在前端方面,Supabase 提供客户端 SDK,可以将任何一个前端框架,比如 React, Vue,甚至手机 APP,用几行代码就可以轻松接入后端。
Supabase 是一个完全开源免费的项目,我们可以使用源代码或者 docker 镜像,自己部署一个 Supabase 的完整实例。如果懒得自己部署,Supabase 的官方还提供一个云服务的版本,我们只需要注册一个账户,就能立即获得一个免费的 Supabase 实例。
Supabase 开箱即用的方便特性,跟 AI 编程是绝配,配合 AI 编程,可以超级快速搭建一个带用户鉴权、加数据库的前后端的完整应用。
本文从数据库核心、Supabase SDK、RLS 行级安全策略、还有自部署这几个方面来全面介绍 Supabase 的使用。Supabase 的基础是一个完整的 PostgreSQL 数据库,它具备 postgres 的一切功能。我们先从最简单易用的云服务版本开始上手,文末会介绍如何进行本地部署。
数据库核心
我们来到 Supabase 的官网 supabase.com,右上角点击 sign in。这里选择用 Github 登录。
登录完成以后创建一个组织,这里填上名字,plan 这里选择免费的,创建。
然后下一步创建一个项目,也就是一个数据库实例,填写一个密码。区域这里我选择新加坡。
开始,这样我们就拥有了一个 postgres 数据库的完整实例。
在左侧 Table Editor,
create table 可以创建数据库表,这里可以添加字段表。创建出来可以编辑新增一条记录,填写好数据,点击保存。在这个 UI 界面,还可以对数据进行编辑,删除等等。左侧找到 SQL Editor,
会打开一个 SQL 语句的编辑窗口,我们可以在这里面直接编写 SQL 语句,点击右下角的 run 就可以执行。
这里有 postgres 的所有的基础功能:schema, 表,函数,触发器,枚举,插件,索引。publications 是一个实时监控,可以把表的修改信息以 Websocket 的形式推送出去。
我们来看一个重要部分,叫做插件 (Extensions)。现代 Web 开发中,各种花哨的工具层出不穷,其实一个 PostgreSQL 数据库搭配上插件,就能存下世间万物,可以很大程度上代替这些花哨的工具。
安装这个插件,postgres 就有了存储地理位置信息的能力,可以把 postgres 变成一个性能顶尖的企业级地理信息系统数据库。我们在右边把这个开关开起来,这里需要选择一个 schema 去应用这个扩展,我选择 public,这样就开启成功了。
我来创建一个表,用来存储城市里面的地理位置信息,GEOMETRY 是插件提供的一个自定义类型,用来存储地理位置信息。
CREATE TABLE city_map (
id SERIAL PRIMARY KEY ,
name TEXT NOT NULL ,
geom GEOMETRY(GEOMETRY, 4326 )
);
往表里插入三个地理位置相关的测试数据:一个四边形的公园,一条直线型的河流,还有一个坐标点。
INSERT INTO city_map (name, geom) VALUES
('人民公园' , ST_GeomFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))' , 4326 )),
('护城河' , ST_GeomFromText('LINESTRING(-5 5, 15 5)' , 4326 )),
('电话亭' , ST_GeomFromText('POINT(12 8)' , 4326 ));
我们可以使用插件提供的函数来计算人民公园的面积,使用插件提供的操作符来计算两个地理位置之间的距离。
SELECT name, ST_Area(geom) FROM city_map WHERE name = '人民公园' ;
数据库连接 除了在网页上操作这个 postgres 数据库,Supabase 还提供了远程连接的方式。我们点击上面的 connect 按钮,
这里 Supabase 为我们提供了一个远程连接的地址,
我们可以把它接入到任意一个数据库的客户端,或者 Java Python 之类的后台代码里面。我用我的数据库工具 DBeaver 来连接一下:
新建数据库连接-->选择 postgres,主机我们填写这一串,端口 5432,数据库名与用户名都不用改,密码填写我们创建 Supabase 项目时候的密码,点击完成。
这样,我们就把 Supabase 的数据库连接进了客户端工具。这里注意一下,选择 Direct Connection,也就是直连模式,它是不支持 IPV4 的。如果你的网络只能用 IPV4 的话,需要选择最下面这个 Session pooler。Session Pooler 跟直连模式非常的像,好处是它支持 IPV4。
在连接模式里面,中间还有一个 Transaction pooler,这个是 supabase 的连接池模式。在直连模式下面,需要后端服务自己维护连接池,比如用 springboot 的 Hikari。
而连接池模式下面,supabase 会自动为我们维护连接池,从而显著降低数据库连接的压力,特别适合一些无状态服务,比如无服务器函数或者边缘函数,他们都是按需启动,不用时就销毁,没有能力长时间维护一个连接池,这时候就应该选择 transaction pooler 模式,让 supabase 来负责维护连接池。
Supabase SDK 以上就是 Supabase 作为一个数据库的功能,我们来看下一部分 Supabase SDK。Supabase SDK 可以将任何一个前端框架,比如 React Vue 甚至手机 APP,用一行代码就接入后端。Supabase SDK 一般是配合这里的鉴权功能来使用的。我们回到项目的首页,在最下面,这里有一段 Javascript 代码,这就是最基础的 SDK 的使用。
我们来创建一个前端项目试一下。这里我们换一个热门的前端框架,就是 VUE。
打开一个文件夹,右键在终端打开,进行前端开发。电脑上需要先安装 node.js,执行第一个命令初始化一个 Vue 工程。项目初始化完成以后,我们根据这里的提示再来操作一下
cd vue-project
npm install
npm run dev
这样一个 VUE 工程就创建好了,我们进入以后就可以看到它的代码。
接下来,我们把 Supabase 的 SDK 接入这个前端工程,第一步就是把 Supabase 的 SDK 在工程里面安装一下,才能 import 进来。
npm install @supabase/supabase-js
我们找一段能写 TS 代码的地方,把这个 SDK 来测试一下。这里我 App.vue 这个文件为例,我把官网上的示例代码粘贴过来。这里的 Supabase API Key 我直接把官网上面粘贴过来。
const supabaseUrl = 'https://sqttzihmuyigautyhyzd.supabase.co'
const supabaseKey = "官网的 API Key"
const supabase = createClient (supabaseUrl, supabaseKey)
await supabase.auth .signUp ({ email : '[email protected] ' , password : 'Supabase123!' })
这里有的观众朋友们可能会好奇,你把 API Key 直接写到前端代码里面,这个 API Key 不就直接泄露了吗?难道这样做不是违反安全规范吗?我们来到 Supabase 的官网,来看一下这段话:
这里说这个 key 在浏览器里面使用是安全的,如果你启用了 RLS,也就是行级安全策略,并且正确地配置了你的表。虽然把 API Key 直接放到前端去用有点反直觉,但这其实是 supabase 的一个强大特性,也就是 RLS 行级安全策略,它保证了我们即使在前端跟数据库交互,也能确保数据的安全。
等下一个章节,我们就来重点看这个行级的安全策略。这里我们先把 SDK 讲完,接下来就可以实现一些 supabase 的功能。这里我们先来一个用户注册,实现用户注册非常简单:
我们来测试一下,把项目启动起来,访问一下前端,然后我们来到 Supabase 的控制台,在 authentication 里面,就可以看到我们在页面上注册的那个账户,找到最右边,这里的状态是 waiting for verification,就是还没有邮箱验证。来到注册用户的邮箱,收一下验证邮件,点一下这个确认链接,确认完毕,这个用户就完全生效了。
就这么几行就简单搞定了用户注册。用户登录只要把这个 signUp 改成 signInWithPassword,就是使用邮箱加密码登录。在前面写个变量接收一下结果,最后把变量打印一下,我们再来试一下,
const { data : signInData, error : signInError } = await supabase.auth .signInWithPassword ({ email : '[email protected] ' , password : 'Supabase123!' })
console .log (signInData)
刷新一下页面,在控制台就可以看到打印出来的用户信息,包括这里的 session,用户的状态邮箱 ID 等等的各种信息。
这就是 Supabase SDK 的基础使用,几行代码就完成了用户的注册还有登录。
RLS 行级安全策略 RLS 行级安全策略它原本是 postgres 的一个原生功能,简单来说,就是约束了哪行数据可以被哪些用户修改或者读取。
在演示 RLS 之前,我们先在数据库里面建一个表。我们看到 Supabase 自带的这个用户表,它只有邮箱,还有电话等信息。我准备创建一个用户信息表,把用户的年龄等信息存一下,表明我叫 user_info,注意一定要把这里的 RLS 启动起来。
添加我想要的字段,我们先来一个年龄字段,再来一个 first name 字段,再来一个 last name 字段。我需要把我的用户信息表跟这张系统表关联起来,所以我需要一个字段把这里的 uid 填进去。添加一个字段叫做 user_id,它的类型选择 uuid,跟系统表是一致的。这里随机生成我不需要。
然后在最下面我新建一个外键,需要把我们的 user_id 跟 auth 这个 schema 里面的用户表关联起来。这里左边我选择 user_id,右边的关联项选择 id,也就是我的 user_info 表的 user_id 字段跟系统表的 auth.users 的 id 字段,两个形成外键关联,保存一下。
然后我们回到左侧菜单,authentication 里面,再新建一个用户,填个邮箱密码,创建,这样系统里面有两个用户了。再回到我们的业务表,我把这两个用户的基础信息都填一下,点击 insert row,
第一个用户最下面的 user_id 我们选 select record,选第一个用户,这样就把他的 ID 关联过来了。
保存,然后第二个用户年龄名字,在下面选择 user_id,这里我选择这个用户,保存。我们在 authentication 的系统表里面有两个用户,在我们的业务表里面存储了这两个用户的年龄。
现在我的需求是,我只想让某个用户查看并且修改属于他自己的记录,而不能去查看或者修改别人的记录。
这里我们需要给业务表配置行级安全策略,点击这个按钮,
create policy。我们选择这个 select 查询,右侧给了一些模板,我们选择最下面这一个
enable user to view their own data。这个模板的意思是登录用户只能读取属于他自己的那一条数据。上面这些都是固定的写法,我们主要看第 7 行,七行的意思是获取登录用户的 ID,这个 ID 必须跟我 user_info 表的 user_id 匹配起来,也就是这个登录用户只能读取属于他自己的那一条数据,这也就是行级安全策略,把它保存一下。
登录用户只能看到属于他自己的数据。有了这个安全保障,我们可以直接把查询语句写到前端代码里面,supabase 通过行级的安全策略保障了数据的安全性。我们来写一下查询语句,查询语句非常简单:supabase.from('user_info').select('*').eq('first_name', 'tech')。这里我要查询 first_name 等于 tech 的数据,我们来试一下。
const { data : signInData, error : signInError } = await supabase.auth .signInWithPassword ({ email : '[email protected] ' , password : 'Supabase123!' , })
const { data, error } = await supabase
.from ('user_info' )
.select ('*' )
.eq ('first_name' , 'Tech' )
console .log ('数据:' , data)
console .log ('错误:' , error)
刷新一下页面,我们看到数据被查询出来了,用户的年龄,他的名字都被查询出来了。
我这里想查询别人的数据看看可不可以。这里我把 first name 换一下,换成数据库里面的另外一个用户 test。
行级安全策略保证了当前的登录用户是不可能看到别人的数据的。
我们在浏览器控制台->network 最下面可以看到这次查询的网络请求。Supabase SDK 会自动的把这种 select 的语句转换成 http 的 get 方法,包括表名,然后 select 的字段,后面的条件都写到了这个 get 方法里面。
我们看到这个请求里面最重要的部分,是在 header 里面的 authentication 里面,有一个 bearer 里面的 JWT TOKEN,这个 TOKEN 也就是当前登录用户的令牌,只有这个令牌跟后面的行级安全策略匹配起来,才能查询到数据。
我这里面还有一些表没有配过行级安全策略,这些表就能随便查吗?比如这里我们看一下 test 表,点击这个
ADD RLS Policy。这里写了通过 supabase API 现在没有一行数据能被查询到,因为行级安全策略还没有配置,也就是没有配过 RLS 的表,通过 SDK 是完全查询不到的。
只有通过后台,或者这种直连数据库的形式,才能查询到这些表的数据。
RLS 除了能保证数据的读取,还能保证数据的写入。我们再来新建一条策略,create policy。这里我们选中 insert,模板的话选择这个,也就是用户只能插入跟自己有关的数据。
我们看到这里的条件跟刚才的 select 是一样的,这样点击 save。我把业务表里面这两条测试数据删除掉,然后我们来修改代码,直接从前端网页来插入数据。插入数据的代码就这么写:supabase from 后面是表明,表明后面就是 insert,接下来就是需要插入的数据:first_name, last_name, 年龄,user_id。
我是从登录的账号里面取用户的 ID,也就是说它只插入 user_id 等于自己的数据。
const { data : signInData, error : signInError } = await supabase.auth .signInWithPassword ({ email : '[email protected] ' , password : 'Supabase123!' , })
const { data : data, error : error } = await supabase
.from ('user_info' )
.insert ([
{ first_name : 'Tech' , last_name : 'Shrimp' , age : 28 , user_id : signInData?.user ?.id }
])
.select ()
console .log ('数据:' , data)
console .log ('错误:' , error)
我们来试一下,刷新一下网页,成功打印了日志,我们来到后台,看到数据也被成功插入了数据库。
我们的行级安全策略约定了用户只能插入跟自己有关的数据,如果我改一下 user_id,看看能不能去插别人的 ID。刷新一下页面,看一下控制台,这里报了 403 forbidden。
我们看到这里的报错:新插入的行违反了行级安全策略。我们的行级安全策略要求只能插入跟自己相关的数据,你不可能去修改别人的数据。从这个例子,我们看到行级安全策略的强大之处。这也就解释了为什么我们使用 supabase 可以把数据库的操作语句写到前端代码里面。
文件存储 接下来我们看另外一个重要功能 storage,也就是文件存储。我们先来看一下它的基础使用。storage 用来存放文件,这里我们点击 add new bucket,
先创建一个存储桶,给存储桶起个名字,点击 create。随便找个文件就可以拖拽进去,我们可以查看下载上传的文件,还有获取它的链接,可以把它当做一个图床使用。这个存储桶功能是适配了 S3 标准的存储协议的,我们可以通过这个地址使用 S3 协议来管理里面的文件。
同样的存储桶也可以配置它的安全措施,使用 Supabase SDK 直接在前端对存储桶进行操作。
这里我们来看一个例子,我们先来到 policy,在存储桶这里新建一个 policy,这里我选择第二个模板,也就是用户只能操作跟他的用户 ID 相同名字的文件夹。
右下角点击创建,我把这些权限都勾选上,点击保存。我准备把这个网页改造一下,变成一个上传的页面。我让 AI 帮我写了一个测试页面,还是用我这套账号名密码。核心上传代码在这里:supabase.storage.form 是我这个存储桶的名字,接下来就是上传,指定一个路径,然后指定一个文件。
我们来试一下,看到用户已经登录了,这里我选择一个文件,我随便填一个路径,点击上传。我们看到这里报错了,他违反了行级安全策略。
我们的安全策略里面约束了,这个文件只能上传到跟他用户 ID 同名的文件夹里面。所以这里随便填一个文件夹是上传不上去的。我把用户的 ID 复制一下,我们把文件夹的名字改成用户的 ID,再次点击上传。这次上传成功,我们去后台看一下。在存储桶里面可以看到用户的文件夹,在文件夹里面就可以看到他上传进来的文件。
我们使用的这个云服务版本,免费用户的最大存储空间有一定的限制:数据库最大使用 500 MB,然后存储桶最大可以使用 1GB。如果空间不够,我们当然也可以进行本地部署,文末我会介绍如何进行本地部署。
边缘函数 也就是边缘函数。Edge Function 的功能非常像 Cloudflare Worker,我之前有一期完整视频介绍什么是边缘函数,supabase 的边缘函数跟我之前讲的几乎一模一样,这里我就不赘述了。
实时推送 下一个功能是这里的 RealTime,简单来说就是推送功能。我们可以配置一个触发器来监听数据库的变化,每当数据库有变化的时候,它就会发送一个 Websocket 的通知,然后通过 Supabase 的 SDK 把这个消息推送到网页端。比如,我们想把一个消息在客户端进行弹窗提醒,我我们就可以建一个提醒表,然后来订阅这个表的变化,每当发现表里面插入的数据跟自己有关,就会在客户端弹一个窗进行提醒。我们可以根据 123 3 个步骤,把一个实时推送配置好。这里由于本期篇幅所限,我就不详细演示了。
MCP supabase 下一个重要功能是 MCP。我们来到文档站,搜索 MCP,找到第二个。
可以根据这里的文档,把 MCP 安装到 AI 工具里面,让 AI 获得操作 Supabase 的能力。在上期视频里面,我对 Supabase MCP 有过完整介绍了。感兴趣的读者可以去看一下。
Supabase 本地部署指引 接下来,我们看如何自己部署一个 supabase。这里我们来到 supabase 的首页 supabase.com,点击这个 Docs,
也就是文档站。在 build 下面有一个 self hosting,
也就是自托管,自部署。这里选择 Docker 的方式,下面有一串部署命令,我们来执行一下。
git clone --depth 1 https://github.com/supabase/supabase
mkdir supabase-project
cp -rf supabase/docker/* supabase-project
cp supabase/docker/.env.example supabase-project/.env
cd supabase-project
docker compose pull
docker compose up -d
supabase 总共有 13 个组件,运行起来整个差不多需要 4GB 的内存。我没有这么大内存的 Linux 服务器,所以这里我就用我这台 Windows 电脑。
我新建一个文件夹,进来以后,右键在终端打开。我们第一件事需要在电脑上安装 Docker,如果对 Docker 使用方式不熟悉,可以参考一下官方文档,里面有所有操作系统使用 Docker 的方式。
把 Docker Desktop 启动起来,然后我们来执行官网上的命令。
首先第一个命令使用 git 克隆命令把源代码克隆到本地。
git clone --depth 1 https://github.com/supabase/supabase
第三个命令拷贝文件,不过 Windows 上不能这么直接执行。
我们来手动拷贝一下,来到这个 supabase 文件夹,找到 docker,把这里面的所有东西复制一下,粘贴到 supabase-project 文件夹里面。
下一个命令是创建这个.env 文件,这里我找到.env.example,把它复制一下创建一个.env 文件
进来以后,需要改一些东西,这里有需要改的是它的前端端口,在 Windows 电脑上必须把这个端口改高一点,这里我在前面加个 1,改成 18,000。下面这个也改 18443,这样配置文件也准备好了。
把所有需要的镜像都拉取下来,总共有 13 个组件,非常的多。
启动完成以后,我们就可以来访问一下了。这里输入 localhost:18000,注意端口填写我们配置文件里配的端口 18000。
账号名是 supabase,密码填写这一串。this_password_is_insecure_and_should_be_updated
登录,这样,我们成功在本地部署好了。一个 supabase 应用。我们可以在数据库里面建表进行测试,然后刚才我们讲的数据库鉴权、文件存储、边缘函数这些功能,在自托管的版本里面也是有。
包括 Supabase SDK 也是可以正常用的,我们只需要把这里的地址,还有 API Key 换成我们本地部署的地址,还有 API Key。在上面的 connect 里面选到 APP framework,这里选到 Vue.js,把这个地址替换到代码里面,包括 API Key 替换到代码里面,supabase SDK 也可以完全正常使用
我们只需要找一个服务器,使用 Docker 把这一整套东西部署上去,就可以解锁 supabase 的全部能力。而且它的源代码在 GitHub 上面是完全开源的,使用的是宽松的 apache 2.0 协议,完全免费自由的商用。
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
随机西班牙地址生成器 随机生成西班牙地址(支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选),支持数量快捷选择、显示全部与下载。 在线工具,随机西班牙地址生成器在线工具,online
SQL 美化和格式化 在线格式化和美化您的 SQL 查询(它支持各种 SQL 方言)。 在线工具,SQL 美化和格式化在线工具,online
SQL转CSV/JSON/XML 解析 INSERT 等受限 SQL,导出为 CSV、JSON、XML、YAML、HTML 表格(见页内语法说明)。 在线工具,SQL转CSV/JSON/XML在线工具,online
CSV 工具包 CSV 与 JSON/XML/HTML/TSV/SQL 等互转,单页多 Tab。 在线工具,CSV 工具包在线工具,online