使用 Fly.io 部署 Electric 同步服务：Postgres、同步引擎与客户端应用的全栈实战

使用 Fly.io 部署 Electric 同步服务Postgres、同步引擎与客户端应用的全栈实战【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electricElectric 是一个构建在 Postgres 逻辑复制之上的实时同步平台其核心是发布为 Docker 镜像electricsql/electric的 Elixir 同步引擎sync service。本文基于仓库中 Fly.io 集成文档 展开完整讲解如何在 Fly.io 上分别部署 Postgres 数据库、Electric 同步服务与客户端应用从fly.toml配置、flyctl启动命令到健康检查验证与 IPv6 连接踩坑并辅以 同步服务配置参考、部署指南 和同步服务源码中的实现细节让你读完即可在 Fly.io 上跑通一整套可用的实时同步栈。Fly.io 与 Electric为什么是天然组合Fly.io 是一个面向需要快速交付的开发者构建的公共云平台。它的一个突出强项是部署 Elixir 应用而 Electric 的同步引擎正是一个 Elixir 应用源码位于 packages/sync-service因此 Fly.io 尤其适合用于部署Electric 同步服务见下文部署 Electric部署基于 Electric 的Phoenix 应用参见 Phoenix 集成文档。按照 Fly.io 集成文档 的划分你可以使用 Fly.io 部署 Electric 技术栈中的任意或全部组件组件说明部署章节Postgres 数据库存放业务数据是同步的变更来源部署 PostgresElectric 同步服务连接 Postgres通过 HTTP 对外提供 shape 同步部署 Electric客户端应用通过 HTTP 订阅 shape接收实时变更部署你的应用[!TIP] 需要更多背景 完整的部署架构与原则请参阅 部署指南。下文每个步骤都会给出与该指南、配置参考 和 故障排查指南 对应的交叉引用。部署前准备理解一次成功部署的三个要素在开始 Fly.io 配置之前先明确 部署指南 定义的三个要素运行一个 Postgres 数据库Electric 通过DATABASE_URL连接 Postgres你的应用则通过 HTTP 连接 Electric通常借助官方 TypeScript 客户端库。运行并连接 Electric 同步服务它负责从 Postgres 捕获变更并组织成 shape 同步流。让应用/客户端通过 HTTP 连接 Electric客户端从/v1/shape等 HTTP 端点拉取数据。关于 Postgres 侧需要注意两个硬性前提详见部署指南必须启用逻辑复制logical replication连接使用的数据库角色必须具备REPLICATION属性。此外配置参考 明确说明DATABASE_URL是 Electric 的两个必需配置项之一另一个是ELECTRIC_SECRET。连接字符串需符合 libpg Connection URI 格式postgresql://[userspec][hostspec][/dbname][?sslmodesslmode]生产环境建议将sslmode设为require。第一步在 Fly 上部署 Postgres在 Fly 上部署 Postgres 有两种途径Fly.io 集成文档 给出了清晰的取舍Fly Postgres它不是托管 Postgres 服务。需要参照部署指南中 Running Postgres 一节的通用建议自行完成逻辑复制启用、REPLICATION角色配置等步骤。Fly 的 Supabase Postgres这是由 Supabase 提供底层能力的托管 Postgres 服务。Supabase Postgres 默认已启用逻辑复制且具备 Electric 所需的权限是开箱即用的选择。如果选择 Supabase Postgres集成文档 有一条关键提醒连接时必须使用 IPv6 的DATABASE_URL而不是DATABASE_POOLER_URL。原因在 Supabase 集成文档 中有详细解释连接池poolerURL 不支持逻辑复制必须使用直连 URL而该直连 URL 目前只支持 IPv6。因此需要在 Electric 侧开启 IPv6 连接ELECTRIC_DATABASE_USE_IPV6true该变量的行为在 配置参考 中有明确说明默认值为false设为true后Electric 会优先通过 IPv6 连接数据库若 IPv6 解析失败则回退到 IPv4 DNS 查找。从 runtime.exs 源码可以看到该开关最终被并入复制连接与查询连接的连接选项中extra_conn_opts Enum.reject( [ipv6: database_ipv6_config, cacertfile: database_cacertfile], fn {_, val} - is_nil(val) end )关于 IPv6 的更多排障细节例如 Docker 守护进程的 IPv6 网络配置见 故障排查指南的 IPv6 支持一节。第二步部署 Electric 同步服务这是本文的核心操作。整个流程只有三个动作写fly.toml、运行flyctl launch、curl 健康检查。编写 fly.toml 配置将以下配置复制到名为fly.toml的文件中替换应用名称和DATABASE_URLapp YOUR_UNIQUE_APP_NAME [build] image electricsql/electric:latest [env] DATABASE_URL postgresql://... ELECTRIC_DATABASE_USE_IPV6 true [http_service] internal_port 3000 force_https true [[http_service.checks]] interval 10s timeout 2s grace_period 20s method GET path /v1/health逐项解读这份配置背后的设计依据[build] image electricsql/electric:latest直接使用官方 Docker 镜像。同步引擎是一个用 Docker 打包的 Elixir Web 服务见 部署指南镜像发布在 Docker Hub 的electricsql/electric仓库。DATABASE_URLPostgres 连接字符串是必需配置项配置参考。注意要填直连地址而不是连接池地址——Electric 依赖逻辑复制而大多数连接池不支持它pgBouncer 自 1.23 起才支持。如果还想为复制之外的其他查询单独走一个连接池可以额外设置ELECTRIC_POOLED_DATABASE_URL。ELECTRIC_DATABASE_USE_IPV6 true对应上文 Fly 上 Supabase Postgres 的 IPv6 直连要求。若你的数据库同时支持 IPv6/IPv4也可以省略此变量让 Electric 走默认的 IPv4 解析。internal_port 3000Fly 平台把公网流量转发到容器的 3000 端口这正是 Electric HTTP API 的默认端口ELECTRIC_PORT默认值3000见 配置参考。force_https true强制 HTTPS 访问符合生产环境对传输安全的要求。[[http_service.checks]]Fly 平台健康检查指向/v1/health端点。该端点不需要认证即使设置了ELECTRIC_SECRET也能正常响应部署指南。检查参数含义interval检查间隔 10 秒、timeout单次超时 2 秒、grace_period启动宽限期 20 秒避免服务冷启动时被误判为不健康。使用 flyctl 启动在包含fly.toml的同一目录下使用flyctl客户端 执行flyctl launch --copy-config --hafalse参数说明--copy-config沿用当前目录下已编写好的fly.toml而不是让 flyctl 重新生成--hafalse关闭高可用冗余只启动单实例。这一点对 Electric 尤其重要——在 状态监控源码 中可以看到实例启动需要先获取 Postgres 侧的 advisory lockpg_lock_acquired条件同一数据库上同时存在多个写实例会互相等待锁这也是滚动升级时需要特殊处理的原因。单实例部署是 Fly.io 上最简单可靠的形态。验证健康检查启动后请求健康检查端点确认一切正常$ curl https://YOUR_UNIQUE_APP_NAME.fly.dev/v1/health {status:active}返回{status:active}表示服务已完全就绪。这个端点的行为可以在源码中找到完整实现health_check_plug.ex 将 status_monitor.ex 的内部状态映射为 HTTP 状态码与状态文本HTTP 状态响应含义200{status: active}完全可用可以处理 shape 请求202{status: waiting}正在等待获取复制锁advisory lock已可只读服务已有 shape202{status: starting}正在启动、建立数据库连接200{status: active}连接已缩放至零scale-to-zero的休眠态收到请求会透明恢复源码中:sleeping映射为200 active实际状态由StatusMonitor综合 8 个就绪条件pg_lock_acquired、replication_client_ready、admin_connection_pool_ready、snapshot_connection_pool_ready、shape_log_collector_ready、supervisor_processes_ready、integrety_checks_passed、shape_metadata_ready推导而来。若长期停留在starting可参考 故障排查指南 检查是否存在未提交的挂起事务、数据库连接池误用或权限问题。此外健康检查响应带有Cache-Control: no-cache, no-store, must-revalidate头见 health_check_plug.ex避免被 CDN 或浏览器缓存导致探活结果失真。第三步部署你的客户端应用Fly.io 可以运行大多数类型的应用包括静态站点。客户端应用与 Electric 的对接方式非常简单通过 HTTP 请求/v1/shape端点订阅 shape。部署指南给出了典型写法const stream new ShapeStream({ url: https://your-electric-service.example.com/v1/shape, params: { table: foo, }, }) const shape new Shape(stream)在 Fly 场景下把url换成你上一步部署的 Electric 服务地址即可例如https://YOUR_UNIQUE_APP_NAME.fly.dev/v1/shape。任何能发起 HTTP 请求的语言/环境都可以接入完整的协议细节见 HTTP API 文档 与 TypeScript 客户端文档。生产环境强化建议部署指南与配置参考还给出了几个在 Fly.io 上跑生产环境必须关注的点建议按需补充到fly.toml的[env]中1. 持久化存储ELECTRIC_STORAGE_DIRElectric 会把 Shape 日志shape logs与元数据缓存在文件系统上部署指南 的Optimizing for disk一节。存储路径通过ELECTRIC_STORAGE_DIR配置默认值为./persistent见 配置参考。部署指南强调该目录中的数据必须能在服务重启后存活。从这一点可以推断在 Fly 上生产部署时应当为应用挂载 Fly Volume 等持久化磁盘并把ELECTRIC_STORAGE_DIR指向挂载路径例如/var/electric。若使用 Fly 默认的临时文件系统每次机器重建都会丢失已缓存的 shape 数据触发全量重同步。磁盘性能的优先级从高到低依次是磁盘速度 内存 CPU。2. 安全ELECTRIC_SECRET与访问控制配置参考明确指出默认情况下 Electric API 是公开的会以ELECTRIC_SECRET校验所有 shape 请求因此生产环境必须设置ELECTRIC_SECRET除非设置ELECTRIC_INSECUREtrue的显式不安全模式。同时建议参照 部署指南的 Securing data access 一节 对 Electric 的 HTTP API 做网络级访问控制或在其前面加一层带认证/授权的代理。3. 代理与缓存Electric 被设计为运行在缓存代理之后Nginx、Caddy、Varnish 或 Cloudflare 等 CDN。虽然不强制但加上缓存代理可以利用 Electric 的缓存头做请求合并request collapsing显著降低并发连接数、提升大规模客户端订阅时的性能。注意代理必须保留响应中的electric-...头否则客户端会因缺少必要响应头而报错故障排查指南。4. 可观测性同步服务支持通过ELECTRIC_OTLP_ENDPOINT导出 OpenTelemetry 追踪也支持ELECTRIC_PROMETHEUS_PORT暴露 Prometheus 指标配置参考。部署指南有一条重要警告如果启用了 Prometheus 端口就必须定期抓取否则指标会在内存中无限累积导致服务崩溃只使用 OpenTelemetry 时应保持ELECTRIC_PROMETHEUS_PORT不设置。5. 监控 WAL 增长Electric 会在 Postgres 中创建逻辑复制槽默认名为electric_slot_default来跟踪 WAL 位置。若槽位长期不推进Postgres 会持续保留 WAL 文件导致存储膨胀。建议在数据库侧设置max_slot_wal_keep_size如10GB作为上限并定期用pg_replication_slots查询槽位状态故障排查指南。如果决定停止使用某个数据库记得同时清理复制槽和electric_publication_default发布保持 Postgres 内持久状态与磁盘上 shape 缓存的一致性。小结与相关资源至此你已经在 Fly.io 上完成了 Electric 技术栈的三层部署用 Supabase PostgresIPv6 直连或自管 Fly Postgres 作为数据源用fly.tomlflyctl launch --copy-config --hafalse拉起同步服务并以/v1/health验证可用性最后让任意 HTTP 客户端订阅/v1/shape获得实时同步。Fly.io 对 Elixir 应用的天然支持让它成为自托管 Electric 同步服务的理想平台之一。若想深入了解各环节建议继续阅读仓库中的以下文档Fly.io 集成文档本文的原始依据部署指南三层部署架构、Postgres 要求、存储与健康检查细节同步服务配置参考全部环境变量及默认值Supabase 集成文档托管 Postgres 的 IPv6 直连细节故障排查指南IPv6 支持、WAL 增长、权限问题等常见坑。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考