ee-database 同步客户端 - Entity Enricher 文档

ee-database 同步客户端

面向 架构数据库 的开源应用客户端。将它与你自己的 PostgreSQL 一起运行，只需配对一次，它便会让该数据库与你的富集结果保持一致——先从快照初始化，再通过单个出站 WebSocket 应用实时增量数据流。你的连接字符串绝不会离开你的机器。

Entity Enricher服务器 · 发件箱ee-database你的机器您的数据库Postgres · MySQL · SQLitebatch · 租约 120 秒apply — 单个事务提交ack 立即推送下一个窗口

每条语句都受修订校验保护，因此重新投递的批次会收敛到相同的行。SQL 错误会回滚整个批次并停止执行——有问题的增量绝不会被静默跳过。

客户端拉取的是 状态，而非操作：每个增量都以幂等的 INSERT … ON CONFLICT … DO UPDATE 形式携带已变更实体的完整当前行，因此即使漏掉某个批次，目标也能收敛一致。

为什么使用同步客户端？

架构数据库可通过多种方式使用——n8n、Make.com、MCP、原始 webhook，或 REST 增量数据流。同步客户端是完全自动化的方式：搭建最少，泄露风险也最小。

无需搭建任何工作流

无需 n8n 场景，无需 cron，无需胶水代码。配对一次即可从快照初始化，随后在每个增量到达时应用它。

你的 DSN 绝不会离开你的机器

连接字符串通过命令行传入，或以 mode-600 权限在本地存储——绝不会发送给 Entity Enricher。客户端仅向外连接。

从设计上即可安全重放

每个增量都是幂等、受修订校验保护的 upsert 操作。若客户端在批次中途中断，租约到期后会重新投递该批次，重新应用会收敛到相同的行。

出错即报，绝不静默

SQL 错误会回滚该批次，将失败的增量报告到数据库页面，并以非零状态退出——有害的增量绝不会被悄悄跳过。

快速开始

先在某个模式上注册数据库，然后配对客户端并在你的数据库旁运行它。

  1. 1

    注册数据库

    在 Databases 页面上，为你想要镜像的模式注册一个数据库，并查看其数据库键。完整模型请参阅 Databases。此步骤会声明客户端将应用的目标方言。

  2. 2

    安装客户端

    从 Releases 下载已签名的二进制文件，或从源代码构建（Go ≥ 1.23）。

    go build -o ee-database .

    源代码与签名发布版本位于 TOT-Concept/ee-database（MIT）。

  3. 3

    通过浏览器配对

    运行 ee-database pair。浏览器会打开 /database/connect 标签页并显示一个短码——确认它，然后选择此客户端应同步哪个数据库。

    ee-database pair --server https://entityenricher.ai

Open this URL in your browser to confirm pairing:
   https://entityenricher.ai/database/connect?code=7QX-KP2

  Code: 7QX-KP2

Waiting for confirmation...

    更喜欢用令牌？在 Databases 页面上签发一个（Sync client → Pair a client），然后直接传入：ee-database pair --server … <refresh-token>。

  4. 4

    在你的数据库旁运行它

    首次运行时，客户端会获取 .sql 快照并应用它，然后连接并流式接收增量。--save-dsn 会将连接字符串保存在本地，因此后续运行无需任何参数。

    ee-database run --dsn "postgres://user:pass@localhost:5432/mydb" --save-dsn

    “紧邻”指的是网络可达，而非运行在数据库服务器上：任何能访问该 DSN 的机器或容器都可以——包括云托管的 PostgreSQL（Azure、OVHcloud、AWS RDS…），它们通常强制使用 TLS：…/mydb?sslmode=require。

投递机制：租约与确认

增量通过严格的按数据库 FIFO 发件箱离开 Entity Enricher。服务器租用可见窗口 120 秒并将其作为一个批次推送；客户端在单个事务中应用整个批次，并回复 ack ，这会推进游标并立即触发下一个窗口。批次处理中途崩溃的客户端由租约到期和服务器端重新推送来兜底——不会丢失或重复提交任何内容。

快照 = 从零开始的增量

引导与稳态共用同一代码路径。如果你的数据库已初始化，可使用 --skip-bootstrap 跳过引导。

受修订校验保护

每条语句都带有 _sync_revision，因此较旧的行永远不会覆盖较新的行，即使顺序乱了也不会。

失败即停止

SQL 错误会将失败的增量 id 存储在数据库页面 → 同步客户端卡片上，进程以非零状态退出，供你的监控程序重启。

数据库与方言

目标方言由 Entity Enricher 中的架构数据库注册决定——客户端会应用服务器渲染出的任何 SQL。PostgreSQL 是首发方言；MySQL 和 SQLite 驱动已一并打包，待其 SQL 渲染器发布即可使用。多语句应用按驱动分别处理（pgx 简单协议、MySQL multiStatements，以及无需 CGO 的 SQLite）。

安全

仅出站

客户端通过 :443/wss 发起 WebSocket 连接。你的数据库主机从不接受入站连接——无需开放端口，也无需配置入口。

一个凭据、一个数据库、一个客户端

凭证绑定到单个 schema 数据库。再次配对会轮换凭证，并立即断开先前的活动连接。

短期访问令牌

365 天的刷新令牌（以 mode-600 权限存储）会兑换为用于验证 WebSocket 的 15 分钟访问令牌。在界面中撤销后，可在约 1 秒内断开在线客户端。

建议使用最小权限

让客户端以一个仅限于已同步架构的专用数据库角色运行，这样即使令牌泄露，也无法触及其他任何内容。

CLI 参考

命令它的功能
ee-database pair --server URL通过浏览器确认的设备码配对。选择要同步的数据库。
ee-database pair --server URL <token>使用在 Databases 页面签发的令牌进行配对（适合无界面环境）。
ee-database run --dsn DSN [--save-dsn] [--skip-bootstrap]从快照引导（除非被跳过），然后连接并应用增量。
ee-database run … --create-missing当目标数据库不存在时，先使用 DSN 自身的凭据创建它（postgres 需要 CREATEDB 权限，mysql 需要 CREATE 权限；sqlite 文件本就会自动创建）。
ee-database run … --create-missing --admin-dsn DSN通过管理员连接初始化目标 DSN 指定的所有内容：缺失的角色/用户（使用该 DSN 的密码）以及归其所有的数据库。此后目标 DSN 无需创建权限；管理员 DSN 绝不会被存储。
ee-database run --all在单个进程中并发同步所有已配对的数据库（每个都需要已保存的 DSN）。
ee-database status显示配对状态、服务器 URL 以及已配对的数据库。
ee-database disconnect忘记某个配对的本地凭据。可在界面中从服务器端撤销。
ee-database version打印版本。

凭据以 mode-600 权限存储，每个已配对数据库对应一个配置文件，位于 ~/.config/ee-database/profiles/ — 每个数据库只需配对一次；当配对了多个时，可用 --database NAME 选择其中一个。完全不想使用自动化？同样的数据源也提供纯 REST 接口：GET /api/databases//changes，然后 POST /api/databases//ack — 参见 数据库。

开源

该客户端采用 MIT 许可，并托管在公开仓库中，任何人都可以审计究竟有哪些内容在对其数据库运行。

源代码： github.com/TOT-Concept/ee-database

发布版本： github.com/TOT-Concept/ee-database/releases — 每个二进制文件在发布前都经过签名。