3步极速部署SubQuery项目：从本地到Web3网络全指南
项目地址: https://gitcode.com/gh_mirrors/su/subql 你还在为Web3数据索引服务的部署流程繁琐而头疼？是否遇到过本地测试正常却在生产环境频频出错的问题？本文将带你通过3个核心步骤，从项目初始化到发布上线，零障碍完成SubQuery项目的部署与发布，让你的区块链数据索引服务稳定运行在去中心化网络中。读完本文，你将掌握：本地开发环境搭建、Kubernetes集群部署、以及SubQuery Network发布的全流程技巧，同时获取常见问题的解决方案。
一、准备工作：环境搭建与项目初始化
SubQuery项目部署的第一步是搭建本地开发环境并初始化项目。这一阶段需要安装必要的工具链、克隆项目代码，并通过CLI工具快速创建项目结构。
1.1 安装SubQuery CLI工具
SubQuery提供了命令行工具@subql/cli，用于项目的创建、构建和部署。通过npm全局安装：
npm install -g @subql/cli
安装完成后，验证CLI版本以确保工具正常工作：
subql --version
@subql/cli/6.4.1-0 linux-x64 node-v22.19.0
1.2 克隆项目代码库
使用以下命令克隆SubQuery项目的官方镜像仓库，获取完整的项目代码和部署配置文件：
git clone https://link.gitcode.com/i/37a5561bc9772a45e0606b3b74434b1e
cd subql
项目结构中包含部署所需的关键组件，如Kubernetes配置文件deploy/k8s/deploy.yaml和CLI命令定义packages/cli/src/commands/deploy-controller.ts。
1.3 初始化SubQuery项目
通过subql init命令创建新项目，指定名称、网络类型和RPC端点。例如，初始化一个基于Ethereum网络的项目：
subql init my-subquery-project --network ethereum --endpoint https://rpc.ankr.com/eth --installDependencies
该命令会自动生成项目目录结构，包括配置文件、数据模型和映射函数模板。初始化过程可通过--networkFamily参数指定网络类型（如EVM或Substrate），详细参数可参考packages/cli/README.md。
二、本地部署与测试：验证项目功能
在将项目部署到生产环境前，需在本地完成构建、代码生成和测试，确保数据索引逻辑正确无误。
2.1 生成类型定义与构建项目
进入项目目录，运行codegen命令生成GraphQL schema和数据源的类型定义，然后通过build命令打包项目代码：
cd my-subquery-project
subql codegen
subql build
codegen命令会根据schema.graphql和数据源配置自动生成TypeScript类型，减少手动编码错误。构建后的代码位于dist目录，可直接用于部署。
2.2 启动本地索引服务
使用subql node命令启动本地索引节点，连接PostgreSQL数据库并开始同步区块链数据。需提前确保本地已安装PostgreSQL，并创建数据库：
# 启动本地节点，使用--local标志在公共模式下创建表
subql node -f . --local
启动过程中，节点会连接指定的RPC端点，同步区块数据并执行映射函数。可通过日志观察索引进度，示例日志截图如下：
日志中会显示区块同步进度、数据处理耗时等关键信息，帮助排查索引逻辑问题。
2.3 测试GraphQL查询
本地节点启动后，默认会启动GraphQL查询服务（端口3000）。通过浏览器访问http://localhost:3000，使用GraphQL Playground测试查询功能，例如查询最近10个区块的信息：
query {
blocks(first: 10, orderBy: TIMESTAMP_DESC) {
nodes {
id
timestamp
height
}
}
}
若查询返回预期结果，表明本地部署成功，可进入下一步生产环境部署。
三、生产环境部署：Kubernetes集群配置
对于生产环境，SubQuery推荐使用Kubernetes（K8s）进行容器化部署，确保服务的高可用性和可扩展性。部署架构包括索引节点、PostgreSQL数据库和GraphQL查询服务三部分。
3.1 配置Kubernetes部署文件
项目提供了完整的K8s部署模板deploy/k8s/deploy.yaml，包含三个核心组件：
索引节点（subql-node）
负责从区块链同步数据并执行索引逻辑，配置示例：
apiVersion: apps/v1
kind: Deployment
metadata:
name: subql-node-1
spec:
replicas: 1
template:
spec:
containers:
- name: indexer
image: onfinality/subql-node:v0.4.0
args: ["-f", "/subquery/block-timestamp"]
env:
- name: DB_HOST
value: subquery-db-svc
PostgreSQL数据库
存储索引后的结构化数据，采用StatefulSet确保数据持久化：
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: subquery-db
spec:
serviceName: subquery-db-svc
volumeClaimTemplates:
- metadata:
name: subquery-db-pvc
spec:
accessModes: [ "ReadWriteOnce" ]
resources:
requests:
storage: 20G
GraphQL查询服务（Hasura）
提供GraphQL接口供客户端查询数据，支持复杂过滤和聚合操作：
apiVersion: apps/v1
kind: Deployment
metadata:
name: hasura-deploy
spec:
replicas: 1
template:
spec:
containers:
- name: hasura
image: hasura/graphql-engine:v1.3.3
env:
- name: HASURA_GRAPHQL_DATABASE_URL
value: postgres://postgres:postgres@subquery-db-svc:5432/postgres
3.2 部署到Kubernetes集群
使用kubectl命令应用部署配置，创建所有必要的K8s资源：
# 应用部署配置
kubectl apply -f deploy/k8s/deploy.yaml
# 检查Pod状态
kubectl get pods
部署完成后，通过K8s Service暴露查询服务，可使用Ingress配置域名和SSL证书，确保外部访问安全。
3.3 监控与扩展
通过Kubernetes的监控工具（如Prometheus和Grafana）监控索引节点性能，关键指标包括区块同步速度、数据库查询延迟等。根据负载情况，可通过调整Deployment的replicas参数水平扩展索引节点数量。
四、发布到SubQuery Network：去中心化托管
完成生产环境部署后，可将项目发布到SubQuery Network，利用去中心化网络实现免运维的索引服务。发布流程包括打包项目、上传IPFS、以及在Network上创建部署。
4.1 打包并发布项目到IPFS
使用subql publish命令将项目代码打包并上传到IPFS，生成唯一的IPFS CID：
subql publish
命令执行成功后，会返回项目的IPFS CID，例如QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco。该CID用于在SubQuery Network上标识项目版本。
4.2 连接钱包并创建部署
通过subql network:connect-wallet命令连接Polygon钱包，然后使用network:create-deployment创建部署：
# 连接钱包
subql network:connect-wallet
# 创建部署
subql network:create-deployment \
--network mainnet \
--projectId 0x... \
--deploymentId QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco \
--deploymentVersion 1.0.0
部署创建后，SubQuery Network的索引器节点会自动开始索引项目数据，用户可通过Network提供的API端点查询数据，无需管理基础设施。
4.3 管理部署与监控
通过subql network命令集管理已发布的部署，例如查看部署状态、调整资源配置或更新项目版本：
# 列出账户下的所有项目
subql network:list-projects --network mainnet
# 为部署增加算力 Boost
subql network:add-deployment-boost --deploymentId <CID> --amount 100
SubQuery Network提供了去中心化的监控机制，可通过区块链浏览器查看部署的索引进度和收益情况。
五、常见问题与解决方案
5.1 数据库连接失败
问题：本地或K8s环境中，索引节点无法连接PostgreSQL数据库。
解决方案：检查数据库服务是否正常运行，连接参数（主机、端口、用户名密码）是否正确。K8s环境中，确保数据库Service名称与索引节点的环境变量DB_HOST一致，可通过kubectl logs <pod-name>查看详细错误日志。
5.2 区块同步速度慢
问题：索引节点同步区块链数据耗时过长。
解决方案：
- 使用更可靠的RPC端点，推荐OnFinality提供的专用端点；
- 调整索引节点的批量处理大小（
--batch-size），默认值为30，可根据网络情况增大； - 启用字典服务（Dictionary），通过
--dict参数指定字典端点，加速历史数据同步。
5.3 部署到Network后无索引器接单
问题：项目发布到SubQuery Network后，长时间没有索引器开始索引。
解决方案：为部署增加SQT代币Boost，提高对索引器的激励。使用subql network:add-deployment-boost命令增加Boost金额，命令示例：
subql network:add-deployment-boost --deploymentId <CID> --amount 500
Boost金额越高，索引器优先处理该部署的概率越大。
总结与展望
通过本文介绍的3个核心步骤，你已掌握SubQuery项目从本地开发到去中心化发布的全流程。SubQuery CLI工具简化了项目初始化和构建，Kubernetes部署确保生产环境的可靠性，而SubQuery Network则提供了免运维的去中心化托管方案。
随着Web3应用的发展，数据索引服务的重要性日益凸显。SubQuery持续迭代其工具链和网络功能，未来将支持更多区块链网络和高级索引特性。建议关注项目的技术文档和GitHub仓库，及时获取更新信息。
如果你在部署过程中遇到问题，欢迎通过SubQuery社区论坛或Discord寻求帮助。最后，别忘了点赞收藏本文，关注作者获取更多Web3开发技巧！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
