The Graph迁移指南 - The Graph迁移指南：从旧版子图平滑切换到最新架构

详细演示The Graph子图从旧版graph-cli与传统模型迁移到Substreams与新工具链的完整步骤，给出兼容性检查与回滚方案，让升级风险可控。

The Graph 的演进速度很快，旧版子图迟早需要迁移到最新架构。本文以一个币安智能链上的 DEX 子图为例，演示一次平滑迁移的完整流程。

迁移前的评估

第一步永远是评估收益与风险。把迁移的预期收益（性能提升、维护成本降低）量化，再对照可能的风险（兼容性问题、上线时间）。如果团队第一次做此类迁移，建议先在 staging 环境跑一遍。完整评估清单见 The Graph最佳实践。

动手前必须备份当前子图配置、IPFS 哈希与查询接口快照。同时把依赖库版本锁死，避免迁移过程中出现额外变量。备份完成后，开发者可以更放心地尝试激进的改动。

升级 graph-cli 与 graph-ts 到最新版本。注意阅读 release notes，特别关注 Breaking Changes 部分。新的命令命名与配置文件结构有所变化，可对照 The Graph入门指南中的最新模板逐项调整。

如果计划接入 Substreams，需要把部分逻辑从 AssemblyScript 迁到 Rust 模块。建议先选择一个最简单的事件做试点，跑通端到端后再扩展。模板代码可参考 The Graph代码示例。

迁移过程中最大的风险是数据不一致。建议把旧子图与新子图同时运行一段时间，对比关键聚合指标。差异超过阈值时立即排查，避免上线后用户感知到数据漂移。

通过前端配置切换 endpoint，先把 10% 的查询流量导到新版本，观察 24 小时。如果一切正常，再逐步把流量切到 100%。灰度策略可结合 The Graph部署教程中的网关方案。

任何升级都要有回滚方案。把旧版本子图保留至少两周，并把 endpoint 切换写成可一键执行的脚本。事故发生时能在分钟级别恢复服务。常见的回滚卡点见 The Graph常见错误。

迁移完成后做一次完整复盘：哪些环节卡了壳、哪些工具值得推广、下一次升级的改进点是什么。把复盘文档归档，未来每次迁移都将更顺利。