mcpField
E
electric-debugging

electric-debugging

github.com/electric-sql开发10.4k54 次安装3 周前更新
代码仓库

关于 electric-debugging

面向 @electric-sql/client 开发者的 Electric 同步故障排查技能，说明错误重试机制，并提供代理、CDN、SSE 和复制槽问题的诊断方法。

主要功能

  1. 01按错误类型说明重试行为
  2. 02诊断响应头缺失与 CORS
  3. 03排查快速循环与缓存键
  4. 04处理 SSE 代理缓冲
  5. 05指导清理复制槽

适用场景

  1. 01排查重复同步请求
  2. 02修复 Electric 响应头缺失
  3. 03解决实时更新延迟
  4. 04避免停止 Electric 后 WAL 持续增长

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/electric-sql/electric --skill electric-debugging

安装后在 Claude Code 中输入/electric-debugging确认已加载。

详细介绍

此技能基于 electric-shapes 和 electric-proxy-auth。请先阅读这两个技能。

Electric — 同步问题调试

设置

启用调试日志，查看重试和状态机行为：

import { ShapeStream, FetchError } from '@electric-sql/client'

const stream = new ShapeStream({
  url: '/api/todos',
  backoffOptions: {
    initialDelay: 1000,
    maxDelay: 32000,
    multiplier: 2,
    debug: true, // Logs retry attempts
  },
  onError: (error) => {
    if (error instanceof FetchError) {
      console.error(`Sync error: ${error.status} at ${error.url}`, error.json)
    }
    return {} // Always return {} to retry
  },
})

核心模式

错误重试行为
错误自动重试？操作
5xx 服务端错误是（指数退避）等待并重试
429 速率限制是（遵循 Retry-After）等待并重试
网络错误是（指数退避）等待并重试
4xx（非 429）否调用 onError — 返回 {} 以手动重试
MissingHeadersError永不修复 CORS/代理问题 — 即使 onError 返回 {} 也无法重试
诊断 MissingHeadersError

此错误表示 Electric 响应标头（electric-offset、electric-handle）被移除，通常是被 CORS 移除：

MissingHeadersError: This is often due to a proxy not setting CORS correctly
so that all Electric headers can be read by the client.

修复方法：在代理 CORS 配置中公开 Electric 标头：

headers.set(
  'Access-Control-Expose-Headers',
  'electric-offset, electric-handle, electric-schema, electric-cursor'
)
诊断快速循环检测

控制台消息：“Detected possible fast loop”，并附带诊断信息。

原因：代理/CDN 缓存键未包含 handle 和 offset 查询参数，因此客户端会反复收到相同的过期响应。

修复方法：确保代理/CDN 将所有查询参数纳入缓存键。

对于 Vercel，请在 vercel.json 中添加：

{
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "CDN-Cache-Control", "value": "no-store" },
        { "key": "Vercel-CDN-Cache-Control", "value": "no-store" }
      ]
    }
  ]
}

常见错误

高优先级：代理或 CDN 未将查询参数纳入缓存键

错误示例：

# nginx caching without query params in key
proxy_cache_key $scheme$host$uri;

正确示例：

# Include query params (handle, offset) in cache key
proxy_cache_key $scheme$host$request_uri;

同一 offset 下，500ms 内请求 5 次后会触发快速循环检测。客户端会自动清除缓存一次，然后应用退避策略，并在连续检测到 5 次后抛出错误。

来源：packages/typescript-client/src/client.ts:929-1002

高优先级：代理缓冲 SSE 响应

错误示例：

location /v1/shape {
  proxy_pass http://electric:3000;
  # Default: proxy_buffering on — SSE responses delayed
}

正确示例：

location /v1/shape {
  proxy_pass http://electric:3000;
  proxy_buffering off;
}

对于 Caddy：

reverse_proxy localhost:3000 {
  flush_interval -1
}

Nginx 和 Caddy 默认会缓冲响应，导致 SSE 实时更新延迟很长。请为 Electric 端点禁用缓冲。请勿完全禁用缓存 — Electric 会使用缓存标头合并请求。

来源：website/docs/guides/troubleshooting.md:69-109

中优先级：本地开发时运行 6 个或更多 shape，但未使用 HTTP/2

错误示例：

# Running Electric directly on localhost:3000
# With 7+ shapes, browser HTTP/1.1 queues all requests (6 connection limit)

正确示例：

# Run Caddy as HTTP/2 proxy on host (not in Docker — Docker prevents HTTP/2)
caddy run --config - --adapter caddyfile <<EOF
localhost:3001 {
  reverse_proxy localhost:3000
}
EOF

浏览器 HTTP/1.1 对每个源最多限制 6 个 TCP 连接。shape 较多时，请求会相互排队。请使用 Caddy 作为本地 HTTP/2 代理。

来源：website/docs/guides/troubleshooting.md:28-53

高优先级：Electric 停止后仍保留活跃的复制槽

错误示例：

docker stop electric
# Replication slot retains WAL indefinitely — disk fills up

正确示例：

docker stop electric

# Drop slot when stopping for extended periods
psql -c "SELECT pg_drop_replication_slot('electric_slot_default');"

# Or set a safety limit
psql -c "ALTER SYSTEM SET max_slot_wal_keep_size = '10GB';"
psql -c "SELECT pg_reload_conf();"

断开 Electric 连接后，复制槽会无限期保留 WAL，导致 Postgres 磁盘空间耗尽。请删除复制槽，或设置 max_slot_wal_keep_size。

来源：website/docs/guides/troubleshooting.md:203-316

另请参阅：electric-deployment/SKILL.md — 许多同步问题源于部署配置。 另请参阅：electric-shapes/SKILL.md — onError 语义和退避行为。

版本

目标版本为 @electric-sql/client v1.5.10。

评论

支持 Markdown