Pangu CLI 深度解析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-corePangu中文盤古是 Pangu 团队为 Aptos 打造的下一代测试网创建与管理 CLI。它是一个部署在既有 Kubernetes 基础设施之上、用严格类型标注的 Python 3 编写的模块化工具目标是把等 devnet/testnet 发版和为跑测试而写 PR变成历史让研究者与开发者可以按需、极速地拉起并管理属于自己的测试网。本文以 testsuite/pangu_lib/README.md 为骨架结合仓库内 CLI 入口、命令实现与模板配置源码完整梳理 Pangu 的全部命令、create 参数、节点蓝图Blueprint自定义拓扑以及其底层基于asyncio并行与 Kubernetes API 的创建流程。Pangu 是什么告别等待按需拉起测试网Aptos 生态中验证一个新区块链功能通常意味着等待官方 devnet/testnet 发版或者通过 Forge 提交 PR 来启动测试网整个周期冗长且不可控。Pangu 正是为解决这一痛点而生它是一个模块化、可定制、下一代的 Aptos 测试网创建/管理 CLI使用 Python 编写允许你按需、极速地在已连接的 Kubernetes 集群中创建和管理测试网相比 Forge 测试网创建流程Pangu 天生更快其核心原因有两点README 明确给出Pangu 不使用 HelmPangu 引入了基于并发/并行concurrency/parallelism的新优化。此外Pangu 使用严格类型标注strictly-typed Python 3并采用模块化组织方式因此源码可读性显著优于其前辈。从源码层面看并行优化的落点清晰可见在 create_testnet.py 的generate_genesis中Pangu 为每个节点收集generate_keys_and_configuration协程通过asyncio.gather(*coroutines)并行生成所有节点的密钥、配置与 StatefulSet在节点内部validator 与 vfn 的 StatefulSet 创建同样通过asyncio.gather并发提交create_testnet.py。设计理念与能力边界Vision从研究者工具到 Forge 的替代者Pangu 的定位首先是面向希望快速创建测试网的研究者/开发者。但它的长期愿景更为宏大取代 Forge 中测试网的创建与部署方式。README 指出Forge 集成不在首版迭代范围内但未来 Forge 将最终调用 Pangu CLI 来完成测试网创建与管理。仓库中的pangu-sdk一个围绕 Pangu CLI 的轻量 Rust 封装正是为Pangu-Forge 集成铺路的起点它允许 Rust 代码通过结构体直接调用 Pangu 命令而无需手写 Pangu 配置 YAML。明确的能力边界Pangu 不提供基础设施这是一个必须牢记的前提Pangu 本身不负责基础设施供给provisioning。连接到一个可用的 K8s 集群是使用 Pangu 的先决条件README 特别说明它可配合 GKE 节点自动扩缩node auto provisioning工作。也就是说Pangu 负责的是在已有集群上完成 genesis 生成、K8s 资源Namespace/StatefulSet/Service/PVC/ConfigMap/Secret的编排与部署、以及后续的更新、健康检查、重启、删除等生命周期管理。快速上手环境准备与安装前置条件本地安装好 aptos-core 并进入testsuite目录testsuite/pangu_lib/README.md中第 1 步拥有一个可用的 Kubernetes 集群环境测试场景建议使用 KinDREADME 提供了用于搭建 KinD 的脚本参考准备好kubectl与aptosCLI若aptos不在$PATH中可在创建时用--aptos-cli-path指定。安装与设置别名Pangu 所有 Python 操作的入口是poetry# 安装 poetry 依赖 poetry install # 设置 pangu 别名 alias pangupoetry run python pangu.py完成 K8s 环境配置后即可用以下命令查看帮助pangu -h pangu node -h pangu testnet -h注意README 建议优先使用pangu [testnet|node] [command] -h获取每个命令的选项与参数详情下文列出的命令签名也以当前仓库 pangu.py 与各命令实现为准。命令全景Testnet 与 Node 两大命令组CLI 入口 pangu.py 使用 Click 框架定义了两个子命令组testnet与node并分别聚合 testnet_commands/commands.py 与 node_commands/commands.py 中导出的命令。Testnet 命令命令功能说明pangu testnet create [OPTIONS]依据选项中给定的配置在已连接集群中创建一个测试网pangu testnet delete [TESTNET_NAME]删除已连接集群中的指定测试网pangu testnet get展示已连接集群中所有活跃测试网pangu testnet get [TESTNET_NAME]展示已连接集群中单个测试网的节点信息pangu testnet healthcheck [TESTNET_NAME]对单个测试网执行健康检查WIPpangu testnet restart [TESTNET_NAME]重启单个测试网中的所有节点pangu testnet update [TESTNET_NAME] [OPTIONS]使用选项更新单个测试网中的所有节点pangu testnet transaction-emitter [TESTNET_NAME] [OPTIONS]按名称为测试网创建事务发射器transaction emitter其中get命令支持-o选项切换输出格式默认为表格print传入json可输出 JSON。仓库实现中pangu testnet get会筛选所有以pangu-开头的 Namespace 并汇总其状态、年龄与节点活跃数get_testnet.py。Node 命令命令功能说明pangu node stop [TESTNET_NAME] [NODE_NAME]停止单个测试网中的某个节点pangu node start [TESTNET_NAME] [NODE_NAME]启动单个测试网中的某个节点pangu node restart [TESTNET_NAME] [NODE_NAME]重启单个测试网中的某个节点pangu node profile [TESTNET_NAME] [NODE_NAME]展示节点 profiling 工具pangu node wipe [TESTNET_NAME] [NODE_NAME]擦除单个测试网中的某个节点WIPpangu node add-pfn [TESTNET_NAME] [NODE_NAME] [OPTIONS]使用选项为单个测试网添加一个 PFNWIPadd-pfn在当前仓库中已实现得相当完整其支持选项见 node_commands/commands.py包括--imagePFN 使用的镜像默认取util.DEFAULT_IMAGE--workspacedry-run 时保存部署指令的工作区路径--storage-class-namePFN 存储类名称默认标准存储类--storage-size存储大小默认10Gi--cpuCPU 请求默认4--memory内存请求默认8Gi。核心命令详解pangu testnet createcreate是 Pangu 最核心的命令本节完整展开其全部选项与底层执行流程。create 参数全解以下参数定义与默认值取自 testnet_commands/commands.py 及 README选项含义默认值示例--pangu-node-configs-pathPangu 节点配置YAML路径仓库默认模板testsuite/pangu_lib/template_testnet_files/pangu_node_config.yaml--pangu-node-configs-path /path/to/node/configs.yaml--layout-pathlayout 文件YAML路径仓库默认模板testsuite/pangu_lib/template_testnet_files/layout.yaml--layout-path /path/to/layout.yaml--framework-path已编译的 Move framework 文件head.mrb或framework.mrbutil.TEMPLATE_DIRECTORY/framework.mrb--framework-path /path/to/framework.mrb--num-of-validators测试网中通用 validator 的数量若传入自定义 Pangu 节点配置该选项会被覆盖10--num-of-validators 20--workspacegenesis 文件生成的目标文件夹默认临时目录临时目录--workspace /path/to/workspace--dry-run传入true表示只跑 genesis、不部署到 K8s所有 K8s YAML 会 dump 到 workspace未提供 workspace 时 dump 到临时目录False--dry-run true--aptos-cli-pathaptosCLI 不在$PATH时的路径aptos--aptos-cli-path /path/to/aptos--name测试网名称默认随机生成无论是否自定义名称都会自动加上pangu-前缀随机生成--name MyTestnet注意事项--framework-path在 Click 定义中是必填项requiredTrue。编译框架的命令为cargo run --locked --package aptos-framework -- release。测试网命名逻辑见 commands.py未传--name时生成pangu-{用户名}-{8位随机小写字母数字}并截断到 63 字符K8s 命名上限传了--name则直接使用pangu-{name}。create在创建前会检查同名测试网是否已存在创建失败时非 dry-run 场景会自动执行清理删除commands.py。create 的底层执行流程从源码 create_testnet.py 可以看到create_testnet_main依次完成以下步骤创建工作区workspace未提供--workspace时使用临时目录mkdtemp提供时会在其下创建pangu_artifacts/{testnet_name}子目录dry-run 模式还会额外创建dry_run子目录创建 Namespace非 dry-run以测试网名称创建 K8s Namespace并打上managed-by: pangu标签解析 Pangu 节点配置未提供配置时回退到模板文件使用dacite.from_dict将 YAML 反序列化为PanguNodeLayout数据类生成临时 layout把提供的 layout 复制到 workspace并根据所有蓝图的count生成形如{blueprint}-node-{i}的users列表写入 layout 的users字段create_testnet.py并行生成 genesis为每个节点并行执行aptos genesis generate-keys、aptos genesis set-validator-configuration传入 validator-host、full-node-host 与 stake-amount随后运行aptos genesis generate-genesis --local-repository-dir {workspace} --output-dir {workspace}产出waypoint.txt与genesis.blob创建 genesis 产物 ConfigMapwaypoint.txt放入data二进制genesis.blobbase64 编码后放入binary_dataConfigMap 名为genesis-artifiact-configmap-pangu编排节点资源为每个节点创建 ConfigMapvalidator/vfn 配置、Secretvalidator 身份、PVC默认10Gi、Service 与 StatefulSet。容器以aptos-node -f /opt/aptos/etc/{type}.yaml启动挂载配置、genesis 与身份目录create_testnet.py。端口与默认资源定义于 util.pyvalidator 6180、vfn 6182vfn 额外暴露 6181 供 pfn 拨号、API 8080、metrics 9101、backup 6186默认镜像为aptoslabs/validator:devnetsha256:...默认资源请求为 CPU4、内存8Gi默认 PVC 大小10Gi。Blueprint 命名校验解析配置时会强制要求所有 blueprint 名称必须全小写且互不相同否则直接抛异常create_testnet.py。Pangu Node Config自定义测试网拓扑Pangu 允许用户通过默认模板快速创建 n 个节点也支持通过自定义 pangu config 创建节点配置与 Pod 镜像各不相同的异构拓扑。仓库中的默认模板为 template_testnet_files/pangu_node_config.yaml完整内容如下blueprints: nodebp: # Must to be all lowercase, and distinct validator_config_path: # Should provide an absolute path. Can leave empty for the default validator_image: # Can leave empty for the default validator_storage_class_name: # Can leave empty for the default vfn_config_path: # Should provide an absolute path. Use empty str if create_vfns: false. # Can leave empty for the default vfn_image: # Can leave empty for the default vfn_storage_class_name: # Can leave empty for the default nodes_persistent_volume_claim_size: # Can leave empty for the default create_vfns: true # CANNOT BE MODIFIED AFTER DEPLOYMENT stake_amount: 100000000000000 # CANNOT BE MODIFIED AFTER DEPLOYMENT count: -1 # CANNOT BE MODIFIED AFTER DEPLOYMENT... This is count of validators. In the template, the count doesnt matter as it gets overriden by either the default (10), users --num-of-validators, or users custom pangue node config. cpu: # Can leave empty for the default memory: # Can leave empty for the default # nodebpexample1: # validator_config_path: # validator_image: # validator_storage_class_name: # Can leave empty for the default # vfn_config_path: # vfn_image: # nodes_persistent_volume_claim_size: # Can leave empty for the default # create_vfns: false # # stake_amount: 100000000000000 # count: -1 # nodebpexample2: # validator_config_path: # validator_image: # validator_storage_class_name: # Can leave empty for the default # vfn_config_path: # nodes_persistent_volume_claim_size: # Can leave empty for the default # vfn_image: # vfn_storage_class_name: # Can leave empty for the default # create_vfns: false # # stake_amount: 100000000000000 # count: -1字段说明与填充规则blueprints:配置文件必须以该顶层键开头一个 blueprint描述一组 validator/vfn 对validator 配置、validator 镜像、vfn 配置、vfn 镜像、validator 的stake_amount以及希望用该 blueprint 创建的 validator/vfn 对数量空字符串字段表示使用默认值validator_config_path/vfn_config_path为空时回退到 template_testnet_files/validator.yaml 与 vfn.yaml镜像为空时回退到util.DEFAULT_IMAGEcpu/memory为空时回退到4/8Gicreate_testnet.pycreate_vfns/stake_amount/count部署后不可修改注释中明确标注 CANNOT BE MODIFIED AFTER DEPLOYMENT模板中的count无实际意义它会被默认值 10、用户的--num-of-validators或用户自定义 pangu config 中的 count 覆盖count为 -1仅出现在模板中表示待覆盖自定义配置中请填写实际数量。命名规则blueprint 名称直接决定创建出的 Pod 命名使用nodebp蓝图创建的 validator 命名为nodebp-node-{i}-validatori 为节点索引相应的 vfn 命名为nodebp-node-{i}-vfn。这一命名规则在代码中由util.type_specific_nameutil.py统一生成是get、restart、update等后续管理命令定位节点的依据。使用自定义配置创建pangu testnet create --pangu-node-configs-path /path/to/my_node_configs.yaml \ --framework-path /path/to/framework.mrb \ --num-of-validators 20README 建议在大多数场景下你应该且应当配置多个 blueprint以便在一个测试网内混合不同镜像、不同资源规格、不同是否带 vfn 的节点组。同时请记住pangu config 不仅用于创建测试网也可用于更新已有测试网见下节。运行期管理更新、健康检查与压测pangu testnet update热更新节点通过修改 pangu node configs 并执行pangu testnet update [TESTNET_NAME] [PANGU-NODE-CONFIGS-PATH]可以更新已经启动的测试网——包括替换镜像与节点配置。从 update_nodes.py 的实现看其流程为解析新的 pangu node configcount传 -1 且不使用默认值逻辑对每个 blueprint 中的每个节点通过ThreadPoolExecutor并行执行update_node使用 K8s JSON Patch 替换 StatefulSet 容器镜像/spec/template/spec/containers/0/imagePatch 对应的 ConfigMapvfn 场景会先借助模板注入正确的 DNS4 种子地址最后调用restart_node_main重启节点使配置生效。pangu testnet healthcheck健康检查pangu testnet healthcheck [TESTNET_NAME]支持-e/--endpoint-name参数默认ledger_info可选值见 healthcheck.pyledger_info通过kubectl port-forward暴露每个 Service 的 8080 端口两次调用/v1获取ledger_version间隔 30 秒若版本号增长则判定健康healthy调用/v1/-/healthy?duration_secs10返回aptos-node:ok判定健康。所有节点通过线程池并行检查最终打印 TOTAL / PASSED / FAILED / UNACCOUNTED 汇总表。pangu testnet transaction-emitter负载压测pangu testnet transaction-emitter [TESTNET_NAME] [OPTIONS]会为测试网创建一个事务发射器 Pod镜像aptoslabs/tools:devnet资源请求/限制为 CPU 15、内存 26Gi见 transaction_emitter.py透传aptos-transaction-emitter的全部参数并支持--dry-run仅 dump Pod YAML与--workspace默认/tmp。非 dry-run 时它会创建 Pod、跟踪日志并在结束后询问是否输入delete删除该 Pod。代码库导航Pangu 的源码位于testsuite下核心目录与文件如下testsuite/pangu.pyPangu CLI 入口聚合 testnet 与 node 两组命令其中的CatchAllExceptions类将所有异常路由到统一代码块默认只打印简洁信息可按注释提示打开log.error(exc, exc_infoTrue)获取详细堆栈testsuite/test_framework测试用系统抽象Shell / Filesystem / Kubernetes 三件套SystemContext数据类将其打包新增 Kubernetes 特性时可能需要更新这里的 Kubernetes 抽象testsuite/pangu_lib/node_commandspangu node {COMMAND}系列命令每个命令一个.py文件汇总到commands.py导出给pangu.pytestsuite/pangu_lib/testnet_commandspangu testnet {COMMAND}系列命令组织结构同上testsuite/pangu_lib/tests单元测试覆盖 create / delete / get / restart / start-stop / update / wipe / add-pfn 等testsuite/pangu-sdkPangu 的 Rust SDK是 Pangu CLI 的轻量 Rust 封装允许 Rust 代码通过传入结构体调用 Pangu 命令而无需手写 YAML目前尚未 feature-complete但已可作为 Pangu-Forge 集成的良好起点testsuite/pangu_lib/template_testnet_files默认模板文件包括 pangu_node_config.yaml、layout.yaml、validator.yaml、vfn.yaml、pfn.yaml。性能实测数据以下数据来自 README 记录的性能测试由 Olsen Budanur 在标准 GKE 集群中执行测试指标为genesis 应用全部 K8s 资源的耗时。需要说明的是与 Forge 不同测试中 Pangu 运行在与测试网部署不同的集群因此在测试时处于劣势Run4 Vals7 Vals 5 VFNs100 Vals 100 VFNs100 Vals 0 VFNs15 s9 s111 s65 s25 s12 s116 s65 s36 s10 s112 s65 s46 s10 s111 s66 s55 s10 s113 s63 s65 s10 sxx75 s10 sxx86 s13 sxx96 s12 sxx105 s12 sxxAVG5.4 s10.8 s112.6 s64.8 sForge AVG~121 s~148 sxxDiffPangu ~22x FasterPangu ~14x Fasterxx上表为 README 中记录的原始实验数据具体节省量Savings因集群资源单价而异README 未给出统一结论。这些数字是在特定 GKE 环境下的单次实验观测值实际表现会随集群规格、网络与镜像拉取情况而变化。重要注意事项与故障排查基础设施边界Pangu 不创建集群务必先连接好 K8s 集群支持 GKE 节点自动扩缩错误排查技巧遇到晦涩难懂的错误时打开 pangu.py 中 UNCOMMENT FOR MORE VERBOSE ERROR MESSAGES 注释下方的log.error(exc, exc_infoTrue)可获取更详细的错误信息所有异常都会路由到该代码块。此外把create_testnet.py中所有stream_output设为True可以获得更多日志Move framework 需经常重新编译不要过度依赖默认的framework.mrb。Move framework 的更新可能且已经破坏 Pangu建议使用cargo run --locked --package aptos-framework -- release频繁编译新版本并通过--framework-path传入vfn 配置注入vfn 与 validator 之间的网络种子地址在节点创建前未知Pangu 通过create_temp_vfn_configutil.py在部署时动态写入正确的/dns4/...地址这也是 vfn 配置不建议手改的原因之一。环境依赖补充Python所有 Python 操作的入口均为poetry安装 poetry 后执行poetry install安装依赖使用poetry run激活虚拟环境执行命令任务工具入口为poetry run poe。Kubernetes你将需要管理多个 Kubernetes 集群至少一个在 GCP一个在开发机上通过 KinD 搭建安装kubectl用于与集群交互安装 KinD 用于本地测试环境。总结Pangu 将 Aptos 测试网的生命周期管理从等待发版 Forge PR缩短为一条 CLI 命令pangu testnet create即可在已连接的 K8s 集群中并行生成密钥、配置与 genesis 产物并完成部署pangu node configs的蓝图机制让异构拓扑成为可能而update、healthcheck、transaction-emitter等命令则覆盖了测试网运行期的更新、巡检与压测需求。对于需要快速验证新功能、复现网络行为或进行性能实验的 Aptos 研究者与开发者而言Pangu 是当前仓库中开箱即用的按需测试网方案其实现细节均可在上文列出的源码文件中进一步追溯。【免费下载链接】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），仅供参考