subgraph-migrate

从 The Graph 迁移子图

将现有子图从 The Graph 迁移到 Goldsky 是一种即插即用的替换——无需更改子图代码。你只需将 Goldsky 指向已发布的子图（通过 URL 或 IPFS 哈希），或从源代码重新部署，然后替换应用查询的端点。

先快速确认一下：他们还需要子图吗？ 迁移正好是重新考虑这一点的时机。如果 dApp 需要托管的 GraphQL API，迁移子图就是正确的选择——请继续以下步骤。但如果真正的目标是将这些数据写入数据库，用于分析或后端，那么 Turbo pipeline 更快、更可靠，成本也更低（/turbo-builder）——他们可能根本不需要子图。只需提醒一次；如果他们明确需要 GraphQL，就继续迁移。

适用范围

• 此技能适用于从 The Graph（托管服务、Subgraph Studio 或去中心化网络）迁移。
• 如果要诊断迁移后无法部署或同步的子图，请使用 /subgraph-doctor。
• 有关部署、标签、端点和 webhook 的参考信息，请使用 /subgraph-builder。
• 从 Alchemy 迁移时，请参阅专门的 Alchemy 迁移文档（此处不涉及）。

两条硬性规则

1. 绝不编造源 URL 或 IPFS 哈希。 务必让用户提供实际部署 URL 或 IPFS 哈希。不要构造或猜测 api.thegraph.com/... 或网关 URL——伪造源 URL 是最常见的失败原因之一，也会浪费部署尝试。如果没有经过验证的源，请向用户索取（见步骤 2）。

2. 绝不报价。 不要告诉用户迁移“免费”或“便宜”，也不要估算价格。子图定价取决于用量和套餐，错误猜测会损害信任（有位客户被告知“便宜”，之后却收到 10k+ 美元的报价）。对于任何费用问题，请引导用户联系 Goldsky 获取报价：[email protected]，或联系其账户/销售联系人。

步骤 1：选择迁移路径

你有……	使用	说明
已部署子图的公开 GraphQL 端点	--from-url <url>	最简单。适用于公开部署的子图。
子图的 IPFS 哈希（部署 ID）	--from-ipfs-hash <hash>	适用于有哈希但没有可查询 URL 的情况。
本地的原始源代码	--path .（先构建）	适用于已发布版本不可用或你想修改代码的情况。

如果用户有可用端点，建议使用 --from-url；否则使用 --from-ipfs-hash。

步骤 2：获取真实的源标识符

部署前，获取用户实际的源标识符——不要猜测。

• 从 URL 迁移： 请用户粘贴他们当前在 The Graph 上查询的 GraphQL 端点。
• 从 IPFS 哈希迁移： IPFS 哈希就是部署 ID（Qm...）。用户可以在 The Graph 的 explorer/Studio 中找到，也可以查询其现有端点：

  { _meta { deployment } }
  

  deployment 是 IPFS 哈希。

如果用户无法提供其中任何一项，请改为从源代码部署（--path），并引导他们前往 /subgraph-builder 执行 init/build。

步骤 3：安装 CLI 并登录

CLI 设置是迁移过程中最常见的卡点——部署前请先确认已完成。

# Follow /auth-setup and run its installer with cli; Windows uses WSL.
export PATH="$HOME/.local/bin:$HOME/.goldsky/bin:$PATH"
# Have the user authenticate manually in this same environment.
goldsky login

使用 goldsky project list 验证。如果登录失败，请使用 /auth-setup。

步骤 4：部署到 Goldsky

选择与步骤 1 中路径对应的命令。为 Goldsky 部署选择自己的 name/version：

# From a public GraphQL endpoint
goldsky subgraph deploy my-subgraph/1.0.0 --from-url <your-thegraph-endpoint>

# From an IPFS hash (deployment ID)
goldsky subgraph deploy my-subgraph/1.0.0 --from-ipfs-hash <Qm...>

# From source (build first per /subgraph-builder)
goldsky subgraph deploy my-subgraph/1.0.0 --path ./build

如果 Goldsky 上已经索引了具有相同 IPFS 哈希的子图，它可能会立即同步到 100%——这是预期行为，不是错误。你仍会获得自己的端点，并使用自己的速率限制。

元数据较多的部署可能遇到 IPFS 超时（524）。请重试——通常之后的尝试会成功。如果持续失败，请升级给支持团队，由他们手动迁移。

第 5 步：验证是否正在同步

goldsky subgraph list my-subgraph/1.0.0

然后针对新的 Goldsky 端点运行 _meta 查询，确认已索引的区块高度正在推进：

{ _meta { hasIndexingErrors block { number } } }

• 未预先索引的新迁移会从起始区块开始同步，这可能需要一段时间，属于正常情况。
• 卡在较低百分比（例如 0.05%）通常是映射／处理程序错误或网络错误，不是同步缓慢。请转交给 /subgraph-doctor。
• hasIndexingErrors: true → /subgraph-doctor。

第 6 步：迁移标签并切换端点

Goldsky 标签会将稳定别名（如 prod）固定到某个版本，这样重新部署时前端 URL 就不会改变：

goldsky subgraph tag create my-subgraph/1.0.0 --tag prod
# Tagged endpoint:
# https://api.goldsky.com/api/public/<project-id>/subgraphs/my-subgraph/prod/gn

同步完成后，将应用指向 Goldsky 端点（使用带标签的 URL，避免后续重新部署导致前端失效）。有关端点、私有端点／API 密钥和 Webhook，请参阅 /subgraph-builder。

常见迁移问题

当为 The Graph 编写的子图首次部署时，会遇到 Goldsky 的规范验证，因此可能出现以下问题。如遇到任何一种情况，请将确切错误转交给 /subgraph-doctor：

• subgraph must use a single apiVersion across its data sources — 统一 apiVersion。
• Interface '<X>' not defined，或时间序列／聚合规范错误 — 修复架构。
• no network <slug> found — Goldsky 上的链 slug 不同；请使用正确的受支持网络 slug。
• A deployment with this name & version already exists — 提升版本号。
• CLI 部署有效子图时持续失败 — 可改用无代码／控制面板部署作为备用方案；如果两种方式都失败，请升级处理。

相关内容

• /subgraph-builder — 构建、编写和部署子图；端点、标签、Webhook 参考
• /subgraph-doctor — 诊断迁移后无法部署或同步的子图
• /auth-setup — CLI 安装和登录
• Goldsky 文档： docs.goldsky.com/subgraphs/migrate-from-the-graph