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

> 依据：`松离线-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 示例：

```text
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，不是串库。

## 用户自助（库级三态）

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

1. 用户 JWT → `POST /api/v1/admin/sync/bindings`（带 `channel_id`）  
2. 同 JWT → `GET .../agent/sync/channels/{id}/whitelist`  
3. 同 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 可能再建回来。

## 开通步骤（增值）

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

## 谁能看什么

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

## 相关文档

- [同步表约定.md](./同步表约定.md)  
- [数据同步-迁移手册.md](./数据同步-迁移手册.md)（旧客从 HTTP 双写迁入）  
- [数据同步-中间件.md](./数据同步-中间件.md)