图模式演进与在线迁移

引言

关系型数据库改表结构有明确的 DDL：ALTER TABLE、加列、建索引，语句执行完就算完成。图数据库看起来没有这一层——Neo4j 里你随时可以给节点加一个新属性、新标签、新关系类型，不需要任何声明，写入就能生效。这带来一个危险的错觉：「图数据库不需要 schema 迁移」。

事实恰恰相反。正因为没有强制声明，模式演进反而更隐蔽也更危险：属性改名后旧数据仍带着旧属性名、新老代码同时读到两种形态；某个标签被拆成两个之后，旧查询的 MATCH (n:Person) 会漏掉已经改成 (n:User) 的数据；关系方向从「A 拥有 B」翻转为「B 属于 A」，所有依赖方向的查询静默返回空集而不是报错。图库不会因为你「忘了迁移」而报错，它只会安静地少给你数据——这才是最难排查的一类故障。

本文把图模式演进当成一个在线迁移工程来对待：先讲图模式的演进特性与三种版本化形态，再讲 expand/contract 四阶段迁移流程，然后是约束与索引的灰度重建、迁移校验、回滚与限流。模式本身的设计原则可先读 图数据建模基础 ，约束与治理的完整讨论见 Schema 约束与治理 ；关系型库上的迁移方法论可横向对照 零停机迁移策略 。

1. 图模式为什么会演进

1.1 三类典型变更

图模式的变更可以按「影响面」和「可回退性」分成三类：

工程上最重要的一条判断是：增量变更可以随意做，结构变更必须走完整流程。把三类混在一起批量上线，是事故的主要来源。

1.2 没有 DDL 的代价

关系型数据库的 schema 是单一事实来源：列不存在就是不存在，插入会失败。图库的「灵活 schema」把这份约束转移到了应用层，代价是：

• 校验延迟：错误在读取时才暴露（n.displayName 返回 null），而不是写入时。
• 形态并存：同一个标签下可能同时存在 v1、v2、v3 三种属性组合，查询必须对每种都成立。
• 统计失真：count(n.name) 与 count(n.displayName) 会给出不同的数字，做报表时容易误判。

对策不是「回到强 schema」，而是显式维护一份模式契约：用约束（Constraint）保住关键的键唯一性与必填性，用文档 + CI 校验保证「新写入必须带 v2 属性」。

1.3 演进的反面：什么时候不该改模式

并非所有模式问题都该靠迁移解决。以下情况应优先改查询或加投影，而不是动数据：

• 只是为了查询方便而给节点加冗余属性。冗余属性的代价是双写一致性，收益往往不如加一个索引。
• 低频读路径上的形态差异。低频查询用 coalesce 兼容层扛着即可，不值得为它做全量回填。
• 探索期/原型期的模式。频繁变的模式应该先稳定下来再迁移，否则迁移脚本本身会成为技术债。

判断标准：如果这次变更三个月内还会再变一次，就先别做全量迁移，用读侧兼容扛到模式稳定为止。

2. 模式版本化的三种形态

演进期的核心矛盾是「新老代码必须能同时读同一份数据」。三种落地形态：

2.1 属性版本号（推荐默认）

给节点/关系打一个 _v 属性，读取方按版本分支：

// 新写入统一带 _v: 2
CREATE (u:User {
  id: $id,
  displayName: $name,
  _v: 2,
  _updatedAt: datetime()
})

读取时用 coalesce 抹平差异，这是最省事的兼容层：

MATCH (u:User {id: $id})
RETURN u.id AS id,
       coalesce(u.displayName, u.name) AS displayName,   // v2 优先，回退 v1
       u._v AS schemaVersion

优点：迁移是惰性的——读路径自动兼容，写路径只写新版；不需要一次性刷全量数据。缺点：兼容层会长期留在代码里，需要定期清理（等 v1 数据比例降到 0 后删掉 coalesce 分支）。

2.2 双写 + 影子标签

结构变更（拆标签、改关系类型）无法靠 coalesce 兼容，需要双写：

// 迁移期：同时维护旧结构 (:Person) 与新结构 (:User)
MATCH (p:Person {id: $id})
SET p.displayName = p.name,        // 双写：旧节点补新属性
    p._v = 2
WITH p
MERGE (u:User {id: p.id})          // 影子节点
SET u.displayName = p.name, u._v = 2

注意 MERGE 而不是 CREATE——迁移脚本可能重跑，幂等性是硬要求。双写期结束后，用一次性批处理把 :Person 节点的关系搬迁到 :User 上，再删掉旧标签。

2.3 视图投影（读侧隔离）

如果不想动数据，可以在读侧建一层投影：用 CALL { ... } 子查询或 GDS 图投影把新旧结构统一成逻辑视图：

CALL {
  MATCH (u:User) RETURN u.id AS id, u.displayName AS name
  UNION
  MATCH (p:Person) WHERE NOT (p)-[:IS]->(:User)
  RETURN p.id AS id, p.name AS name
}
RETURN id, name

投影层的成本是每次查询都要跑两个分支，且 UNION 会阻止部分优化（无法用单一索引扫描）。只适合过渡期或低频读路径，不适合作为长期方案。

2.4 一个完整示例：Person 拆成 User + Profile

假设要把「一个 :Person 节点同时承载账号信息与个人档案」拆成 :User（账号）与 :Profile（档案）两个标签，用 :HAS_PROFILE 相连。这是典型的结构变更，必须走双写 + 回填 + 切读 + 清理：

// 阶段 1（Expand）：新写入同时创建 User 与 Profile
MERGE (u:User {id: $id})
SET u.displayName = $name, u._v = 2, u.createdAt = coalesce(u.createdAt, datetime())
MERGE (u)-[:HAS_PROFILE]->(p:Profile {userId: $id})
SET p.bio = $bio, p.avatar = $avatar, p._v = 2

// 阶段 2（Backfill）：把存量 Person 拆开，按 id 分批
MATCH (old:Person)
WHERE NOT (old)-[:IS]->(:User) AND old.id > $lastId
WITH old ORDER BY old.id LIMIT 1000
MERGE (u:User {id: old.id})
SET u.displayName = old.name, u._v = 2, u._migratedFrom = 'Person'
MERGE (old)-[:IS]->(u)                 // 保留映射，回滚时用
MERGE (u)-[:HAS_PROFILE]->(p:Profile {userId: old.id})
SET p.bio = old.bio, p._v = 2
RETURN count(old) AS migrated, max(old.id) AS newLastId

:IS 这条映射关系是回滚的保险绳：切读后发现异常，只要 MATCH (p:Person)-[:IS]->(u:User) 就能反查，不必依赖备份。等 contract 阶段再把它一起删掉。

// 阶段 3（Migrate）：读路径切到新结构
MATCH (u:User {id: $id})-[:HAS_PROFILE]->(p:Profile)
RETURN u.displayName AS name, p.bio AS bio

// 阶段 4（Contract）：确认零残留后清理
MATCH (p:Person) RETURN count(p) AS remaining;   // 必须为 0 才继续
MATCH (old:Person) DETACH DELETE old;
DROP INDEX person_name_index IF EXISTS;

3. expand/contract 四阶段流程

在线迁移的通用范式是 expand/contract（扩展-收缩），图场景下拆成四步。每一步都必须是独立可发布、可回滚的：

阶段 1（Expand）：加新结构，不删旧的
  - 新增属性/标签/关系类型，写入侧开始双写
  - 老代码完全不受影响，读路径仍走旧结构
  - 验证：新写入的数据里新属性齐全

阶段 2（Backfill）：回填历史数据
  - 分批把存量数据补上新属性/新结构
  - 限流执行，避免打满 IO 与 page cache
  - 验证：新旧结构计数一致（见第 5 节校验查询）

阶段 3（Migrate）：读路径切到新结构
  - 应用层读逻辑改为优先读新结构
  - 观察一个完整业务周期（至少一个日报周期）
  - 验证：监控无异常、关键指标（QPS/延迟/错误率）无漂移

阶段 4（Contract）：清理旧结构
  - 停掉双写，删除旧属性/旧标签/旧关系
  - 删除兼容层代码（coalesce 分支、UNION 投影）
  - 验证：全库扫描确认旧结构计数为 0

关键纪律：

• 每个阶段单独发版，不要在同一个 PR 里同时做 expand 和 contract。
• 回填与切读之间必须有一个观察期。跳过观察期直接切读，等于把风险压到一次发布里。
• contract 是唯一不可逆的步骤。删旧属性前必须确认所有读写路径都已切走，回退方案只能是「从备份恢复」。

3.1 分批回填的具体写法

回填不能一条 Cypher 扫全库。按主键区间分批，每批用独立事务：

// 单批：回填 1000 个节点，按 id 区间推进
MATCH (p:Person)
WHERE p._v IS NULL AND p.id > $lastId
WITH p ORDER BY p.id LIMIT 1000
SET p.displayName = coalesce(p.displayName, p.name),
    p._v = 2,
    p._backfilledAt = datetime()
RETURN count(p) AS updated, max(p.id) AS newLastId

驱动层循环推进 lastId，每批之间 sleep 一小段：

import time

def backfill(session, batch=1000, pause=0.05):
    last_id = 0
    while True:
        rec = session.run(BACKFILL_CYPHER, lastId=last_id).single()
        if rec["updated"] == 0:
            break
        last_id = rec["newLastId"]
        print(f"backfilled up to {last_id}")
        time.sleep(pause)          # 主动限流，给在线流量让路

pause 的取值靠观察 page cache 命中率与查询 p99 来定，通常在 20~200ms 之间。回填任务必须可中断、可续跑，用 WHERE p._v IS NULL 天然幂等。

4. 约束与索引的灰度重建

图上的约束（唯一性、存在性）与索引往往和模式绑定。改模式时常要同步改索引，而建索引在部分版本里是阻塞操作，需要特别处理。

4.1 新增约束的注意事项

// Neo4j 5.x：唯一约束默认后台创建（不阻塞读写）
CREATE CONSTRAINT user_id_unique IF NOT EXISTS
FOR (u:User) REQUIRE u.id IS UNIQUE;

// 复合索引（新属性组合）
CREATE INDEX user_name_v2 IF NOT EXISTS
FOR (u:User) ON (u.displayName, u._v);

// 查看约束/索引的创建进度
SHOW CONSTRAINTS YIELD name, type, labelsOrTypes, properties, ownedIndex;
SHOW INDEXES YIELD name, state, populationPercent, type;

要点：

• state 必须是 ONLINE 才算建好，POPULATING 期间查询不会用该索引（但仍能走旧索引或全表扫）。
• 唯一约束创建前必须先查重。存量数据里有重复值会让创建失败，且失败后可能留下半成品索引，需要 DROP CONSTRAINT 清理后重来：

// 建唯一约束前的查重（发现即修，否则约束建不上）
MATCH (u:User)
WITH u.id AS id, count(*) AS c
WHERE c > 1
RETURN id, c ORDER BY c DESC LIMIT 20;

• 删除旧索引要等新索引 ONLINE 之后。先建后删，中间有一个双索引并存期，查询优化器会自动选更优的那个。

4.2 索引重建的灰度

对大库而言，重建一个索引可能耗时数小时。灰度策略：

切勿在建索引期间跑回填任务——两者都要读全量数据，叠加会把 IO 打满。

4.3 迁移后的性能回归

模式变更经常顺带改变查询计划。迁移完成后必须重跑关键查询的执行计划，确认仍然命中索引：

// 迁移前/后各跑一次，对比计划差异
EXPLAIN MATCH (u:User {id: $id})-[:HAS_PROFILE]->(p:Profile)
RETURN u.displayName, p.bio;

EXPLAIN 输出里要重点看两个运算符：NodeIndexSeek（命中索引）与 NodeByLabelScan（全标签扫描）。如果迁移后从前者退化成后者，说明新属性上缺索引，或者属性名改了但索引还建在旧名上。用 PROFILE 还能看到实际 dbHits，量化退化程度：

PROFILE 关键指标：
dbHits       实际访问的存储记录数（越低越好）
rows         运算符产出的行数
estimatedRows 优化器估算（与实际差一个数量级说明统计信息过时）
time         各运算符耗时（微秒）

退化原因通常是三类：索引建在旧属性名上、新标签没有索引、或者 coalesce 兼容层让优化器无法下推条件（WHERE coalesce(u.displayName, u.name) = $x 这种写法不会用索引，因为索引是按单属性建的）。兼容层的条件尽量放在 RETURN 里而不是 WHERE 里。

5. 迁移校验查询

迁移做完了不等于做对了。每个阶段结束都要跑校验，校验必须是可重复执行的查询，而不是人工抽查：

// 校验 1：新旧结构计数一致性
MATCH (p:Person) WITH count(p) AS oldCount
MATCH (u:User)   WITH oldCount, count(u) AS newCount
RETURN oldCount, newCount, oldCount - newCount AS diff;

// 校验 2：是否存在「新属性缺失」的记录
MATCH (u:User) WHERE u.displayName IS NULL
RETURN count(u) AS missingDisplayName;   // 期望 0

// 校验 3：关系是否全部搬迁完成
MATCH (p:Person)-[r:OWNS]->(x)
WHERE NOT (p)-[:IS]->(:User)              // 还没映射到 User 的 Person
RETURN count(r) AS orphanRels;            // 期望 0

// 校验 4：双写一致性抽样（新旧值必须相同）
MATCH (p:Person) WHERE p._v = 2
WHERE p.name <> p.displayName
RETURN p.id, p.name, p.displayName LIMIT 20;   // 期望空

把这四个查询固化成一个 migration_verify.cypher，在 CI 与生产巡检里都跑。校验 2 和校验 4 是「静默错误」的守门员：它们能抓到「迁移脚本跑完了但部分数据没更新」这种最隐蔽的问题。

版本与差异比对（diff）的完整方法可参考 图版本化与差异比对 ，那里讲了如何用快照 + 变更日志还原任意时间点的图状态。

6. 回滚与限流

6.1 回滚策略

前三个阶段之所以能安全回滚，靠的是「只加不删」原则。这也是为什么 contract 必须放到最后、且必须等观察期结束。

6.2 限流与资源隔离

回填与建索引都是重 IO 操作，必须限流：

限流手段：
1. 批间 sleep（最简单，效果最直接）
2. 用单独的 driver session，限制并发事务数
3. 错峰执行：避开业务高峰（例如凌晨 2~6 点）
4. 设置事务超时，避免长事务把 page cache 挤出去
5. 监控 page cache 命中率，低于阈值自动降速

在 Neo4j 上还可以用 dbms.listQueries 观察正在跑的回填查询，必要时 CALL dbms.killQuery(id) 中止：

CALL dbms.listQueries() YIELD queryId, query, elapsedTime, allocatedBytes
WHERE query CONTAINS 'backfill'
RETURN queryId, elapsedTime, allocatedBytes
ORDER BY elapsedTime DESC;

6.3 迁移进度的持久化

长跑的回填任务需要把进度记在图里，否则进程一挂就得从头扫。用一个 :Migration 节点维护状态机：

MERGE (m:Migration {name: 'person-to-user-v2'})
SET m.phase = $phase,          // expand | backfill | migrate | contract
    m.cursor = $cursor,        // 当前推进到的 id
    m.updatedAt = datetime()
RETURN m.phase, m.cursor;

续跑时先读 m.cursor 作为起始 lastId，跳过已完成的区间。phase 字段同时充当发布闸门：应用启动时读一次，若 phase 尚未到 migrate，就读路径继续走旧结构。这把「代码版本」与「数据版本」解耦，避免了「代码先上、数据没迁完」的窗口期故障。

状态机约束（必须在应用层强制）：
expand   → 只允许双写，读走旧结构
backfill → 允许双写与回填，读仍走旧结构
migrate  → 读走新结构，双写仍在（防止旧客户端写入丢数据）
contract → 停双写，删旧结构
任何回退 → phase 只允许回退到上一档，且 contract 不可回退

7. 常见反模式

反模式一：用一条 Cypher 扫全库迁移。 单事务改百万节点会撑爆事务日志（transaction log）与内存，且中途失败要全部回滚。必须分批。

反模式二：CREATE 代替 MERGE。 迁移脚本重跑时会产生重复节点。凡是有唯一键的写入一律 MERGE。

反模式三：迁移与业务发布同批次。 一旦迁移出问题，无法判断是代码问题还是数据问题。每个阶段独立发版。

反模式四：跳过回填直接改读。 新属性只对新增数据存在，历史数据读出来是 null，表现为「老用户看不到信息」的诡异 bug。

反模式五：contract 前不做零残留校验。 直接 DETACH DELETE 可能删掉还没搬迁完的数据。必须先 count 校验为 0。

反模式六：把索引当约束用。 建了索引不等于有唯一性保证。需要唯一性就必须建约束，索引只影响查询性能。

8. 跨版本兼容的长期策略

如果系统会长期经历多次模式演进，建议一开始就把兼容层做成基础设施，而不是每次临时加 coalesce：

• 统一读模型：应用层只读一个内部 DTO，DTO 的组装函数负责把任意版本的图数据归一化。这样兼容逻辑集中在一处，迁移时只改这一处。
• 写入校验钩子：所有写入经过一个校验函数，强制带上当前 _v 与必填属性，把「形态并存」的口子收紧。
• 模式契约测试：在 CI 里对一组固定 fixture 跑读模型，断言输出与期望一致。模式变更若破坏了读模型，CI 会立刻失败。这套「契约先行」的测试思路在关系型库上已经非常成熟，可以整体搬过来。

图模式演进的本质不是「改数据」，而是**「管理形态并存期」**。谁能把并存期控制得越短、越可观测，谁的迁移就越安全。

一个可操作的验收清单：迁移前写下「期望的新旧计数、期望的属性非空率、期望的关键查询计划」三组数字；迁移中每批回填后核对计数增量；迁移后逐条比对查询计划是否退化。三组数字都对得上，才算迁移完成，而不是「脚本没报错」就算完成。

最后提醒一点：迁移脚本本身也要进版本控制并做代码评审。迁移是一次性执行但需要长期可读的代码——半年后有人要查「当时那批数据是怎么补的」，只能靠这份脚本。把每一步的意图写进注释，比写一份事后没人看的迁移文档有用得多。

小结

图模式演进的关键认知是：图库不会替你守住 schema，你得自己守。落地时记住四条：增量变更随时做，结构变更走 expand/contract 四阶段且每阶段单独发版；版本化优先用属性版本号 + coalesce 兼容层，结构变化才上双写；约束与索引坚持「先建后删」并盯 state = ONLINE；每个阶段结束都跑固化的校验查询，尤其别漏掉「新属性缺失」与「双写不一致」这两类静默错误。contract 之前留足观察期，因为那是唯一回不去的步骤。