企业官网建设流程全解析

Electric Sync 服务安装指南：Docker 快速部署与 Elixir 源码构建全流程

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

Electric Sync 是运行在 Postgres 与客户端之间的一组同步服务，它消费 Postgres 的逻辑复制流（logical replication stream），并通过 HTTP 接口将数据的子集（Shape）同步到 Web、移动端、边缘服务乃至本地 AI 系统。本指南基于仓库中的 安装文档，系统讲解 Electric Sync 服务的两种安装路径——推荐的一键 Docker 部署，以及适合开发与二次开发的从源码构建方式，并深入剖析 Postgres 前置条件、连接配置与底层实现。读完本文，你将能够独立完成从"零环境"到"Electric 正在为你的数据库提供同步服务"的完整搭建，并能针对开发与生产场景做出正确的配置选择。

运行架构：Postgres 与 Electric Sync 服务

在动手安装之前，需要先明确 Electric 的运行模型。安装文档明确指出，使用 Electric 需要两个基本组件：

1. 一个 Postgres 数据库——承载业务数据，并开启逻辑复制能力；
2. Electric sync service——以 Web 应用形式运行在数据库"前面"，通过DATABASE_URL连接 Postgres，消费复制流并向客户端提供 HTTP API。

整个链路在 部署指南 中被概括为三个要素：运行 Postgres、运行并连接 Electric、客户端通过 HTTP 连接 Electric（通常借助 TypeScript Client 之类的客户端库）。其中 Postgres 可以是任意标准 Postgres 14+ 实例，无论是自建还是托管服务均可；而 Electric 本身是一个基于 Elixir 的 Web 服务，其核心实现位于仓库的 packages/sync-service 目录下。

从源码结构看，sync-service 是一个标准的 Mix 项目（见 mix.exs），应用名为:electric，依赖包括 Postgrex（数据库连接）、Bandit（HTTP 服务器）、pg_query_ex（SQL 解析）等，并通过Electric.Application启动整个同步引擎。

推荐方式：使用 Docker 运行 Electric

对于绝大多数场景，最简单可靠的方式是直接使用官方 Docker 镜像。Electric 以 Docker 镜像形式发布在electricsql/electric（镜像仓库位于website/public/docker-compose.yaml所引用的docker.io/electricsql/electric），它通过DATABASE_URL环境变量连接 Postgres。

方式一：Docker Compose 一键拉起（Postgres + Electric）

仓库在 website/public/docker-compose.yaml 中提供了一个可直接运行的 Compose 编排文件，它同时启动一个全新的 Postgres 和一个与之相连的 Electric 服务：

name: 'electric_quickstart' services: postgres: image: docker.io/postgres:16-alpine environment: POSTGRES_DB: electric POSTGRES_USER: postgres POSTGRES_PASSWORD: password ports: - '54321:5432' tmpfs: - /var/lib/postgresql/data - /tmp command: - -c - listen_addresses=* - -c - wal_level=logical healthcheck: test: ['CMD-SHELL', 'pg_isready -U postgres'] interval: 5s timeout: 5s retries: 5 electric: image: docker.io/electricsql/electric:latest environment: DATABASE_URL: postgresql://postgres:password@postgres:5432/electric?sslmode=disable # Not suitable for production. Only use insecure mode in development or if you've otherwise secured the Electric API. # See https://electric-sql.com/docs/guides/security ELECTRIC_INSECURE: true ports: - '3000:3000' depends_on: postgres: condition: service_healthy

这份配置中有几个值得注意的关键点：

• Postgres 的wal_level=logical：通过command段向 Postgres 传入启动参数，这是启用逻辑复制的前提（见下文"Postgres 前置要求"）。
• tmpfs数据目录：Postgres 数据存放在内存文件系统上，容器重启后数据即丢失，这非常适合快速试用与测试，但不适合保存重要数据。
• ELECTRIC_INSECURE: true：关闭 Electric 的认证要求，仅用于开发环境或已通过其他手段保护 API 的场景（详见 安全指南 与下方"生产环境注意事项"）。
• depends_on的健康检查联动：Electric 会等待 Postgres 通过pg_isready健康检查后才启动，避免启动竞态。

启动命令非常简单：

curl -O https://electric-sql.com/docker-compose.yaml docker compose up

说明：上述命令中的curl -O从 Electric 官网获取 Compose 文件。如果你在本地已有该仓库，也可以直接使用仓库内的 website/public/docker-compose.yaml 文件，无需额外下载。启动后，Electric 的 HTTP API 默认监听本机3000端口，Postgres 则暴露在54321端口（容器内为5432）。

方式二：单独运行 Electric 并连接已有 Postgres

如果你已经有一个正在运行的 Postgres 数据库，也可以只启动 Electric 容器并指向它：

docker run \ -e "DATABASE_URL=postgresql://..." \ -p 3000:3000 \ -t \ electricsql/electric:latest

这里的DATABASE_URL是唯一必需的关键配置。它必须采用 libpg 连接 URI 格式，即postgresql://[userspec@][hostspec][/dbname][?sslmode=<sslmode>]（见 配置参考）。其中：

• userspec指定 Electric 连接 Postgres 所使用的数据库用户，该用户必须具备REPLICATION角色；
• sslmode建议在生产环境设为require以启用 TLS 加密连接；
• 若连接出现non-existing domain - :nxdomain或network is unreachable - :enetunreach之类的 TCP 错误，可以尝试通过ELECTRIC_DATABASE_USE_IPV6=true启用 IPv6 连接。

容器内部的启动细节可以从 packages/sync-service/Dockerfile 中看到：镜像最终以nobody用户运行，入口为entrypoint start，并且内置了一个健康检查——通过curl --fail http://localhost:${ELECTRIC_PORT-3000}/v1/health检测服务状态，健康检查默认端口为 3000，可通过ELECTRIC_PORT环境变量调整。

Postgres 前置要求

安装文档强调，你可以使用任何已启用逻辑复制的新建或现有 Postgres 数据库，并且需要以具备REPLICATION角色的数据库用户身份连接。

具体来说，Electric 对 Postgres 的依赖体现在两个层面：

1. 逻辑复制（logical replication）：Postgres 服务端需要开启逻辑复制配置，即wal_level=logical。这正是上述 Compose 文件中通过-c wal_level=logical传入参数的用意。
2. REPLICATION数据库角色：Electric 连接数据库所用的用户必须拥有REPLICATION属性，否则无法建立复制流。

根据 PostgreSQL 权限指南，Electric 在不同运行模式下所需的权限也不同：

• 开发环境（推荐超级用户）：直接使用默认的postgres超级用户，Electric 会自动创建 publication、配置REPLICA IDENTITY FULL并管理一切。
• 生产环境自动模式：创建专有用户并转移表所有权，例如CREATE ROLE electric_user WITH LOGIN PASSWORD 'secure_password' REPLICATION;并配合GRANT CREATE ON DATABASE、GRANT SELECT ON ALL TABLES IN SCHEMA public以及ALTER TABLE ... OWNER TO electric_user。
• 手动模式（最小权限）：设置ELECTRIC_MANUAL_TABLE_PUBLISHING=true，仅授予REPLICATION与SELECT权限，由 DBA 预先创建 publication、添加表并配置REPLICA IDENTITY FULL。

从 packages/sync-service/config/runtime.exs 的源码可以看到，DATABASE_URL会被Electric.Config.parse_postgresql_uri!/1解析为连接选项（replication_connection_opts），同时还可以通过ELECTRIC_POOLED_DATABASE_URL单独指定一个用于复制之外查询的连接池地址（对应query_connection_opts）——这一设计允许你将普通查询请求导向连接池，而复制连接保持直连 Postgres。

进阶方式：从源码构建与运行

如果你希望参与开发、调试底层逻辑或定制 sync-service，可以从源码构建。安装文档给出了完整的构建流程，仓库的 packages/sync-service 目录即为 Electric 同步引擎的 Elixir 源码所在。

1. 克隆仓库

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

2. 使用 asdf 安装系统依赖

项目使用 asdf 中：

caddy 2.10.0 elixir 1.20.2 erlang 29.0.2 nodejs 24.11.1 pnpm 10.12.1

安装插件并执行asdf install即可一键装齐上述版本：

asdf plugin-add elixir asdf plugin-add erlang asdf plugin-add nodejs asdf plugin-add pnpm asdf install

注意：.tool-versions同时列出了nodejs与pnpm（以及caddy）。虽然运行 sync-service 本体只需要 Elixir 与 Erlang，但仓库是 pnpm workspace 结构（见根目录 pnpm-workspace.yaml），nodejs/pnpm用于仓库内 TypeScript 客户端等兄弟包的开发；按文档完整安装可以避免后续切换目录开发时遇到版本不一致的问题。

3. 安装 Elixir 依赖

进入 sync-service 目录，使用 Mix 拉取依赖：

cd packages/sync-service mix deps.get

依赖清单可以在 packages/sync-service/mix.exs 中查看，核心依赖包括postgrex（Postgres 驱动）、bandit（HTTP 服务器）、plug、jason（JSON 编解码）以及opentelemetry系列（遥测）等。值得注意的是，telemetry 相关依赖仅在MIX_TARGET=application目标下才会引入（见 mix.exs 中的telemetry_deps/1）。

4. 运行开发服务器

mix run --no-halt

启动时，Electric 会尝试使用DATABASE_URL连接 Postgres。开发环境的默认配置来自 packages/sync-service/.env.dev，其内容为：

ELECTRIC_LOG_LEVEL=debug DATABASE_URL=postgresql://postgres:password@localhost:54321/electric?sslmode=disable ELECTRIC_ENABLE_INTEGRATION_TESTING=true ELECTRIC_CACHE_MAX_AGE=1 ELECTRIC_CACHE_STALE_AGE=3 # using a small chunk size of 10kB for dev to speed up tests ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD=10000 # configuring a second database for multi-tenancy integration testing OTHER_DATABASE_URL=postgresql://postgres:password@localhost:54322/electric?sslmode=disable ELECTRIC_PROFILE_WHERE_CLAUSES=false ELECTRIC_OTEL_SAMPLING_RATIO=1 ELECTRIC_OTEL_DEBUG=false ELECTRIC_INSECURE=true ELECTRIC_TWEAKS_PROCESS_REGISTRY_PARTITIONS=1 ELECTRIC_TWEAKS_HTTP_API_NUM_ACCEPTORS=1

注意这里的DATABASE_URL指向localhost:54321——恰好与仓库提供的 Compose 文件中 Postgres 的对外端口一致。因此标准的开发流程是：先用docker compose拉起一个符合要求的 Postgres（例如website/public/docker-compose.yaml中的 postgres 服务，或 sync-service 目录下的 dev 编排），再执行mix run --no-halt启动 Electric。

从源码看，环境变量是在 config/runtime.exs 中通过Dotenvy加载的：开发与测试环境会依次读取.env.<env>、.env.<env>.local与系统环境变量；生产环境（:prod）则只读取系统环境变量。你可以编辑.env.dev文件，或直接以系统环境变量覆盖（系统环境变量优先级最高）来调整配置。

结合 runtime.exs 的实现，.env.dev中几个开发向配置的作用如下：

• ELECTRIC_LOG_LEVEL=debug：日志级别，runtime.exs中通过Electric.Config.parse_log_level!/1解析，默认:info；
• ELECTRIC_CACHE_MAX_AGE=1/ELECTRIC_CACHE_STALE_AGE=3：Shape 响应缓存的新鲜期与过期宽限（秒级），开发环境下调小便于立即看到数据变化；
• ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD=10000：Shape 日志单次响应的最大字节阈值，生产默认 10MB（10485760），开发环境刻意调小到 10KB 以加速测试；
• ELECTRIC_INSECURE=true：开发环境跳过 API 认证，便于本地调试；
• ELECTRIC_TWEAKS_HTTP_API_NUM_ACCEPTORS=1：HTTP 监听器 acceptor 进程数，生产默认 100。

5. 运行测试

要运行测试，你需要一个符合:test环境配置的 Postgres（即 config/runtime.exs 中:test环境所指向的数据库），然后执行：

mix test

从 mix.exs 中的 aliases 还可以看到几个开发辅助命令：mix start_dev/mix stop_dev通过docker compose启停本地开发用的 Postgres，mix reset则一键清理持久化数据并重建开发环境。

生产环境注意事项

安装文档将 Docker 快速启动定位为推荐路径，而将源码构建定位为进阶选项。如果你要在生产环境部署，仓库中的 部署指南 与 安全指南 提供了更完整的建议，这里提炼几个与安装直接相关的要点：

1. 关闭不安全模式并配置认证：ELECTRIC_INSECURE=true仅适合开发环境。生产环境必须配置ELECTRIC_SECRET（API token），所有请求需携带secret参数；更好的做法是将 Electric 置于授权代理（authorizing proxy）之后，由代理注入 token 并实现数据访问控制。
2. 持久化存储：Electric 会在文件系统上缓存 Shape 日志与元数据。默认存储目录可通过ELECTRIC_STORAGE_DIR配置（如ELECTRIC_STORAGE_DIR=/var/lib/electric/persistent），该目录必须能够跨服务重启存活。同时注意：磁盘上的缓存与 Postgres 中的复制槽/发布必须保持一致——若更换DATABASE_URL或ELECTRIC_STORAGE_DIR，需要手动清理另一侧的资源。
3. 健康检查：Electric 提供/v1/health端点，200表示完全就绪（返回{"status": "active"}），202表示启动中或等待复制锁。Docker 镜像自带的HEALTHCHECK正是基于该端点实现的（见 Dockerfile）。
4. 数据库资源：Electric 默认会在 Postgres 中创建名为electric_publication_default的发布与electric_slot_default的复制槽，可通过ELECTRIC_REPLICATION_STREAM_ID修改名称后缀；普通查询连接池大小默认 20，可通过ELECTRIC_DB_POOL_SIZE调整。

总结

安装 Electric 的核心是"一个开启逻辑复制的 Postgres + 一个通过DATABASE_URL连接它的 sync service"。对大多数用户，复制仓库内的 docker-compose.yaml 并执行docker compose up即可在几分钟内获得完整的同步环境；对需要深入开发与调试的场景，则可按照.tool-versions指定版本用 asdf 准备工具链，在 packages/sync-service 目录下通过mix deps.get、mix run --no-halt与mix test完成构建、运行与验证。无论哪种路径，都请牢记 Postgres 用户的REPLICATION角色与逻辑复制的wal_level=logical这两个不可省略的前置条件，并在生产环境遵循 安全指南 关闭不安全模式、启用认证与持久化存储。

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