企业官网建设流程全解析

Aptos 节点 Terraform 云部署指南：从零搭建 Validator 与 Fullnode 的完整实战

【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core

本指南以 terraform/aptos-node/README.md 为核心，系统讲解如何用 Terraform 在 AWS / GCP 上从零部署一套典型的 Aptos 节点，其中同时包含验证节点（Validator）、全节点（Fullnode）以及用于流量管理的 HAProxy。读完本文你将掌握：Terraform 模块的组成与工作原理、AWS 与 GCP 两套完整的部署操作流程、核心变量与配置项的含义，以及如何通过 Kubernetes Secret 注入 genesis 数据完成节点启动。

一、模块定位与整体架构

terraform/aptos-node目录为 Aptos 节点提供了一套云平台专属的 Terraform 模块。从源码结构看，它按云厂商拆分为三个子模块：

• terraform/aptos-node/aws：基于 AWS EKS 的部署模块（含auth.tf、cluster.tf、network.tf、dns.tf、kubernetes.tf、security.tf、outputs.tf等）；
• terraform/aptos-node/gcp：基于 GCP GKE 的部署模块（含 AAD 相关的aad/aks-aad.tf等文件）；
• terraform/aptos-node/azure：Azure AKS 模块。

每个模块整体上由三个高层组件构成：

1. 云网络配置（Cloud network configuration）：例如 AWS 模块中的 VPC、子网、NAT 网关（见 terraform/aptos-node/aws/network.tf 与 outputs.tf 中暴露的vpc_id、aws_subnet_public、aws_subnet_private、aws_eip_nat_public_ip）；
2. 该云厂商托管 Kubernetes 服务（Managed Kubernetes service）：AWS 的 EKS 集群、GCP 的 GKE 集群；
3. 向该 Kubernetes 集群发布的 Helm Chart（Helm releases）：核心是 terraform/helm/aptos-node 这个 aptos-node Chart，它真正定义并创建 validator、fullnode、HAProxy 等 Kubernetes 工作负载。

如果你的 Kubernetes 集群已经存在，也可以跳过 Terraform，直接在该集群上安装 Helm Chart；Terraform 只是"从零起步"最省事的方式。部署完成后的节点运维（查看 Pod、日志、服务等）请参考 terraform/helm/aptos-node/README.md（即本仓库根目录下的terraform/helm/aptos-node/README.md）。

二、前置条件与工作区准备（AWS / GCP 通用）

两种云平台部署前都需要准备如下工具链（以仓库 README 为准）：

• Terraform：仓库 README 标注的版本为 1.1.7，同时模块内required_version = "~> 1.2.0"（见下文main.tf示例），建议使用满足该约束的 Terraform 1.2.x 版本；
• Kubernetes CLI（kubectl）：用于后续检查 Pod 与服务；
• 云厂商 CLI：AWS 使用 AWS CLI，GCP 使用 Google Cloud CLI（gcloud / gsutil）；
• Aptos CLI（aptos）：用于生成密钥对、配置验证节点信息、编译 genesis。

无论哪种云平台，第一步都是创建工作目录并设定工作区（workspace）名称。工作区名称会被用作 Terraform workspace 名称，并进一步参与云资源命名，例如集群名aptos-$WORKSPACE：

$ export WORKSPACE=testnet $ mkdir -p ~/$WORKSPACE

三、AWS 部署完整流程（17 步）

本节完整继承并展开 terraform/aptos-node/aws/README.md 的部署步骤。前提：已拥有可用的 AWS 账号。

3.1 创建 S3 状态存储桶

Terraform state 需要持久化存储，先在 AWS 上创建 S3 bucket（也可在 AWS UI 完成）：

$ aws s3api create-bucket --bucket <bucket name> --region <region name>

3.2 编写 main.tf 并引用 Terraform 模块

$ cd ~/$WORKSPACE $ touch main.tf

编辑main.tf，通过source引用本仓库的terraform/aptos-node/aws模块：

variable "region" { type = string default = <aws region> # pick a region } terraform { required_version = "~> 1.2.0" backend "s3" { bucket = "terraform.aptos-node" key = "state/aptos-node" region = var.region } } provider "aws" { region = var.region } module "aptos-node" { # download Terraform module from aptos-labs/aptos-core repo source = "github.com/aptos-labs/aptos-core.git//terraform/aptos-node/aws?ref=main" region = var.region # Specify the region # zone_id = "<Route53 zone id>" # zone id for Route53 if you want to use DNS era = 1 # bump era number to wipe the chain chain_id = 5 image_tag = "testnet" # Specify the docker image tag to use validator_name = "<Name of Your Validator>" }

其中各参数含义：era为链的代数，用于开启一条全新的链（bump 该数字即可清空底层存储重新开始）；chain_id为 Aptos 链 ID；image_tag为要使用的 Docker 镜像 tag；validator_name为你的验证节点名称。zone_id为可选参数，指定 Route 53 托管区的 zone ID 以自动创建 DNS 记录（在 AWS 上默认会创建指向 Kubernetes Service 的 DNS 记录）。

仓库中同样提供了带占位符的变量模板，可直接参考 terraform/aptos-node/aws/terraform.tfvars 和 terraform/aptos-node/aws/backend.tfvars（后者的bucket、key、region用于 backend 配置）。

3.3 初始化、创建 workspace 并 apply

$ terraform init

terraform init会把所有依赖下载到当前目录的.terraform文件夹中。随后用 workspace 隔离环境：

$ terraform workspace new $WORKSPACE $ terraform workspace list

最后应用配置（AWS 上大约需要 20 分钟，Terraform 会在你的云账号中创建全部资源）：

$ terraform apply

3.4 验证资源与获取节点地址

apply 完成后：

# 配置 k8s 集群访问 $ aws eks update-kubeconfig --name aptos-$WORKSPACE # 应看到 haproxy、validator 和 fullnode 三个 Pod；validator/fullnode 此时为 pending（需后续步骤注入数据） $ kubectl get pods # 应看到 validator-lb 和 fullnode-lb 两个 Service，并带有可对外分享的 external-IP $ kubectl get svc

获取节点 IP 信息：

$ export VALIDATOR_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-validator-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')" $ export FULLNODE_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-fullnode-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')"

3.5 生成密钥对与验证节点配置

在工作目录中生成三组密钥（节点 owner 密钥、共识密钥、网络密钥）：

$ aptos genesis generate-keys --output-dir ~/$WORKSPACE

该命令会生成private-keys.yaml、validator-identity.yaml、validator-full-node-identity.yaml三个文件。务必备份好密钥文件——它是你确立节点所有权的凭证，将来若符合条件，将用于领取奖励。

配置验证节点信息：

$ aptos genesis set-validator-configuration --keys-dir ~/$WORKSPACE --local-repository-dir ~/$WORKSPACE --username <pick a username for your node> --validator-host $VALIDATOR_ADDRESS:6180 --full-node-host $FULLNODE_ADDRESS:6182

这会在工作目录生成以你的 username 命名的 YAML（如aptosbot.yaml），内容类似：

--- account_address: 7410973313fd0b5c69560fd8cd9c4aaeef873f869d292d1bb94b1872e737d64f consensus_key: "0x4e6323a4692866d54316f3b08493f161746fda4daaacb6f0a04ec36b6160fdce" account_key: "0x83f090aee4525052f3b504805c2a0b1d37553d611129289ede2fc9ca5f6aed3c" network_key: "0xa06381a17b090b8db5ffef97c6e861baad94a1b0e3210e6309de84c15337811d" validator_host: host: 30247cc34f270cb8.elb.us-west-2.amazonaws.com port: 6180 full_node_host: host: abc5b9734d4cc418.elb.us-west-2.amazonaws.com port: 6182 stake_amount: 1

3.6 创建 layout、下载 Framework 并编译 genesis

创建layout.yaml，定义节点在 validatorSet 中的角色（测试模式可以只包含一个节点）：

--- root_key: "0x5243ca72b0766d9e9cbf2debf6153443b01a1e0e6d086c7ea206eaf6f8043956" users: - <username you created in step 5> chain_id: 5

下载 AptosFramework Move 字节码（从aptos-framework-v0.1.0发布版本获取framework.zip）并解压，得到包含.mv字节码文件的framework文件夹：

$ unzip framework.zip

编译 genesis blob 与 waypoint：

$ aptos genesis generate-genesis --local-repository-dir ~/$WORKSPACE --output-dir ~/$WORKSPACE

这会生成genesis.blob与waypoint.txt两个文件。此时工作目录中应已具备以下完整文件集：

3.7 注入 genesis 数据并确认节点运行

将genesis.blob、waypoint.txt与身份文件作为 Secret 注入 k8s 集群：

$ kubectl create secret generic ${WORKSPACE}-aptos-node-genesis-e1 \ --from-file=genesis.blob=genesis.blob \ --from-file=waypoint.txt=waypoint.txt \ --from-file=validator-identity.yaml=validator-identity.yaml \ --from-file=validator-full-node-identity.yaml=validator-full-node-identity.yaml

如果你修改过era数值，创建 Secret 时务必保持一致（Secret 名称中的-e1后缀即对应era=1）。

最终确认所有 Pod 进入 Running 状态：

$ kubectl get pods NAME READY STATUS RESTARTS AGE node1-aptos-node-fullnode-e9-0 1/1 Running 0 4h31m node1-aptos-node-haproxy-7cc4c5f74c-l4l6n 1/1 Running 0 4h40m node1-aptos-node-validator-0 1/1 Running 0 4h30m

四、GCP 部署完整流程

本节完整继承 terraform/aptos-node/gcp/README.md 的部署步骤。前提：已拥有 GCP 账号，并已为部署 Aptos 节点创建独立的 GCP 项目。

4.1 创建 GCS 状态存储桶

使用 gsutil 创建 bucket（名称必须全局唯一）：

$ gsutil mb gs://BUCKET_NAME # 例如 $ gsutil mb gs://<project-name>-aptos-terraform-dev

4.2 编写 main.tf

$ cd ~/$WORKSPACE $ touch main.tf

terraform { required_version = "~> 1.2.0" backend "gcs" { bucket = "BUCKET_NAME" # bucket name created in step 2 prefix = "state/aptos-node" } } module "aptos-node" { # download Terraform module from aptos-labs/aptos-core repo source = "github.com/aptos-labs/aptos-core.git//terraform/aptos-node/gcp?ref=testnet" region = "us-central1" # Specify the region zone = "c" # Specify the zone suffix project = "<GCP Project Name>" # Specify your GCP project name era = 1 # bump era number to wipe the chain chain_id = 5 image_tag = "testnet" # Specify the docker image tag to use validator_name = "<Name of Your Validator, no space>" }

GCP 模块的变量模板见 terraform/aptos-node/gcp/terraform.tfvars 与 terraform/aptos-node/gcp/backend.tfvars。

4.3 初始化、创建 workspace 并 apply

$ terraform init $ terraform workspace new $WORKSPACE $ terraform workspace list $ terraform apply

GCP 上大约需要 10–20 分钟完成资源创建。apply 完成后：

# 配置 k8s 集群访问（注意 zone 的写法为 <region>/<zone>） $ gcloud container clusters get-credentials aptos-$WORKSPACE --zone <region/zone> --project <project> $ kubectl get pods # 应看到 haproxy、validator、fullnode，其中 validator/fullnode 为 pending $ kubectl get svc # 应看到 validator-lb 与 fullnode-lb 及其 external-IP

GCP 专属注意点：如果项目刚刚创建，需要授权集群的 service account 从aptos-globalDocker registry 拉取镜像——在 Artifact Registry 的aptos-internal仓库中为对应 service account 授予Artifact Registry Reader角色。

获取节点 IP 信息：

$ export VALIDATOR_ADDRESS="$(kubectl get svc \ ${WORKSPACE}-aptos-node-0-validator-lb \ --output jsonpath='{.status.loadBalancer.ingress[0].ip}')" $ export FULLNODE_ADDRESS="$(kubectl get svc \ ${WORKSPACE}-aptos-node-0-fullnode-lb \ --output jsonpath='{.status.loadBalancer.ingress[0].ip}')"

4.4 生成密钥与节点配置

$ aptos genesis generate-keys --output-dir ~/$WORKSPACE

GCP 流程会生成四个文件：public-keys.yaml、private-keys.yaml、validator-identity.yaml、validator-full-node-identity.yaml。同样必须妥善备份。

配置验证节点信息：

$ aptos genesis set-validator-configuration \ --local-repository-dir ~/$WORKSPACE \ --username <pick a username for your node> \ --validator-host $VALIDATOR_ADDRESS:6180 \ --full-node-host $FULLNODE_ADDRESS:6182

与 AWS 不同的是，GCP 流程会生成以 username 命名的目录，内含operator.yaml与owner.yaml两个文件。operator.yaml示例：

--- operator_account_address: 2adeace541c3018d1117ae528c95a6cd91d924ab916f6e16d910b0668fe74b34 operator_account_public_key: "0xb612f2727550042e0f8e3c0525f2b64a01e987598bc17c01167ccc94b30e32b4" consensus_public_key: "0x92eed9b185de3745b374200a3bb5e2173573bf8822edcee473a668182a1b1232c692c9a5c008f7425e752bf9aa84e03c" consensus_proof_of_possession: "0x810b0d3afb62e9905fcbe215a150d9709bb7c977ceaf05e1ab576c542b087743b35bf655e5db86c5db83ccbacb5926f40bc07e48bd2a00bcedacb43858a7fe3594890abccd03ff1ba340e3fe0e7895a27cdfe8739c16ca75e275af95d026caba" validator_network_public_key: "0xe83246a3f3203bb3919621330417243c891e67d8efd3072e237d7d97d4bbe70f" validator_host: host: xxx.xxx.xxx.xxx port: 6180 full_node_network_public_key: "0x8f385f894027cfaa95c46d8a3c1b50476114a8bcdb62b2c7c07b391509b45717" full_node_host: host: xxx.xxx.xxx.xxx port: 6182

4.5 layout、framework 与 genesis（GCP）

创建layout.yaml（内容与 AWS 相同：root key、用户名、chain_id）。注意：layout、framework 下载与 genesis 编译三步在 GCP 指南中明确标注：仅在测试模式启动节点时需要；生产环境这些内容由 Aptos Labs 统一生成。

# 下载 framework.zip 并解压得到 framework/ 目录 $ unzip framework.zip # 编译 genesis 与 waypoint $ aptos genesis generate-genesis --local-repository-dir ~/$WORKSPACE --output-dir ~/$WORKSPACE

工作目录最终文件清单与 AWS 相同（private-keys.yaml、validator-identity.yaml、validator-full-node-identity.yaml、<username>.yaml、layout.yaml、framework/、waypoint.txt、genesis.blob）。

4.6 注入 Secret 并确认运行

$ kubectl create secret generic ${WORKSPACE}-aptos-node-genesis-e1 \ --from-file=genesis.blob=genesis.blob \ --from-file=waypoint.txt=waypoint.txt \ --from-file=validator-identity.yaml=validator-identity.yaml \ --from-file=validator-full-node-identity.yaml=validator-full-node-identity.yaml

最终kubectl get pods输出与 AWS 相同：node1-aptos-node-fullnode-e9-0、node1-aptos-node-haproxy-*、node1-aptos-node-validator-0全部1/1 Running。

五、核心变量详解：如何按需定制部署

两个模块的完整变量定义分别见 terraform/aptos-node/aws/variables.tf 与 terraform/aptos-node/gcp/variables.tf。下面按功能分类整理关键参数。

5.1 链与节点基础参数（两云通用）

5.2 Helm 集成参数

从 terraform/aptos-node/aws/kubernetes.tf 的源码可以看出 Helm 集成的实现方式：模块通过helm_release资源将numValidators、numFullnodeGroups、imageTag、chain.era/chain_id/chain.name、validator/fullnode 的存储类与节点选择器、HAProxy 节点选择器等参数编码为 JSON 后传给 Chart（helm_values = jsonencode({...})），Chart 路径默认指向../../helm/aptos-node。此外该文件还演示了 AWS 专属的存储类初始化：删除 EKS 默认的gp2StorageClass，并创建gp3（ebs.csi.aws.com）、io1（kubernetes.io/aws-ebs，iopsPerGB=50）、io2（ebs.csi.aws.com，iops=40000）三个 StorageClass，且均为WaitForFirstConsumer绑定模式——这正是validator_storage_class/fullnode_storage_class变量（默认io1，可选gp3/io1/io2）的落地实现。

5.3 基础设施与节点池参数

AWS 模块：

GCP 模块：

六、部署完成后的 Kubernetes 运维要点

Terraform apply 之后，节点工作负载由 terraform/helm/aptos-node 这个 Helm Chart 管理。从 terraform/helm/aptos-node/README.md 可以整理出以下运维要点。

6.1 Chart 创建的 Kubernetes 资源

Chart 创建的所有资源都以 Helm release 名为前缀（记作<RELEASE_NAME>）：

• StatefulSet：<RELEASE_NAME>-aptos-node-0-validator（validator）、<RELEASE_NAME>-aptos-node-0-fullnode-e<ERA>（fullnode）；
• Deployment：<RELEASE_NAME>-aptos-node-0-validator下的 HAProxy deployment；
• PersistentVolumeClaim：<RELEASE_NAME>-0-validator-e<ERA>（validator）、fn-<RELEASE_NAME>-0-fullnode-e<ERA>-0（fullnode，命名不同是因为可部署多个 fullnode 而 validator 只有一个）；
• Service：<RELEASE_NAME>-aptos-node-0-validator-lb（validator 入站负载均衡）、<RELEASE_NAME>-aptos-node-0-fullnode-lb（fullnode 入站负载均衡）；
• ConfigMap：<RELEASE_NAME>-0（validator 与 fullnode 的 NodeConfig）、<RELEASE_NAME>-0-haproxy（HAProxy 配置）；
• 以及 NetworkPolicy、ServiceAccount、可选的 PodSecurityPolicy。

这解释了为什么部署指南中kubectl get svc能看到${WORKSPACE}-aptos-node-validator-lb与${WORKSPACE}-aptos-node-fullnode-lb——它们正是 Chart 创建的 LoadBalancer 类型 Service。

6.2 常用运维命令

# 查看 Pod 状态：validator、fullnode、HAProxy 至少应有 1/1 Running $ kubectl get pods # 查看单个 Pod 详情（含重启次数） $ kubectl describe pod <POD_NAME> # 查看 Pod 日志 $ kubectl logs <POD_NAME> # 查看所有 Service（LoadBalancer 类型会展示公网 IP 或 DNS） $ kubectl get services # 临时缩容某个工作负载 $ kubectl scale statefulset <STS_NAME> --replicas=0

6.3 多验证节点与 Era 概念

• 多节点测试模式：通过.Values.numValidators可在同一集群部署多个 validator，命名规则为<RELEASE_NAME>-aptos-node-<INDEX>-validator；每个 validator 都必须提供对应的 genesis ConfigMap（<RELEASE_NAME>-<INDEX>-genesis-e<ERA>）。fullnode 则通过.Values.numFullnodeGroups与.Values.fullnode.groups控制组数与副本数。
• Era：.Values.chain.era是每次清空 validator 存储时递增的数值，常用于测试网重置——这也解释了部署指南中 Secret 名称里-e1后缀的由来。

6.4 关键 Helm Values 速查

Chart 的核心 values 一览（完整表格见 terraform/helm/aptos-node/README.md）：

七、总结：两种云平台的差异对照

从整体看，Terraform 模块负责"搭台"（网络、托管 Kubernetes），Helm Chart 负责"唱戏"（validator、fullnode、HAProxy 等实际工作负载），而aptos genesis系列命令则负责产出节点身份与链的创世数据。三者的衔接点正是部署指南中那个注入 Kubernetes Secret 的动作——把genesis.blob、waypoint.txt与身份文件交给 Chart 创建的 StatefulSet，节点即可正式启动。按此流程，你可以在任一主流公有云上快速获得一个可运行的 Aptos 验证节点与配套全节点。

【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core