Electric-SQL 项目中的 Gatekeeper 认证模式详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00818/article/details/148440514

Electric-SQL 项目中的 Gatekeeper 认证模式详解

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

什么是 Gatekeeper 认证模式

Gatekeeper 认证模式是 Electric-SQL 项目中实现的一种安全访问控制机制，主要用于保护对 Electric 同步服务的访问。这种模式通过将认证逻辑与授权逻辑分离，实现了高效且安全的访问控制。

核心概念与工作原理

认证流程的两个阶段

令牌获取阶段：
- 客户端向 Gatekeeper 端点提交认证凭据和形状定义
- Gatekeeper 验证凭据并授权访问请求的形状
- 授权成功后生成包含形状声明的 JWT 令牌
数据请求阶段：
- 客户端使用获取的令牌通过代理访问 Electric 服务
- 代理验证令牌的有效性和形状匹配性
- 验证通过后将请求转发给 Electric 服务

形状范围令牌的优势

形状范围令牌（Shape-scoped Token）是这种模式的核心创新点，它允许：

将主要授权逻辑集中在 API 层（Gatekeeper 端点）
只在令牌生成时执行一次授权逻辑，而不是在每个形状请求时都执行
通过比较令牌中的形状声明与请求参数中的形状定义来实现细粒度访问控制

三种实现方案对比

1. API 同时作为 Gatekeeper 和代理

架构特点：

使用 Elixir/Phoenix 实现的 Web 应用
提供 /gatekeeper/:table 和 /proxy/v1/shape 两个端点
简单直接，适合小型应用或开发环境

操作流程：

构建并启动服务
通过 POST 请求获取令牌
使用令牌访问代理端点

2. Caddy 作为反向代理

架构特点：

API 仅处理认证和令牌发放
Caddy 服务器负责令牌验证和请求转发
性能更好，适合生产环境

配置要点：

需要正确设置 Caddyfile 配置
环境变量需要指向正确的服务地址

3. 边缘函数作为代理

架构特点：

设计运行在 CDN 边缘节点
使用 Deno 实现的轻量级 HTTP 服务器
最小化边缘节点的逻辑和权限需求

优势：

减少中心化代理带来的延迟
更自然的网络拓扑结构
保持 CDN 的性能优势

实践指南

环境准备

确保已安装：

Docker Compose
curl（用于测试 API）
psql（可选，用于数据库操作）
jq（可选，用于 JSON 格式化）

通用步骤

构建相关服务镜像
清理并启动服务
通过 Gatekeeper 端点获取令牌
使用令牌访问代理端点

常见问题排查

401 未授权：检查是否提供了有效的令牌
403 禁止访问：检查请求的形状是否与令牌中的声明匹配
空响应：可能是数据库中没有对应数据

进阶应用

与 TypeScript 客户端集成

项目提供了客户端示例，展示了如何：

在客户端代码中实现认证流程
处理令牌过期和刷新
与 Electric 的高级客户端 API 集成

数据库操作示例

可以通过 psql 连接数据库进行数据操作：

-- 连接数据库
psql "postgresql://postgres:password@localhost:54321/electric"

-- 查看表结构
\d

-- 查询数据
SELECT * FROM items;

-- 插入数据
INSERT INTO items (id) VALUES (gen_random_uuid());