企业官网建设流程全解析

Chainlink Local CRE 的 workflow-gateway-don 拓扑：单 DON 工作流执行环境的配置与源码解析

【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink

导读

本文围绕 Chainlink 仓库中 Local CRE（本地 Chainlink Runtime Environment）的默认拓扑workflow-gateway-don展开，完整解读其能力矩阵、双 DON 结构（bootstrap-gateway+workflow）以及对应的 workflow-gateway-don.toml 全量配置。读者将掌握该拓扑的每个配置字段含义、能力放置规则、拓扑文档的生成机制，以及工作流部署时 DON 选择与 gateway 接入的底层逻辑，从而能够在本地 Docker 环境中正确启动、验证和扩展这套工作流执行环境。

拓扑定位：Local CRE 的默认本地开发拓扑

workflow-gateway-don是 Chainlink 仓库 core/scripts/cre/environment 下 Local CRE 工具链提供的一类标准拓扑。它的元信息如下：

• Config：configs/workflow-gateway-don.toml
• Class：single-don
• Infra：docker

其中 Class 为single-don，表示该拓扑只有一个执行工作流的 DON（workflow DON），配套一个承担引导（bootstrap）与网关（gateway）职责的单节点 DON。从 topology.go 的实现看，topology show命令的默认--config值正是configs/workflow-gateway-don.toml，这也印证了它是 Local CRE 的默认开发拓扑；同时 docs/local-cre/environment/topologies.md 明确说明：CLI shell 启动时默认将CTF_CONFIGS指向该文件。

该拓扑适用于只需要本地能力（local capability）的工作流场景——例如仅依赖 cron 定时触发、consensus 共识、http 触发/动作、don-time 等能力的快速本地迭代；当工作流需要跨 DON 远程暴露能力（如单独的 capabilities DON）时，则应切换到workflow-gateway-capabilities-don等多 DON 拓扑。

能力矩阵：能力放置的唯一事实来源

原文档明确声明，下述矩阵是按 DON 进行能力放置的事实来源（source of truth）。在workflow-gateway-don拓扑中，全部七类能力都被放置在workflowDON 上，且均为local模式，bootstrap-gatewayDON 不承载任何能力：

几点值得注意的细节：

• evm能力的local (1337,2337)表示 EVM 能力由 workflow DON 本地承载，并绑定两条 Anvil 测试链（chain id 1337 与 2337）。这与配置文件中capabilities = ["evm-1337", "evm-2337"]一一对应。
• vault为local：vault 能力内置于节点（capability_defaults.toml注释说明 "no binary path for vault, it's built-in"），由 workflow DON 本地提供，而不是像workflow-gateway-capabilities-don拓扑那样由独立的 capabilities DON 远程暴露。
• 所有能力均不跨 DON 暴露：由于bootstrap-gateway与workflow两个 DON 的 "Exposes remote capabilities" 均为false，这是一个纯粹的单 DON 能力模型——工作流执行与全部能力运行在同一个 workflow DON 内。

能力默认值来自 capability_defaults.toml

能力名称与配置默认值并不是硬编码在拓扑文件里的。拓扑加载时，Local CRE 会把默认能力配置 configs/capability_defaults.toml 与拓扑文件合并（loadAndSummarizeConfig中执行defaultCapabilitiesConfigFile + "," + configPath的组合加载）。例如该文件为evm定义了LogTriggerPollInterval = 1500000000（1.5 秒，纳秒单位）与ReceiverGasMinimum = 500，为http-action/http-trigger定义了出入方向的 RPS/Burst 限流参数，为consensus定义了最大请求体尺寸等默认值。这些默认值在拓扑启动时注入到对应 DON 的节点中。

DON 结构详解

bootstrap-gateway：引导与网关合一

该 DON 仅 1 个节点，同时扮演两类角色：

• bootstrap：作为 DON 的引导节点（bootstrap peer），为 workflow DON 的 OCR/共识类工作提供 P2P 引导服务；
• gateway：承载 Chainlink gateway 组件，作为工作流与外部世界之间的连接器。gateway 的一个重要用途是为 vault 能力提供入站访问入口——配置文件为该 DON 的节点指定了custom_ports = ["5002:5002", "15002:15002"]，其中 5002 是 web API capabilities 端口（接收网关入站请求），15002 是 vault 端口（接收 vault 入站请求）。

workflow：工作流执行 DON

该 DON 由 4 个节点组成，角色为plugin，即运行工作流执行引擎（workflow engine）及全部本地能力的标准 Chainlink 节点。能力矩阵中的所有能力（consensus、cron、don-time、evm、http-action、http-trigger、vault）都在这 4 个节点上以本地模式运行。

配置文件全量解读：workflow-gateway-don.toml

以下为 configs/workflow-gateway-don.toml 的完整内容，并附逐段解读：

[chip_router] image = "local-cre-chip-router:v1.0.1"

chip_router：网关流量路由组件（CHIP ingress router）的镜像。该组件在 Local CRE 环境中负责把外部 HTTP 请求按规则路由到对应的能力端点。

[[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"]

blockchains：定义本地测试链。两条链均为 Foundryanvil类型：

• 链 1337：容器名anvil-1337，使用默认 RPC 端口（8545），anvil 启动参数为-b 0.5（每 0.5 秒产块）与--mixed-mining（混合挖矿模式，兼顾即时交易与周期性出块）；
• 链 2337：容器名anvil-2337，显式指定port = "8546"以避免与第一条链端口冲突，其余参数相同。

这两条链对应能力矩阵中evm local (1337,2337)，也对应 workflow DON 的capabilities = ["evm-1337", "evm-2337"]与bootstrap-gateway的supported_evm_chains = [1337, 2337]。

[jd] csa_encryption_key = "d1093c0060d50a3c89c189b2e485da5a3ce57f3dcb38ab7e2c0d5f0bb2314a44" # any random 32 byte hex string # change to your version image = "job-distributor:0.28.0"

jd：Job Distributor 服务配置。csa_encryption_key为任意随机的 32 字节十六进制字符串（用于与节点通信的加密密钥），示例值可按需替换；image指定 job-distributor 的镜像版本，注释提示按实际版本修改。

[fake] port = 8171 [fake_http] port = 8666

fake / fake_http：本地模拟服务。fake（端口 8171）通常用于模拟外部数据源/喂价等；fake_http（端口 8666）用于模拟 HTTP 服务，供http-action/http-trigger能力在测试中请求外部端点。

#[s3provider] # # use all defaults # port = 9000 # console_port = 9001

s3provider（注释掉）：可选的对象存储模拟服务（MinIO 风格），默认端口 9000、控制台端口 9001。需要工作流访问 S3 兼容存储时取消注释启用。

[infra] # either "docker" or "kubernetes" type = "docker"

infra：基础设施类型，取值docker或kubernetes。本拓扑使用 Docker，即所有组件（anvil、JD、Postgres、Chainlink 节点）以容器形式在本地运行。

[[nodesets]] nodes = 4 name = "workflow" don_family = "test-don-family" don_types = ["workflow"] override_mode = "all" http_port_range_start = 10000 p2p_port_range_start = 12000 env_vars = { CL_EVM_CMD = "", OTEL_SERVICE_NAME = "chainlink-node", CL_CRE_SETTINGS = '{"global":{"PerOrg":{"BaseTriggerRetransmitEnabled":"true"}}}' } capabilities = ["vault", "cron", "http-action", "http-trigger", "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 = 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 = ""

nodesets（workflow）是理解该拓扑的核心段落：

• nodes = 4：4 个节点构成该 DON，与文档 "Nodes: 4" 一致；
• name = "workflow"：DON 名称，作为容器命名前缀（<name>-node<索引>）与部署选择依据（见下文 DON 选择逻辑）；
• don_family = "test-don-family"：DON 家族标识，便于跨拓扑复用与部署时按家族定位 DON；
• don_types = ["workflow"]：DON 类型；
• override_mode = "all"：节点的 TOML 覆盖以"全部节点统一"方式应用；
• http_port_range_start = 10000、p2p_port_range_start = 12000：4 个节点的 HTTP 端口从 10000 起、P2P 端口从 12000 起顺序分配；
• env_vars：注入节点的环境变量，包括清空CL_EVM_CMD（走默认 EVM 命令）、设置OTEL_SERVICE_NAME = "chainlink-node"以统一可观测性服务名，以及CL_CRE_SETTINGS携带的按组织（PerOrg）工作流设置BaseTriggerRetransmitEnabled = "true"（启用触发重传）；
• capabilities：该 DON 本地承载的全部能力清单，与能力矩阵完全一致（vault、cron、http-action、http-trigger、consensus、don-time、evm-1337、evm-2337）；
• registry_based_launch_allowlist：允许通过 registry 机制启动的能力白名单（cron-trigger@1.0.0、dontime@1.0.0）；
• db：该 DON 使用postgres:12.0，数据库端口 13000；
• node_specs.node：节点镜像构建规格——docker_ctx = "../../../.."指向仓库根目录，docker_file = "core/chainlink.Dockerfile"使用核心节点 Dockerfile，CL_IS_PROD_BUILD = "false"表示本地非生产构建（注释中还提供了直接复用chainlink-tmp:latest预构建镜像的快捷方式）。

[[nodesets]] nodes = 1 name = "bootstrap-gateway" don_family = "test-don-family" don_types = ["bootstrap", "gateway"] override_mode = "each" http_port_range_start = 10100 p2p_port_range_start = 12100 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 = 13100 [[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 = ""

nodesets（bootstrap-gateway）：

• 仅nodes = 1的单节点 DON，don_types = ["bootstrap", "gateway"]使其同时具备引导与网关两种角色；
• 与 workflow DON 共享同一个don_family = "test-don-family"，便于按家族统一管理；
• override_mode = "each"：按节点逐个应用覆盖；
• 端口段与 workflow DON 错开（HTTP 10100 起、P2P 12100 起），避免冲突；
• supported_evm_chains = [1337, 2337]：显式声明支持两条测试链（用于网关侧的链上交互，如 vault 相关合约）；
• 数据库端口 13100（postgres:12.0）；
• 最关键的custom_ports = ["5002:5002", "15002:15002"]：5002 是 web API capabilities 端口（接收来自外部的入站请求），15002 是 vault 端口（接收 vault 入站请求），这是网关将外部流量接入工作流 DON 本地能力（尤其是 vault）的通道。

拓扑文档的生成机制：docs 与源码闭环

值得强调的是，本文所解析的关联文档 workflow-gateway-don.md 本身不是手写的——它由拓扑工具自动生成，因此文档内容与 TOML 配置始终同步。相关实现见 topology.go 与 topologyviz：

# 从 core/scripts/cre/environment 目录执行 go run . topology list # 列出所有可用拓扑及其 Class 与 DON 数量 go run . topology show # 展示默认拓扑（workflow-gateway-don.toml）的 ASCII 可视化 go run . topology show --config configs/workflow-gateway-don.toml -o state go run . topology generate # 重新生成 docs/topologies/*.md 与 docs/TOPOLOGIES.md 索引 go run . topology generate --check # 检查生成的文档是否最新

• topology list扫描configs/目录下满足条件的 TOML（通过topologyProbe探测：必须同时包含blockchains、nodesets、jd、infra段，见isTopologyConfig），渲染成终端表格；
• topology show加载配置、构建TopologySummary并输出 ASCII 拓扑图，同时可选写出 artifacts；
• topology generate遍历所有拓扑，生成各自的 Markdown 文档（即docs/topologies/*.md，其 "Capability Matrix" 与 "DONs" 小节即来源于此）以及总索引 docs/TOPOLOGIES.md。该索引文件头部也明确标注 "This file is generated bygo run . topology generate. Do not edit manually."。

因此，当读者在仓库中看到该能力矩阵时，其内容正是由workflow-gateway-don.toml中两个nodesets段（capabilities列表 + 节点规格）推导生成的，二者互为印证。

工作流部署时的 DON 选择逻辑

当环境启动后执行go run . workflow deploy部署工作流时，需要把工作流定向到正确的 workflow DON。该逻辑实现在 workflow_don_resolver.go 中，选择优先级如下：

1. --workflow-don-name：显式指定nodesets.name（如workflow），精确匹配，优先级最高；
2. --don-family：按don_family解析，要求该家族下恰好有一个 workflow DON；若多个分片 DON（shard）共享同一家族，则需配合--shard-index消歧；
3. 唯一 DON 兜底：当拓扑中恰好只有一个 workflow DON 时，无需任何选择器参数即可自动命中。

对于本文的workflow-gateway-don这类single-don拓扑，由于只存在一个 workflow DON，部署时通常无需额外传参；多 DON 拓扑（如workflow-gateway-capabilities-don）则必须显式提供选择器。环境启动时会保存状态文件，LocalCREStateResolver（见 state_resolver.go）负责从保存的状态重建拓扑并完成上述解析。

gateway 在部署链路中的作用

bootstrap-gatewayDON 中的 gateway 角色并非摆设，它深度参与了工作流部署链路（见 workflow.go）：

• 当工作流使用 secrets（--secrets-file-path）时，必须提供 gateway URL（--gateway-url标志，或从本地 CRE 状态文件中解析），否则部署直接报错；
• 部署流程首先通过 gateway 获取 vault 公钥（FetchVaultPublicKey），随后将加密后的 secrets 经 gateway 发送到 vault（ExecuteSecrets）——这正是custom_ports中15002（vault 端口）存在的意义；
• workflow deploy子命令提供了-g/--gateway-url标志用于显式指定网关地址。

换言之，网关是 workflow DON 本地vault能力与外部客户端之间的桥梁：外部（本地主机）通过 5002/15002 端口访问 gateway，再由 gateway 把请求路由到 vault 能力。

与相邻拓扑的对比：何时选用哪种

将workflow-gateway-don（Classsingle-don）与同一目录下的其他拓扑对比（见 TOPOLOGIES.md 索引）：

从源码注释可以提炼出选择经验（见 docs/local-cre/environment/topologies.md）：工作流只需本地能力时用更简单的拓扑；需要 EVM 读合约、vault、web API 目标等远程暴露能力时切换到 capabilities 拓扑。修改能力放置后，务必重跑go run . topology show --config <file>.toml与go run . topology generate校验生成的能力矩阵。

快速启动与验证

在仓库根目录下，Local CRE 的快速启动路径为（详见 README.md 与 docs/local-cre/getting-started/index.md）：

cd core/scripts/cre/environment go run . env start --auto-setup # 按默认拓扑（workflow-gateway-don.toml）启动整套环境 go run . workflow deploy -w ./examples/workflows/v2/cron/main.go --compile -n cron_example

验证拓扑是否符合预期：

go run . topology show # 默认即 workflow-gateway-don.toml，输出 ASCII 拓扑 go run . topology show --config configs/workflow-gateway-don.toml -o state

env start启动后，期望看到：2 条 Anvil 链（1337/2337）、1 个 job-distributor、1 个bootstrap-gateway节点（bootstrap + gateway 角色，暴露 5002/15002 端口）、4 个workflow节点（plugin 角色，承载 8 项本地能力）、以及配套的 Postgres 与 fake 模拟服务。

总结

workflow-gateway-don是理解 Chainlink Local CRE 拓扑体系的起点：它以最小的single-don结构，把七类核心能力（consensus、cron、don-time、evm、http-action、http-trigger、vault）全部本地化到 4 节点的 workflow DON，同时用 1 个bootstrap-gateway节点承担引导与网关职责，为 vault 等能力提供 5002/15002 入站通道。其能力矩阵由 TOML 配置自动生成文档，部署时的 DON 选择、gateway 接入均有对应的源码实现可循。掌握该拓扑的配置语义与生成机制，即可在此基础上举一反三地理解 capabilities、sharded、多链等更复杂拓扑的设计思路。

【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink