架构与系统设计 / 系统课时
数据迁移与存量改造
数据迁移与存量改造
把单租户系统改造成多租户系统,不能直接给所有表增加非空 tenant_id 后一次性上线。本课给出可回滚的灰度迁移路径:先兼容旧数据,再回填租户归属,随后双写校验,最后收紧约束与切换流量。
学习目标
- 能识别存量表改造前必须确认的数据归属
- 能按兼容、回填、双写、校验、收口五个阶段实施迁移
- 能设计可量化的校验项与回滚边界
迁移前先建立数据清单
先按表梳理数据类型、记录量、写入入口、唯一索引、外键关系和历史数据所属租户。平台表不应机械增加 tenant_id;只有租户私有表和有明确所有者的共享表需要迁移。
对于无法直接判断归属的历史记录,必须定义映射来源,例如旧客户编号、组织编号、域名或业务线。不能确认归属的数据应进入隔离清单,由人工处理,而不是统一写入一个虚构租户。
五阶段灰度迁移流程

迁移顺序应保持“数据库先兼容、应用后使用、约束最后收紧”。这样旧版本应用仍能运行,新版本应用可以逐步写入租户字段,出现问题时也能回退到旧读写路径。
五个阶段分别是:
- 兼容建表:新增允许为空的
tenant_id和辅助索引,不立即修改旧唯一索引。 - 历史回填:按确定的映射规则分批更新,记录成功数、失败数和最后处理位置。
- 应用双写:新代码同时写入旧业务字段和租户字段,读取仍可保留旧逻辑。
- 数据校验:比较总量、空值、重复键、抽样业务结果和跨租户异常。
- 约束收口:将字段改为非空,重建租户维度唯一索引,再切换全部读流量。
用最小示例完成表结构改造
下面以旧表 customer_account 为例。历史系统使用全局唯一的 customer_no,改造后希望同一客户编号只在租户内唯一。
DROP TABLE IF EXISTS customer_account;
CREATE TABLE customer_account (
id BIGINT PRIMARY KEY,
customer_no VARCHAR(64) NOT NULL,
customer_name VARCHAR(128) NOT NULL,
legacy_org_code VARCHAR(32) NOT NULL,
UNIQUE KEY uk_customer_no (customer_no)
);
INSERT INTO customer_account VALUES
(1, 'CUST-001', '华东客户', 'ORG-A'),
(2, 'CUST-002', '华南客户', 'ORG-B');
ALTER TABLE customer_account
ADD COLUMN tenant_id BIGINT NULL AFTER id,
ADD KEY idx_tenant_id (tenant_id);
UPDATE customer_account
SET tenant_id = CASE legacy_org_code
WHEN 'ORG-A' THEN 1001
WHEN 'ORG-B' THEN 1002
ELSE NULL
END
WHERE tenant_id IS NULL;
SELECT id, tenant_id, customer_no, legacy_org_code
FROM customer_account
ORDER BY id;预期输出:
id tenant_id customer_no legacy_org_code
1 1001 CUST-001 ORG-A
2 1002 CUST-002 ORG-B这里先允许 tenant_id 为空,是为了让旧应用和未识别记录继续存在。真实迁移应按主键范围分批更新,例如每批 1000 至 10000 行,避免长事务、锁等待和主从延迟骤增。
校验通过后再收紧约束
收口前至少检查三类问题:是否仍有空租户、同一租户内是否出现重复业务键、租户映射后的记录总数是否与迁移前一致。
SELECT COUNT(*) AS null_tenant_count
FROM customer_account
WHERE tenant_id IS NULL;
SELECT tenant_id, customer_no, COUNT(*) AS duplicate_count
FROM customer_account
GROUP BY tenant_id, customer_no
HAVING COUNT(*) > 1;预期输出:
null_tenant_count
0
tenant_id customer_no duplicate_count
无记录只有校验全部通过,才能执行最终约束变更:
ALTER TABLE customer_account
MODIFY tenant_id BIGINT NOT NULL,
DROP INDEX uk_customer_no,
ADD UNIQUE KEY uk_tenant_customer_no (tenant_id, customer_no);预期结果:
表结构变更成功;tenant_id 不再允许为空,customer_no 的唯一性范围调整为租户内。DDL 在 MySQL 中通常会隐式提交,不能依赖一个事务回滚全部结构变更。生产执行前应在影子表或测试库验证锁表时间,并准备反向 DDL 和应用回退版本。
双写与灰度读取策略
双写阶段由新版本应用负责填充 tenant_id,旧版本仍可写入空值,因此应尽快缩短新旧版本并存时间。更稳妥的做法是在网关或服务层逐租户放量,并监控空租户新增量是否持续为零。
读取切换可分两步:先用“租户条件加旧条件”进行影子查询,只记录差异;确认结果一致后,再让租户查询成为主路径。任何跨租户结果、数量不一致或空租户增长都应立即停止放量。
回滚边界与验收标准
迁移不是“脚本执行成功”就结束。可验收的标准应包括:空租户记录为零、租户内唯一索引无冲突、核心接口新旧结果一致、后台任务携带租户上下文、审计日志能定位迁移批次。
在字段仍可为空、旧索引尚未删除时,通常可以回退应用并重新回填;一旦删除旧索引或开放多个租户写入,回滚就需要同步处理新产生的数据。每个阶段都应记录开始时间、批次号、处理范围和校验结果,实际动态值可使用 <TIME>、<ID> 等占位记录。
本课总结
- 存量改造应按兼容、回填、双写、校验、收口顺序推进
- 非空约束和租户维度唯一索引只能在数据校验通过后启用
- 回滚能力取决于阶段边界,越接近最终切流,越需要处理新增多租户数据
下一课预告
下一课将继续处理多租户数据访问层,重点说明如何自动注入租户条件并防止后台任务、批处理和管理员查询绕过隔离。