Electric-SQL 项目中的认证与授权机制详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00411/article/details/148440521

Electric-SQL 项目中的认证与授权机制详解

electric electric-sql/electric: 这是一个用于查询数据库的JavaScript库，支持多种数据库。适合用于需要使用JavaScript查询数据库的场景。特点：易于使用，支持多种数据库，具有灵活的查询构建和结果处理功能。项目地址: https://gitcode.com/gh_mirrors/el/electric

引言

在现代分布式应用开发中，数据同步和权限控制是两个核心挑战。Electric-SQL 作为一个创新的数据同步解决方案，通过 HTTP 协议实现了优雅的认证与授权机制。本文将深入解析 Electric-SQL 的认证授权体系，帮助开发者构建安全可靠的数据同步应用。

Electric-SQL 认证授权基础

HTTP 原生支持

Electric-SQL 最显著的特点是完全基于 HTTP 协议构建其数据同步机制。这意味着：

所有数据同步请求都是标准的 HTTP 请求
可以利用现有的 HTTP 认证机制（如 JWT、OAuth 等）
能够无缝集成各种 API 网关和中间件

Shape 即资源

在 Electric-SQL 中，数据同步的基本单位是 Shape（数据形状）。每个 Shape 请求本质上是对 /v1/shape 端点的 HTTP GET 请求，携带了 Shape 定义作为查询参数。这种设计使得：

可以像保护普通 API 端点一样保护 Shape 请求
权限检查可以在请求到达 Electric-SQL 服务前完成
授权逻辑可以灵活地放在中间层或 API 层

核心认证模式

1. 中间认证模式 (Middleware Auth)

工作原理

中间认证模式是最直接的实现方式，其流程如下：

客户端发起 Shape 请求时携带认证信息（如 Authorization 头）
请求首先到达中间层（可以是 API 服务或专用中间件）
中间层验证用户凭证和请求参数
验证通过后，中间层将请求转发到 Electric-SQL 服务

技术实现示例

// 客户端代码 - 添加认证头
const usersShape = (): ShapeStreamOptions => {
  const user = loadCurrentUser();
  return {
    url: new URL(`/api/shapes/users`, window.location.origin).href,
    headers: {
      authorization: `Bearer ${user.token}`
    }
  };
}

// 中间层代码 - 验证并转发
export async function GET(request: Request) {
  const user = await loadUser(request.headers.get(`authorization`));
  if (!user) return new Response(`user not found`, { status: 401 });
  
  // 构建上游请求URL
  const originUrl = new URL(`http://localhost:3000/v1/shape`);
  // 添加权限过滤条件
  if (!user.roles.includes(`admin`)) {
    originUrl.searchParams.set(`where`, `"org_id" = ${user.org_id}`);
  }
  
  // 转发请求
  const response = await fetch(originUrl);
  return new Response(response.body, {
    status: response.status,
    headers: response.headers
  });
}

适用场景

需要实时权限检查的场景
已存在 API 网关或中间层基础设施
权限逻辑相对简单直接

2. 令牌认证模式 (Token Auth)

工作原理

令牌模式采用令牌机制，流程更复杂但更安全：

客户端首先向令牌端点请求形状特定的访问令牌
令牌服务验证用户权限并生成包含形状声明的 JWT
客户端使用该令牌通过中间层访问 Electric-SQL
中间层验证令牌中的形状声明是否匹配请求参数

架构优势

权限检查在令牌端点集中完成
中间层只需验证令牌有效性，减轻性能压力
令牌可设置有效期，自动过期保障安全

实现组件

典型的令牌模式实现包含：

令牌服务：负责验证用户和生成令牌
中间层：验证令牌并转发请求
- 可以是独立服务
- 也可以是边缘函数（如 Supabase Edge Functions）
客户端：管理令牌生命周期

适用场景

需要精细控制数据访问权限
权限检查逻辑较复杂
希望减少中间层的计算负担

高级技巧与最佳实践

动态认证选项

Electric-SQL 的 TypeScript 客户端支持函数式认证选项，非常适合需要动态令牌的场景：

const stream = new ShapeStream({
  url: 'http://localhost:3000/v1/shape',
  headers: {
    // 每次请求自动刷新令牌
    'Authorization': async () => `Bearer ${await getAccessToken()}`
  }
});

这种模式特别适用于：