18 KiB

Originalformat Permalink Blame Verlauf

海外已注册用户迁移到国内主站设计文档

日期：2026-06-02
状态：待评审
范围：将一批已注册于海外站点的历史用户迁移为“国内主账号 + 海外同步从账号”模型，保留原登录方式和海外入口，不迁移历史日志，不考虑订阅迁移。

背景与目标

当前项目已经具备基础的 region_sync 主从同步能力，核心方向是：

主站创建用户后向从站推送同步用户
从站上的 synced user 消费额度后回写主站
从站周期性拉取主站额度用于本地 synced_quota

本次需求不是新增长期双主能力，而是把一批“历史上注册在海外站的用户”迁移为与现有同步用户一致的模型：

国内站成为唯一主数据源
海外站保留原用户入口，但该用户转为 synced user
保留原密码登录能力
保留原 OAuth 登录能力
保留海外站入口可登录、可使用
迁移用户的可用额度进入国内主账号
不迁移调用日志、充值日志、普通操作日志

本次不考虑活动订阅用户，因为当前确认这批用户不存在订阅数据。

非目标

本次设计明确不做以下事情：

不实现长期双向双主同步
不共享国内和海外数据库
不迁移 topups、subscription_orders、usage logs、quota logs
不重构现有普通登录链路
不删除海外原用户
不修改项目受保护标识、品牌、模块路径

核心设计原则

1. 国内唯一主账号

迁移完成后，国内站是该批用户唯一主账号归属地。之后额度主数据、用户主数据、后续运营动作都以国内站为准。

2. 海外原账号保留

不删除海外账号，不替换海外用户主键，不强制切登录入口。迁移后只是将其降级为同步从账号。

3. 冲突必须显式决策

对 username、email、OAuth 绑定冲突，不做隐式自动合并。允许自动推荐，但最终决策必须可审计。

4. 幂等优先

整个迁移链路按“可能中断、可能重试、可能部分成功”的现实场景设计，所有关键步骤必须可安全重跑。

5. 不做整批自动回滚

跨站点、带人工决策的迁移不适合整批一键回滚。系统只提供受限的单用户回退能力。

整体架构

新增一个独立迁移模块，由以下部分组成：

国内站后端迁移服务
海外站内部迁移接口
国内站管理端迁移页面
迁移批次表和迁移明细表

职责分工如下：

国内站迁移服务：
- 抓取海外候选用户快照
- 执行国内侧冲突预检查
- 记录批次与条目状态
- 根据策略创建或合并国内主账号
- 调用海外内部接口把原账号转换为 synced
- 做迁移后验证
海外内部接口：
- 返回候选用户快照
- 返回单用户最新快照
- 执行“转换为 synced 用户”
管理端页面：
- 批次管理
- 冲突处理
- 迁移执行
- 结果查看和验证

数据模型

本次不复用 quota_sync_logs，新增两张迁移专用表。

`user_migration_batches`

表示一次迁移批次。

建议字段：

id
name
source_region
target_region
status
- draft
- scanned
- ready
- running
- completed
- failed
- cancelled
total_users
conflict_users
migrated_users
failed_users
operator_id
created_at
updated_at

`user_migration_items`

表示一个海外用户在某个批次中的迁移决议和执行结果。

建议字段：

id
batch_id
source_user_id
target_user_id
source_username
source_email
source_quota
conflict_flags
- JSON 字符串
- 记录 username/email/oauth/aff_code 等冲突
resolution_strategy
- create_new
- merge_into_existing
- skip
status
- pending_scan
- conflict
- ready
- migrating
- migrated
- skipped
- failed
error_message
snapshot
- JSON 字符串
- 保存预检查时的海外用户快照
migration_token
- 用于额度合并和幂等保护
migrated_at
created_at
updated_at

唯一性建议

user_migration_items(batch_id, source_user_id) 唯一
迁移执行时按 migration_token 保证不会重复做额度叠加

状态机

批次状态

draft：已创建，未扫描
scanned：预检查完成，但仍可能存在冲突项
ready：所有项都已变成 ready 或 skipped
running：正在执行迁移
completed：全部可迁移项执行成功
failed：存在失败项，需要人工修正后重试
cancelled：人工取消

条目状态

pending_scan：尚未预检查
conflict：发现冲突，等待人工决策
ready：策略已明确，可以执行迁移
migrating：迁移进行中
migrated：迁移成功
skipped：人工跳过
failed：执行失败，允许单项重试

迁移范围

必迁数据

从海外站迁移以下主数据：

users 主字段
密码哈希
display_name
email
status
role
group
created_at
setting
aff_code
内置 OAuth 字段
- github_id
- discord_id
- oidc_id
- wechat_id
- telegram_id
- linux_do_id
user_oauth_bindings
可用额度

不迁数据

topups
subscription_orders
quota_sync_logs
usage logs
普通系统日志

预检查设计

海外候选用户快照

海外站为国内站提供用户快照接口，返回：

用户主字段
内置 OAuth 字段
自定义 OAuth 绑定
quota
group
status
aff_code
created_at
可选 setting
可选 display_name

国内预检查规则

对每个海外用户，在国内检查：

username 是否已存在
email 是否已存在
每个内置 OAuth ID 是否已被其他用户占用
每个自定义 OAuth 绑定是否已被其他用户占用
aff_code 是否已存在

自定义 OAuth 绑定匹配规则

不能直接按 provider_id 比较，必须先通过 custom_oauth_providers.slug 建立海外与国内的 provider 映射，再按：

provider_slug
provider_user_id

进行冲突判断。

冲突分级

硬冲突

必须人工处理，不能自动迁移：

用户名冲突且无法确认同一人
邮箱冲突且无法确认同一人
OAuth 身份已绑定到另一个明确不同的国内用户
自定义 OAuth 绑定指向多个不同国内候选目标

可合并冲突

可以由界面推荐合并，但仍需要人工确认：

同邮箱，且无其他矛盾
唯一 OAuth 身份指向同一个国内用户，且无其他矛盾

软冲突

不阻塞迁移，可自动处理：

aff_code 冲突
display_name 冲突

默认推荐策略

无冲突：推荐 create_new
仅 aff_code 冲突：推荐 create_new
同邮箱且无其他矛盾、且目标国内用户尚未在海外存在其他 synced 副本：推荐 merge_into_existing
任意 OAuth 多对一、一对多关系：强制人工处理

执行一致性约束

预检查快照只用于冲突决策和界面展示，不作为最终额度结算依据。
执行阶段必须重新拉取海外用户最新快照，并以该快照中的最终额度为准。
V1 版本要求在运维冻结窗口内执行批次。冻结窗口至少要覆盖待迁用户的充值、兑换码、额度转移和新请求入口，并等待已在途请求自然结束。
如果执行时最新快照与预检查结论发生冲突性漂移（例如邮箱归属变化、OAuth 绑定目标变化、原本计划合并的国内账号已存在其他海外 synced 副本），该条目必须失败并要求重新扫描，不得静默沿用旧决议。

单用户迁移执行流程

执行顺序不能改变，必须先构建国内主账号，再将海外原账号降级。执行阶段读取的“最新快照”必须发生在冻结窗口内。

`create_new`

在冻结窗口内，从海外拉取该用户最新快照
在国内开启事务
通过“按哈希导入”的专用逻辑创建国内主账号
- 不能走普通 Insert()
- 否则密码会再次哈希
在同一个国内事务中完成以下动作：
- 创建国内主账号
- 复制主字段
- 复制内置 OAuth 字段
- 复制 user_oauth_bindings
- 处理 aff_code 冲突
- 回写 user_migration_items.target_user_id
如在执行阶段遇到新的唯一键冲突：
- 直接将该迁移项标记为失败
- 要求重新扫描或人工修正
- 不允许按用户名/邮箱自动认领为“上次已创建成功”的账号
复制主字段：
- username
- password
- email
- display_name
- status
- role
- group
- created_at
- setting
复制内置 OAuth ID 字段
复制 user_oauth_bindings
- 先通过 slug 将海外 provider_id 映射为国内 provider_id
处理邀请码
- 如冲突则生成新的 aff_code
将国内额度设置为“执行时最新快照中的最终额度”
国内事务提交，得到 cn_user_id
调海外内部接口，将原海外用户转换为 synced
- source = synced
- remote_user_id = cn_user_id
- synced_quota = 国内提交后的最终额度
- last_sync_at = now
更新迁移项为成功

`merge_into_existing`

在冻结窗口内拉取该用户最新快照
锁定目标国内账号
重新校验该用户仍应合并到这个目标
- 同邮箱或唯一 OAuth 目标仍然成立
- 目标国内账号在海外不存在其他 synced 副本
补齐国内为空、海外有值的字段
补齐国内缺失的 OAuth 绑定
额度合并规则：
- 国内最终额度 = 国内原额度 + 执行时最新海外额度
- 通过 migration_token 保证每个迁移项最多叠加一次
提交国内事务
调海外接口将原账号转换为 synced
更新迁移项为成功

为什么不删除海外原用户

海外已有 session 兼容性更好
海外已有 API token 兼容性更好
现有 synced user 逻辑天然支持这种模型
回退成本远低于删除账号再重建

海外用户转换接口

不建议国内直接操作海外数据库，建议由海外站提供内部接口执行切换。

转换接口行为

接口需要做以下校验：

仅允许内部受信任调用
用户存在
用户尚未迁移，或已迁移且目标一致
remote_user_id 不为空
如果用户已是 synced 但 remote_user_id 与请求不一致，返回冲突错误

幂等语义：

如果该用户已经是 source=synced
且 remote_user_id 与请求目标一致
则直接返回成功

管理端页面设计

新增一个 root-only 页面：用户迁移中心。

页面建议拆为四个区域：

1. 批次列表

展示：

批次名
状态
总用户数
冲突数
已迁移数
失败数
创建人
创建时间

2. 批次详情

展示用户级迁移项列表：

海外用户 ID
用户名
邮箱
海外额度
冲突类型
处理策略
当前状态
目标国内账号
错误信息

3. 冲突处理面板

对单个冲突用户允许操作：

create_new
merge_into_existing
skip

并展示推荐策略及依据。

4. 执行与验证面板

提供以下操作：

预检查
开始迁移
重试失败项
迁移后验证
导出失败项

后端 API 设计

新增一组管理端 API，不混入普通 region_sync。

国内管理端 API

POST /api/user-migrations/batches
- 创建批次
GET /api/user-migrations/batches
- 批次列表
GET /api/user-migrations/batches/:id
- 批次详情
POST /api/user-migrations/batches/:id/scan
- 触发预检查
POST /api/user-migrations/items/:id/resolve
- 设置处理策略
- 成功后重新统计批次状态；若所有项都已变为 ready 或 skipped，批次自动转为 ready
POST /api/user-migrations/batches/:id/execute
- 执行迁移
POST /api/user-migrations/batches/:id/retry
- 仅重试失败项
POST /api/user-migrations/batches/:id/verify
- 执行迁移后校验

鉴权要求

仅 root 管理员可访问
不能开放给普通管理员

幂等要求

幂等是本设计的核心要求。

扫描幂等

同一批次重复 scan
不得重复插入相同 source_user_id
只能刷新已有条目的快照与冲突分析结果

执行幂等

批次级重试时，已成功的条目必须跳过
create_new 条目如已存在 target_user_id，不得再次创建账号
merge_into_existing 额度叠加必须有一次性保护

海外转换幂等

已是 synced
且 remote_user_id 一致
直接返回成功

OAuth 复制幂等

已存在同一绑定则跳过
不因重复插入报错

额度合并幂等

通过 migration_token 或同等级唯一标识保证：

每个迁移项对国内额度的修改最多成功一次

冻结窗口设计

本次迁移不要求全站停机，但 V1 版本将“冻结窗口”定义为执行前的强制运维前置条件，而不是可选建议。

冻结范围应仅限该批次用户：

禁止充值
禁止兑换码
禁止额度转移
禁止发起新请求
等待已在途请求自然结束

执行要求：

root 操作员在点击“开始迁移”前确认冻结窗口已经生效
批次执行期间如果发现冻结条件被破坏，应立即停止后续条目并重新扫描

目的：

稳定海外最终额度
避免预检查和执行之间继续发生额度变化

回滚边界

本次设计不提供整批自动回滚，只提供有限的单用户回退能力。

`create_new` 的可回退场景

如果国内主账号刚创建成功，但海外尚未转换为 synced：

可直接删除国内主账号

如果海外已经完成降级：

海外用户改回 source=local
清空 remote_user_id
将确认后的额度写回海外 quota
国内新账号按策略禁用或删除

`merge_into_existing` 的回退限制

不建议自动回滚，因为：

额度已合并进既有国内账号
自动扣减可能伤及已发生的后续业务动作

这类只建议人工修正。

系统提供的回退能力

查看失败现场
导出失败项
对 create_new 类型执行受限回退

迁移后验证清单

系统至少应提供以下自动校验：

国内目标主账号存在
海外原账号已为 source=synced
海外 remote_user_id 指向正确国内账号
国内额度与迁移决议一致
海外 synced_quota 与国内额度一致，或在允许误差范围内一致
密码登录抽样验证可用
OAuth 绑定抽样验证存在
冲突用户未被误迁
重跑执行不会重复加额度

实施顺序

建议按以下顺序推进：

新增迁移数据模型与数据库迁移
实现国内迁移服务内核
实现海外内部迁移接口
实现国内管理端 API
实现管理端迁移页面
补充测试
- 无冲突迁移
- 邮箱冲突合并
- OAuth 冲突阻断
- 中断后重试
- 已迁移项重复执行
- 海外重复转换幂等
先在测试库验证
线上先跑 5-10 个用户的灰度批次
观察成功率和验证结果后再执行全量

关键实现注意事项

1. 密码导入必须是“导入哈希”

当前用户创建逻辑会对密码再次哈希。迁移实现必须提供专用导入路径，直接写入海外已有哈希值。

2. 自定义 OAuth provider 不能直接按 `provider_id` 迁移

必须按 slug 对齐国内外 provider 后再复制绑定，否则绑定会错位。

3. 不能直接复用现有 `SyncUserCreate`

现有 region_sync 的建用户请求字段不足，不能覆盖：

完整冲突处理
自定义 OAuth 绑定复制
哈希密码导入控制
合并已有国内用户

本次迁移需要单独实现迁移接口和迁移服务。

4. 与现有 `synced user` 模型兼容

本方案完成后，海外侧行为应回归现有同步用户路径：

海外读取本地 synced_quota
海外消费额度走批量回写主站
海外周期性从主站拉取额度

结论

本次海外历史用户迁移的最佳路径是：

不做双主
不做纯脚本黑盒迁移
使用“单独迁移界面 + 后端幂等迁移任务内核”
将海外原用户保留并降级为 synced
将国内账号作为唯一主账号

这条路径最符合当前代码库已有的 region_sync 架构，改动集中、风险可控、审计清晰，且能保留用户现有登录方式和海外站访问体验。

18 KiB Originalformat Permalink Blame Verlauf