Electric Cloud CLI 实战指南用命令行管理 Electric Sync 数据源与 Electric Streams 服务【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electricelectric-sql/cli是 Electric Cloud 提供的官方命令行界面让你无需打开浏览器即可在终端中管理云端资源从创建工作区、项目、环境到按需拉起 Electric Sync 数据源与 Electric Streams 服务再到在 CI/CD 流水线中创建与销毁 per-PR 预览环境。读完本文你将掌握 CLI 的安装、三种认证方式的优先级、数据源与服务的一键供给命令、凭据安全获取方法以及基于 JSON 输出的全自动化脚本编写能力。为什么需要命令行管理 Cloud 资源Electric Cloud 是 Electric 的托管平台负责托管运行 Electric Streams 与 Electric Sync。与自托管在仓库的 examples 目录中可以看到基于 Docker 与 SST 的多种本地部署示例不同Cloud 模式下基础设施由平台托管用户只需要通过workspace → project → environment → service四级资源层次来组织自己的资源层级含义典型命名workspace团队或组织acme-incproject每个应用或产品一个my-appenvironment部署环境如production、staging、per-PR 预览pr-1234service一个 Electric Sync 数据源或一个 Electric Streams 服务器svc_abcCLI 正是在这一资源模型之上的终端控制面它提供对 Cloud 资源的完整控制能力所有命令都支持 JSON 输出便于脚本化与自动化集成参见 使用指南 中对资源层次与供给流程的完整说明。安装 CLICLI 以 npm 包形式发布全局安装即可使用electric命令npm install -g electric-sql/cli如果不希望全局安装也可以直接用npx临时运行例如查看帮助npx electric-sql/cli --helpnpx 方式非常适合 CI 流水线或一次性操作场景——无需预先安装任何东西。认证三种凭据来源与优先级CLI 在执行任何需要身份的操作前会按固定顺序检查凭据取第一个命中的来源1. 浏览器登录交互式使用首选electric auth login该命令会在浏览器中打开 Electric Cloud 控制台通过 OAuth 完成登录。认证成功后会话会保存在本地的~/.config/electric/auth.json有效期7 天。适合开发者日常在终端中进行交互式操作。2.ELECTRIC_API_TOKEN环境变量CI/CD 推荐为流水线设置 API token无需任何交互export ELECTRIC_API_TOKENsv_live_... electric projects listtoken 以sv_live_前缀开头应作为机密妥善管理如 CI 平台的 Secret 配置不要硬编码进代码仓库。3.--token参数一次性命令对于单条命令或脚本可以直接把 token 作为参数传入electric projects list --token sv_live_...该方式的优点是作用域仅限于当前命令适合临时调试。三种来源的优先级固定为浏览器登录会话 →ELECTRIC_API_TOKEN环境变量 →--token参数。熟悉这一顺序有助于排查为什么命令用了别的凭据这类问题。供给一个 Electric Sync 数据源Electric Sync 会连接你的 Postgres 数据库通过逻辑复制消费变更并将其以可缓存的 HTTP Shape 形式对外提供详见 Sync 文档。在 Cloud 上供给数据源需要三个步骤创建项目、创建环境、创建服务。# 1. 创建一个项目每个应用/产品一个 electric projects create --name my-app # 2. 在项目下创建一个环境如 staging electric environments create --project proj_abc --name staging # 3. 在环境中创建一个 Postgres 类型的数据源服务 electric services create postgres \ --environment env_abc \ --database-url postgresql://user:passhost:5432/db \ --region us-east-1要点说明--database-url传入的是你的 PostgreSQL 连接串Cloud 侧会用它建立到数据库的逻辑复制连接。连接串中的数据库需要满足 部署指南 与 PostgreSQL 权限指南 中列出的逻辑复制配置要求并确保数据库可被 Electric Cloud 访问。--region指定部署区域如us-east-1选择靠近你数据库与应用用户的区域有助于降低同步延迟。命令返回的资源 ID如proj_abc、env_abc会被后续命令作为参数引用建议在脚本中用变量保存。供给一个 Electric Streams 服务Electric Streams 是开放的 Durable Streams 协议持久、只追加、可回放的 HTTP 流的托管实现适合事件、Agent 循环与实时数据场景。供给一个 Streams 服务只需一条命令electric services create streams \ --environment env_abc \ --region us-east-1创建成功后你会得到一个 base URL 与一个 service secret。之后便可以向流POST事件、从任意 offsetGET回放数据具体协议交互可参考 Streams 快速开始如PUT /v1/stream/hello创建流、POST追加数据、GET ?offset-1读取、?livesse实时尾随与 Streams 文档。获取服务凭据每个服务都有一对ID与secret服务ID唯一标识该资源服务secret是授予访问权限的令牌应像数据库密码一样对待。从终端获取凭据使用electric services get-secret svc_abc该命令返回服务的 secret供你在 API 请求或后端代理中注入使用安全模型详见下文。Per-PR 环境把供给与销毁写进 CI/CDElectric Cloud 的环境非常轻量拉起与销毁成本都很低天然适合 per-PR 预览部署场景。CLI 对这一场景提供了一等支持配合--json输出与jq即可在流水线中全自动完成创建、供给、销毁的完整生命周期# 为 PR 创建一个环境并用 jq 从 JSON 输出中提取环境 ID ENV_ID$(electric environments create \ --project $PROJECT_ID --name pr-$PR_NUMBER \ --json | jq -r .id) # 在该环境中供给 Sync 数据源 electric services create postgres \ --environment $ENV_ID \ --database-url $DATABASE_URL \ --region us-east-1 # PR 关闭时销毁环境--force 跳过交互确认 electric environments delete $ENV_ID --force这套模式把环境命名如pr-$PR_NUMBER、资源供给与清理全部封装为无人工介入的脚本步骤是 CI/CD 中预览部署的标准做法使用指南 的 Operations 一节同样推荐这一模式。环境变量CLI 支持以下环境变量用于免参数地指定默认行为变量说明ELECTRIC_API_TOKENAPI 认证令牌ELECTRIC_WORKSPACE_ID默认 workspace IDELECTRIC_API_URL覆盖 API base URL例如访问自托管或区域化端点其中ELECTRIC_API_URL在代理、调试或接入非默认端点时尤其有用。JSON 输出与脚本化所有 CLI 命令都支持--json输出机器可读的结构化结果便于脚本解析electric projects list --json配合jq等工具即可在 shell 中完成字段提取前面的 per-PR 示例就是典型用法。一个重要的行为差异破坏性命令delete、revoke在--json模式下必须显式加--force因为 JSON 模式下没有交互提示CLI 默认拒绝执行破坏性操作以避免误删。源码视角CLI 背后的安全模型与代理模式理解 CLI 管理的资源在运行时的安全模型有助于正确编排命令。根据 使用指南 与 安全指南Cloud 上的每个服务通过ID secret鉴权请求 shape 或流时需要携带凭据例如向 Sync 数据源发起 shape 请求export SOURCE_ID8ea4e5fb-9217-4ca6-80b7-0a97581c4c10 export SECRETlong secret value export SHAPE_DEFINITIONtableitemsoffset-1 curl -i https://api.electric-sql.cloud/v1/shape?$SHAPE_DEFINITION\ source_id$SOURCE_ID\ secret$SECRET切勿在客户端代码中内嵌 service secret一旦 secret 暴露给恶意用户对方即可直接连接你的服务。官方文档明确建议secret 只能由你的后端或 Auth 代理 注入到origin request中客户端只访问不带凭据的端点。推荐的代理模式是客户端通过ShapeStream正常请求 shape不携带source_id与secret由后端如 Next.js Route Handler、边缘 Worker 或现有 API在校验用户身份后把凭据注入转发请求。这一点在 TypeScript 客户端文档 中被明确列为生产环境的推荐实践ELECTRIC_PROTOCOL_QUERY_PARAMS常量可用来精确转发 Electric 协议参数。同样的代理模式也适用于 Electric Streams——secret 永远只存在于服务端。仓库中的 proxy-auth 示例 实现了完整的端到端参考实现而 gatekeeper-auth 示例 展示了另一种基于 API 签发 shape 级访问令牌的模式均可作为落地参考。在 CI/CD 中这正好与 CLI 的electric services get-secret svc_abc命令衔接流水线可以在供给服务后安全地拉取 secret注入到代理部署的运行时环境中实现供给 → 取凭据 → 部署代理 → 清理的全自动闭环。小结electric-sql/cli把 Electric Cloud 的完整资源生命周期压缩为一组简单、可组合、可脚本化的命令安装零成本npm install -g electric-sql/cli或npx即用认证三选一交互用electric auth loginCI 用ELECTRIC_API_TOKEN一次性命令用--token供给一条命令electric services create postgres|streams配合--region按需拉起数据源或流服务per-PR 开箱即用--jsonjq--force支撑起 CI/CD 中的创建-供给-销毁闭环安全默认secret 只在服务端注入客户端永远走代理配合 Auth 指南 形成完整的安全链路。至此从本地开发到云端生产、从手工交互到全自动流水线你都可以在终端里完成对 Electric Sync 数据源与 Electric Streams 服务的全生命周期管理。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考