终极指南：Electric同步链路加密与认证机制全解析

终极指南：Electric同步链路加密与认证机制全解析

【免费下载链接】electricRead-path sync engine for Postgres that handles partial replication, data delivery and fan-out.项目地址: https://gitcode.com/GitHub_Trending/el/electric

Electric是一个针对Postgres的读取路径同步引擎，专注于处理部分复制、数据交付和扇出。在当今数据驱动的应用环境中，确保数据在传输过程中的安全性和访问控制的严密性至关重要。本指南将深入剖析Electric同步链路的加密与认证机制，为新手和普通用户提供专业易懂的安全配置实践。

为什么Electric同步安全如此重要？

在分布式应用架构中，数据同步链路如同信息高速公路，一旦出现安全漏洞，可能导致敏感数据泄露、未授权访问等严重后果。Electric作为Postgres的同步引擎，其安全机制直接关系到整个应用的数据安全防线。

图1：Electric同步链路中的认证流程，展示了客户端、Gatekeeper、Proxy和Electric之间的交互过程

Electric安全架构核心组件

Electric的安全体系建立在多个核心组件协同工作的基础上，每个组件都承担着特定的安全职责，共同构建起坚固的数据保护屏障。

1. Gatekeeper认证服务

Gatekeeper作为Electric安全架构的第一道防线，负责对客户端进行身份验证并颁发访问令牌。在示例项目examples/gatekeeper-auth/中，完整展示了这一机制的实现。

认证流程如下：

1. 客户端向Gatekeeper发送认证请求
2. Gatekeeper验证客户端身份后返回带有令牌的响应
3. 客户端使用令牌通过Proxy访问Electric服务

2. 代理服务器（Proxy）

代理服务器是Electric安全架构的核心，所有客户端请求必须经过代理转发，杜绝直接访问Electric服务的可能。代理服务器在packages/typescript-client/skills/electric-proxy-auth/SKILL.md中有详细配置说明。

3. 数据库权限控制

Postgres数据库本身的权限配置是Electric安全的基础。Electric用户必须正确配置REPLICATION角色、SELECT权限等关键权限，具体检查项可参考packages/typescript-client/skills/electric-postgres-security/SKILL.md。

一步一步配置Electric安全机制

前置准备：环境与依赖

开始配置前，请确保已克隆Electric项目：

git clone https://gitcode.com/GitHub_Trending/el/electric cd electric

配置Postgres安全设置

1. 创建具有REPLICATION角色的Electric用户：

CREATE USER electric_user WITH PASSWORD 'your_secure_password' REPLICATION; GRANT SELECT ON ALL TABLES IN SCHEMA public TO electric_user;

2. 设置表的REPLICA IDENTITY为FULL：

ALTER TABLE your_table REPLICA IDENTITY FULL;

3. 验证Postgres配置：

SHOW wal_level; -- 应返回logical

配置代理服务器

以下是一个基本的代理服务器配置示例（基于Next.js App Router）：

import { ELECTRIC_PROTOCOL_QUERY_PARAMS } from '@electric-sql/client' export async function GET(request: Request) { const url = new URL(request.url) const originUrl = new URL('/v1/shape', process.env.ELECTRIC_URL) // 仅转发Electric协议参数，防止客户端控制敏感参数 url.searchParams.forEach((value, key) => { if (ELECTRIC_PROTOCOL_QUERY_PARAMS.includes(key)) { originUrl.searchParams.set(key, value) } }) // 服务器端设置shape定义，确保安全控制 originUrl.searchParams.set('table', 'todos') originUrl.searchParams.set('secret', process.env.ELECTRIC_SOURCE_SECRET!) const response = await fetch(originUrl) const headers = new Headers(response.headers) // 清理可能导致问题的响应头 headers.delete('content-encoding') headers.delete('content-length') // 配置CORS以允许Electric特定头 headers.set( 'Access-Control-Expose-Headers', 'electric-offset, electric-handle, electric-schema, electric-cursor' ) return new Response(response.body, { status: response.status, statusText: response.statusText, headers, }) }

客户端安全连接配置

import { ShapeStream } from '@electric-sql/client' const stream = new ShapeStream({ url: '/api/todos', // 指向代理路由，而非直接访问Electric headers: { Authorization: async () => `Bearer ${await getToken()}`, }, onError: async (error) => { if (error instanceof FetchError && error.status === 401) { const newToken = await refreshToken() return { headers: { Authorization: `Bearer ${newToken}` } } } return {} }, })

常见安全错误与解决方案

错误1：将所有客户端参数转发到Electric

错误示例：

// 危险！允许客户端控制所有参数 url.searchParams.forEach((value, key) => { originUrl.searchParams.set(key, value) })

正确做法：

// 仅转发Electric协议参数 import { ELECTRIC_PROTOCOL_QUERY_PARAMS } from '@electric-sql/client' url.searchParams.forEach((value, key) => { if (ELECTRIC_PROTOCOL_QUERY_PARAMS.includes(key)) { originUrl.searchParams.set(key, value) } }) // 服务器端设置表名等敏感参数 originUrl.searchParams.set('table', 'todos')

错误2：将ELECTRIC_SECRET暴露给客户端

错误示例：

// 客户端代码中直接使用密钥 const url = `/v1/shape?table=todos&secret=${import.meta.env.VITE_ELECTRIC_SOURCE_SECRET}`

正确做法：

// 仅在服务器代理中使用密钥 originUrl.searchParams.set('secret', process.env.ELECTRIC_SOURCE_SECRET!)

错误3：直接从客户端调用Electric服务

错误示例：

new ShapeStream({ url: 'https://my-electric.example.com/v1/shape', // 直接访问Electric params: { table: 'todos' }, })

正确做法：

new ShapeStream({ url: '/api/todos', // 通过代理路由访问 })

Electric安全检查清单 📋

部署前请确保完成以下安全检查：

• Electric用户具有REPLICATION角色
• Electric用户对所有同步表有SELECT权限
• 所有同步表已设置REPLICA IDENTITY FULL
• DATABASE_URL使用直接Postgres连接（非连接池）
• Postgres配置中wal_level = logical
• 已设置ELECTRIC_SECRET，未使用ELECTRIC_INSECURE=true
• 所有密钥仅在服务器端注入（不在客户端代码中）
• 已正确配置CORS，暴露Electric所需响应头

图2：Electric数据同步安全流程全景图，展示了从Postgres到客户端的完整数据流向和安全控制点

总结

Electric提供了一套全面的同步链路加密与认证机制，通过Gatekeeper认证服务、代理服务器和数据库权限控制的协同工作，确保数据在传输过程中的安全性。遵循本指南中的最佳实践，您可以为您的Electric部署构建起坚固的安全防线，保护敏感数据免受未授权访问和潜在的安全威胁。

如需更深入的安全配置细节，请参考官方文档：

• Electric Postgres安全检查清单
• Electric代理认证配置指南

【免费下载链接】electricRead-path sync engine for Postgres that handles partial replication, data delivery and fan-out.项目地址: https://gitcode.com/GitHub_Trending/el/electric