electric-deployment

Electric — 部署

设置

Postgres 配置

# postgresql.conf
wal_level = logical
max_replication_slots = 10

Docker Compose

name: 'electric-backend'
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: electric
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    ports: ['54321:5432']
    volumes: ['./postgres.conf:/etc/postgresql/postgresql.conf:ro']
    tmpfs: ['/var/lib/postgresql/data', '/tmp']
    command: ['postgres', '-c', 'config_file=/etc/postgresql/postgresql.conf']

  electric:
    image: electricsql/electric:latest
    environment:
      DATABASE_URL: postgresql://postgres:password@postgres:5432/electric?sslmode=disable
      ELECTRIC_SECRET: ${ELECTRIC_SECRET}
    ports: ['3000:3000']
    volumes: ['electric_data:/var/lib/electric']
    depends_on: ['postgres']

volumes:
  electric_data:

Electric Cloud

npx @electric-sql/start my-app
pnpm claim && pnpm deploy

核心模式

环境变量

变量	必需	描述
DATABASE_URL	是	直接连接 Postgres（非连接池）
ELECTRIC_SECRET	是（生产环境）	API 身份验证密钥
ELECTRIC_INSECURE	仅开发环境	设置为 true 可跳过密钥要求
ELECTRIC_STORAGE_DIR	否	持久化 shape 缓存目录
ELECTRIC_POOLED_DATABASE_URL	否	用于非复制查询的连接池连接
ELECTRIC_DATABASE_USE_IPV6	否	设置为 true，使用 IPv6 Postgres 连接

Kubernetes 健康检查

livenessProbe:
  httpGet:
    path: /v1/health
    port: 3000
readinessProbe:
  exec:
    command: ['curl', '-sf', 'http://localhost:3000/v1/health']
  # Use exec, not httpGet — 202 means "alive but not ready"
  # Only 200 means fully ready for traffic

复制槽清理

-- When stopping Electric for extended periods:
SELECT pg_drop_replication_slot('electric_slot_default');

-- Prevent unbounded WAL growth:
ALTER SYSTEM SET max_slot_wal_keep_size = '10GB';
SELECT pg_reload_conf();

常见错误

严重：未将 wal_level 设置为 logical

错误：

# postgresql.conf (default)
wal_level = replica

正确：

wal_level = logical
max_replication_slots = 10

Electric 需要逻辑复制。默认的 wal_level = replica 不支持该功能。更改后需要重启 Postgres。

来源：packages/sync-service/dev/postgres.conf

严重：生产环境未设置 ELECTRIC_SECRET

错误：

docker run electricsql/electric \
  -e DATABASE_URL=postgres://user:pass@host/db

正确：

docker run electricsql/electric \
  -e DATABASE_URL=postgres://user:pass@host/db \
  -e ELECTRIC_SECRET=my-secret-key

从 v1.x 开始，ELECTRIC_SECRET 为必需项。如果未设置，除非设置了 ELECTRIC_INSECURE=true（仅开发环境），否则 Electric 将拒绝启动。

来源：packages/sync-service/CHANGELOG.md:832-834

中等：将临时存储用于 ELECTRIC_STORAGE_DIR

错误：

electric:
  image: electricsql/electric:latest
  # No volume — shape cache lost on restart

正确：

electric:
  image: electricsql/electric:latest
  volumes: ['electric_data:/var/lib/electric']

Electric 会在磁盘上缓存 shape 日志。临时存储会导致每次容器重启时都进行完整重新同步。

来源：website/docs/guides/deployment.md:133-157

高：Bun 代理在 256 个并发 fetch 请求时出现瓶颈

错误：

bun run proxy.ts

正确：

BUN_CONFIG_MAX_HTTP_REQUESTS=4096 bun run proxy.ts

在 Bun 运行时中，将身份验证／缓存代理部署在 Electric 前面时，请将 BUN_CONFIG_MAX_HTTP_REQUESTS 设置为与预期的并发 shape 请求数相匹配。Bun 默认将同时执行的 fetch() 调用数限制为 256，超出的请求会被静默排队——代理看似响应正常，但对 Electric 的上游调用会停滞，在负载下表现为延迟，而非错误。最大值为 65,336。Node 和 Deno 没有此限制。

来源：https://bun.com/docs/runtime/networking/fetch

中等：使用已弃用的 ELECTRIC_QUERY_DATABASE_URL

错误：

ELECTRIC_QUERY_DATABASE_URL=postgres://user:pass@pooler:6432/db

正确：

ELECTRIC_POOLED_DATABASE_URL=postgres://user:pass@pooler:6432/db

在 v1.3.x 中，名称从 ELECTRIC_QUERY_DATABASE_URL 更改为 ELECTRIC_POOLED_DATABASE_URL。旧名称将来可能停止工作。

来源：packages/sync-service/CHANGELOG.md:415

另请参阅：electric-proxy-auth/SKILL.md — 生产环境需要使用带有 ELECTRIC_SECRET 的代理。 另请参阅：electric-postgres-security/SKILL.md — 部署需要正确配置 Postgres。 另请参阅：electric-debugging/SKILL.md — 许多同步问题源于部署配置。

版本

目标版本为 Electric sync service v1.x。