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 本地 CRE（Capabilities Runtime Environment）中"分片（sharded）"类多 DON 拓扑的部署形态。读完本文，你将掌握：如何读懂该拓扑的能力矩阵与 7 个 DON 的分工、如何从 TOML 配置还原每个节点的角色与端口、拓扑文档的生成机制与校验命令，以及分片拓扑背后的 Ring OCR3 与 ShardConfig 合约启动流程。
一、文档定位：由topology generate自动生成的拓扑说明书
在 Chainlink 仓库中，core/scripts/cre/environment/docs/topologies/下的每一份*.md都是自动生成的，其源头是 TOPOLOGIES.md 中登记的各份 TOML 拓扑配置。索引表明确记载：
| Config | Class | DONs |
|---|---|---|
configs/workflow-gateway-sharded-5-dons.toml | sharded | 7 |
生成机制在 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 # 校验文档是否过期其中isTopologyConfig（topology.go）会检查一份 TOML 是否同时具备nodesets、blockchains、jd、infra四个区块，只有四者齐全才会被识别为合法拓扑配置。因此本文档中的三个元数据字段Config、Class、Infra均直接来自对应 TOML：
- Config:
configs/workflow-gateway-sharded-5-dons.toml - Class:
sharded - Infra:
docker
Class字段并非手工填写，而是由 topologyviz.go 的classifyTopology函数动态判定：只要存在任意 DON 的ShardIndex > 0或其DONTypes包含shard，即归类为sharded。
二、拓扑总览：1 个网关 + 6 个分片 = 7 个 DON
该拓扑由 7 个 DON 组成，按功能可划分为两类：
| DON | 节点数 | DON 类型 | 节点角色 | 分工 |
|---|---|---|---|---|
bootstrap-gateway | 1 | bootstrap,gateway | bootstrap / gateway | 负责 DON 引导（bootstrap）与网关流量（gateway） |
shard0~shard5 | 各 4 | shard,workflow | plugin | 分片工作流 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/-）存在，都以这张表为准：
| Capability | bootstrap-gateway | shard0 | shard1 | shard2 | shard3 | shard4 | shard5 |
|---|---|---|---|---|---|---|---|
consensus | - | local | local | local | local | local | local |
cron | - | local | local | local | local | local | local |
don-time | - | local | local | local | local | local | local |
evm | - | 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 后缀的解析逻辑splitCapabilityFlag（topologyviz.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 leader）
Types: shard, workflow Nodes: 4 Roles: plugin EVM chains: 1337,2337 Exposes remote capabilities: falseshard0是唯一显式写出 4 个node_specs的 nodeset（TOML 第 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-trigger@1.0.0", "dontime@1.0.0"] [nodesets.db] image = "postgres:12.0" port = 13100要点：
override_mode = "all"表示下方单个node_specs会应用到该 nodeset 的所有 4 个节点（对比shard0的override_mode = "each"+ 4 个独立node_specs）；shard_index从 1 递增到 5，是分片在 Ring 中的唯一标识；- 每个分片有独立的 PostgreSQL 实例（
postgres:12.0，端口 13100~13500 递增）； http_port_range_start从 10100 递增到 10500，为各分片节点分配独立的 HTTP 端口段；registry_based_launch_allowlist限定了通过 registry 启动的触发器插件版本（cron-trigger@1.0.0、dontime@1.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 与 ShardConfig
sharded类拓扑与普通多 DON 拓扑的本质差异在于：分片之间需要通过链上的分片协调机制保证共识与状态一致性。这一机制在 sharding.go 的SetupSharding中以六步流程落地：
- 校验分片拓扑：调用
ValidateShardTopology，确保分片数量、shard_index=0的组长唯一性等约束成立（校验逻辑见 sharding_test.go，其中覆盖了"多个shard_index=0"、"找不到shard_index=0"等错误场景）； - 部署 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_CONFIGS=configs/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_DISABLED=true，避免命令结束时 Ryuk 销毁容器； - 清理历史
state目录后开始拉起容器。
注意：若不设置
CTF_CONFIGS，env 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 0resolveWorkflowDONByFamily（workflow_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），仅供参考
