whm
76cdcd760e
Add UUID/FK channel checks, agent whitelist/push APIs, bindings, super-admin LWW audit with rollback, reconcile rate limits, and sync docs. Default customers stay opt-in; company conflict UI is removed. Co-authored-by: Cursor <cursoragent@cursor.com>
41 lines
2.0 KiB
Markdown
41 lines
2.0 KiB
Markdown
# 数据同步 · 迁移手册（O7）
|
||
|
||
> 从旧路径 `online_primary`（HTTP 双写）迁到 `local_dbsync`（松离线 + agent）。
|
||
> **禁止静默迁移、禁止全员一刀切关双写。**
|
||
|
||
## 硬规则
|
||
|
||
1. **旧客默认不变**：未评估、未签字前不得改默认模式。
|
||
2. **同表互斥**：某表不得「一边 HTTP 双写、一边进 dbsync 白名单」。
|
||
3. **顺序不可颠倒**：先停该表双写 → 再进白名单 / 切 `local_dbsync`。
|
||
4. **agent 非安装强依赖**：迁移观察期允许只落本地 + 积压；须告知「需 agent 才上云」。
|
||
|
||
## 推荐流程（单表 / 单库）
|
||
|
||
| 步骤 | 动作 | 验收 |
|
||
|------|------|------|
|
||
| 1 | 智建通道准备：目标表白名单、UUID PK 校验通过、remote DSN 可达 | 保存通道成功 |
|
||
| 2 | 客户端仍 `online_primary`：对该表**停止**双写（或从双写表白名单移除） | 该表仅写本地或仅走约定路径 |
|
||
| 3 | 观察 ≥1 个业务周期：无双写残留、无重复行 | 抽查线上/本地主键 |
|
||
| 4 | 显式设 `YXD_SYNC_MODE=local_dbsync`，写入表白名单缓存/通道拉名单 | `/sync/status` 显示 local_dbsync |
|
||
| 5 | 登记 Binding（可选）`local_database_id → online_db_id` | GET bindings 命中 |
|
||
| 6 | 装本机 agent，观察 outbox 清空、同 UUID 上云 | agent push 成功；超管可查 LWW（若有覆盖） |
|
||
| 7 | 确认稳定后再扩大白名单；**勿**对全员默认切模式 | 旧客未改默认 |
|
||
|
||
## 回滚
|
||
|
||
1. 客户端改回 `online_primary` 或 `local_only`。
|
||
2. 智建侧可停通道 / 缩表白名单（勿删线上数据）。
|
||
3. 未推完的 outbox 由对方客户端自行处理；平台不强制清。
|
||
|
||
## 新客评估（M4）
|
||
|
||
仅对**新客**或**书面确认的迁移客**评估是否默认 `local_dbsync`。
|
||
M4 前：**禁止**全员切默认。
|
||
|
||
## 相关
|
||
|
||
- [数据同步-开通说明.md](./数据同步-开通说明.md)
|
||
- [同步表约定.md](./同步表约定.md)
|
||
- 冻结方案：`松离线-dbsync方案-最终版.md` §8 / O7
|