前置要求
确保系统已安装以下工具:
- Docker 和 Docker Compose
- Node.js 20+ 和 Yarn
- 充足的磁盘空间(建议 500GB+)
一、配置 Graph Node
1.1 创建项目目录结构
CodeBlock Loading...
1.2 配置 config.toml
创建 config.toml 文件,这是 Graph Node 的核心配置文件:
CodeBlock Loading...
关键配置说明:
- 数据库连接池大小:
pool_size = 10适合中等负载,高负载场景可增加到 20-30 - RPC 节点配置:
features = ["archive", "traces"]:支持历史数据查询和交易追踪- 建议配置多个 RPC 节点实现高可用
- 可使用 Infura、Alchemy、QuickNode 等服务或自建节点
- 网络名称:
[chains.xxx]中的名称必须与后续subgraph.yaml中的network字段完全一致 - 分片策略:单节点部署使用
primary分片,集群部署可配置多个分片实现水平扩展
二、配置 Docker Compose
创建 docker-compose.yaml 文件:
CodeBlock Loading...
关键配置说明:
PostgreSQL 内存配置:
shared_buffers:应为系统内存的 25%effective_cache_size:应为系统内存的 50%- 示例基于 8GB 内存服务器,请根据实际调整
Graph Node 端口说明:
8000:GraphQL 查询接口,前端应用连接此端口8020:部署管理接口,graph deploy使用此端口8030:索引状态查询,监控同步进度8040:Prometheus 指标,用于监控告警
数据持久化:
./data/postgres:数据库数据目录,建议挂载到 SSD./data/ipfs:IPFS 存储,存放 subgraph 文件
三、启动 Graph Node
CodeBlock Loading...
启动成功标志:
- PostgreSQL 健康检查通过
- Graph Node 日志显示 "Starting JSON-RPC admin server"
- 访问
http://localhost:8030返回 GraphQL Playground
常见问题排查:
CodeBlock Loading...
四、安装 Graph CLI
Graph CLI 是用于创建、构建和部署 Subgraph 的命令行工具。
4.1 全局安装
CodeBlock Loading...
4.2 项目本地安装(推荐)
CodeBlock Loading...
版本说明:
- 最新稳定版:
v0.79.2 - 建议使用
yarn global add安装,方便在任意目录使用 - 如果遇到权限问题,可以使用
sudo或配置 npm/yarn 全局路径
五、从合约 ABI 部署 Subgraph
5.1 准备合约 ABI 文件
CodeBlock Loading...
5.2 初始化 Subgraph 项目
CodeBlock Loading...
参数说明:
--abi:合约 ABI 文件路径--from-contract:合约地址(建议从区块浏览器复制)--network:网络名称(必须与 config.toml 中的[chains.xxx]完全一致)--contract-name:合约名称,用于生成类型和文件名--index-events:自动为所有事件生成索引处理函数
自动生成的文件:
schema.graphql:GraphQL schema 定义subgraph.yaml:Subgraph 配置清单src/mytoken.ts:事件处理函数abis/MyToken.json:ABI 文件副本
5.3 配置部署脚本
编辑 package.json,修改部署脚本:
CodeBlock Loading...
远程服务器部署(将 IP 改为实际地址):
CodeBlock Loading...
5.4 自定义事件处理逻辑(可选)
如果需要添加业务逻辑,可以修改自动生成的 src/mytoken.ts:
CodeBlock Loading...
5.5 编译和部署
CodeBlock Loading...
部署提示:
- 首次部署会提示输入版本标签(如
v0.0.1) - 版本标签用于追踪部署历史,建议使用语义化版本
- 部署成功后 Graph Node 会自动开始同步区块数据
5.6 验证部署
CodeBlock Loading...
索引状态字段说明:
synced: true:已同步到链头health: "healthy":索引器运行正常latestBlock:当前已索引的区块chainHeadBlock:链上最新区块
六、管理和清理过时的 Subgraph
6.1 查看所有已部署的 Subgraph
CodeBlock Loading...
查询返回信息:
subgraph:Subgraph 名称deployment:部署 ID(IPFS 哈希)synced:是否同步完成health:健康状态(healthy/unhealthy/failed)
6.2 删除单个 Subgraph
CodeBlock Loading...
6.3 批量清理过时的 Subgraph
创建清理脚本 cleanup-subgraphs.sh:
CodeBlock Loading...
使用脚本:
CodeBlock Loading...
6.4 清理数据库中的历史数据
方法1:重置整个数据库(删除所有 subgraph 数据)
CodeBlock Loading...
方法2:清理特定 Subgraph 的数据
CodeBlock Loading...
方法3:定期自动清理过期部署
创建定期清理脚本 auto-cleanup.sh:
CodeBlock Loading...
6.5 设置定时任务自动清理
CodeBlock Loading...
6.6 监控数据库大小
创建监控脚本 monitor-db.sh:
CodeBlock Loading...
使用监控脚本:
CodeBlock Loading...
七、常见问题和最佳实践
7.1 性能优化
数据库优化:
CodeBlock Loading...
Graph Node 优化:
CodeBlock Loading...