企业官网建设流程全解析

Electric Cloud CLI 实战指南：用命令行管理 Electric Sync 数据源与 Electric Streams 服务

【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric

@electric-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四级资源层次来组织自己的资源：

CLI 正是在这一资源模型之上的终端控制面：它提供对 Cloud 资源的完整控制能力，所有命令都支持 JSON 输出，便于脚本化与自动化集成（参见 使用指南 中对资源层次与供给流程的完整说明）。

安装 CLI

CLI 以 npm 包形式发布，全局安装即可使用electric命令：

npm install -g @electric-sql/cli

如果不希望全局安装，也可以直接用npx临时运行，例如查看帮助：

npx @electric-sql/cli --help

npx 方式非常适合 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_TOKEN=sv_live_... electric projects list

token 以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:pass@host: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读取、?live=sse实时尾随）与 Streams 文档。

获取服务凭据

每个服务都有一对ID与secret：

• 服务ID唯一标识该资源；
• 服务secret是授予访问权限的令牌，应像数据库密码一样对待。

从终端获取凭据使用：

electric services get-secret svc_abc

该命令返回服务的 secret，供你在 API 请求或后端代理中注入使用（安全模型详见下文）。

Per-PR 环境：把供给与销毁写进 CI/CD

Electric 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_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_ID="8ea4e5fb-9217-4ca6-80b7-0a97581c4c10" export SECRET="<long secret value>" export SHAPE_DEFINITION="table=items&offset=-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 login，CI 用ELECTRIC_API_TOKEN，一次性命令用--token；
• 供给一条命令：electric services create postgres|streams配合--region按需拉起数据源或流服务；
• per-PR 开箱即用：--json+jq+--force支撑起 CI/CD 中的创建-供给-销毁闭环；
• 安全默认：secret 只在服务端注入，客户端永远走代理，配合 Auth 指南 形成完整的安全链路。

至此，从本地开发到云端生产、从手工交互到全自动流水线，你都可以在终端里完成对 Electric Sync 数据源与 Electric Streams 服务的全生命周期管理。

【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric