Chainlink 本地 CRE 分片拓扑解析workflow-gateway-sharded-5-dons 的 7 DON 架构与能力矩阵【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink本文以 Chainlink 仓库中自动生成的拓扑文档 workflow-gateway-sharded-5-dons.md 为骨架结合其对应配置文件 workflow-gateway-sharded-5-dons.toml 与system-tests/lib/cre、core/scripts/cre/environment等源码实现完整讲解 Chainlink 本地 CRECapabilities Runtime Environment中分片sharded类多 DON 拓扑的部署形态。读完本文你将掌握如何读懂该拓扑的能力矩阵与 7 个 DON 的分工、如何从 TOML 配置还原每个节点的角色与端口、拓扑文档的生成机制与校验命令以及分片拓扑背后的 Ring OCR3 与 ShardConfig 合约启动流程。一、文档定位由topology generate自动生成的拓扑说明书在 Chainlink 仓库中core/scripts/cre/environment/docs/topologies/下的每一份*.md都是自动生成的其源头是 TOPOLOGIES.md 中登记的各份 TOML 拓扑配置。索引表明确记载ConfigClassDONsconfigs/workflow-gateway-sharded-5-dons.tomlsharded7生成机制在 environment/topology.go 的TopologyCmd中实现入口命令为cd core/scripts/cre/environment go run . topology list # 列出 configs/ 下所有可用拓扑 go run . topology show -c configs/workflow-gateway-sharded-5-dons.toml # 查看单个拓扑 go run . topology generate # 重新生成全部拓扑文档与索引 go run . topology generate --check # 校验文档是否过期其中isTopologyConfigtopology.go会检查一份 TOML 是否同时具备nodesets、blockchains、jd、infra四个区块只有四者齐全才会被识别为合法拓扑配置。因此本文档中的三个元数据字段Config、Class、Infra均直接来自对应 TOMLConfig:configs/workflow-gateway-sharded-5-dons.tomlClass:shardedInfra:dockerClass字段并非手工填写而是由 topologyviz.go 的classifyTopology函数动态判定只要存在任意 DON 的ShardIndex 0或其DONTypes包含shard即归类为sharded。二、拓扑总览1 个网关 6 个分片 7 个 DON该拓扑由 7 个 DON 组成按功能可划分为两类DON节点数DON 类型节点角色分工bootstrap-gateway1bootstrap,gatewaybootstrap / gateway负责 DON 引导bootstrap与网关流量gatewayshard0~shard5各 4shard,workflowplugin分片工作流 DON执行工作流并承载本地能力DON 总节点数为1 6 × 4 25且全部 DON 均声明支持 EVM 链1337, 2337且均不对外暴露远程能力Exposes remote capabilities: false。bootstrap-gateway节点在 TOML 配置 中以nodes 1、don_types [bootstrap, gateway]、roles [bootstrap, gateway]声明并额外通过custom_ports暴露两个关键入站端口# 5002 is the web API capabilities port for incoming requests # 15002 is the vault port for incoming requests custom_ports [5002:5002,15002:15002]这意味着外部请求Web API 能力调用、vault 请求都汇聚到bootstrap-gateway这一单一入口再由网关路由到各分片。三、能力矩阵能力在 DON 间的放置真相能力矩阵Capability Matrix被文档明确标注为source of truth for capability placement by DON即能力在哪个 DON 上运行、以何种模式local/-存在都以这张表为准Capabilitybootstrap-gatewayshard0shard1shard2shard3shard4shard5consensus-locallocallocallocallocallocalcron-locallocallocallocallocallocaldon-time-locallocallocallocallocallocalevm-local (1337,2337)local (1337,2337)local (1337,2337)local (1337,2337)local (1337,2337)local (1337,2337)http-action-local-----http-trigger-local-----vault-local-----读表的要点-表示该 DON 未声明此能力即工作流在该分片上运行到对应步骤时会失败或无法调度local表示能力以本地插件形式装载在该 DON 的节点内非远程代理local (1337,2337)表示链相关能力绑定到具体 EVM 链 ID——evm能力在配置中实际写作evm-1337与evm-2337两个能力标志。矩阵中的local/-判定由 topologyviz.go 的buildCapabilityMatrix生成它先按BaseFlag去掉链 ID 后缀后的能力名聚合并按名称排序随后对每个 DON 标记local或remote-exposed。链 ID 后缀的解析逻辑splitCapabilityFlagtopologyviz.go会把evm-1337拆成evm 链 ID1337——这也是矩阵中evm行出现(1337,2337)的原因。分片能力的差异化放置从矩阵可以直观看到本拓扑的核心设计意图cron、consensus、don-time、evm是全分片标配6 个分片各自独立承载任何分片都能独立完成基于 cron/时间/共识/EVM 的工作流http-action、http-trigger、vault仅放置在shard0这类与外部 HTTP/敏感凭据相关的能力被刻意收敛到单一分片。TOML 中shard1~shard5的注释说明了原因add vault, http-action, http-trigger, when gateway can support more than 1 DON per service——即当前网关对每个服务仅支持单 DON 挂载因此这类能力暂时只能放在一个分片。配置侧的对应关系shard0的capabilities列表为[vault, cron, http-action, http-trigger, consensus, don-time, evm-1337, evm-2337]TOML 第 50 行而shard1~shard5则缺省为[cron, consensus, don-time, evm-1337, evm-2337]。四、逐 DON 解剖从文档字段到 TOML 配置文档为每个 DON 列出了Types、Nodes、Roles、EVM chains、Exposes remote capabilities五个字段。这些字段与 TOML 的映射关系如下4.1shard0分片组长shard leaderTypes: shard, workflow Nodes: 4 Roles: plugin EVM chains: 1337,2337 Exposes remote capabilities: falseshard0是唯一显式写出 4 个node_specs的 nodesetTOML 第 41-95 行其中node 0额外暴露了两个调试端口[[nodesets.node_specs]] roles [plugin] [nodesets.node_specs.node] docker_ctx ../../../.. docker_file core/chainlink.Dockerfile docker_build_args { CL_IS_PROD_BUILD false } custom_ports [60051:50051, 19876:9876] user_config_overrides 60051:50051对应 ShardOrchestrator 的 gRPC 端口19876:9876对应 Arbiter 端口配置注释明确说明使用高位端口60051、19876是为了避免与其他服务冲突。结合 sharding.go 的getShardLeaderDON按ShardIndex 0寻找组长可以确认shard0即分片组长Ring OCR3 的 Ring 任务只创建在组长 DON 上。4.2shard1~shard5通用分片这 5 个 nodeset 结构完全一致以shard1为例[[nodesets]] nodes 4 name shard1 don_family test-don-family don_types [workflow, shard] shard_index 1 override_mode all http_port_range_start 10100 env_vars { CL_EVM_CMD } capabilities [cron, 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 13100要点override_mode all表示下方单个node_specs会应用到该 nodeset 的所有 4 个节点对比shard0的override_mode each 4 个独立node_specsshard_index从 1 递增到 5是分片在 Ring 中的唯一标识每个分片有独立的 PostgreSQL 实例postgres:12.0端口 13100~13500 递增http_port_range_start从 10100 递增到 10500为各分片节点分配独立的 HTTP 端口段registry_based_launch_allowlist限定了通过 registry 启动的触发器插件版本cron-trigger1.0.0、dontime1.0.0。4.3bootstrap-gateway引导与网关合一Types: bootstrap, gateway Nodes: 1 Roles: bootstrap, gateway EVM chains: 1337,2337 Exposes remote capabilities: false在 TOML 中通过don_types [bootstrap, gateway]声明双重职责并显式给出supported_evm_chains [1337, 2337]。它不声明任何capabilities仅作为工作流 DON 与外部世界之间的流量入口。五、分片拓扑的底层原理Ring OCR3 与 ShardConfigsharded类拓扑与普通多 DON 拓扑的本质差异在于分片之间需要通过链上的分片协调机制保证共识与状态一致性。这一机制在 sharding.go 的SetupSharding中以六步流程落地校验分片拓扑调用ValidateShardTopology确保分片数量、shard_index0的组长唯一性等约束成立校验逻辑见 sharding_test.go其中覆盖了多个shard_index0、找不到shard_index0等错误场景部署 ShardConfig 合约以len(shardDONs)作为InitialShardCount部署分片配置合约部署 Ring OCR3 合约为分片 Ring 部署多链共识合约获取 Ring P2P bootstrap URL从 bootstrap DON 收集 P2P 引导地址在组长 DON 上创建 Ring 任务等待 ConfigPoller filter 注册后配置 OCR3。分片的 DON 类型在 system-tests/lib/cre/don.go 中以ShardIndex uint \toml:shard_index建模而classifyTopology也正是读取该字段来判定sharded 类别。六、本地实操启动该拓扑并部署工作流6.1 环境准备先在 core/scripts/cre/environment 目录下完成依赖准备详见go run . setup然后通过CTF_CONFIGS环境变量指定拓扑并启动cd core/scripts/cre/environment export CTF_CONFIGSconfigs/workflow-gateway-sharded-5-dons.toml go run . env start --auto-setup启动流程environment.go的关键行为若设置--auto-setup会先执行RunSetup框架会自动把 capability_defaults.toml前置拼接到CTF_CONFIGS之前setDefaultCtfConfigs因此最终生效的是默认能力配置 拓扑配置的组合设置TESTCONTAINERS_RYUK_DISABLEDtrue避免命令结束时 Ryuk 销毁容器清理历史state目录后开始拉起容器。注意若不设置CTF_CONFIGSenv start会默认使用configs/workflow-gateway-capabilities-don.toml见 environment.go。6.2 部署工作流时的 DON 选择分片拓扑下部署工作流必须明确目标 DON否则会因为存在多个 workflow DON 而报错。选择逻辑实现在 workflow_don_resolver.go 的ResolveWorkflowDONMetadata优先级为--workflow-don-name按nodesets.name精确匹配如shard0--don-family按don_family匹配多个分片共享同一 family 时必须再带--shard-index若拓扑中恰好只有一个 workflow DON 则自动选中。# 方式一显式指定分片名 go run . workflow deploy -w ./examples/workflows/v2/cron/main.go --compile -n cron_example \ --workflow-don-name shard0 # 方式二按 family shard index 定位 go run . workflow deploy -w ./examples/workflows/v2/cron/main.go --compile -n cron_example \ --don-family test-don-family --shard-index 0resolveWorkflowDONByFamilyworkflow_don_resolver.go会在don_family命中多个分片且未指定--shard-index时报错提示set --shard-index or --workflow-don-name——这正是本拓扑6 个分片同属test-don-family的典型使用场景。6.3 校验放置是否与预期一致修改拓扑配置后务必重新生成并核对矩阵go run . topology show -c configs/workflow-gateway-sharded-5-dons.toml go run . topology generate生成的产物包括docs/topologies/*.md与docs/TOPOLOGIES.md索引generate --check可校验其是否过期。官方实践指南docs/local-cre/environment/topologies.md强调sharded 及专用拓扑只应在测试或功能确实需要分片能力时选用——如果工作流仅依赖cron、consensus等本地能力使用更简单的拓扑如workflow-gateway-don.toml或workflow-gateway-capabilities-don.toml即可获得更快的启动与迭代速度。七、小结workflow-gateway-sharded-5-dons是 Chainlink 本地 CRE 中规模最大的分片拓扑之一bootstrap-gateway承担引导与网关入口shard0作为组长承载http-action/http-trigger/vault等受限能力shard1~shard5各自以 4 节点并行承载cron/consensus/don-time/evm通用能力。其能力矩阵文档由go run . topology generate自动维护可作为能力放置的单一事实来源部署工作流时则需借助--workflow-don-name或--don-family --shard-index精确路由。理解了这份拓扑也就掌握了 Chainlink CRE 从单 DON到多分片协同的扩展路径及其链上协调机制Ring OCR3 ShardConfig的运作方式。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/16 14:37:53 · 阅读 1.2k Chainlink 本地 CRE 分片拓扑解析：workflow-gateway-sharded-5-dons 的 7 DON 架构与能力矩阵
Chainlink 本地 CRE 分片拓扑解析workflow-gateway-sharded-5-dons 的 7 DON 架构与能力矩阵【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink本文以 Chainlink 仓库中自动生成的拓扑文档 workflow-gateway-sharded-5-dons.md 为骨架结合其对应配置文件 workflow-gateway-sharded-5-dons.toml 与system-tests/lib/cre、core/scripts/cre/environment等源码实现完整讲解 Chainlink 本地 CRECapabilities Runtime Environment中分片sharded类多 DON 拓扑的部署形态。读完本文你将掌握如何读懂该拓扑的能力矩阵与 7 个 DON 的分工、如何从 TOML 配置还原每个节点的角色与端口、拓扑文档的生成机制与校验命令以及分片拓扑背后的 Ring OCR3 与 ShardConfig 合约启动流程。一、文档定位由topology generate自动生成的拓扑说明书在 Chainlink 仓库中core/scripts/cre/environment/docs/topologies/下的每一份*.md都是自动生成的其源头是 TOPOLOGIES.md 中登记的各份 TOML 拓扑配置。索引表明确记载ConfigClassDONsconfigs/workflow-gateway-sharded-5-dons.tomlsharded7生成机制在 environment/topology.go 的TopologyCmd中实现入口命令为cd core/scripts/cre/environment go run . topology list # 列出 configs/ 下所有可用拓扑 go run . topology show -c configs/workflow-gateway-sharded-5-dons.toml # 查看单个拓扑 go run . topology generate # 重新生成全部拓扑文档与索引 go run . topology generate --check # 校验文档是否过期其中isTopologyConfigtopology.go会检查一份 TOML 是否同时具备nodesets、blockchains、jd、infra四个区块只有四者齐全才会被识别为合法拓扑配置。因此本文档中的三个元数据字段Config、Class、Infra均直接来自对应 TOMLConfig:configs/workflow-gateway-sharded-5-dons.tomlClass:shardedInfra:dockerClass字段并非手工填写而是由 topologyviz.go 的classifyTopology函数动态判定只要存在任意 DON 的ShardIndex 0或其DONTypes包含shard即归类为sharded。二、拓扑总览1 个网关 6 个分片 7 个 DON该拓扑由 7 个 DON 组成按功能可划分为两类DON节点数DON 类型节点角色分工bootstrap-gateway1bootstrap,gatewaybootstrap / gateway负责 DON 引导bootstrap与网关流量gatewayshard0~shard5各 4shard,workflowplugin分片工作流 DON执行工作流并承载本地能力DON 总节点数为1 6 × 4 25且全部 DON 均声明支持 EVM 链1337, 2337且均不对外暴露远程能力Exposes remote capabilities: false。bootstrap-gateway节点在 TOML 配置 中以nodes 1、don_types [bootstrap, gateway]、roles [bootstrap, gateway]声明并额外通过custom_ports暴露两个关键入站端口# 5002 is the web API capabilities port for incoming requests # 15002 is the vault port for incoming requests custom_ports [5002:5002,15002:15002]这意味着外部请求Web API 能力调用、vault 请求都汇聚到bootstrap-gateway这一单一入口再由网关路由到各分片。三、能力矩阵能力在 DON 间的放置真相能力矩阵Capability Matrix被文档明确标注为source of truth for capability placement by DON即能力在哪个 DON 上运行、以何种模式local/-存在都以这张表为准Capabilitybootstrap-gatewayshard0shard1shard2shard3shard4shard5consensus-locallocallocallocallocallocalcron-locallocallocallocallocallocaldon-time-locallocallocallocallocallocalevm-local (1337,2337)local (1337,2337)local (1337,2337)local (1337,2337)local (1337,2337)local (1337,2337)http-action-local-----http-trigger-local-----vault-local-----读表的要点-表示该 DON 未声明此能力即工作流在该分片上运行到对应步骤时会失败或无法调度local表示能力以本地插件形式装载在该 DON 的节点内非远程代理local (1337,2337)表示链相关能力绑定到具体 EVM 链 ID——evm能力在配置中实际写作evm-1337与evm-2337两个能力标志。矩阵中的local/-判定由 topologyviz.go 的buildCapabilityMatrix生成它先按BaseFlag去掉链 ID 后缀后的能力名聚合并按名称排序随后对每个 DON 标记local或remote-exposed。链 ID 后缀的解析逻辑splitCapabilityFlagtopologyviz.go会把evm-1337拆成evm 链 ID1337——这也是矩阵中evm行出现(1337,2337)的原因。分片能力的差异化放置从矩阵可以直观看到本拓扑的核心设计意图cron、consensus、don-time、evm是全分片标配6 个分片各自独立承载任何分片都能独立完成基于 cron/时间/共识/EVM 的工作流http-action、http-trigger、vault仅放置在shard0这类与外部 HTTP/敏感凭据相关的能力被刻意收敛到单一分片。TOML 中shard1~shard5的注释说明了原因add vault, http-action, http-trigger, when gateway can support more than 1 DON per service——即当前网关对每个服务仅支持单 DON 挂载因此这类能力暂时只能放在一个分片。配置侧的对应关系shard0的capabilities列表为[vault, cron, http-action, http-trigger, consensus, don-time, evm-1337, evm-2337]TOML 第 50 行而shard1~shard5则缺省为[cron, consensus, don-time, evm-1337, evm-2337]。四、逐 DON 解剖从文档字段到 TOML 配置文档为每个 DON 列出了Types、Nodes、Roles、EVM chains、Exposes remote capabilities五个字段。这些字段与 TOML 的映射关系如下4.1shard0分片组长shard leaderTypes: shard, workflow Nodes: 4 Roles: plugin EVM chains: 1337,2337 Exposes remote capabilities: falseshard0是唯一显式写出 4 个node_specs的 nodesetTOML 第 41-95 行其中node 0额外暴露了两个调试端口[[nodesets.node_specs]] roles [plugin] [nodesets.node_specs.node] docker_ctx ../../../.. docker_file core/chainlink.Dockerfile docker_build_args { CL_IS_PROD_BUILD false } custom_ports [60051:50051, 19876:9876] user_config_overrides 60051:50051对应 ShardOrchestrator 的 gRPC 端口19876:9876对应 Arbiter 端口配置注释明确说明使用高位端口60051、19876是为了避免与其他服务冲突。结合 sharding.go 的getShardLeaderDON按ShardIndex 0寻找组长可以确认shard0即分片组长Ring OCR3 的 Ring 任务只创建在组长 DON 上。4.2shard1~shard5通用分片这 5 个 nodeset 结构完全一致以shard1为例[[nodesets]] nodes 4 name shard1 don_family test-don-family don_types [workflow, shard] shard_index 1 override_mode all http_port_range_start 10100 env_vars { CL_EVM_CMD } capabilities [cron, 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 13100要点override_mode all表示下方单个node_specs会应用到该 nodeset 的所有 4 个节点对比shard0的override_mode each 4 个独立node_specsshard_index从 1 递增到 5是分片在 Ring 中的唯一标识每个分片有独立的 PostgreSQL 实例postgres:12.0端口 13100~13500 递增http_port_range_start从 10100 递增到 10500为各分片节点分配独立的 HTTP 端口段registry_based_launch_allowlist限定了通过 registry 启动的触发器插件版本cron-trigger1.0.0、dontime1.0.0。4.3bootstrap-gateway引导与网关合一Types: bootstrap, gateway Nodes: 1 Roles: bootstrap, gateway EVM chains: 1337,2337 Exposes remote capabilities: false在 TOML 中通过don_types [bootstrap, gateway]声明双重职责并显式给出supported_evm_chains [1337, 2337]。它不声明任何capabilities仅作为工作流 DON 与外部世界之间的流量入口。五、分片拓扑的底层原理Ring OCR3 与 ShardConfigsharded类拓扑与普通多 DON 拓扑的本质差异在于分片之间需要通过链上的分片协调机制保证共识与状态一致性。这一机制在 sharding.go 的SetupSharding中以六步流程落地校验分片拓扑调用ValidateShardTopology确保分片数量、shard_index0的组长唯一性等约束成立校验逻辑见 sharding_test.go其中覆盖了多个shard_index0、找不到shard_index0等错误场景部署 ShardConfig 合约以len(shardDONs)作为InitialShardCount部署分片配置合约部署 Ring OCR3 合约为分片 Ring 部署多链共识合约获取 Ring P2P bootstrap URL从 bootstrap DON 收集 P2P 引导地址在组长 DON 上创建 Ring 任务等待 ConfigPoller filter 注册后配置 OCR3。分片的 DON 类型在 system-tests/lib/cre/don.go 中以ShardIndex uint \toml:shard_index建模而classifyTopology也正是读取该字段来判定sharded 类别。六、本地实操启动该拓扑并部署工作流6.1 环境准备先在 core/scripts/cre/environment 目录下完成依赖准备详见go run . setup然后通过CTF_CONFIGS环境变量指定拓扑并启动cd core/scripts/cre/environment export CTF_CONFIGSconfigs/workflow-gateway-sharded-5-dons.toml go run . env start --auto-setup启动流程environment.go的关键行为若设置--auto-setup会先执行RunSetup框架会自动把 capability_defaults.toml前置拼接到CTF_CONFIGS之前setDefaultCtfConfigs因此最终生效的是默认能力配置 拓扑配置的组合设置TESTCONTAINERS_RYUK_DISABLEDtrue避免命令结束时 Ryuk 销毁容器清理历史state目录后开始拉起容器。注意若不设置CTF_CONFIGSenv start会默认使用configs/workflow-gateway-capabilities-don.toml见 environment.go。6.2 部署工作流时的 DON 选择分片拓扑下部署工作流必须明确目标 DON否则会因为存在多个 workflow DON 而报错。选择逻辑实现在 workflow_don_resolver.go 的ResolveWorkflowDONMetadata优先级为--workflow-don-name按nodesets.name精确匹配如shard0--don-family按don_family匹配多个分片共享同一 family 时必须再带--shard-index若拓扑中恰好只有一个 workflow DON 则自动选中。# 方式一显式指定分片名 go run . workflow deploy -w ./examples/workflows/v2/cron/main.go --compile -n cron_example \ --workflow-don-name shard0 # 方式二按 family shard index 定位 go run . workflow deploy -w ./examples/workflows/v2/cron/main.go --compile -n cron_example \ --don-family test-don-family --shard-index 0resolveWorkflowDONByFamilyworkflow_don_resolver.go会在don_family命中多个分片且未指定--shard-index时报错提示set --shard-index or --workflow-don-name——这正是本拓扑6 个分片同属test-don-family的典型使用场景。6.3 校验放置是否与预期一致修改拓扑配置后务必重新生成并核对矩阵go run . topology show -c configs/workflow-gateway-sharded-5-dons.toml go run . topology generate生成的产物包括docs/topologies/*.md与docs/TOPOLOGIES.md索引generate --check可校验其是否过期。官方实践指南docs/local-cre/environment/topologies.md强调sharded 及专用拓扑只应在测试或功能确实需要分片能力时选用——如果工作流仅依赖cron、consensus等本地能力使用更简单的拓扑如workflow-gateway-don.toml或workflow-gateway-capabilities-don.toml即可获得更快的启动与迭代速度。七、小结workflow-gateway-sharded-5-dons是 Chainlink 本地 CRE 中规模最大的分片拓扑之一bootstrap-gateway承担引导与网关入口shard0作为组长承载http-action/http-trigger/vault等受限能力shard1~shard5各自以 4 节点并行承载cron/consensus/don-time/evm通用能力。其能力矩阵文档由go run . topology generate自动维护可作为能力放置的单一事实来源部署工作流时则需借助--workflow-don-name或--don-family --shard-index精确路由。理解了这份拓扑也就掌握了 Chainlink CRE 从单 DON到多分片协同的扩展路径及其链上协调机制Ring OCR3 ShardConfig的运作方式。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考