Chainlink CRE 多 DON 拓扑解析workflow-gateway-capabilities-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的标准多 DON 拓扑文档workflow-gateway-capabilities-don为骨架结合其 TOML 配置与源码实现系统讲解如何在 Docker 基础设施上搭建一个由workflow、capabilities、bootstrap-gateway三个 DON 组成的本地开发环境包括能力矩阵Capability Matrix的放置规则、远程能力暴露的配置方式、拓扑发现与文档生成命令以及启动环境与部署工作流的完整步骤。读完本文你将掌握 Local CRE 多 DON 拓扑的阅读、验证、调整与启动方法并能基于源码理解能力放置背后的校验逻辑。一、拓扑概览三类 DON 的分工该拓扑对应的文档位于 core/scripts/cre/environment/docs/topologies/workflow-gateway-capabilities-don.md其底层配置文件为 core/scripts/cre/environment/configs/workflow-gateway-capabilities-don.toml。它被归类为拓扑类Classmulti-don基础设施InfradockerDON 数量3与单 DON 拓扑如workflow-gateway-don.toml不同该拓扑把工作流执行、能力托管和网关/引导职责拆分成三个独立的 DON。这种拆分正是multi-don类的核心价值当工作流栈需要在不同 DON 之间分配职责而不是在单点运行一切时就应选择多 DON 拓扑参见 docs/local-cre/environment/topologies.md。三个 DON 的顶层摘要如下DON类型Types节点数角色RolesEVM 链暴露远程能力bootstrap-gatewaybootstrap,gateway1bootstrap,gateway1337, 2337falsecapabilitiescapabilities4plugin1337, 2337trueworkflowworkflow4plugin1337, 2337false其中capabilitiesDON 是唯一设置了Exposes remote capabilities: true的 DON承担向其他 DON 提供远程能力如 EVM、vault的职责workflowDON 负责执行工作流将触发类与共识类能力本地化bootstrap-gatewayDON 则承担 DON 引导bootstrap与网关gateway流量接入。二、能力矩阵能力放置的真相来源文档中明确指出能力矩阵是该拓扑下能力按 DON 放置的真相来源source of truth。下表完整复刻该矩阵Capabilitybootstrap-gatewaycapabilitiesworkflowconsensus--localcron--localdon-time--localevm-remote-exposed (2337)local (1337)http-action--localhttp-trigger--localvault-remote-exposed-矩阵语义解读local表示该能力在对应 DON 内部本地运行。workflowDON 本地承载了consensus、cron、don-time、http-action、http-trigger以及绑定链 ID 1337 的evmremote-exposed表示该能力托管在capabilitiesDON 上并通过远程调用暴露给其他 DON 使用。其中evm对应链 ID 2337配置中写为evm-2337vault无具体链绑定-表示该 DON 上不放置该能力。矩阵中的local (1337)与remote-exposed (2337)说明了同一个evm能力如何按链 ID 拆分链 1337 的 EVM 能力由工作流 DON 本地提供链 2337 的 EVM 能力则由能力 DON 远程暴露。这在 TOML 配置中体现为capabilities [evm-1337]workflow DON与capabilities [evm-2337]capabilities DON两条不同的能力旗标。从源码角度能力旗标中的链 ID 后缀会被解析并剥离system-tests/lib/cre/environment/config/config.go中的removeChainIDFromFlag会提取evm-2337尾部的数字作为 chain ID并将基础能力名evm用于能力校验。这意味着同一基础能力可以以多个链感知旗标的形式出现每个旗标绑定不同的链 ID。三、逐 DON 详解3.1bootstrap-gateway1 节点Typesbootstrap,gatewayNodes1Rolesbootstrap,gatewayEVM chains1337, 2337Exposes remote capabilitiesfalse该 DON 是拓扑的入口节点同时扮演引导节点与网关节点。引导节点负责 DON 网络引导网关节点负责接收外部连接器与网关流量。配置中为其声明了自定义端口映射5002:5002与15002:15002注释说明 5002 是 Web API 能力端口用于接收入站请求15002 是 vault 端口用于接收 vault 入站请求。3.2capabilities4 节点TypescapabilitiesNodes4RolespluginEVM chains1337, 2337Exposes remote capabilitiestrue该 DON 是唯一远程暴露能力的 DON托管vault与evm-2337。配置注释特别强调即使该 DON 没有能力使用链 1337也必须连接链 1337因为网关配置中需要用链 1337 上的节点地址来标识节点这是 vault 与基于网关的 HTTP 能力的前置要求。3.3workflow4 节点TypesworkflowNodes4RolespluginEVM chains1337, 2337Exposes remote capabilitiesfalse该 DON 是工作流执行者本地承载cron、http-action、http-trigger、consensus、don-time、evm-1337六类能力。配置注释同样说明尽管该 DON 没有使用链 2337 上的任何能力仍需连接到链 2337因为能力 DON 的引导任务bootstrap job会创建在此 DON 的引导节点上。四、配置 TOML 全量解析以下是 workflow-gateway-capabilities-don.toml 的完整结构与逐段说明。该文件由 Local CRE 的Config结构体承载其字段定义在 system-tests/lib/cre/environment/config/config.goblockchains、nodesets、jd、infra均为必填项缺失时无法通过拓扑探测。4.1 全局组件与链[chip_router] image local-cre-chip-router:v1.0.1 [[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]chip_routerCHIP 路由器镜像用于连接器流量路由blockchains两条基于 Anvil 的本地 EVM 链chain ID 分别为1337与2337。第二条链显式指定了外部端口8546第一条链使用默认端口。-b 0.5控制区块生成间隔--mixed-mining启用混合挖矿模式链 ID 1337/2337 与能力矩阵中evm的local (1337)、remote-exposed (2337)一一对应。4.2 Job Distributor 与辅助服务[jd] csa_encryption_key d1093c0060d50a3c89c189b2e485da5a3ce57f3dcb38ab7e2c0d5f0bb2314a44 # any random 32 byte hex string image job-distributor:0.28.0 [fake] port 8171 [fake_http] port 8666 #[s3provider] # # use all defaults # port 9000 # console_port 9001 [infra] type dockerjd.csa_encryption_keyCSA 加密密钥任意 32 字节十六进制字符串源码校验中该字段为必填缺失会报错jd.csa_encryption_key must be providedjd.imageJob Distributor 镜像版本需按实际环境调整fake/fake_http用于模拟外部服务的假服务端口s3provider被注释掉的 S3 提供方需要时取消注释并使用默认端口9000/9001infra.type基础设施类型本拓扑为docker可选kubernetes。4.3workflownodeset[[nodesets]] nodes 4 name workflow don_family test-don-family don_types [workflow] enable_metering true override_mode all http_port_range_start 10100 # even though this DON is not using any capability for chain with ID 2337 we still need it to be connected to it, # because bootstrap job for capability DON will be created on the bootstrap node from this DON supported_evm_chains [1337, 2337] env_vars { CL_EVM_CMD , OTEL_SERVICE_NAME chainlink-node, CL_CRE_SETTINGS {global:{PerOrg:{BaseTriggerRetransmitEnabled:true}}} } capabilities [cron, http-action, http-trigger, consensus, don-time, evm-1337] registry_based_launch_allowlist [cron-trigger1.0.0, dontime1.0.0]要点don_family test-don-family所有 nodeset 必须设置don_family用于网关配对、能力注册与工作流部署的分组源码中该字段标注为validate:required缺失会导致环境启动失败参见 system-tests/lib/cre/types.go 中NodeSet的定义supported_evm_chains [1337, 2337]即使本 DON 不使用链 2337 的能力仍需连接该链因为能力 DON 的引导任务创建在本 DON 的引导节点上capabilities本地能力列表与能力矩阵的workflow列完全一致registry_based_launch_allowlist基于注册表的启动白名单允许通过能力注册表Capabilities Registry启动cron-trigger1.0.0与dontime1.0.0env_vars为节点注入环境变量CL_CRE_SETTINGS覆盖了组织级的BaseTriggerRetransmitEnabled配置http_port_range_start 10100节点 HTTP 端口起始值。数据库与节点规格[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 } # image chainlink-tmp:latest user_config_overrides 每个 DON 使用独立的 PostgreSQL 12 实例workflow使用端口13000node_specs声明节点角色为plugin节点镜像基于仓库内core/chainlink.Dockerfile构建docker_ctx ../../../..指向上层仓库根目录。4.4capabilitiesnodeset[[nodesets]] nodes 4 name capabilities don_family test-don-family don_types [capabilities] enable_metering true exposes_remote_capabilities true override_mode all http_port_range_start 10200 # we need to have chain 1337 configured (even if no capability uses it), because we use node addresses on chain 1337 # to identify nodes in the gateway configuration (required by vault and gateway-based HTTP capabilities) supported_evm_chains [1337, 2337] env_vars { CL_EVM_CMD , OTEL_SERVICE_NAME chainlink-node, CL_CRE_SETTINGS {global:{PerOrg:{BaseTriggerRetransmitEnabled:true}}} } capabilities [vault, evm-2337]关键差异点exposes_remote_capabilities true这是该 DON 与另外两个 DON 的核心区别。该字段在 system-tests/lib/cre/types.go 的NodeSet结构中声明为toml:exposes_remote_capabilities并传播到DonMetadata.ExposesRemoteCapabilities驱动能力注册时的远程暴露逻辑capabilities [vault, evm-2337]仅托管 vault 与链 2337 的 EVM 能力链 1337 仍然必须配置——网关配置使用链 1337 上的节点地址标识节点vault 与基于网关的 HTTP 能力的前置要求数据库端口为13100HTTP 端口从10200起始。4.5bootstrap-gatewaynodeset[[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 , OTEL_SERVICE_NAME chainlink-node, CL_CRE_SETTINGS {global:{PerOrg:{BaseTriggerRetransmitEnabled:true}}} } 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 } # 5002 is the web API capabilities port for incoming requests # 15002 is the vault port for incoming requests custom_ports [5002:5002,15002:15002] # image chainlink-tmp:latest user_config_overrides 单节点override_mode each与前两个 nodeset 的all不同角色为bootstrap与gateway数据库端口13200HTTP 端口从10300起始custom_ports暴露两个入站端口5002Web API 能力端口与15002vault 端口。五、能力放置的源码级原理5.1 NodeSet 结构能力配置的载体system-tests/lib/cre/types.go 中定义的NodeSet结构体完整承载了拓扑配置中的能力放置语义Capabilities []string全局能力列表无链特定配置的能力如 cron、http-triggerDONTypes []stringDON 类型workflow、capabilities、gatewayDonFamily string标记validate:required缺失会导致环境启动失败同时NewDonMetadata中会校验don_family非空否则报错ExposesRemoteCapabilities bool是否向其他 DON 远程暴露能力RegistryBasedLaunchAllowlist []string基于能力注册表的启动白名单SupportedEVMChains []uint64DON 支持的链 ID 过滤器CapabilityConfigs按 DON 覆盖全局能力配置示例见[nodesets.capability_configs.http-action.values]。这些字段会传播到DonMetadata供网关配对、能力注册与工作流部署使用。5.2 能力校验未知能力直接报错配置加载时system-tests/lib/cre/environment/config/config.go 的Validate方法会对每个 nodeset 的能力旗标做白名单校验先通过removeChainIDFromFlag剥离链 ID 后缀再与SupportedCapabilityFlags()返回的合法能力集合比对未知能力会直接报错并列出合法值。这意味着向capabilities列表添加一个尚未注册的新能力会导致环境启动失败必须先在能力旗标提供者capabilityFlagsProvider中登记。5.3 能力默认值capability_defaults.toml全局能力默认配置位于 core/scripts/cre/environment/configs/capability_defaults.toml环境启动时会自动将该文件前置合并参见 docs/local-cre/environment/topologies.md。其中与本拓扑能力直接相关的默认值包括evmLogTriggerPollInterval 15000000001.5 秒纳秒、ReceiverGasMinimum 500http-action/http-trigger一组入站/出站的 RPS 与 Burst 限流参数如IncomingGlobalBurst 10、IncomingGlobalRPS 50、OutgoingPerSenderRPS 10consensusbinary_name consensusOCR 相关字段在运行时解析vault无独立二进制内建于节点配置包含 auth0 的issuerURL、audience、tenantID。这些默认值可通过每个 nodeset 内的[nodesets.capability_configs.cap.values]按 DON 覆盖具体示例参见 core/scripts/cre/environment/configs/examples/workflow-don-overrides.toml。六、拓扑工具链发现、可视化与文档生成Local CRE 的 topology 子命令实现于 core/scripts/cre/environment/environment/topology.go提供了三组命令# 列出 configs/ 下所有可用的拓扑配置 go run . topology list # 查看单个拓扑并生成可视化产物 go run . topology show --config configs/workflow-gateway-capabilities-don.toml # 为所有拓扑配置生成 Markdown 文档与索引 go run . topology generate # 仅检查生成的文档是否过期 go run . topology generate --check命令默认值来自源码topology show --config默认configs/workflow-gateway-don.tomltopology show --output-dir默认statetopology generate --output-dir默认docs/topologiestopology generate --index-path默认docs/TOPOLOGIES.md。拓扑发现逻辑discoverTopologies会递归扫描configs/目录解析每个 TOML仅当同时包含nodesets、blockchains、jd、infra四类键时才认定为拓扑配置。生成的总索引即 core/scripts/cre/environment/docs/TOPOLOGIES.md它列出了包括本拓扑在内的全部拓扑并标注multi-don类与 DON 数量。文档头部明确提示This file is generated bygo run . topology generate. Do not edit manually.该文件由命令生成请勿手工编辑。七、启动环境与部署工作流7.1 快速启动在core/scripts/cre/environment目录下执行参见 core/scripts/cre/environment/README.mdgo run . env start --auto-setup go run . workflow deploy -w ./examples/workflows/cron/main.go --compile -n cron_exampleenv start --auto-setup启动本地环境并自动完成初始化配置workflow deploy编译并部署示例工作流如 cron 示例-n指定工作流名称。环境启动时Local CRE 会默认前置合并能力默认配置对于冒烟测试默认本地流程使用configs/workflow-gateway-capabilities-don.toml除非显式覆盖见 docs/local-cre/environment/topologies.md。工作流示例位于 core/scripts/cre/environment/examples/workflows涵盖 cron、http、time、time_consensus、proof-of-reserve 等多种类型。7.2 变更能力放置后的验证流程按 docs/local-cre/environment/topologies.md 的指引启用一项能力并非单步操作需要四件事对齐拓扑 TOML 将能力放置在正确的 DON、DON 所用节点镜像包含对应插件或二进制、环境允许网关出站端口、生成的拓扑文档确认最终放置符合预期。修改能力放置后应重新运行go run . topology show --config your-topology.toml go run . topology generate再检查生成的能力矩阵确认无误后再启动环境。八、选择多 DON 拓扑的实践建议依据 docs/local-cre/environment/topologies.md 的指导原则工作流只需本地能力如 cron、consensus时优先使用更简单的单 DON 拓扑便于快速本地迭代工作流需要远程暴露能力如 EVM、read-contract、vault、Web API 目标时使用本拓扑这类能力启用的多 DON 拓扑这是贴近真实冒烟测试覆盖的标准路径分片与专用拓扑sharded 及各类专项拓扑仅在测试或功能确实需要时选用。如需多网关路由冒烟测试可改用 workflow-gateway-capabilities-multi-gateway-don.toml它在 US 引导网关之外增加第二个网关 nodesetgateway-eu带独立gateway_don_id并将工作流 DON 的CL_CRE_SETTINGS组织覆盖指向gateway_don_eu启用PropagateOrgIDInRequestMetadata true后运行Test_CRE_V2_HTTP_Action_Multi_Gateway冒烟测试。结语workflow-gateway-capabilities-don是 Local CRE 中标准冒烟测试拓扑的代表它以multi-don类在 Docker 上编排 9 个节点1 引导网关 4 能力节点 4 工作流节点、两条 Anvil 链1337/2337与独立数据库通过能力矩阵精确控制local与remote-exposed的能力放置。理解这张矩阵与底层 TOML 配置的对应关系是你在本地复现、修改并验证 CRE 多 DON 工作流的基础能力。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考