Aptos Forge CLI 实战指南本地与云端 Swarm 测试网络的部署、运维与压测【免费下载链接】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导读Forge 是 Aptos 区块链的端到端E2E测试框架而 Forge CLIcrate 名aptos-forge-cli二进制名forge则是驱动该框架的命令行工具负责在本机或 Kubernetes 集群中一键拉起由多个验证节点Validator与验证节点全节点Validator Fullnode组成的 Swarm 测试网络并在其上执行预定义或自定义的测试套件。本文以仓库 testsuite/forge-cli/src/README.md 为主线结合 testsuite/forge-cli/src/main.rs 与 testsuite/forge/src 的源码实现完整讲解本地 Swarm 的启动、节点运维、Faucet 铸币、Validator Fullnode 扩展以及全部 CLI 参数帮助你从零开始搭建属于自己的 Aptos 多节点测试环境。一、Forge CLI 是什么从测试框架到命令行入口Forge 的定位在 testsuite/forge/src/lib.rs 中写得很明确Forge is a framework for writing and running end-to-end tests in Aptos——即一套用于编写和运行 Aptos 端到端测试的框架。它对外提供三大抽象Factory负责创建 Swarm测试网络的工厂分为本地后端LocalFactory与 Kubernetes 后端K8sFactoryForgeConfig描述一次测试运行的完整配置包括测试列表、验证节点/全节点数量、交易负载EmitJob、成功判定标准SuccessCriteria等定义见 testsuite/forge/src/config.rsTest / AptosTest / NetworkTest / AdminTest不同类型测试的 trait分别对应单链上操作、网络级操作与链上管理操作。Forge CLI 就是这些能力的命令行封装。它接收用户指定的测试套件名、节点数量等参数构造ForgeConfig再通过Forge::new(...)与run_forge(...)完成测试编排见 main.rs。CLI 的包名与二进制定义在 testsuite/forge-cli/Cargo.toml 中package.name aptos-forge-cli[[bin]] name forge因此可以直接用cargo run -p aptos-forge-cli运行。二、快速开始部署一个 4 验证节点的本地 Swarm2.1 基础命令Forge CLI 可以在本机直接部署一个本地 Swarm——即一组验证节点每个节点运行在独立的进程中。启动一个由 4 个验证节点组成、且持续运行除非手动终止的网络命令如下cargo run -p aptos-forge-cli -- --suite run_forever --num-validators 4 test local-swarm命令解析如下--suite run_forever指定测试套件。run_forever是 testsuite/forge-cli/src/suites/ungrouped.rs 中定义的一个套件别名其ForgeConfig只包含一个RunForever测试。该测试的实现非常直白打印The network has been deployed. Hit CtrlC to kill this, otherwise it will run forever.后让线程永久挂起见同文件RunForever::run也就是说网络一旦启动就不会自动结束适合长期开发调试--num-validators 4覆盖测试套件默认的验证节点数量为 4test local-swarm子命令test表示运行测试local-swarm表示使用本地 Swarm 后端对应TestCommand::LocalSwarm。CLI 的参数定义见 main.rs--duration_secs默认 300 秒--suite默认值为land_blocking--num-validators与--num-validator-fullnodes均为可选覆盖项。在本地模式下CLI 还会自动放宽成功标准min_avg_tps 400.0并把交易负载切换为MaxLoad模式mempool_backlog: 5000避免本地环境因吞吐不足而误报失败见 main.rs。2.2 启动输出解读执行上述命令后终端会打印关键信息包括genesis 构建目录、Swarm 的 rootmint私钥、每个节点的 PID、启动命令、REST API 与 Inspection 服务地址示例如下2022-09-01T15:41:27.228289Z [main] INFO crates/aptos-genesis/src/builder.rs:462 Building genesis with 4 validators. Directory of output: /private/var/folders/dx/.../.tmpq9uPMJ 2022-09-01T15:41:28.090606Z [main] INFO testsuite/forge/src/backend/local/swarm.rs:207 The root (or mint) key for the swarm is: 0xf9f... 2022-09-01T15:41:28.094800Z [main] INFO testsuite/forge/src/backend/local/node.rs:129 Started node 0 (PID: 78939) with command: .../aptos-core/target/debug/aptos-node -f .../.tmpq9uPMJ/0/node.yaml 2022-09-01T15:41:28.094825Z [main] INFO testsuite/forge/src/backend/local/node.rs:137 Node 0: REST API is listening at: http://127.0.0.1:64566 2022-09-01T15:41:28.094838Z [main] INFO testsuite/forge/src/backend/local/node.rs:142 Node 0: Inspection service is listening at http://127.0.0.1:64568这些日志分别来自genesis 构建crates/aptos-genesis/src/builder.rs说明本地 Swarm 会现场生成一份含 4 个验证节点的 genesis 文件root 密钥testsuite/forge/src/backend/local/swarm.rs当前仓库中对应的LocalSwarm结构体亦维护root_key字段这是后续 Faucet 铸币所需的key节点启动testsuite/forge/src/backend/local/node.rs中的Started node ... (PID: ...)、REST API is listening at: http://127.0.0.1:port、Inspection service is listening at http://127.0.0.1:port三条日志。也就是说每个验证节点都是一个独立的aptos-node进程其配置文件node.yaml与日志都落在 swarm 输出目录下REST API 端口随机分配。2.3 手动停掉并重启单个节点利用上述输出信息可以精确地停掉并重启某个节点。例如停掉并重启节点 0kill -9 Node 0 PID cargo run -p aptos-node -- -f Location to the node 0 configuration file displayed above第一条命令按 PID 强杀节点进程第二条命令用-f指定该节点的node.yaml配置路径重新拉起aptos-node。这种杀节点—重启节点的操作正是 Forge 中RestartValidator这类网络测试见 ungrouped.rs所模拟的场景先health_check再stop()然后start()并再次health_check。三、Faucet 与铸币为测试网络注入代币Swarm 启动后是一个空链——没有流通中的 APT。要铸造代币需要额外运行一个 Faucet 服务。3.1 启动 Faucet 服务cargo run -p aptos-faucet-service -- run-simple --key key --node-url node_url两个参数的取值直接来自 2.2 节的启动输出key启动 Swarm 时打印的The root (or mint) key for the swarm is: 0xf9f...即 root/mint 私钥node_url启动 Swarm 时打印的REST API is listening at: http://127.0.0.1:64566。该命令会在本机启动一个 Faucet 服务默认监听8081端口背后对接的就是上面这个 REST API 地址。3.2 通过 Faucet 铸币Faucet 启动后即可通过 HTTP 接口向测试账户铸币curl -X POST http://127.0.0.1:8081/mint?amountamount to mintpub_keypublic key to mint tokens to例如想给公钥为0x1234...的账户铸造 1000 个代币curl -X POST http://127.0.0.1:8081/mint?amount1000pub_key0x1234...3.3 替代方案直接用 Faucet CLI如果不想启动常驻的 Faucet 服务也可以直接用 Faucet 的命令行客户端完成一次性铸币cargo run -p aptos-faucet-cli -- --amount 10 --accounts account_address --key private_key其中--amount是铸币数量--accounts是目标账户地址--key是私钥。两个子 crateaptos-faucet-service与aptos-faucet-cli均位于仓库 crates/aptos-faucet 目录下更完整的 Faucet 使用说明可参考该目录的 README。四、扩展网络同时启动 Validator Fullnode默认情况下本地 Swarm 只包含验证节点。若要同时启动验证节点全节点Validator Fullnode使用--num-validator-fullnodes参数cargo run -p aptos-forge-cli -- --suite run_forever --num-validators 3 --num-validator-fullnodes 1 test local-swarm该命令会启动 3 个验证节点 1 个验证节点全节点。CLI 会对该参数做合法性校验在 main.rs 中全节点数量不能超过验证节点数量否则报错Cannot have more fullnodes than validators!且--num-validators必须为正数NonZeroUsize校验。这与 config.rs 中ForgeConfig的initial_validator_count: NonZeroUsize默认为 1与initial_fullnode_count: usize默认为 0的设计一致。五、全部 CLI 参数速查运行以下命令可查看完整帮助cargo run -p aptos-forge-cli --help结合 main.rs 的 clap 定义与 runner.rs 中Options结构体常用参数汇总如下5.1 全局参数参数默认值说明--suite NAMEland_blocking要运行的测试套件名--duration-secs N300测试运行时长秒--num-validators N由套件决定覆盖验证节点数量必须为正数--num-validator-fullnodes N0覆盖验证节点全节点数量不能超过验证节点数--list关闭仅列出所有测试不实际运行--filter FILTER无按子串过滤要运行的测试名--exact关闭过滤时要求精确匹配而非子串匹配--format pretty\|terse\|jsonpretty输出格式json 仅为兼容占位不支持--retain-debug-logs关闭为所有节点保留 debug 及以上日志默认仅前 5 个节点可用环境变量FORGE_RETAIN_DEBUG_LOGS设置--junit-xml-path PATH无将测试结果写成 JUnit XML 报告可用环境变量FORGE_JUNIT_XML_PATH设置5.2test local-swarm子命令参数参数默认值说明--swarmdir PATH临时目录本地 swarm 的构建目录持久化输出 genesis、日志、配置--cpu-affinity LIST无按节点指定 CPU 亲和性冒号分隔如0-5,7-8:10-20,23表示节点 0 绑到 CPU 0-5、7-8节点 1 绑到 10-20、23--mem-bind LIST无按节点指定 NUMA 内存绑定冒号分隔如0:1-2:1,3--concurrency-level N1每个节点的执行并发级别--aptos-node-binary PATH无指定预编译的aptos-node二进制路径可跳过 cargo build--auto-restart关闭自动重启崩溃的验证节点5.3test k8s-swarm子命令参数Kubernetes 后端用于在集群中运行测试CI 常用主要参数--namespace测试命名空间缺省时自动生成一个如forge-word1-word2-word3-word4的随机命名空间、--image-tag默认devnet、--upgrade-image-tag升级测试目标镜像、--port-forward使用 kubectl 端口转发而非集群内 DNS、--reuse/--keep复用/保留测试网络、--enable-haproxy、--enable-indexer附带启动 indexer 栈、--num-pfns附带部署的公共全节点数量等完整定义见 main.rs。5.4operator子命令除运行测试外CLI 还提供集群运维子命令见 main.rsoperator set-node-image-tag更新集群中某个节点 StatefulSet 的镜像标签operator clean-up [--namespace NS] [--dry-run]清理已有集群指定 namespace 则清理该命名空间否则根据 forge-management configmap 尝试全量清理operator create直接创建一个用于测试的新集群可指定--num-validators、--num-fullnodes、--num-pfns、--enable-indexer等。六、内置测试套件速览Forge CLI 支持通过--suite指定预置套件或直接指定某个命名测试。套件解析逻辑位于 main.rs 的get_test_suite函数高层套件别名表达意图的快捷方式local_test_suite本地冒烟套件包含FundAccount、TransferCoins、GetMetadata、RestartValidator、EmitTransaction等测试pre_release预发布套件30 个验证节点 NetworkBandwidthTestrun_forever无限运行的网络适合本地开发调试k8s_suiteKubernetes 套件30 验证节点含框架升级与性能基准测试chaos混沌测试套件含网络带宽、三区域模拟、网络丢包等见 ungrouped.rs。按优先级匹配的命名测试分组land_blocking阻塞发布的主套件、multi_region、pfn、realistic_env、state_sync、dag、indexer、ungrouped散装测试如consensus_stress_test、network_partition、twin_validator_test、validator_reboot_stress_test、mainnet_like_simulation_test等。若无法匹配任何套件CLI 会报错Invalid --suite given: name。每个命名测试最终都会落到一个ForgeConfig它由测试类型Admin / Aptos / Network、初始节点数、交易负载EmitJobRequest、成功标准SuccessCriteria如最低平均 TPS、无重启、链进度阈值、系统资源阈值等构成详见 testsuite/forge/src/config.rs 与 testsuite/forge/src/success_criteria.rs。七、测试结果与退出码测试运行由run_forgemain.rs收尾全部通过进程正常退出退出码 0软失败soft failure进程以退出码51退出硬失败进程以退出码1退出。本地环境无需担心吞吐相关的硬性指标——正如前文所述本地模式下 CLI 会自动把min_avg_tps放宽到 400 并切换到MaxLoad负载模式。八、常见问题与排查建议网络端口冲突REST API 与 Inspection 服务端口是随机分配的若希望固定端口可结合--swarmdir持久化目录中的node.yaml自行调整节点配置后重启节点。--num-validator-fullnodes大于--num-validatorsCLI 会直接报错二者须满足全节点数 ≤ 验证节点数。想跳过重复编译本地调试可先用cargo build -p aptos-node构建好节点二进制再通过--aptos-node-binary PATH传入避免每次启动都重新构建。测试用例筛选使用--filter 关键字只运行名称中包含关键字的测试配合--list先查看全部测试名。崩溃节点自动恢复本地 Swarm 可加--auto-restart由后台监控线程自动拉起异常退出的验证节点对应LocalSwarm中的auto_restart与monitor_handle机制见 testsuite/forge/src/backend/local/swarm.rs。至此你已经掌握了 Forge CLI 从本地多节点 Swarm 部署、节点级运维、Faucet 铸币到云端集群测试的完整链路。无论是验证共识行为、压测性能还是调试链上功能都可以在这套命令行工具之上快速展开。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考