Spring Boot中Logback日志配置与优化实践
2026/9/18 8:55:16
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 CLI（crate 名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 后端K8sFactory； - ForgeConfig：描述一次测试运行的完整配置，包括测试列表、验证节点/全节点数量、交易负载（EmitJob）、成功判定标准（SuccessCriteria）等，定义见 testsuite/forge/src/config.rs；
- Test / 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 验证节点的本地 Swarm
2.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 Ctrl+C to kill this, otherwise it will run forever.后让线程永久挂起（见同文件RunForever::run），也就是说网络一旦启动就不会自动结束，适合长期开发调试；--num-validators 4：覆盖测试套件默认的验证节点数量为 4；test 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 的 root（mint）私钥、每个节点的 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 手动停掉并重启单个节点
利用上述输出信息，可以精确地停掉并重启某个节点。例如停掉并重启节点 0：
kill -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?amount=<amount to mint>&pub_key=<public key to mint tokens to>例如想给公钥为0x1234...的账户铸造 1000 个代币：
curl -X POST "http://127.0.0.1:8081/mint?amount=1000&pub_key=0x1234..."3.3 替代方案：直接用 Faucet CLI
如果不想启动常驻的 Faucet 服务，也可以直接用 Faucet 的命令行客户端完成一次性铸币：
cargo run -p aptos-faucet-cli -- --amount 10 --accounts <account_address> --key <private_key>其中--amount是铸币数量，--accounts是目标账户地址，--key是私钥。两个子 crate（aptos-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 <NAME> | land_blocking | 要运行的测试套件名 |
--duration-secs <N> | 300 | 测试运行时长（秒） |
--num-validators <N> | 由套件决定 | 覆盖验证节点数量（必须为正数） |
--num-validator-fullnodes <N> | 0 | 覆盖验证节点全节点数量（不能超过验证节点数） |
--list | 关闭 | 仅列出所有测试，不实际运行 |
--filter <FILTER> | 无 | 按子串过滤要运行的测试名 |
--exact | 关闭 | 过滤时要求精确匹配而非子串匹配 |
--format <pretty\|terse\|json> | pretty | 输出格式（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 <N> | 1 | 每个节点的执行并发级别 |
--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.rs）：
operator 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 个验证节点 +NetworkBandwidthTest）；run_forever：无限运行的网络，适合本地开发调试；k8s_suite：Kubernetes 套件（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_forge（main.rs）收尾：
- 全部通过：进程正常退出（退出码 0）；
- 软失败（soft failure）：进程以退出码
51退出； - 硬失败：进程以退出码
1退出。
本地环境无需担心吞吐相关的硬性指标——正如前文所述，本地模式下 CLI 会自动把min_avg_tps放宽到 400 并切换到MaxLoad负载模式。
八、常见问题与排查建议
- 网络端口冲突：REST API 与 Inspection 服务端口是随机分配的，若希望固定端口，可结合
--swarmdir持久化目录中的node.yaml自行调整节点配置后重启节点。 --num-validator-fullnodes大于--num-validators：CLI 会直接报错，二者须满足全节点数 ≤ 验证节点数。- 想跳过重复编译：本地调试可先用
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），仅供参考