Chainlink 本地 CRE E2E 实战指南环境生命周期、冒烟/回归测试与自定义拓扑【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink本文面向需要在chainlink仓库中本地开发、调试 CREChainlink Runtime Environment链上/链下工作流运行时的开发者和测试工程师系统讲解如何在本地拉起完整的 CRE 环境、运行 CRE 冒烟/回归端到端测试以及通过自定义拓扑覆盖 limits、feature flags、capability 配置与user_config_overrides的完整方法。读完本文你将掌握从env stop到env start的完整环境生命周期操作、默认拓扑下的测试执行套路以及基于CTF_CONFIGS 拓扑 TOML 灵活定制测试场景的实战技能。本文的核心依据是仓库内 Agent Skill 文档 docs/local-cre/agent-skills/local-cre-e2e/SKILL.md并辅以 Local CRE 环境 CLI 与 CRE 冒烟测试套件 的源码佐证。适用范围与基本假设这个 Skill 解决什么问题local-cre-e2e是一个面向 Agent 与开发者的操作技能说明适用于以下场景启动、停止或重启本地 CRE 环境在默认拓扑上运行 CRE 冒烟smoke或回归regression端到端测试针对特定拓扑运行测试创建自定义拓扑以覆盖 limits、flags、capability 配置或user_config_overrides。需要特别注意的是它面向的是Local CRE 系统级测试工作流不适用于普通单元测试。运行前提假设根据 SKILL.md使用该工作流需满足四个前提仓库根目录是chainlink的检出目录即当前仓库根本地 CRE 命令统一在core/scripts/cre/environment目录下执行CRE E2E 测试命令统一在system-tests/tests目录下执行除非明确知道 harness 支持隔离否则同一时间只应有一个活动的本地 CRE 环境——这是避免状态串扰的关键纪律。从源码看CLI 入口位于 core/scripts/cre/environment/main.go它把env、topology、examples、bs、obs五组子命令挂到根命令root.RootCmd上因此所有环境操作都通过go run . command [subcommand]的统一形态调用。默认工作流从清理到启动一次本地 CRE第一步停止可能存在的旧环境每次开始前先彻底停止可能残留的本地 CRE 环境避免新环境与旧状态的端口、容器、状态文件冲突cd core/scripts/cre/environment go run . env stop -a-a--all会连同所有额外服务一起停止。对应源码见 environment.go 中stop子命令的定义其提示信息明确写道All extra services: stop withgo run . env stop --all。第二步一次性准备环境如果环境尚未准备过或需要重新拉取/构建依赖镜像先执行一次设置cd core/scripts/cre/environment go run . env setupenv setup由configs/setup.toml驱动负责确保 Job Distributor、Chip Router、Chip Ingress、Chip Config 等托管镜像就绪。它也可以显式指定配置并跳过交互提示go run . env setup --config configs/setup.toml --no-prompt如果需要重建或重新拉取全部前置依赖env setup支持--purge需要计费billing资产时可加--with-billing详见 docs/local-cre/getting-started/index.md。提示env setup并非每次都要跑。镜像已经就位、只改拓扑 TOML 的情况下直接env start即可。SKILL.md 强调它是环境尚未准备时的一次性步骤。第三步启动默认拓扑cd core/scripts/cre/environment go run . env startenv start默认读取CTF_CONFIGS指向的拓扑 TOML未设置时使用默认拓扑workflow-gateway-capabilities-don.toml。对应源码见 environment.go其中还包含对 Job Distributor 镜像的存在性检查environment.go若镜像缺失会提示先执行go run . env setup。快速上手时也可以一步到位使用--auto-setupgo run . env start --auto-setup第四步可选启动可观测性组件go run . obs up当你需要日志、追踪或面板来调试工作流事件时用obs up拉起 observability 辅助栈。SKILL.md 特别指出当测试依赖真实 ChIP Ingress 栈或你想用Red Panda Console调试工作流事件时在env start上加--with-chip-ingress-stack--with-beholder已废弃deprecated等价行为请改用--with-chip-ingress-stack。为什么默认冒烟流程不建议开--with-chip-ingress-stackdocs/local-cre/system-tests/running-tests.md 给出了实现层面的原因大多数 CRE 冒烟测试会在默认 gRPC 端口50051上启动 ChIP 测试 sinktest sink而 Chip Ingress 栈的 ChIP ingress 也绑定同一端口。两者抢同一端口会导致测试 sink 启动失败。因此仅在以下情况才启用该栈你在跑 Chip Ingress 栈专属的覆盖场景你需要用它做调试你通过--grpc-port给它换一个端口把默认50051留给测试 sink。Chip 相关组件的默认端口布局来自 docs/local-cre/environment/index.md50050Chip Router admin API50051Chip Router ingress gRPC50052chip-config50053真实 ChIP / Chip Ingress 栈 gRPC。补充本地源码构建模式在默认拓扑基础上如果你正在开发 node 或某个 capabilitydocs/local-cre/environment/index.md 还提供了两个高频扩展 flag# 节点 全部 capability 都用本地工作树构建含 observability go run . env start --with-observability --local-node --local-capabilities all # 节点用固定镜像仅 cron evm 用本地构建覆盖 go run . env start --local-capabilities cron,evm--local-node在宿主机交叉编译本地 checkout 的 Chainlink 节点并烘焙进最小镜像覆盖拓扑中的docker_ctx/image--local-capabilities names|all从本地源码构建指定 CRE capability 并注入节点未列出的 capability 保留镜像内版本--capabilities-path dir本地 capabilities 仓库位置默认$CRE_CAPABILITIES_PATH否则为~/go/src/github.com/smartcontractkit/capabilities--local-build-platform os/arch本地构建目标平台默认linux/宿主机架构--local-node-image tag本地构建节点的镜像标签默认cre-node:local。在默认拓扑上运行 E2E 测试环境起来后切到测试目录执行测试。测试命令必须在system-tests/tests下运行这一目录本身是一个独立的 Go module见 system-tests/tests/go.mod。常规 CRE 冒烟套件cd system-tests/tests go test ./smoke/cre -timeout 20m -run ^Test_CRE_仅 V2 冒烟套件cd system-tests/tests go test ./smoke/cre -timeout 15m -run ^Test_CRE_V2回归测试cd system-tests/tests go test ./regression/cre -timeout 20m -run ^Test_CRE_smoke 与 regression 的划分规则SKILL.md 给出的经验法则与源码注释完全一致smoke面向 happy path 与 sanity 覆盖regression面向边界条件与负向场景。这一点在测试入口文件 cre_suite_test.go 的注释中写得很明确//////////// SMOKE TESTS ///////////// // target happy path and sanity checks // all other tests (e.g. edge cases, negative conditions) // should go to a regression package /////////////////////////////////////测试与环境的衔接机制你可能好奇为什么先启动 Local CRE 再跑测试就能对上这依赖system-tests/tests/test-helpers/before_suite.go中的 helper 逻辑before_suite.go如果CTF_CONFIGS为空helper 会把它设置为请求的配置如果本地 CRE 状态文件Local CRE state file不存在helper 会自动执行go run . env start把环境拉起来环境创建完成后CTF_CONFIGS会被切换为指向本地 CRE 状态文件而不是原始拓扑 TOML从而让测试使用已部署的环境。因此两种工作方式都成立手动先起环境再跑测试或直接让 helper 帮你引导环境。运行特定测试或桶用窄正则调试单个场景当你在排查单个场景或某个桶时使用收窄的正则表达式并配合-count1防止测试缓存带来的假结果cd system-tests/tests go test ./smoke/cre -timeout 20m -run ^Test_CRE_V2_Suite_Bucket_B$ -count1 -v按场景子路径过滤V2 套件内部按场景组织子测试可以用/继续下钻cd system-tests/tests go test ./smoke/cre -timeout 20m -run Test_CRE_V2_Suite_Bucket_B/.*/Vault -count1 -vcd system-tests/tests go test ./regression/cre -timeout 20m -run ^Test_CRE_V2_Consensus_Regression$ -count1 -vSKILL.md 强调重跑易 flaky 或带状态stateful的 CRE 场景时务必加-count1跳过 Go 测试缓存确保从头执行。桶Bucket结构与场景分配较大的 CRE 冒烟套件按运行时均衡拆分为多个桶而不是一个巨型测试入口。旧的 V2 套件拆分为Test_CRE_V2_Suite_Bucket_ATest_CRE_V2_Suite_Bucket_BTest_CRE_V2_Suite_Bucket_C入口定义在 cre_suite_test.go每个入口都会先校验桶注册表再执行场景。桶到场景的分配定义在 system-tests/tests/smoke/cre/config/bucketing.go桶包含场景suite-bucket-aProofOfReserve、HTTPTriggerAction、DONTime、Consensussuite-bucket-bVaultDONsuite-bucket-cCronChipIngressStack、HTTPActionCRUD、HTTPActionMultiGateway除非TOPOLOGY_NAME含multi-gateway否则跳过suiteBucketRegistry是旧 V2 套件场景分配桶的唯一登记处新增场景时应在此添加并通过 CI 实测时间重新均衡各桶运行时bucketing.go 的注释给出了这一维护流程。EVM 读取套件还有一套独立的桶注册表位于 system-tests/tests/smoke/cre/evm/evmread/config/bucketing.go对应入口Test_CRE_V2_EVM_Read_HeavyCallsTest_CRE_V2_EVM_Read_StateQueriesTest_CRE_V2_EVM_Read_TxArtifacts使用桶化入口的意义在于更短的本地反馈回路、更稳定的 CI 运行时长以及在套件增长时可控地再平衡场景运行时。本地调试的 VS Code 配置docs/local-cre/system-tests/running-tests.md 提供了一个可直接套用的 VS Code launch 配置模板{ name: Launch CRE V2 Bucket A, type: go, request: launch, mode: test, program: ${workspaceFolder}/system-tests/tests/smoke/cre, args: [-test.run, ^Test_CRE_V2_Suite_Bucket_A$] }配合 debug 日志跑一个窄测试的常见形态是CTF_LOG_LEVELdebug \ go test ./system-tests/tests/smoke/cre -timeout 20m -run ^Test_CRE_V2_Suite_Bucket_A$CTF_LOG_LEVELdebug会让框架在 setup 与测试执行阶段输出更详细的日志而窄化的-run保证仍走与完整套件相同的拓扑与工作流 setup。使用特定拓扑当测试需要特定的 DON 布局、链或功能配置时使用非默认拓扑。流程停旧环境 → 指定拓扑启动 → 跑目标测试# 1. 停止现有环境 cd core/scripts/cre/environment go run . env stop -a # 2. 用 CTF_CONFIGS 指定拓扑文件启动 cd core/scripts/cre/environment CTF_CONFIGS./configs/workflow-gateway-capabilities-don.toml go run . env start # 3. 运行目标测试TOPOLOGY_NAME 可选 cd system-tests/tests TOPOLOGY_NAMEworkflow-gateway-capabilities \ go test ./smoke/cre -timeout 20m -run ^Test_CRE_V2_Suite_Bucket_B$ -count1 -vTOPOLOGY_NAME的作用TOPOLOGY_NAME是可选但很有用的环境变量。为什么有用因为大量 CRE 套件测试会把拓扑名包含进子测试名、桶标签与日志输出让结果始终与所测拓扑挂钩。实现上套件入口在 cre_suite_test.go 直接读取该变量var ( parallelEnabled t_helpers.ParallelEnabled() // topology is used in test names topology os.Getenv(TOPOLOGY_NAME) )典型例子多网关 HTTP action 路由场景需要启动configs/workflow-gateway-capabilities-multi-gateway-don.toml然后执行TOPOLOGY_NAMEworkflow-gateway-capabilities-multi-gateway \ go test ./system-tests/tests/smoke/cre -timeout 20m -run ^Test_CRE_V2_HTTP_Action_Multi_Gateway$测试助手的拓扑衔接细节docs/local-cre/system-tests/running-tests.md 汇总了冒烟套件使用的核心环境变量CTF_CONFIGS启动前指向拓扑 TOML启动后被 helper 自动切换为生成的 Local CRE 状态文件本地运行由before_suite.go完成切换TOPOLOGY_NAME进入测试名、桶标签与日志输出CTF_LOG_LEVELdebug启用更详细的框架日志CTF_JD_IMAGE固定 Job Distributor 镜像避免默认本地镜像选择CTF_CHAINLINK_IMAGE固定 Chainlink 节点镜像system-tests/lib/cre/environment/dons.go 在选择节点镜像时直接检查该变量。并行执行可选并行测试是显式开启的设置环境变量即可CRE_TEST_PARALLEL_ENABLED1注意冒烟套件并不会盲目地对所有用例开t.Parallel()——runner 在cre_suite_test.go中只对确定可以安全共存的场景启用并行。创建自定义拓扑当你想覆盖以下内容时就需要创建自定义拓扑limitsfeature flagscapability 配置DON 组成额外的数据源user_config_overrides。工作流从core/scripts/cre/environment/configs/里挑一个最接近现有需求的拓扑复制为同目录下的新文件只改场景需要的字段用CTF_CONFIGS新拓扑启动本地 CRE先只跑相关测试。示例cd core/scripts/cre/environment/configs cp workflow-gateway-capabilities-don.toml workflow-gateway-capabilities-don-my-override.toml然后启动并测试cd ../ CTF_CONFIGS./configs/workflow-gateway-capabilities-don-my-override.toml go run . env startcd ../../../system-tests/tests TOPOLOGY_NAMEworkflow-gateway-capabilities-my-override \ go test ./smoke/cre -timeout 20m -run ^Test_CRE_V2_Suite_Bucket_B$ -count1 -v默认拓扑长什么样理解默认拓扑是定制的基础。workflow-gateway-capabilities-don.tomlconfigs/workflow-gateway-capabilities-don.toml是一个 multi-don 拓扑包含 3 个 nodesetworkflow4 个节点don_types [workflow]capabilities 含cron、http-action、http-trigger、consensus、don-time、evm-1337同时连接 1337/2337 两条 anvil 链注释解释即使不用 2337 上的 capabilitybootstrap 节点上仍要创建 capability DON 的 bootstrap jobcapabilities4 个节点don_types [capabilities]exposes_remote_capabilities truecapabilities 含vault、evm-2337连接 1337 是为了用链上节点地址在 gateway 配置中标识节点这是 vault 与 gateway 型 HTTP capability 的要求bootstrap-gateway1 个节点don_types [bootstrap, gateway]override_mode each通过custom_ports [5002:5002,15002:15002]暴露 web API capabilities 端口5002与 vault 端口15002。其他公共段包括[chip_router]、两条[[blockchains]]anvil 1337/2337、[jd]Job Distributor 镜像与 CSA 加密密钥、[fake]/[fake_http]mock 服务端口、[infra]docker 或 kubernetes。仓库现有拓扑的全量清单可参考 core/scripts/cre/environment/docs/TOPOLOGIES.md该文件由go run . topology generate自动生成涵盖workflow-don-solana.tomlmulti-don3 DONworkflow-gateway-capabilities-multi-gateway-don.tomlmulti-don4 DONworkflow-gateway-don-aptos.tomlsingle-don2 DONworkflow-gateway-don-cache-test.toml/workflow-gateway-don-cache-soak-test.tomlworkflow-gateway-don-grpc-source.tomlworkflow-gateway-don.tomlsingle-don2 DONworkflow-gateway-sharded-5-dons.tomlsharded7 DONworkflow-gateway-sharded-don.tomlsharded3 DON快速查看清单可运行go run . topology list。覆盖指南制作自定义拓扑时的纪律SKILL.md 原文要点保持 diff 小而目的明确优先复制最近似的拓扑而不是从零新建使用能表明改动内容的描述性文件名除非测试需要不要改动无关的镜像、链或 capability如果拓扑只用于一次性本地检查保留在本地避免加进 CI。典型的覆盖点包括nodesets.capability_configscapability 配置覆盖nodesets.user_config_overrides节点用户配置覆盖CRE feature flags额外的 mock 或支持服务端点。capability_configs 的完整覆盖语义仓库提供了一个专门讲解覆盖写法的示例拓扑 configs/examples/workflow-don-overrides.toml其中对capability_configs的关键语义写得很清楚覆盖某个 capability 配置时必须提供该 capability 的全部值——不支持部分覆盖。如果你指定了某个 key整个CapabilityConfig会原样使用不会与默认值合并默认值只对完全没有配置的 capability 生效。示例链级 EVM 覆盖LogTriggerPollInterval以纳秒为单位[nodesets.capability_configs.evm-1337.values] LogTriggerPollInterval 2500000000 # 2.5s in nanoseconds # 其他 capability 同样可覆盖例如 # [nodesets.capability_configs.http-action] # binary_name http_action # [nodesets.capability_configs.http-action.values] # IncomingGlobalBurst 20user_config_overrides 的边界与写法同一示例还演示了user_config_overrides的用法并给出一个重要的实现约束[Telemetry]、[Billing]、[Metering]是框架托管的段会被框架拒绝validateUserConfigOverrides位于system-tests/lib因为框架会自己生成这些配置把遥测指向 chip-router 以便下游订阅者如 CI test sink看到全部事件。要启用 metering应设置 nodeset 的enable_metering true。[[nodesets.node_specs]] roles [plugin] # override_mode all 时DON 内所有节点都是 plugin 角色 [nodesets.node_specs.node] image chainlink-tmp:latest user_config_overrides [Log] Level debug JSONConsole true # 删掉这段可以让工作流从远程源下载 [CRE.WorkflowFetcher] URL file:///home/chainlink/workflows 重启与清理干净重启当改动拓扑或底层配置时优先完整 stop/start不要假设运行中的环境会自动收敛cd core/scripts/cre/environment go run . env stop -a CTF_CONFIGS./configs/topology.toml go run . env start这也是 SKILL.md 故障排查的第一条如果测试意外使用了错误的拓扑停止 Local CRE 并按预期的CTF_CONFIGS重启。用完后清理cd core/scripts/cre/environment go run . env stop -a彻底重置当保存的状态或缓存产物看起来不一致时使用 purgego run . env state purgestate子命令组定义在 environment.go包含list列出环境中所有状态文件与purge清空所有状态与缓存文件。Local CRE 把环境状态持久化到仓库本地的状态文件中这正是冒烟测试 helper 能检测到已存在环境、避免重复创建的原因详见 docs/local-cre/environment/index.md。需要完全重置时先 purge 状态再重新 setup/start。故障排除SKILL.md 的四条速查测试意外使用了错误拓扑→ 停止 Local CRE按预期的CTF_CONFIGS重启套件似乎在复用陈旧状态→ 用-count1重跑测试依赖日志、追踪或面板→ 执行go run . obs up拓扑相关的失败看似与测试无关→ 先确认环境确实是以预期拓扑启动的。测试逻辑尚未执行就失败的清单docs/local-cre/system-tests/running-tests.md 给出了测试还没跑到测试逻辑就失败时的五步检查确认CTF_CONFIGS确认 Local CRE 状态文件有效确认所需镜像存在重跑go run . env setup用 debug 日志重跑。环境启动阶段的高频故障docs/local-cre/environment/index.md 归纳了环境侧最常见的四类失败Chainlink 节点数据库迁移失败Docker 镜像找不到Docker 无法下载所需公共镜像gh缺失或未认证构建需要私有插件访问的镜像时必需。对应的处理顺序重跑go run . env setup→ 确认镜像访问与认证 → 状态陈旧则 purge 状态 → 需要更多信号则带 observability 或 Chip Ingress 栈重启。超时经验实践中的超时经验来自 docs/local-cre/system-tests/running-tests.md从源码构建镜像时给约20 分钟的预算使用预构建镜像时运行时长会短得多。深入参考本文基于的 SKILL 文档还推荐了以下仓库内资料供深入阅读docs/local-cre/index.mdLocal CRE 文档总览与导航docs/local-cre/system-tests/index.mdCRE 系统测试的结构、smoke/regression 划分与 helper 衔接机制docs/local-cre/system-tests/running-tests.md本地、Kubernetes 与 CI 视角下的运行细节、环境变量与桶化选择docs/local-cre/getting-started/index.md从干净 checkout 到跑起第一个环境的最短路径docs/local-cre/environment/index.md环境生命周期命令、env start全部 flag 与 Chip 端口布局core/scripts/cre/environment环境 CLI 源码main.go命令注册、environment/生命周期实现、configs/拓扑目录system-tests/tests/smoke/cre冒烟套件源码cre_suite_test.go桶入口、config/bucketing.go桶注册表。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考