Files

whm b04b180d30 feat: harden loose-offline sync for user JWT, schema, and console ops

Enable Binding-scoped agent push/pull, empty-table schema ensure, SyncPage inspect/drop-table, default module import, and agent-bound publish docs from the 宇恒联调意见.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-05 09:47:35 +08:00

4.8 KiB

Raw Blame History

数据同步 · 开通说明（管理员）

依据：松离线-dbsync方案-最终版.md
默认客户无感：未显式开通时，终端保存与自增表行为与现网一致。

三分模式（客户端配置，智建通道为表白名单源）

模式	含义	谁改
`local_only`	仅本地，无同步	默认之一
`online_primary`	HTTP 双写 / 离线 pending（旧路径）	已配线上 API 且未写 MODE 时兼容升
`local_dbsync`	松离线 + 表白名单 + 本机 agent	仅显式配置，禁止自动升

智建控制台「数据同步」配的是通道 + 表白名单 + 线上 DSN；是否走 local_dbsync 由客户端环境变量决定，平台不会替全员切默认。

线上库 A：统一 Postgres

场景	推荐
生产 A	`postgres`（经智建 agent push 写入；可与平台同机或独立实例）
本机 B	宇恒侧多为 SQLite（通道 `local` 仅描述表白名单，形态 B 下平台可不连 B）
联调临时 A	可用 sqlite 文件；不宜多 agent 并发写

Postgres DSN 示例：

postgres://user:pass@127.0.0.1:5432/app_online?sslmode=disable

单服务器 / 多服务器（同一套 API）

同步一律经智建平台（agent → whitelist/push），不因服务器数量改协议。

部署	怎么配
单服务器	公司一条通道：`remote` 指向该 Postgres；宇恒配置一个 `YXD_SYNC_CHANNEL_ID`
多服务器	每台线上库一条通道（不同 remote DSN）；宇恒按 `local_database_id` / Binding 选用对应 `channel_id`（或多 agent 实例各绑一通道）

Binding：POST /api/v1/admin/sync/bindings 登记 local_database_id → online_db_id，并带上 channel_id。
管理员 Token 或登录用户 JWT均可登记；普通用户只能登记/查看本人 Binding。

模块与本机库（一份表 · Z8）

原则	说明
本机 B 管理面	模块业务表应能在宇恒本机库（如「AI建站智能体API」）里增删改查/导入，与普通表同一体验
上云	开通 sync 后经 outbox → agent push → 智能体绑定的线上库 A
智能体绑库	控制台「用户管理」为智能体填 `channel_id` / `online_db_id` / `database_name`；「数据同步」可按智能体筛通道
发布落库	智能体 Token 新建发布时，若已设 `database_name`，优先 `database_per_app` 写入该库

不要默认维持「模块只在平台 /apps schema、松离线又一套 SQLite」双轨；对账时本机有、线上无 = 尚未 push，不是串库。

用户自助（库级三态）

客户端对每个库可选：仅本地 / 仅线上 / 同步。选同步后：

用户 JWT → POST /api/v1/admin/sync/bindings（带 channel_id）
同 JWT → GET .../agent/sync/channels/{id}/whitelist
同 JWT → POST .../push，Body 须含本人 online_db_id

通道表白名单非空时只同步命中表；空名单时平台接受整库表名（UUID PK）。
「仅线上 / 下行拉齐」：POST .../agent/sync/channels/{id}/pull（mode=bootstrap|pks|rows）或 .../bootstrap；平台返回 A 上行，客户端写入本机 B。
空表也要两侧建齐：本机空表 → POST .../schema/ensure；线上空表 → POST .../schema（或 pull 的 columns）在本机 CREATE IF NOT EXISTS。仅靠 outbox 行 push 不会带上空表。
控制台「查看线上表」可删表（POST .../admin/sync/channels/{id}/drop-table）：只删当前查看侧，不同步 DROP 到另一侧；本机仍有同名表时下次 push/ensure 可能再建回来。

开通步骤（增值）

「数据同步」新建通道：remote.driver=postgres + 线上 DSN；表白名单须 UUID TEXT/UUID PK + FK 闭包。
方向 本地 → 线上，策略 源端覆盖（lww_source）。
客户端显式 YXD_SYNC_MODE=local_dbsync，配置 YXD_ONLINE_API_BASE、YXD_SYNC_CHANNEL_ID、token（见 同步表约定.md）。
装本机 sync agent 后才上云；未装：本地可保存，文案「需 agent 才上云」。
多库时登记 Binding，避免串库。

谁能看什么

角色	可见
公司管理员	通道配置、对账（同步修复）、统计；无冲突台 / LWW 覆盖明细
普通登录用户	不可配通道；可自助 Binding + 用登录 JWT push 本人库
平台超级管理员	LWW 覆盖审计（平台工作台）
未开通终端用户	零同步文案，无强制状态条

4.8 KiB Raw Blame History Unescape Escape