# 数据同步 · 迁移手册（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