subgraphs

Goldsky 子图

子图是托管的 GraphQL API，可索引链上事件，并通过可查询的端点提供这些事件。它们最适合需要通过 GraphQL 灵活查询结构化链上数据的前端应用和 dApp。

Turbo 流水线能否解决这个问题？ 如果你的目标是将原始链上数据流式传输到数据库（PostgreSQL、ClickHouse、Kafka、S3），而不是通过 GraphQL 查询，那么 Turbo 流水线速度更快、成本更低，而且无需编写自定义索引代码。说“帮我构建 Turbo 流水线”，turbo-builder 技能就会为你提供指导。

---

何时使用子图

用例	最佳工具
前端 / dApp 需要 GraphQL API	子图
在索引处理程序中实现自定义业务逻辑	子图
迁移现有的 TheGraph 子图	子图
将原始区块链数据流式传输到数据库	Turbo 流水线
在 ClickHouse 或 Kafka 中进行实时分析	Turbo 流水线
将子图数据同步到自己的数据库	Mirror + 子图数据源

---

初始化子图

在本地搭建新的子图项目：

goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph

主要初始化标志

标志	描述
--target-path <path>	写入子图文件的目录
--from-config <path>	即时子图 JSON 配置文件的路径
--abi <source>	合约的 ABI 来源
--contract <address>	要监听的合约地址
--contract-events <names>	要索引的事件名称
--contract-calls <names>	要索引的调用名称
--contract-name <name>	合约名称
--network <network>	合约所在的网络——支持的网络请参阅文档
--start-block <block>	开始索引的区块
--description <text>	子图描述
--call-handlers	启用调用处理程序
--build	写入文件后构建子图
--deploy	构建后部署子图
--force	覆盖目标路径中的现有文件

---

部署子图

Goldsky 支持多种部署方式：

从源代码部署（最常见）

需要本地目录中有已编译的子图。

# Install CLI and log in
curl https://goldsky.com | sh
goldsky login

# Deploy from local build output
goldsky subgraph deploy my-subgraph/1.0.0 --path ./build

从 ABI 部署（即时子图）

直接根据合约 ABI 生成并部署子图——无需 AssemblyScript：

goldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json

从 IPFS 哈希部署

部署已发布到 IPFS 的子图：

goldsky subgraph deploy my-subgraph/1.0.0 --from-ipfs-hash QmXyz...

使用 --ipfs-gateway <url> 指定自定义网关（默认为 https://ipfs.network.thegraph.com）。

无代码方式（控制面板向导）

使用 Goldsky 控制面板部署常见标准（ERC-20、ERC-721 等）的预构建子图，无需编写代码。前往 app.goldsky.com → Subgraphs → Create。

从 The Graph 迁移

一步完成迁移——无需更改代码：

goldsky subgraph deploy my-subgraph/1.0.0 \
  --from-url <your-thegraph-deployment-url>

请参阅 docs.goldsky.com/subgraphs/deploying-subgraphs。

部署标志参考

标志	描述
--path <dir>	已编译子图目录的路径
--from-url <url>	已公开部署的子图的 GraphQL 端点（迁移 The Graph 子图时使用）
--from-ipfs-hash <hash>	已公开部署的子图的 IPFS 哈希
--from-abi <path>	根据 ABI 文件生成子图
--ipfs-gateway <url>	自定义 IPFS 网关（默认值：https://ipfs.network.thegraph.com）
--tag <tags>	部署后为子图添加标签（多个标签用逗号分隔）
--start-block <number>	覆盖起始区块
--graft-from <name/version>	从现有子图的最新区块进行嫁接
--remove-graft	部署前移除子图的嫁接
--enable-call-handlers	启用调用处理程序（仅与 --from-abi 搭配使用）
--description <text>	子图的描述 / 备注

注意： --path、--from-url、--from-ipfs-hash 和 --from-abi 互斥——只能使用其中一个。

---

GraphQL 端点

每个已部署的子图都有一个公开的 GraphQL 端点：

https://api.goldsky.com/api/public/<project-id>/subgraphs/<name>/<version>/gn

要获取端点 URL：

goldsky subgraph list

公开端点与私有端点

端点默认是公开的。要控制端点的可见性：

# Disable public endpoint
goldsky subgraph update my-subgraph/1.0.0 --public-endpoint disabled

# Enable private endpoint (requires API key)
goldsky subgraph update my-subgraph/1.0.0 --private-endpoint enabled

要为私有端点配置 API 密钥要求：

1. 前往 app.goldsky.com → Settings → API Keys 并创建密钥。
2. 在请求中添加 Authorization 标头：

   Authorization: Bearer <your-api-key>
   

---

子图标签

标签会将易读的别名（例如 prod）固定到特定的子图版本，这样重新部署时前端 URL 就不会变化。

# Create or update a tag
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

# Delete a tag
goldsky subgraph tag delete my-subgraph/1.0.0 --tag prod

你也可以在部署时添加标签：

goldsky subgraph deploy my-subgraph/2.0.0 --path ./build --tag prod

参见 docs.goldsky.com/subgraphs/tags。

---

Webhook

子图 webhook 会在每次实体变更（INSERT、UPDATE、DELETE）时，向 HTTP 端点发送负载。适用于通知和推送式工作流。

# Create a webhook
goldsky subgraph webhook create my-subgraph/1.0.0 \
  --name my-webhook \
  --url https://example.com/hook \
  --entity Transfer \
  --secret my-secret

# List all webhooks
goldsky subgraph webhook list

# List available entities for a subgraph
goldsky subgraph webhook list-entities my-subgraph/1.0.0

# Delete a webhook
goldsky subgraph webhook delete my-webhook

标志	描述
--name <name>	Webhook 名称（必须唯一）——必填
--url <url>	接收事件的 URL——必填
--entity <entity>	要发送事件的子图实体——必填
--secret <secret>	随每个 webhook 请求一起发送的密钥

提示： 如果需要确保数据送达数据库，请使用 Mirror 同步子图数据，而不是使用 webhook——它更可靠。

参见 docs.goldsky.com/subgraphs/webhooks。

---

管理子图

列出子图

# List all subgraphs
goldsky subgraph list

# List a specific subgraph
goldsky subgraph list my-subgraph/1.0.0

# Show only tags or deployments
goldsky subgraph list --filter tags
goldsky subgraph list --filter deployments

# Summary view
goldsky subgraph list --summary

更新子图

goldsky subgraph update my-subgraph/1.0.0 \
  --public-endpoint enabled \
  --private-endpoint disabled \
  --description "Production deployment"

标志	值	描述
--public-endpoint	enabled / disabled	切换公开端点的可见性
--private-endpoint	enabled / disabled	切换私有端点（需要 API 密钥）
--description	文本	子图的描述/备注

暂停和恢复

# Pause a subgraph (stops indexing)
goldsky subgraph pause my-subgraph/1.0.0

# Resume a paused subgraph
goldsky subgraph start my-subgraph/1.0.0

删除子图

goldsky subgraph delete my-subgraph/1.0.0

# Skip confirmation prompt
goldsky subgraph delete my-subgraph/1.0.0 --force

---

日志和调试

实时查看子图日志以诊断问题：

# View recent logs
goldsky subgraph log my-subgraph/1.0.0

# Logs from the last hour, errors only
goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error

# JSON format for parsing
goldsky subgraph log my-subgraph/1.0.0 --format json

标志	默认值	描述
--since <duration>	1m	显示指定时长内的新日志（例如 5s、2m、3h）
--format <format>	text	输出格式：pretty、json 或 text
--filter <level>	info	最低日志级别：error、warn、info、debug
--levels <levels>	—	要包含的明确日志级别，以逗号分隔
--interval <seconds>	5	检查日志的间隔秒数

停滞的子图

如果子图停止推进，Goldsky 会自动暂停它并发送电子邮件通知。诊断方法：

1. 检查日志：goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error
2. 查找处理程序错误、RPC 超时或内存不足问题
3. 修复问题并重新部署，或联系 [email protected]

---

跨链子图

要在多条链上索引同一个合约，请为每条链分别部署子图，然后使用 Mirror pipeline 将它们合并到一个数据库表中。

参见 docs.goldsky.com/subgraphs/introduction。

---

CLI 命令参考

操作	命令
初始化子图	goldsky subgraph init <name/version>
从源代码部署	goldsky subgraph deploy <name/version> --path .
从 The Graph 部署	goldsky subgraph deploy <name/version> --from-url <url>
从 ABI 部署	goldsky subgraph deploy <name/version> --from-abi <path>
从 IPFS 部署	goldsky subgraph deploy <name/version> --from-ipfs-hash <hash>
列出子图	goldsky subgraph list
删除子图	goldsky subgraph delete <name/version>
暂停子图	goldsky subgraph pause <name/version>
启动子图	goldsky subgraph start <name/version>
更新子图	goldsky subgraph update <name/version> --public-endpoint enabled
实时查看日志	goldsky subgraph log <name/version>
创建标签	goldsky subgraph tag create <name/version> --tag <tag>
删除标签	goldsky subgraph tag delete <name/version> --tag <tag>
创建 webhook	goldsky subgraph webhook create <name/version> --name <n> --url <u> --entity <e>
列出 webhook	goldsky subgraph webhook list
删除 webhook	goldsky subgraph webhook delete <webhook-name>
列出 webhook 实体	goldsky subgraph webhook list-entities <name/version>

---

相关内容

• /turbo-builder — 构建流式数据管道，将数据写入数据库，而不是 GraphQL API
• Goldsky 文档： docs.goldsky.com/subgraphs/introduction