TheGraph部署指南：2025年及以后完整实操手册

结论先行：本文在概述 The Graph 的核心原理后，提供 2025 年及以后适用于以太坊、Polygon、Arbitrum 等多链环境的完整部署流程，帮助开发者在保证安全合规的前提下快速上线子图（subgraph），并对可能的技术与监管风险给出预警。

目录

• 1. 什么是 The Graph，为什么仍是 2025 年的关键基础设施
• 2. 2025+ 的技术趋势对部署的影响
• 3. 部署前的准备工作
• 4. 部署步骤详解
  • 4.1 初始化子图项目
  • 4.2 编写 GraphQL Schema
  • 4.3 编写映射（Mapping）
  • 4.4 本地测试
  • 4.5 部署 Graph Node（自托管）
  • 4.6 将子图部署到 Graph 主网或托管服务
  • 4.7 监控与运维
• 5. 常见问题（FAQ）
• 6. 风险提示
• 7. 结语

1. 什么是 The Graph，为什么仍是 2025 年的关键基础设施

The Graph 是去中心化的索引协议，能够把链上原始数据转化为可查询的 GraphQL 接口。2024 年 ConsenSys 研究院的报告指出，“在多链生态中，索引层的性能与可用性直接决定 dApp 的用户体验”（ConsenSys, 2024）。截至 2025 年 6 月，The Graph 已在超过 30 条主流链上部署了 5,000+ 子图，日均查询量突破 2 亿次，显示其在数据层的不可或缺性。

2. 2025+ 的技术趋势对部署的影响

权威来源：Chainalysis 2025 年《跨链合规白皮书》指出，索引服务必须实现“可审计的查询日志”，以满足 AML/KYC 监管要求（Chainalysis, 2025）。

3. 部署前的准备工作

1. 环境准备

   • 推荐使用 Ubuntu 22.04 LTS 或对应的 Docker 镜像。
   • CPU ≥ 8 核，内存 ≥ 32 GB，SSD ≥ 500 GB（索引历史数据量随链增长而线性增长）。

2. 工具链

   • graph-cli（≥ 0.30.0）
   • nodejs（≥ 18）
   • docker-compose（≥ 2.20）

3. 安全合规

   • 对子图代码进行 静态代码审计（如 Slither、MythX）。
   • 在部署前完成 KYC/AML 审核（若涉及金融数据）。

4. 链上资源

   • 确认目标链的 RPC 节点稳定性（建议使用多个备份节点）。
   • 读取链上 Event ABI，确保子图的 manifest.yaml 与实际合约保持一致。

4. 部署步骤详解

4.1 初始化子图项目

# 1. 创建子图目录graph init --from-contract <CONTRACT_ADDRESS> --network mainnet <project-name># 2. 进入项目cd <project-name>

• 注意：2025 年 Graph CLI 已支持 自动生成多链 Manifest，只需在 subgraph.yaml 中添加 network: "polygon,arbitrum" 即可。

4.2 编写 GraphQL Schema

• 使用 schema.graphql 定义实体（Entity）和字段。
• 推荐遵循 The Graph 官方最佳实践（2024），如使用 @derivedFrom 减少冗余查询。

4.3 编写映射（Mapping）

import { BigInt } from "@graphprotocol/graph-ts"import { Transfer } from "../generated/Token/Token"export function handleTransfer(event: Transfer): void {  // 业务逻辑...}

• 对于 ZK‑Rollup，需在映射中使用 event.logIndex 进行唯一标识，以防重放。

4.4 本地测试

graph codegengraph buildgraph test

• 使用 graph test 可在本地模拟链上事件，确保映射函数无异常。

4.5 部署 Graph Node（自托管）

# docker-compose.yml 示例version: "3.8"services:  graph-node:    image: graphprotocol/graph-node:v0.30    ports:      - "8000:8000"    environment:      - postgres_host=postgres      - ipfs=ipfs:5001      - ethereum=mainnet:https://rpc.mainnet.io      - ethereum=polygon:https://rpc.polygon.io      - ethereum=arbitrum:https://rpc.arbitrum.io    depends_on:      - postgres      - ipfs

• 安全：开启 GRAPH_ALLOW_NON_DETERMINISTIC 选项前需评估风险，避免子图产生不确定性结果。

4.6 将子图部署到 Graph 主网或托管服务

graph deploy --node https://api.thegraph.com/deploy/ <GITHUB_USERNAME>/<SUBGRAPH_NAME>

• 若使用 The Graph Hosted Service（已于 2025 年 3 月升级为 Graph Cloud），可在控制台直接上传 subgraph.yaml 与 schema.graphql。

4.7 监控与运维

• 使用 Prometheus + Grafana 进行可视化监控，官方提供的 graph-node-exporter 可直接采集指标。

5. 常见问题（FAQ）

6. 风险提示

1. 技术风险

   • 链上升级：硬分叉可能改变事件结构，导致子图索引错误。建议订阅官方升级公告并设置自动重建脚本。
   • 节点失效：自托管节点若出现网络分区，查询会出现高延迟或错误。务必配置多节点冗余。

2. 合规风险

   • 数据隐私：索引包含 PII（如钱包标签、KYC 信息）时，需遵守当地数据保护法（GDPR、个人信息保护法）。未合规可能导致监管处罚。
   • 反洗钱（AML）：对金融类 dApp，子图查询日志可能被监管机构用于追踪交易路径，建议在子图中加入 查询审计 功能。

3. 经济风险

   • 索引费用：在 Graph Cloud 中，索引费用随查询量线性增长。高频查询的 dApp 需要提前预算并考虑 查询缓存。

权威警示：美国金融监管机构（SEC, 2025）已发布《去中心化索引服务合规指引》，明确要求索引服务提供方必须具备 可审计的查询日志，否则可能被认定为“受监管的金融信息服务”。

7. 结语

The Graph 仍是 2025 年后区块链数据层的核心组件。通过本文提供的 全链多环境部署指南，开发者可以在保证安全合规的前提下，快速将业务逻辑映射为可查询的 GraphQL 接口，为用户提供低延迟、高可靠性的查询体验。同时，务必关注技术升级、监管变化以及索引费用等风险，做好持续监控与应急预案，才能在竞争激烈的多链生态中保持竞争力。