Chainlink Local CRE 拓扑实战workflow-gateway-don-cache-test 的 DON 布局与模块缓存验证【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink本文聚焦 Chainlink 仓库中 Local CREChainlink Runtime Environment开发环境的workflow-gateway-don-cache-test拓扑它如何通过单 DON 集群single-don Docker 基础设施承载 bootstrap-gateway 与 workflow 两类节点如何将七类能力capability本地化部署到 workflow DON并借助[Capabilities.WorkflowRegistry.ModuleCache]配置验证 WASM 模块缓存Module Cache的加载、闲置驱逐与命中行为。读完本文你将掌握该拓扑的 TOML 配置含义、能力矩阵的生成规则、如何启动并运行对应的缓存冒烟测试以及模块缓存底层的 LRU 磁盘两级实现原理。拓扑概览一份由工具自动生成的标准参考文档workflow-gateway-don-cache-test.md位于 core/scripts/cre/environment/docs/topologies/workflow-gateway-don-cache-test.md它并非手写文档而是由 Local CRE CLI 的go run . topology generate命令根据拓扑 TOML 自动渲染生成。其头部的三条元信息即是对这份拓扑最直接的定性元信息值含义Configconfigs/workflow-gateway-don-cache-test.toml定义该拓扑的 TOML 文件位于 core/scripts/cre/environment/configs/workflow-gateway-don-cache-test.tomlClasssingle-don拓扑类别为单 DON——所有能力均本地化放置在 workflow DON 上不涉及独立 capabilities DON 或多网关路由Infradocker基础设施类型为 Docker 容器编排从生成器源码 environment/topology.go 可以看到topology generate会扫描configs/目录下所有满足条件的 TOML同时具备blockchains、nodesets、jd、infra四类键逐份生成docs/topologies/name.md与索引文件docs/TOPOLOGIES.md见 TOPOLOGIES.md 的索引表并支持--check模式校验文档是否过期。这意味着要理解任何拓扑文档真正的源是它对应的 TOML 配置文件文档只是把配置中 DON 布局与能力放置关系投影为人类可读形式。能力矩阵Capability MatrixDON 能力放置的事实来源文档在## Capability Matrix一节强调This matrix is the source of truth for capability placement by DON.——即能力矩阵是能力放置的权威依据。完整矩阵如下Capabilitybootstrap-gatewayworkflowconsensus-localcron-localdon-time-localevm-local (1337,2337)http-action-localhttp-trigger-localvault-local解读这张矩阵需要理解三个关键语义local表示能力本地挂载该能力由本 DON 内的节点直接注册并提供而非通过远程调用其他 DON 的能力。topologyviz.go中buildCapabilityMatrix将能力分为local与remote-exposed两种模式只有当节点集声明ExposesRemoteCapabilities且属于 capabilities DON 时才会标记为remote-exposed见 topologyviz/topologyviz.go。evm带链 ID 后缀local (1337,2337)表示 EVM 能力同时挂载到 chain 1337 与 chain 2337 两条链。这在 TOML 中对应capabilities [evm-1337, evm-2337]两个带链 ID 的能力旗标生成器通过splitCapabilityFlag把evm-1337拆为基础名evm与链 ID1337见 topologyviz.go。-表示该 DON 未放置此能力bootstrap-gateway 节点集没有声明任何能力因此矩阵整列为空。矩阵的生成逻辑还做了两项规范化能力按基础名排序输出链 ID 去重排序后以逗号拼接确保同一能力在多链场景下的表达稳定可比较。DON 布局详解bootstrap-gateway 与 workflow 的分工bootstrap-gateway1 节点承担引导与网关双重职责文档给出的属性如下Types:bootstrap,gateway—— 该节点集同时承担 DON 引导bootstrap与网关gateway两种类型Nodes:1—— 单节点部署Roles:bootstrap,gatewayEVM chains:1337,2337Exposes remote capabilities:false—— 不对外暴露远程能力对应 TOML 片段configs/workflow-gateway-don-cache-test.toml[[nodesets]] nodes 1 name bootstrap-gateway don_family test-don-family don_types [bootstrap, gateway] override_mode each http_port_range_start 10300 env_vars { CL_EVM_CMD } supported_evm_chains [1337, 2337] [nodesets.db] image postgres:12.0 port 13200 [[nodesets.node_specs]] roles [bootstrap, gateway] [nodesets.node_specs.node] docker_ctx ../../../.. docker_file core/chainlink.Dockerfile docker_build_args { CL_IS_PROD_BUILD false } custom_ports [5002:5002,15002:15002] user_config_overrides 要点说明override_mode each每个节点规格node_specs单独应用于节点而非所有节点共享同一套覆盖配置。该节点集只有一个 node_spec声明roles [bootstrap, gateway]使同一节点同时运行 bootstrap 与 gateway 两个角色。custom_ports [5002:5002,15002:15002]显式映射网关/引导相关端口供本地调试访问。supported_evm_chains [1337, 2337]与文档中 EVM chains:1337,2337 一致生成器从该字段聚合出 DONSummary 的 SupportedEVMChains 并渲染进文档见 topologyviz.go。镜像构建docker_ctx ../../../..指向仓库根目录docker_file core/chainlink.DockerfileCL_IS_PROD_BUILD false表示构建非生产开发版本节点镜像。env_vars { CL_EVM_CMD }清空 EVM 命令行参数使用默认行为。workflow4 节点承载全部能力执行Types:workflowNodes:4Roles:pluginEVM chains:1337,2337Exposes remote capabilities:false对应 TOML 片段configs/workflow-gateway-don-cache-test.toml[[nodesets]] nodes 4 name workflow don_family test-don-family don_types [workflow] override_mode all http_port_range_start 10100 env_vars { CL_EVM_CMD } capabilities [vault, cron, http-action, http-trigger, consensus, don-time, evm-1337, evm-2337] registry_based_launch_allowlist [cron-trigger1.0.0, dontime1.0.0] [nodesets.db] image postgres:12.0 port 13000 [[nodesets.node_specs]] roles [plugin] [nodesets.node_specs.node] docker_ctx ../../../.. docker_file core/chainlink.Dockerfile docker_build_args { CL_IS_PROD_BUILD false } user_config_overrides [Capabilities.WorkflowRegistry.ModuleCache] Enabled true MaxLoaded 1 IdleEviction true IdleTimeout 30s 本节点集是该拓扑的主角四个细节值得展开能力旗标与矩阵的对应关系capabilities列表中的vault、cron、http-action、http-trigger、consensus、don-time以及链绑定的evm-1337、evm-2337正是能力矩阵中local或local (1337,2337)的来源。矩阵中没有bootstrap-gateway的能力因为该节点集未声明capabilities字段。registry_based_launch_allowlist允许以 registry 方式启动的触发器版本白名单这里放行cron-trigger1.0.0与dontime1.0.0——即 cron 触发器和 don-time 能力按版本从外部 registry 注册。override_mode all所有节点共享同一份覆盖配置本例中即模块缓存覆盖。模块缓存覆盖本拓扑的核心差异点user_config_overrides注入了[Capabilities.WorkflowRegistry.ModuleCache]配置块[Capabilities.WorkflowRegistry.ModuleCache] Enabled true MaxLoaded 1 IdleEviction true IdleTimeout 30s这是workflow-gateway-don-cache-test与普通workflow-gateway-don拓扑见 topologies/workflow-gateway-don.md其配置 configs/workflow-gateway-don.toml 不带模块缓存覆盖最本质的区别它刻意把MaxLoaded压到1、IdleTimeout缩到30s从而在缓存冒烟测试中快速制造加载 → 闲置 → 驱逐 → 重载的循环用于观察缓存是否按预期工作。对比同目录下的浸泡测试拓扑 configs/workflow-gateway-don-cache-soak-test.toml其覆盖配置为MaxLoaded 100、IdleTimeout 5m并额外设置[Workflows.Limits] Global 5000、PerOwner 5000——两个拓扑分别服务于快速验证与长时间浸泡两种测试目的。支撑组件链、Job Distributor 与辅助服务两条 Anvil 链[[blockchains]] type anvil chain_id 1337 container_name anvil-1337 docker_cmd_params [-b, 0.5, --mixed-mining] [[blockchains]] type anvil chain_id 2337 container_name anvil-2337 port 8546 docker_cmd_params [-b, 0.5, --mixed-mining]两条链均为 Anvil 本地节点Foundry 自带chain_id 分别为 1337 与 2337第一条使用默认 RPC 端口8545第二条显式指定port 8546以避免冲突docker_cmd_params [-b, 0.5, --mixed-mining]-b 0.5表示每 0.5 秒出一个块--mixed-mining开启混合挖矿模式同时支持即时与定时出块为依赖日志触发器与区块高度的能力如 evm 的 LogTrigger提供可控的区块节奏。Job Distributor、fake 服务与基础设施[jd] csa_encryption_key d1093c0060d50a3c89c189b2e485da5a3ce57f3dcb38ab7e2c0d5f0bb2314a44 image job-distributor:0.28.0 [fake] port 8171 [fake_http] port 8666 [infra] type docker[jd]Job Distributor 镜像固定为job-distributor:0.28.0与 setup.toml 中 job_distributor 的本地镜像一致csa_encryption_key用于节点与 JD 之间的 CSA 密钥加密通信[fake]/[fake_http]提供本地 fake 服务端口8171与 fake HTTP 服务端口8666供 http-action / http-trigger 等能力在测试中回环访问[infra] type docker与文档头部 Infra:docker 一致所有节点与链均以 Docker 容器方式运行。能力默认值全局叠加层capability_defaults.tomlconfigs/capability_defaults.toml会在拓扑加载时被自动前置合并loadAndSummarizeConfig中以defaultCapabilitiesConfigFile , configPath方式加载见 environment/topology.go。它对本拓扑中涉及的能力给出全局默认值例如[capability_configs.evm.values]LogTriggerPollInterval 15000000001.5s、ReceiverGasMinimum 500[capability_configs.http-action.values]/[capability_configs.http-trigger.values]进出向的IncomingGlobalRPS 50、IncomingPerSenderRPS 10、对应 Burst 参数等限流配置[capability_configs.vault.values]vault 能力内置于节点无独立 binary其 auth0 配置指向本地模拟端点http://host.docker.internal:18123/。拓扑类别Class是如何判定的single-don 的判定逻辑workflow-gateway-don-cache-test被归类为single-don其判定逻辑写在classifyTopologytopologyviz.goif hasShards { return ClassSharded } if capDONs 0 || workflowDONs 1 || len(dons) 2 { return ClassMultiDON } return ClassSingleDON对照本拓扑两个 DONbootstrap-gateway与workflow、无 shard DON、无独立 capabilities DON、workflow 类型 DON 恰好 1 个、DON 总数 ≤ 2因此落入single-don。这也解释了为什么该拓扑能够单 DON 全本地——bootstrap-gateway 只负责引导与网关流量能力执行全部集中在 workflow DON 内。与之形成对照的是 workflow-gateway-sharded-5-dons.md7 个 DONsharded类与 workflow-gateway-capabilities-don.md3 个 DON含独立 capabilities DONmulti-don类。完整索引见 docs/TOPOLOGIES.md。实战如何启动该拓扑并运行模块缓存冒烟测试1. 启动环境该拓扑专为模块缓存冒烟测试设计。参考系统测试文件 system-tests/tests/smoke/cre/v2_module_cache_test.go 中的前置说明启动命令为cd core/scripts/cre/environment CTF_CONFIGSconfigs/workflow-gateway-don-cache-test.toml go run . env startCTF_CONFIGS环境变量显式指定拓扑配置文件覆盖 CLI 默认值main.go中shell子命令默认注入configs/workflow-gateway-don.toml见 environment/main.go若需要先拉取/构建托管镜像可加--auto-setupenv start的-a简写源码见 environment/environment.gogo run . env start --auto-setup其他常用生命周期命令go run . env stop、go run . env restart、go run . env state purge完整命令清单见 docs/local-cre/environment/index.md。2. 启动前检查拓扑官方推荐在启动前先用拓扑命令核对最终的能力放置# 在 core/scripts/cre/environment 目录下执行 go run . topology list # 列出全部可用拓扑 go run . topology show --config configs/workflow-gateway-don-cache-test.toml # 渲染 ASCII 概览与能力矩阵 go run . topology generate # 重新生成 docs/topologies/*.md 与索引其中topology show默认--config为configs/workflow-gateway-don.toml、--output-dir为statetopology generate默认输出到docs/topologies、索引到docs/TOPOLOGIES.md见 environment/topology.go。3. 运行冒烟测试go test -timeout 10m -run ^Test_CRE_V2_Module_Cache$ -v测试入口定义于 system-tests/tests/smoke/cre/cre_suite_test.gofunc Test_CRE_V2_Module_Cache(t *testing.T) { testEnv : t_helpers.SetupTestEnvironmentWithConfig(t, t_helpers.GetTestConfig(t, /configs/workflow-gateway-don-cache-test.toml)) ExecuteModuleCacheTest(t, testEnv) }测试的验证流程v2_module_cache_test.go如下启动 Chip test sink用于接收 workflow 遥测日志并保证退出时带排空drain地关闭避免 gRPC Publish 阻塞编译并部署10 个基于 cron 触发器的 workflow复用examples/workflows/cron/main.go调度为*/30 * * * * *命名cachetest0cachetest9等待第一个 workflow 执行成功以日志Amazing workflow user log为信号随后进入1 分钟缓存观察窗口期间持续排空用户日志但不做业务断言最终断言节点日志中出现Module cache enabled确认模块缓存确实被启用。由于拓扑将MaxLoaded 110 个 workflow 的 WASM 模块在同一时刻最多只能有 1 个驻留内存配合IdleTimeout 30s测试期间必然反复触发驱逐旧模块、从磁盘重载新模块的行为——这正是该测试验证的核心路径。模块缓存的底层实现LRU 磁盘两级缓存配置项语义来自官方配置文档core/config/docs/core.tomlcore/config/docs/core.toml对[Capabilities.WorkflowRegistry.ModuleCache]的完整语义说明如下配置项默认值语义Enabledfalse激活两级模块缓存LRU 磁盘。开启后编译好的 WASM 模块会驻留内存并持久化到磁盘避免后续激活时重复编译DiskMonitorEnabledfalse启用磁盘用量监控以cacheDir为监控对象输出到 Beholder 遥测与节点/metrics端点IdleEvictiontrue启用基于闲置时间的驱逐模块超过IdleTimeout未使用即被移出内存IdleTimeout10m模块允许闲置的最长时间仅当IdleEviction true时生效MaxLoaded200同时驻留内存的模块数量上限超出时立即驱逐最久未使用LRU的模块。0表示不设上限CacheDir序列化模块二进制的存放目录为空时使用临时目录注意Enabled true同时会启动磁盘监控即使DiskMonitorEnabled false。对应的 Go 接口定义于 core/config/capabilities_config.go。执行侧实现EvictableModule ModuleLRU运行时实现位于 core/services/workflows/syncer/v2/evictable_module.go核心是两个组件EvictableModule对host.ModuleV2的包装。它持有两层引用——current强引用 引用计数用于正在执行的模块与weakInner弱引用模块被驱逐后仍存活到 GC 回收为止用于快速复活。模块加载遵循三级策略命中强引用 → 命中弱引用无需重编译→ 从磁盘读取序列化二进制重新实例化ensureLoaded中通过m.store.GetModule读取见 evictable_module.go。ModuleLRU全局 LRU 管理器内部维护map[string]*EvictableModule每 30 秒执行一次reap()defaultScanInterval 30 * time.Second见 evictable_module.go。reap()分两步evictable_module.go闲置驱逐遍历所有模块now - LastUsed IdleTimeout且处于加载态IsLoaded()的模块被Evict()上限驱逐若加载模块数超过MaxLoaded按最近使用时间排序驱逐最久未使用且超额的模块enforceCapLocked。Evict()采用引用计数守卫 单次 CAS设计evictable_module.go只有当引用计数为 1仅所有者、无正在执行的 Execute 钉住时才允许驱逐避免旧模块仍在服务、新模块又加载导致的瞬时双实例内存抖动驱逐失败会在下一个 reap 周期重试保证最终一致。驱逐只释放 WASM 内存不影响触发器注册与事件通道这些归引擎所有。reap()还会记录loaded数、每次驱逐计数与累计节省内存字节数recordMemorySaved供CacheMetrics与磁盘监控导出。磁盘监控实现于 core/services/workflows/syncer/v2/disk_monitor.go按固定间隔采样cacheDir的磁盘用量并同时输出到 Beholder 遥测与 Prometheus 指标promModuleCacheDiskUsageBytes。配置项与实现的映射拓扑中的覆盖配置实现落点Enabled true创建ModuleLRU与磁盘序列化存储SerialisedModuleStore并启动磁盘监控MaxLoaded 1注入ModuleLRU.maxLoadedWithMaxLoadedModules见 evictable_module.goreap()中触发上限驱逐IdleEviction truereap()中启用闲置扫描分支IdleTimeout 30s注入ModuleLRU.idleTimeoutWithIdleTimeout见 evictable_module.go这意味着本拓扑中MaxLoaded 1IdleTimeout 30s的组合会让ModuleLRU在每次reap()30 秒周期时都试图把上一个闲置模块驱逐出去从而在 1 分钟观察窗口内制造至少 23 次完整的驱逐 → 弱引用/磁盘重载循环足以暴露缓存逻辑的并发缺陷例如 Evict 与 Execute 的竞态。常见问题与调参建议想复现模块缓存命中而非频繁驱逐将MaxLoaded调大如 soak 拓扑的100、IdleTimeout调长如5m使多个 workflow 模块同时驻留内存需要压测大量 workflow 注册参考 soak 拓扑追加[Workflows.Limits]把Global/PerOwner从默认的200见 core/config/docs/core.toml提升到目标规模节点启动报镜像缺失先执行go run . env setup拉取 Job Distributor、Chip Router、Chip Ingress、Chip Config 等托管镜像必要时配置MAIN_AWS_ECR与SDLC_AWS_ECR两个 ECR 仓库想用本地源码构建节点/能力使用env start的--local-node与--local-capabilities旗标详见 docs/local-cre/environment/index.md本地构建可感知replace指令如本地 chainlink-common这是 Docker 内构建看不到的。小结workflow-gateway-don-cache-test拓扑是 Chainlink Local CRE 中一个小而专的参考实现它用 single-don 类别把七类能力全部本地化到 4 节点的 workflow DON让 1 节点的 bootstrap-gateway 专注引导与网关流量两条 Anvil 链1337/2337为 EVM 能力提供可控的区块环境其独特之处在于通过user_config_overrides注入MaxLoaded 1、IdleTimeout 30s的模块缓存覆盖配合Test_CRE_V2_Module_Cache冒烟测试定向验证了两级模块缓存的启用、驱逐与重载路径。理解这份拓扑也就掌握了 Local CRE 拓扑文档配置为源、文档为投影的生成范式以及从 TOML 到能力矩阵、再到运行时实现的完整证据链。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Chainlink Local CRE 拓扑实战：workflow-gateway-don-cache-test 的 DON 布局与模块缓存验证
Chainlink Local CRE 拓扑实战workflow-gateway-don-cache-test 的 DON 布局与模块缓存验证【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink本文聚焦 Chainlink 仓库中 Local CREChainlink Runtime Environment开发环境的workflow-gateway-don-cache-test拓扑它如何通过单 DON 集群single-don Docker 基础设施承载 bootstrap-gateway 与 workflow 两类节点如何将七类能力capability本地化部署到 workflow DON并借助[Capabilities.WorkflowRegistry.ModuleCache]配置验证 WASM 模块缓存Module Cache的加载、闲置驱逐与命中行为。读完本文你将掌握该拓扑的 TOML 配置含义、能力矩阵的生成规则、如何启动并运行对应的缓存冒烟测试以及模块缓存底层的 LRU 磁盘两级实现原理。拓扑概览一份由工具自动生成的标准参考文档workflow-gateway-don-cache-test.md位于 core/scripts/cre/environment/docs/topologies/workflow-gateway-don-cache-test.md它并非手写文档而是由 Local CRE CLI 的go run . topology generate命令根据拓扑 TOML 自动渲染生成。其头部的三条元信息即是对这份拓扑最直接的定性元信息值含义Configconfigs/workflow-gateway-don-cache-test.toml定义该拓扑的 TOML 文件位于 core/scripts/cre/environment/configs/workflow-gateway-don-cache-test.tomlClasssingle-don拓扑类别为单 DON——所有能力均本地化放置在 workflow DON 上不涉及独立 capabilities DON 或多网关路由Infradocker基础设施类型为 Docker 容器编排从生成器源码 environment/topology.go 可以看到topology generate会扫描configs/目录下所有满足条件的 TOML同时具备blockchains、nodesets、jd、infra四类键逐份生成docs/topologies/name.md与索引文件docs/TOPOLOGIES.md见 TOPOLOGIES.md 的索引表并支持--check模式校验文档是否过期。这意味着要理解任何拓扑文档真正的源是它对应的 TOML 配置文件文档只是把配置中 DON 布局与能力放置关系投影为人类可读形式。能力矩阵Capability MatrixDON 能力放置的事实来源文档在## Capability Matrix一节强调This matrix is the source of truth for capability placement by DON.——即能力矩阵是能力放置的权威依据。完整矩阵如下Capabilitybootstrap-gatewayworkflowconsensus-localcron-localdon-time-localevm-local (1337,2337)http-action-localhttp-trigger-localvault-local解读这张矩阵需要理解三个关键语义local表示能力本地挂载该能力由本 DON 内的节点直接注册并提供而非通过远程调用其他 DON 的能力。topologyviz.go中buildCapabilityMatrix将能力分为local与remote-exposed两种模式只有当节点集声明ExposesRemoteCapabilities且属于 capabilities DON 时才会标记为remote-exposed见 topologyviz/topologyviz.go。evm带链 ID 后缀local (1337,2337)表示 EVM 能力同时挂载到 chain 1337 与 chain 2337 两条链。这在 TOML 中对应capabilities [evm-1337, evm-2337]两个带链 ID 的能力旗标生成器通过splitCapabilityFlag把evm-1337拆为基础名evm与链 ID1337见 topologyviz.go。-表示该 DON 未放置此能力bootstrap-gateway 节点集没有声明任何能力因此矩阵整列为空。矩阵的生成逻辑还做了两项规范化能力按基础名排序输出链 ID 去重排序后以逗号拼接确保同一能力在多链场景下的表达稳定可比较。DON 布局详解bootstrap-gateway 与 workflow 的分工bootstrap-gateway1 节点承担引导与网关双重职责文档给出的属性如下Types:bootstrap,gateway—— 该节点集同时承担 DON 引导bootstrap与网关gateway两种类型Nodes:1—— 单节点部署Roles:bootstrap,gatewayEVM chains:1337,2337Exposes remote capabilities:false—— 不对外暴露远程能力对应 TOML 片段configs/workflow-gateway-don-cache-test.toml[[nodesets]] nodes 1 name bootstrap-gateway don_family test-don-family don_types [bootstrap, gateway] override_mode each http_port_range_start 10300 env_vars { CL_EVM_CMD } supported_evm_chains [1337, 2337] [nodesets.db] image postgres:12.0 port 13200 [[nodesets.node_specs]] roles [bootstrap, gateway] [nodesets.node_specs.node] docker_ctx ../../../.. docker_file core/chainlink.Dockerfile docker_build_args { CL_IS_PROD_BUILD false } custom_ports [5002:5002,15002:15002] user_config_overrides 要点说明override_mode each每个节点规格node_specs单独应用于节点而非所有节点共享同一套覆盖配置。该节点集只有一个 node_spec声明roles [bootstrap, gateway]使同一节点同时运行 bootstrap 与 gateway 两个角色。custom_ports [5002:5002,15002:15002]显式映射网关/引导相关端口供本地调试访问。supported_evm_chains [1337, 2337]与文档中 EVM chains:1337,2337 一致生成器从该字段聚合出 DONSummary 的 SupportedEVMChains 并渲染进文档见 topologyviz.go。镜像构建docker_ctx ../../../..指向仓库根目录docker_file core/chainlink.DockerfileCL_IS_PROD_BUILD false表示构建非生产开发版本节点镜像。env_vars { CL_EVM_CMD }清空 EVM 命令行参数使用默认行为。workflow4 节点承载全部能力执行Types:workflowNodes:4Roles:pluginEVM chains:1337,2337Exposes remote capabilities:false对应 TOML 片段configs/workflow-gateway-don-cache-test.toml[[nodesets]] nodes 4 name workflow don_family test-don-family don_types [workflow] override_mode all http_port_range_start 10100 env_vars { CL_EVM_CMD } capabilities [vault, cron, http-action, http-trigger, consensus, don-time, evm-1337, evm-2337] registry_based_launch_allowlist [cron-trigger1.0.0, dontime1.0.0] [nodesets.db] image postgres:12.0 port 13000 [[nodesets.node_specs]] roles [plugin] [nodesets.node_specs.node] docker_ctx ../../../.. docker_file core/chainlink.Dockerfile docker_build_args { CL_IS_PROD_BUILD false } user_config_overrides [Capabilities.WorkflowRegistry.ModuleCache] Enabled true MaxLoaded 1 IdleEviction true IdleTimeout 30s 本节点集是该拓扑的主角四个细节值得展开能力旗标与矩阵的对应关系capabilities列表中的vault、cron、http-action、http-trigger、consensus、don-time以及链绑定的evm-1337、evm-2337正是能力矩阵中local或local (1337,2337)的来源。矩阵中没有bootstrap-gateway的能力因为该节点集未声明capabilities字段。registry_based_launch_allowlist允许以 registry 方式启动的触发器版本白名单这里放行cron-trigger1.0.0与dontime1.0.0——即 cron 触发器和 don-time 能力按版本从外部 registry 注册。override_mode all所有节点共享同一份覆盖配置本例中即模块缓存覆盖。模块缓存覆盖本拓扑的核心差异点user_config_overrides注入了[Capabilities.WorkflowRegistry.ModuleCache]配置块[Capabilities.WorkflowRegistry.ModuleCache] Enabled true MaxLoaded 1 IdleEviction true IdleTimeout 30s这是workflow-gateway-don-cache-test与普通workflow-gateway-don拓扑见 topologies/workflow-gateway-don.md其配置 configs/workflow-gateway-don.toml 不带模块缓存覆盖最本质的区别它刻意把MaxLoaded压到1、IdleTimeout缩到30s从而在缓存冒烟测试中快速制造加载 → 闲置 → 驱逐 → 重载的循环用于观察缓存是否按预期工作。对比同目录下的浸泡测试拓扑 configs/workflow-gateway-don-cache-soak-test.toml其覆盖配置为MaxLoaded 100、IdleTimeout 5m并额外设置[Workflows.Limits] Global 5000、PerOwner 5000——两个拓扑分别服务于快速验证与长时间浸泡两种测试目的。支撑组件链、Job Distributor 与辅助服务两条 Anvil 链[[blockchains]] type anvil chain_id 1337 container_name anvil-1337 docker_cmd_params [-b, 0.5, --mixed-mining] [[blockchains]] type anvil chain_id 2337 container_name anvil-2337 port 8546 docker_cmd_params [-b, 0.5, --mixed-mining]两条链均为 Anvil 本地节点Foundry 自带chain_id 分别为 1337 与 2337第一条使用默认 RPC 端口8545第二条显式指定port 8546以避免冲突docker_cmd_params [-b, 0.5, --mixed-mining]-b 0.5表示每 0.5 秒出一个块--mixed-mining开启混合挖矿模式同时支持即时与定时出块为依赖日志触发器与区块高度的能力如 evm 的 LogTrigger提供可控的区块节奏。Job Distributor、fake 服务与基础设施[jd] csa_encryption_key d1093c0060d50a3c89c189b2e485da5a3ce57f3dcb38ab7e2c0d5f0bb2314a44 image job-distributor:0.28.0 [fake] port 8171 [fake_http] port 8666 [infra] type docker[jd]Job Distributor 镜像固定为job-distributor:0.28.0与 setup.toml 中 job_distributor 的本地镜像一致csa_encryption_key用于节点与 JD 之间的 CSA 密钥加密通信[fake]/[fake_http]提供本地 fake 服务端口8171与 fake HTTP 服务端口8666供 http-action / http-trigger 等能力在测试中回环访问[infra] type docker与文档头部 Infra:docker 一致所有节点与链均以 Docker 容器方式运行。能力默认值全局叠加层capability_defaults.tomlconfigs/capability_defaults.toml会在拓扑加载时被自动前置合并loadAndSummarizeConfig中以defaultCapabilitiesConfigFile , configPath方式加载见 environment/topology.go。它对本拓扑中涉及的能力给出全局默认值例如[capability_configs.evm.values]LogTriggerPollInterval 15000000001.5s、ReceiverGasMinimum 500[capability_configs.http-action.values]/[capability_configs.http-trigger.values]进出向的IncomingGlobalRPS 50、IncomingPerSenderRPS 10、对应 Burst 参数等限流配置[capability_configs.vault.values]vault 能力内置于节点无独立 binary其 auth0 配置指向本地模拟端点http://host.docker.internal:18123/。拓扑类别Class是如何判定的single-don 的判定逻辑workflow-gateway-don-cache-test被归类为single-don其判定逻辑写在classifyTopologytopologyviz.goif hasShards { return ClassSharded } if capDONs 0 || workflowDONs 1 || len(dons) 2 { return ClassMultiDON } return ClassSingleDON对照本拓扑两个 DONbootstrap-gateway与workflow、无 shard DON、无独立 capabilities DON、workflow 类型 DON 恰好 1 个、DON 总数 ≤ 2因此落入single-don。这也解释了为什么该拓扑能够单 DON 全本地——bootstrap-gateway 只负责引导与网关流量能力执行全部集中在 workflow DON 内。与之形成对照的是 workflow-gateway-sharded-5-dons.md7 个 DONsharded类与 workflow-gateway-capabilities-don.md3 个 DON含独立 capabilities DONmulti-don类。完整索引见 docs/TOPOLOGIES.md。实战如何启动该拓扑并运行模块缓存冒烟测试1. 启动环境该拓扑专为模块缓存冒烟测试设计。参考系统测试文件 system-tests/tests/smoke/cre/v2_module_cache_test.go 中的前置说明启动命令为cd core/scripts/cre/environment CTF_CONFIGSconfigs/workflow-gateway-don-cache-test.toml go run . env startCTF_CONFIGS环境变量显式指定拓扑配置文件覆盖 CLI 默认值main.go中shell子命令默认注入configs/workflow-gateway-don.toml见 environment/main.go若需要先拉取/构建托管镜像可加--auto-setupenv start的-a简写源码见 environment/environment.gogo run . env start --auto-setup其他常用生命周期命令go run . env stop、go run . env restart、go run . env state purge完整命令清单见 docs/local-cre/environment/index.md。2. 启动前检查拓扑官方推荐在启动前先用拓扑命令核对最终的能力放置# 在 core/scripts/cre/environment 目录下执行 go run . topology list # 列出全部可用拓扑 go run . topology show --config configs/workflow-gateway-don-cache-test.toml # 渲染 ASCII 概览与能力矩阵 go run . topology generate # 重新生成 docs/topologies/*.md 与索引其中topology show默认--config为configs/workflow-gateway-don.toml、--output-dir为statetopology generate默认输出到docs/topologies、索引到docs/TOPOLOGIES.md见 environment/topology.go。3. 运行冒烟测试go test -timeout 10m -run ^Test_CRE_V2_Module_Cache$ -v测试入口定义于 system-tests/tests/smoke/cre/cre_suite_test.gofunc Test_CRE_V2_Module_Cache(t *testing.T) { testEnv : t_helpers.SetupTestEnvironmentWithConfig(t, t_helpers.GetTestConfig(t, /configs/workflow-gateway-don-cache-test.toml)) ExecuteModuleCacheTest(t, testEnv) }测试的验证流程v2_module_cache_test.go如下启动 Chip test sink用于接收 workflow 遥测日志并保证退出时带排空drain地关闭避免 gRPC Publish 阻塞编译并部署10 个基于 cron 触发器的 workflow复用examples/workflows/cron/main.go调度为*/30 * * * * *命名cachetest0cachetest9等待第一个 workflow 执行成功以日志Amazing workflow user log为信号随后进入1 分钟缓存观察窗口期间持续排空用户日志但不做业务断言最终断言节点日志中出现Module cache enabled确认模块缓存确实被启用。由于拓扑将MaxLoaded 110 个 workflow 的 WASM 模块在同一时刻最多只能有 1 个驻留内存配合IdleTimeout 30s测试期间必然反复触发驱逐旧模块、从磁盘重载新模块的行为——这正是该测试验证的核心路径。模块缓存的底层实现LRU 磁盘两级缓存配置项语义来自官方配置文档core/config/docs/core.tomlcore/config/docs/core.toml对[Capabilities.WorkflowRegistry.ModuleCache]的完整语义说明如下配置项默认值语义Enabledfalse激活两级模块缓存LRU 磁盘。开启后编译好的 WASM 模块会驻留内存并持久化到磁盘避免后续激活时重复编译DiskMonitorEnabledfalse启用磁盘用量监控以cacheDir为监控对象输出到 Beholder 遥测与节点/metrics端点IdleEvictiontrue启用基于闲置时间的驱逐模块超过IdleTimeout未使用即被移出内存IdleTimeout10m模块允许闲置的最长时间仅当IdleEviction true时生效MaxLoaded200同时驻留内存的模块数量上限超出时立即驱逐最久未使用LRU的模块。0表示不设上限CacheDir序列化模块二进制的存放目录为空时使用临时目录注意Enabled true同时会启动磁盘监控即使DiskMonitorEnabled false。对应的 Go 接口定义于 core/config/capabilities_config.go。执行侧实现EvictableModule ModuleLRU运行时实现位于 core/services/workflows/syncer/v2/evictable_module.go核心是两个组件EvictableModule对host.ModuleV2的包装。它持有两层引用——current强引用 引用计数用于正在执行的模块与weakInner弱引用模块被驱逐后仍存活到 GC 回收为止用于快速复活。模块加载遵循三级策略命中强引用 → 命中弱引用无需重编译→ 从磁盘读取序列化二进制重新实例化ensureLoaded中通过m.store.GetModule读取见 evictable_module.go。ModuleLRU全局 LRU 管理器内部维护map[string]*EvictableModule每 30 秒执行一次reap()defaultScanInterval 30 * time.Second见 evictable_module.go。reap()分两步evictable_module.go闲置驱逐遍历所有模块now - LastUsed IdleTimeout且处于加载态IsLoaded()的模块被Evict()上限驱逐若加载模块数超过MaxLoaded按最近使用时间排序驱逐最久未使用且超额的模块enforceCapLocked。Evict()采用引用计数守卫 单次 CAS设计evictable_module.go只有当引用计数为 1仅所有者、无正在执行的 Execute 钉住时才允许驱逐避免旧模块仍在服务、新模块又加载导致的瞬时双实例内存抖动驱逐失败会在下一个 reap 周期重试保证最终一致。驱逐只释放 WASM 内存不影响触发器注册与事件通道这些归引擎所有。reap()还会记录loaded数、每次驱逐计数与累计节省内存字节数recordMemorySaved供CacheMetrics与磁盘监控导出。磁盘监控实现于 core/services/workflows/syncer/v2/disk_monitor.go按固定间隔采样cacheDir的磁盘用量并同时输出到 Beholder 遥测与 Prometheus 指标promModuleCacheDiskUsageBytes。配置项与实现的映射拓扑中的覆盖配置实现落点Enabled true创建ModuleLRU与磁盘序列化存储SerialisedModuleStore并启动磁盘监控MaxLoaded 1注入ModuleLRU.maxLoadedWithMaxLoadedModules见 evictable_module.goreap()中触发上限驱逐IdleEviction truereap()中启用闲置扫描分支IdleTimeout 30s注入ModuleLRU.idleTimeoutWithIdleTimeout见 evictable_module.go这意味着本拓扑中MaxLoaded 1IdleTimeout 30s的组合会让ModuleLRU在每次reap()30 秒周期时都试图把上一个闲置模块驱逐出去从而在 1 分钟观察窗口内制造至少 23 次完整的驱逐 → 弱引用/磁盘重载循环足以暴露缓存逻辑的并发缺陷例如 Evict 与 Execute 的竞态。常见问题与调参建议想复现模块缓存命中而非频繁驱逐将MaxLoaded调大如 soak 拓扑的100、IdleTimeout调长如5m使多个 workflow 模块同时驻留内存需要压测大量 workflow 注册参考 soak 拓扑追加[Workflows.Limits]把Global/PerOwner从默认的200见 core/config/docs/core.toml提升到目标规模节点启动报镜像缺失先执行go run . env setup拉取 Job Distributor、Chip Router、Chip Ingress、Chip Config 等托管镜像必要时配置MAIN_AWS_ECR与SDLC_AWS_ECR两个 ECR 仓库想用本地源码构建节点/能力使用env start的--local-node与--local-capabilities旗标详见 docs/local-cre/environment/index.md本地构建可感知replace指令如本地 chainlink-common这是 Docker 内构建看不到的。小结workflow-gateway-don-cache-test拓扑是 Chainlink Local CRE 中一个小而专的参考实现它用 single-don 类别把七类能力全部本地化到 4 节点的 workflow DON让 1 节点的 bootstrap-gateway 专注引导与网关流量两条 Anvil 链1337/2337为 EVM 能力提供可控的区块环境其独特之处在于通过user_config_overrides注入MaxLoaded 1、IdleTimeout 30s的模块缓存覆盖配合Test_CRE_V2_Module_Cache冒烟测试定向验证了两级模块缓存的启用、驱逐与重载路径。理解这份拓扑也就掌握了 Local CRE 拓扑文档配置为源、文档为投影的生成范式以及从 TOML 到能力矩阵、再到运行时实现的完整证据链。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考