Supabase：开源Firebase替代完全指南：后端即服务的完整教程

Supabase：开源Firebase替代完全指南：后端即服务的完整教程

背景

在移动应用和 Web 应用开发中，构建完整的后端服务是一项复杂且耗时的任务。Firebase 作为 Google 提供的后端即服务（BaaS）平台，提供了数据库、认证、存储、推送等一站式服务，但其闭源特性和数据隐私顾虑让一些开发者望而却步。

Supabase 正是为解决这一需求而生的开源 Firebase 替代方案。它基于 PostgreSQL 数据库，提供了完整的后端服务，包括数据库、实时订阅、身份认证、文件存储、Edge Functions 等，同时支持完全私有化部署。

本文将提供一份保姆级教程，详细讲解 Supabase 的部署与配置，帮助开发者快速搭建完整的后端服务平台。

一、项目概述

1.1 Supabase 简介

Supabase 是开源的 Firebase 替代方案，GitHub Star 数超过 65K。它建立在 PostgreSQL 之上，提供了现代化、可扩展的后端服务。

Supabase 的核心特点：

• 开源自由：基于 Apache 2.0 协议，完全开源
• PostgreSQL 核心：强大的关系型数据库
• 实时订阅：WebSocket 实时数据推送
• 身份认证：完整的用户认证系统
• 文件存储：大文件存储和管理
• Edge Functions：边缘计算函数
• API 自动生成：自动生成 RESTful 和 GraphQL API

1.2 核心功能

1.2.1 数据库

基于 PostgreSQL 的数据库服务：

• PostgreSQL 完整功能：支持所有 PostgreSQL 特性
• 表编辑器：可视化数据管理
• SQL 编辑器：在线执行 SQL
• 数据库分支：创建数据库副本进行测试
• 自动备份：数据自动备份

1.2.2 实时订阅

强大的实时数据订阅：

• WebSocket 订阅：监听数据变更
• 过滤订阅：按条件订阅
• 广播：向所有客户端广播消息
• Presence：在线状态同步

1.2.3 身份认证

完整的用户认证系统：

• 邮箱密码：传统的邮箱注册登录
• 社交登录：Google、GitHub、微信等
• Magic Link：无密码登录
• JWT 管理：安全的 Token 管理
• RLS 策略：行级安全策略

1.2.4 存储服务

文件存储和管理：

• bucket 管理：创建存储桶
• 文件上传：上传文件和图片
• 图片转换：图片缩放、裁剪
• 访问控制：基于策略的访问控制

1.3 技术架构

Supabase 采用现代化的技术栈：

• 数据库：PostgreSQL 15+
• 实时引擎：Go + WebSocket
• 认证：Go + JWT
• 存储：S3 兼容存储
• Edge Functions：Deno 运行时
• API 网关：PostgREST
• 容器化：Docker Compose

二、Docker Compose 部署

2.1 环境准备

确保服务器已安装：

• Docker 20.10+
• Docker Compose 2.0+
• 内存：最低 4GB，推荐 8GB+
• 磁盘：至少 20GB

2.2 系统要求

Supabase 是一个完整的自托管方案，需要较多资源：

组件	最低内存	推荐内存
Kong	256MB	512MB
GoTrue	256MB	512MB
PostgREST	256MB	512MB
PostgreSQL	2GB	4GB
Redis	256MB	512MB
Storage	512MB	1GB
Total	4GB	8GB+

2.3 下载部署配置

# 下载 Supabase Docker 配置
git clone https://github.com/supabase/supabase
cd supabase/docker

# 复制环境变量模板
cp .env.example .env

2.4 配置环境变量

编辑 .env 文件，配置必要的参数：

# 基础配置
POSTGRES_PASSWORD=your-super-secret-and-long-postgres-password
JWT_SECRET=your-super-secret-jwt-token-with-at-least-32-characters

# 域名配置
SITE_URL=http://your-domain.com
ADDITIONAL_REDIRECT_URLS=http://localhost:3000

# 功能开关
ENABLE_EMAIL_SIGNUP=true
ENABLE_ANON_KEY=true

2.5 配置 DNS

在 DNS 中添加以下记录：

记录类型	主机名	指向
A	api.your-domain.com	服务器 IP
A	your-domain.com	服务器 IP
CNAME	supabase	your-domain.com

2.6 启动服务

# 启动所有服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看特定服务日志
docker compose logs -f kong
docker compose logs -f postgres

2.7 访问服务

服务启动后，访问以下地址：

服务	地址
Studio	http://your-domain.com
API	http://api.your-domain.com
Health	http://your-domain.com/health

2.8 Nginx 反向代理配置

如果需要更复杂的配置，可以添加 Nginx 反向代理：

cat > /etc/nginx/sites-available/supabase << 'EOF'
server {
    listen 80;
    server_name your-domain.com api.your-domain.com;

    client_max_body_size 500M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /rest/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }

    location /auth/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }

    location /storage/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }
}
EOF

三、数据库使用

3.1 Supabase Studio

Supabase Studio 提供可视化的数据库管理界面：

1. 访问 http://your-domain.com
2. 登录使用配置的邮箱密码
3. 进入数据库管理

3.2 创建表

3.2.1 使用 Table Editor

1. 点击"New Table"
2. 填写表名和列信息
3. 设置主键和默认值
4. 点击"Save"

3.2.2 使用 SQL Editor

-- 创建用户表
CREATE TABLE profiles (
    id UUID REFERENCES auth.users PRIMARY KEY,
    email TEXT,
    display_name TEXT,
    avatar_url TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 启用行级安全
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

-- 创建默认 RLS 策略
CREATE POLICY "Users can view own profile"
    ON profiles FOR SELECT
    USING (auth.uid() = id);

CREATE POLICY "Users can update own profile"
    ON profiles FOR UPDATE
    USING (auth.uid() = id);

3.3 行级安全（RLS）

RLS 是 Supabase 安全的核心：

-- 创建 RLS 策略
CREATE POLICY "Enable read for authenticated users"
    ON posts FOR SELECT
    TO authenticated
    USING (true);

CREATE POLICY "Enable insert for authenticated users"
    ON posts FOR INSERT
    TO authenticated
    WITH CHECK (auth.uid() = author_id);

CREATE POLICY "Enable update for post authors"
    ON posts FOR UPDATE
    TO authenticated
    USING (auth.uid() = author_id);

四、客户端集成

4.1 JavaScript/TypeScript SDK

4.1.1 安装

npm install @supabase/supabase-js

4.1.2 初始化

import { createClient } from '@supabase/supabase-js'

const supabaseUrl = 'https://your-project.supabase.co'
const supabaseKey = 'your-anon-key'

const supabase = createClient(supabaseUrl, supabaseKey)

4.1.3 数据操作

// 获取数据
const { data: posts, error } = await supabase
    .from('posts')
    .select('*')

// 插入数据
const { data, error } = await supabase
    .from('posts')
    .insert([
        { title: 'Hello', content: 'World', author_id: user.id }
    ])

// 更新数据
const { data, error } = await supabase
    .from('posts')
    .update({ title: 'Updated' })
    .eq('id', postId)

// 删除数据
const { error } = await supabase
    .from('posts')
    .delete()
    .eq('id', postId)

4.2 Flutter SDK

4.2.1 安装

flutter pub add supabase_flutter

4.2.2 初始化

import 'package:supabase_flutter/supabase_flutter.dart';

void main() async {
    await Supabase.initialize(
        url: 'https://xxx.supabase.co',
        anonKey: 'your-anon-key',
    );
    runApp(MyApp());
}

4.2.3 使用

// 获取数据
final posts = await Supabase.instance.client
    .from('posts')
    .select();

// 插入数据
await Supabase.instance.client
    .from('posts')
    .insert({'title': 'Hello'});

4.3 Swift/iOS SDK

import Supabase

// 初始化
try await Supabase.initialize(
    url: URL(string: "https://xxx.supabase.co")!,
    anonKey: "your-anon-key"
)

// 查询数据
let posts = try await Supabase.instance.client
    .from("posts")
    .select()
    .execute()

五、实时订阅

5.1 开启实时订阅

在数据库中启用逻辑复制：

-- 启用 REPLICA IDENTITY
ALTER TABLE posts REPLICA IDENTITY DEFAULT;

-- 开启表级别的实时
ALTER PUBLICATION supabase_realtime ADD TABLE posts;

5.2 客户端订阅

// 订阅所有变更
const subscription = supabase
    .channel('posts')
    .on('postgres_changes', { event: '*', schema: 'public', table: 'posts' }, 
        (payload) => {
            console.log('Change received!', payload)
        })
    .subscribe()

// 订阅插入事件
const insertSubscription = supabase
    .channel('new-posts')
    .on('postgres_changes', 
        { event: 'INSERT', schema: 'public', table: 'posts' },
        (payload) => {
            console.log('New post added!', payload.new)
        })
    .subscribe()

5.3 Presence（在线状态）

// 同步在线状态
const channel = supabase.channel('room-1')

channel.on('presence', { event: 'sync' }, () => {
    const state = channel.presenceState()
    console.log('Online users:', state)
})

// 加入 Presence
channel.track({
    user_id: '1',
    user_name: 'John'
})

// 离开
channel.untrack()

六、身份认证

6.1 邮箱密码认证

// 注册
const { data, error } = await supabase.auth.signUp({
    email: 'user@example.com',
    password: 'password123'
})

// 登录
const { data, error } = await supabase.auth.signInWithPassword({
    email: 'user@example.com',
    password: 'password123'
})

// 登出
const { error } = await supabase.auth.signOut()

// 获取当前用户
const { data: { user } } = supabase.auth.getUser()

6.2 Magic Link（无密码登录）

const { error } = await supabase.auth.signInWithOtp({
    email: 'user@example.com',
    options: {
        emailRedirectTo: 'https://your-app.com/callback'
    }
})

6.3 社交登录

6.3.1 配置 Provider

在 Supabase 后台配置 OAuth Provider：

1. 访问 Authentication → Providers
2. 启用需要的 Provider
3. 配置 Client ID 和 Secret

6.3.2 使用社交登录

const { data, error } = await supabase.auth.signInWithOAuth({
    provider: 'github',
    options: {
        redirectTo: 'https://your-app.com/callback'
    }
})

七、存储服务

7.1 创建 Bucket

7.1.1 使用 Studio

1. 访问 Storage
2. 点击"New Bucket"
3. 输入名称和权限设置

7.1.2 使用 SQL

INSERT INTO storage.buckets (id, name, public)
VALUES ('avatars', 'avatars', true);

7.2 上传文件

const { data, error } = await supabase.storage
    .from('avatars')
    .upload('public/avatar1.jpg', file)

7.3 下载文件

const { data, error } = await supabase.storage
    .from('avatars')
    .download('public/avatar1.jpg')

7.4 获取公开 URL

const { data } = supabase.storage
    .from('avatars')
    .getPublicUrl('public/avatar1.jpg')

八、Edge Functions

8.1 创建 Function

# 创建 Function
mkdir -p ./functions/hello-world
cd ./functions/hello-world

# 创建 index.ts
cat > index.ts << 'EOF'
Deno.serve(async (req) => {
    const { name } = await req.json()
    return new Response(
        JSON.stringify({ message: `Hello ${name || 'World'}!` }),
        { headers: { 'Content-Type': 'application/json' } }
    )
})
EOF

8.2 部署 Function

supabase functions deploy hello-world

8.3 调用 Function

curl -X POST https://your-project.supabase.co/functions/v1/hello-world \
  -H "Authorization: Bearer ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supabase"}'

九、常见问题

9.1 部署问题

Q：服务启动失败

A：检查资源是否足够（内存至少 4GB）：

docker compose logs

Q：Kong 网关 502 错误

A：检查各个服务启动状态：

docker compose ps

9.2 使用问题

Q：RLS 策略不生效

A：检查是否在表上启用了 RLS：

SELECT tablename, rowsecurity
FROM pg_tables
WHERE schemaname = 'public';

Q：实时订阅不工作

A：确保表已添加到实时出版物：

ALTER PUBLICATION supabase_realtime ADD TABLE your_table;

十、总结

Supabase 作为开源的 Firebase 替代方案，以其 PostgreSQL 核心、实时订阅、完整的认证系统等强大功能，为开发者提供了一个完整的应用后端解决方案。

通过本文的保姆级教程，读者应该已经掌握了：

1. Docker 部署：使用 Docker Compose 部署完整的 Supabase
2. 数据库使用：创建表、配置 RLS
3. 客户端集成：JavaScript、Flutter 等 SDK
4. 实时订阅：WebSocket 数据订阅
5. 身份认证：邮箱登录、社交登录
6. 存储服务：文件上传和下载
7. Edge Functions：边缘计算函数

对于需要构建现代应用的开发者，Supabase 是一个值得信赖的开源选择。

---

© 版权归无边界科技所有，版权所有。